Skip to content

docs: enhance architecture documentation for Author and AuthorAgent r… #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JesseLiberty merged 1 commit into from
Sep 10, 2026
Merged

docs: enhance architecture documentation for Author and AuthorAgent r… #31

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,21 @@ terminates, either on reviewer approval or on hitting the revision cap.
console app never issues a raw HTTP call to an agent endpoint.** This is a hard
constraint of this codebase (see `AGENTS.md`), not just a convention.

## Relationship betwen Hosted Agents and Agents
Under `HostedAgents` there is, e.g., `Author` as a project. In the main project there is `AuthorAgent`.

`Author` and `AuthorAgent` are two halves of the same distributed design:

`Author` is the deployable Azure AI Foundry Hosted Agent. Its Program.cs creates an `AIAgent` with the Author instructions and exposes it through the `Responses` protocol. azure.yaml packages and deploys it as the `Author/blogwriter-author service`.

`AuthorAgent.cs` is the local workflow adapter. The main app connects to the hosted agent by name in Program.cs, wraps the remote endpoint as an `AIAgent`, and passes that client into `AuthorAgent`.

During execution, `AuthorAgent` converts `ResearchState` into a prompt, calls the remote hosted agent with _agent.RunAsync(...), then writes the returned draft back into ResearchState. It also owns workflow concerns such as logging, tracing, revision counting, error handling, and fallback drafts.
Comment on lines +58 to +62

**They are not the same class and are not directly project-referenced. The hosted project is independently deployable; communication happens over the Foundry Responses endpoint.**

One detail to maintain: the Author instructions are duplicated in Prompts.cs and AgentPrompt.cs. The hosted copy is used at deployment/runtime, while the root copy documents or supports the local architecture, so changes should keep both aligned.

## Authentication

Every hop — console app → hosted agent, and hosted agent → Foundry model/tools — uses
Expand Down