microsoft--agent-framework/dotnet/samples/02-agents/AGUI

AG-UI Getting Started Samples

This directory contains samples that demonstrate how to build AG-UI (Agent UI Protocol) servers and clients using the Microsoft Agent Framework.

Prerequisites

• .NET 9.0 or later
• Azure OpenAI service endpoint and deployment configured
• Azure CLI installed and authenticated (az login)
• User has the Cognitive Services OpenAI Contributor role for the Azure OpenAI resource

Environment Variables

All samples require the following environment variables:

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"

For the client samples, you can optionally set:

export AGUI_SERVER_URL="http://localhost:8888"

Samples

Step01_GettingStarted

A basic AG-UI server and client that demonstrate the foundational concepts.

Server (Step01_GettingStarted/Server)

A basic AG-UI server that hosts an AI agent accessible via HTTP. Demonstrates:

• Creating an ASP.NET Core web application
• Setting up an AG-UI server endpoint with MapAGUIServer
• Creating an AI agent from an Azure OpenAI chat client
• Streaming responses via Server-Sent Events (SSE)

Run the server:

cd Step01_GettingStarted/Server
dotnet run --urls http://localhost:8888

Client (Step01_GettingStarted/Client)

An interactive console client that connects to an AG-UI server. Demonstrates:

• Creating an AG-UI client with AGUIChatClient
• Managing multi-turn conversations with an AgentSession
• Streaming responses with RunStreamingAsync
• Displaying colored console output for different content types
• Supporting both interactive and automated modes

Prerequisites: The Step01_GettingStarted server (or any AG-UI server) must be running.

Run the client:

cd Step01_GettingStarted/Client
dotnet run

Type messages and press Enter to interact with the agent. Type :q or quit to exit.

Step02_BackendTools

An AG-UI server with function tools that execute on the backend.

Server (Step02_BackendTools/Server)

Demonstrates:

• Creating function tools using AIFunctionFactory.Create
• Using [Description] attributes for tool documentation
• Defining explicit request/response types for type safety
• Setting up JSON serialization contexts for source generation
• Backend tool rendering (tools execute on the server)

Run the server:

cd Step02_BackendTools/Server
dotnet run --urls http://localhost:8888

Client (Step02_BackendTools/Client)

A client that works with the backend tools server. Try asking: "Find Italian restaurants in Seattle" or "Search for Mexican food in Portland".

Run the client:

cd Step02_BackendTools/Client
dotnet run

Step03_FrontendTools

Demonstrates frontend tool rendering (tools defined on client, executed on server).

Server (Step03_FrontendTools/Server)

A basic AG-UI server that accepts tool definitions from the client.

Run the server:

cd Step03_FrontendTools/Server
dotnet run --urls http://localhost:8888

Client (Step03_FrontendTools/Client)

A client that defines and sends tools to the server for execution.

Run the client:

cd Step03_FrontendTools/Client
dotnet run

Step04_HumanInLoop

Demonstrates human-in-the-loop approval workflows for sensitive operations. This sample includes both a server and client component.

Server (Step04_HumanInLoop/Server)

An AG-UI server that implements approval workflows. Demonstrates:

• Wrapping a tool with ApprovalRequiredAIFunction so it requires approval before running
• Mapping a plain agent with MapAGUIServer, which natively emits an approval interrupt when the model calls the approval-required tool and resumes the run once the client sends the decision back

Run the server:

cd Step04_HumanInLoop/Server
dotnet run --urls http://localhost:5100

Client (Step04_HumanInLoop/Client)

An interactive client that handles approval requests from the server. Demonstrates:

• Detecting ToolApprovalRequestContent in the streamed response
• Displaying approval details to the user and prompting for approval or rejection
• Sending the decision back as a ToolApprovalResponseContent created with approvalRequest.CreateResponse(approved)
• Resuming the run so the server continues after the decision is received

Run the client:

cd Step04_HumanInLoop/Client
dotnet run

Try asking the agent to perform sensitive operations like "Approve expense report EXP-12345".

Step05_StateManagement

An AG-UI server and client that demonstrate shared state management.

