A sample application demonstrating AI agent workflows using Microsoft Agent Framework. This project showcases how to build collaborative AI agents that work together to create and edit stories.

This application demonstrates a multi-agent system with two specialized AI agents:

• Writer Agent: Creates engaging and creative stories based on prompts
• Editor Agent: Reviews and improves the writer's drafts with recommendations and revisions

The agents collaborate using workflow orchestration to produce high-quality creative content.

Get started instantly with GitHub Codespaces - a fully configured development environment in the cloud:

This will create a new codespace with all dependencies pre-installed and configured, including:

• .NET 9.0 SDK
• Docker support
• Aspire CLI + tooling
• Git integration

Once your codespace is ready, you can immediately start building and running the agents!

├── src/
│   ├── HelloWorldAgents.API/          # Web API with agent endpoints
│   │   └── wwwroot/                   # Static web chat UI files (only used for testing)
│   ├── HelloWorldAgents.AppHost/      # .NET Aspire orchestrator
│   ├── HelloWorldAgents.Console/      # Console application example
│   └── HelloWorldAgents.ServiceDefaults/ # Shared service configurations
└── hello-world-agents.slnx           # Solution file

• Multi-Agent Workflows: Demonstrates sequential and group chat patterns
• Tool Integration: Agents can use custom tools for formatting and data retrieval
• GitHub Models: Supports GitHub Models for LLMs
• Web Chat UI: Interactive JavaScript chat interface with Markdown rendering
• Web API: RESTful endpoint for agent interactions
• Console App: Direct agent interaction example
• Aspire Integration: Cloud-ready orchestration and observability with Aspire

• .NET 9.0 SDK
• Aspire CLI
• A personal access token (PAT) with the models scope, which you can create in settings. For more details, see the GitHub documentation

This project can use GitHub-hosted models. To enable access outside of Codespaces, create a GitHub Personal Access Token (PAT) with the models scope and expose it to the app using an environment variable named GITHUB_TOKEN.

Set the environment variable for your platform:

setx GITHUB_TOKEN "YOUR-GITHUB-TOKEN"
# Restart your shell to pick up the value

export GITHUB_TOKEN="YOUR-GITHUB-TOKEN"

After setting the variable, run the application as normal. The app will detect GITHUB_TOKEN and use it when calling GitHub Models.

git clone <repository-url>
cd hello-world-agents
dotnet restore
dotnet build

cd src/HelloWorldAgents.Console
dotnet run

Use the Aspire CLI to orchestrate and run the Web API and related services:

aspire run

This will start the Aspire dashboard and all required services, including the Minimal Web AP and chat UI.

1. Open the Aspire dashboard

2. Select the Chat UI URL for the api resource.

   

3. In the Chat UI, enter a prompt in the text box (i.e. "Write a short story about a haunted hotel") and select Send

   

1. After sending a request to the /agents/chat endpoint, select the Traces tab.

2. Select one of the traces /agets/chat traces.

   

3. Select the sparkle icon in the trace details to see more deatils.

   

For more details, see the Aspire Dashboard documentation.

The console application demonstrates a sequential workflow where the Writer creates content first, then the Editor reviews and improves it.

The API uses a round-robin group chat manager that allows agents to collaborate iteratively with a maximum of 2 iterations.

1. Create a new agent using ChatClientAgent
2. Define custom instructions and tools
3. Register the agent in the DI container
4. Add to workflow configuration

Example:

builder.AddAIAgent("MyAgent", (sp, key) =>
{
    var chatClient = sp.GetRequiredService<IChatClient>();
    return new ChatClientAgent(
        chatClient,
        name: key,
        instructions: "Your agent instructions here",
        tools: [/* your tools */]
    );
});

Agents can use custom tools defined as static methods:

[Description("Description of what the tool does")]
string MyTool(string parameter) => "Result";

The web chat interface is built with:

• HTML/CSS/JavaScript: Clean, responsive design
• Marked.js: Markdown rendering for formatted stories
• Static file serving: Hosted directly from the API

Files located in src/HelloWorldAgents.API/wwwroot/:

• index.html: Main chat interface
• styles.css: Responsive styling
• main.js: Chat logic and Markdown rendering

• Microsoft.Agents.Workflows: Agent workflow orchestration
• Microsoft.Agents.AI: Core agent abstractions
• Microsoft.Extensions.AI: Core AI abstractions and GitHub Models integration

• Microsoft Agent Framework Documentation
• Aspire Documentation
• GitHub Models Documentation
• .NET AI Documentation
• Microsoft.Extensions.AI Documentation