Server (Step05_StateManagement/Server)

Demonstrates:

• Exposing a generate_recipe tool that returns the complete recipe
• Mapping the tool result to a STATE_SNAPSHOT event with AGUIStreamOptions.MapResultAsStateSnapshot
• Reading the client's current recipe from RunAgentInput.State
• Managing shared state between client and server
• Using JSON serialization contexts for state types

Run the server:

cd Step05_StateManagement/Server
dotnet run

The server runs on port 8888 by default.

Client (Step05_StateManagement/Client)

A client that displays and updates shared state from the server. Try asking: "Create a recipe for chocolate chip cookies" or "Suggest a pasta dish".

Run the client:

cd Step05_StateManagement/Client
dotnet run

How AG-UI Works

Server-Side

1. Client sends HTTP POST request with messages
2. ASP.NET Core endpoint receives the request via MapAGUIServer
3. Agent processes messages using Agent Framework
4. Responses are streamed back as Server-Sent Events (SSE)

Client-Side

1. AGUIChatClient sends HTTP POST request to server
2. Server responds with SSE stream
3. Client parses events into AgentResponseUpdate objects
4. Updates are displayed based on content type
5. The client sends the full message history each turn (the stateless AG-UI client does not rely on a server-assigned ConversationId)

Protocol Features

• HTTP POST for requests
• Server-Sent Events (SSE) for streaming responses
• JSON for event serialization
• Thread IDs (read from the RUN_STARTED event's raw representation) for conversation context. AGUIChatClient is stateless and intentionally does not surface a ConversationId.
• Run IDs (as ResponseId) for tracking individual executions

Security considerations

ConversationId keeps request/response continuity. It is not proof that the caller owns that conversation. In multi-user deployments, authenticate each AG-UI request and authorize conversation access using your application's real boundary, such as the authenticated user, tenant, or workspace.

If your ASP.NET Core host shares session storage across users, pair MapAGUIServer with an isolation strategy such as UseClaimsBasedAgentIsolation(...) so the storage key includes a principal-specific dimension instead of relying on the conversation identifier alone.

Troubleshooting

Connection Refused

Ensure the server is running before starting the client:

# Terminal 1
cd AGUI_Step01_ServerBasic
dotnet run --urls http://localhost:8888

# Terminal 2 (after server starts)
cd AGUI_Step02_ClientBasic
dotnet run

Port Already in Use

If port 8888 is already in use, choose a different port:

# Server
dotnet run --urls http://localhost:8889

# Client (set environment variable)
export AGUI_SERVER_URL="http://localhost:8889"
dotnet run

Authentication Errors

Make sure you're authenticated with Azure:

az login

Verify you have the Cognitive Services OpenAI Contributor role on the Azure OpenAI resource.

Missing Environment Variables

If you see "AZURE_OPENAI_ENDPOINT is not set" errors, ensure environment variables are set in your current shell session before running the samples.

Streaming Not Working

Check that the client timeout is sufficient (default is 60 seconds). For long-running operations, you may need to increase the timeout in the client code.

Next Steps

After completing these samples, explore more AG-UI capabilities:

Currently Available in C#

The samples above demonstrate the AG-UI features currently available in C#:

• ✅ Basic Server and Client: Setting up AG-UI communication
• ✅ Backend Tool Rendering: Function tools that execute on the server
• ✅ Streaming Responses: Real-time Server-Sent Events
• ✅ State Management: State schemas with predictive updates
• ✅ Human-in-the-Loop: Approval workflows for sensitive operations

Coming Soon to C#

The following advanced AG-UI features are available in the Python implementation and are planned for future C# releases:

• ⏳ Generative UI: Custom UI component generation
• ⏳ Advanced State Patterns: Complex state synchronization scenarios

For the most up-to-date AG-UI features, see the Python samples for working examples.

Related Documentation

• AG-UI Overview - Complete AG-UI documentation
• Getting Started Tutorial - Step-by-step walkthrough
• Backend Tool Rendering - Function tools tutorial
• Human-in-the-Loop - Approval workflows tutorial
• State Management - State management tutorial
• Agent Framework Overview - Core framework concepts