AG-UI Now Has a .NET SDK for AI Agent Applications

Introduction

AI agents are becoming part of normal application development, but connecting an agent to a real user interface is still more complicated than calling an AI model.

An agent may need to stream text, call tools, request user approval, maintain conversation state, send files, and report what it is doing while a task is running. If every frontend and backend implements these interactions differently, building a reliable agent application becomes difficult.

AG-UI, or Agent-User Interaction Protocol, provides a standardized event-based protocol for connecting AI agents with user-facing applications. The official AG-UI project now has a supported .NET SDK, which brings the protocol directly into the .NET ecosystem. The SDK includes client, server, protocol, formatting, and optional Protobuf components, and is built around Microsoft.Extensions.AI.

For .NET developers, this means an ASP.NET Core application can expose an agent through an AG-UI endpoint while another .NET application can connect to that endpoint using AGUIChatClient.

The result is a cleaner separation:

.NET Agent
    |
    v
AG-UI Protocol
    |
    v
Frontend / Client

The agent remains responsible for reasoning and tools, while the client receives standardized events that it can turn into a user experience.

What Is AG-UI?

AG-UI is an event-based protocol designed to connect AI agents with user-facing applications.

Instead of defining how a particular frontend should render an AI response, AG-UI defines the information exchanged between the agent and the client.

Conceptually:

User
 |
 v
Frontend
 |
 | AG-UI
 v
Agent
 |
 +-- Model
 +-- Tools
 +-- State
 +-- Business Logic

The frontend can receive events representing things such as text generation, tool activity, state changes, and other agent interactions.

This is important because an agent is no longer limited to returning one final string.

A modern agent may produce a sequence of events:

Run Started
     |
     v
Text Started
     |
     v
Text Chunks
     |
     v
Tool Call
     |
     v
Tool Result
     |
     v
More Text
     |
     v
Run Finished

The client can react to these events as they arrive.

What the .NET SDK Provides

The AG-UI .NET SDK is organized into several packages.

The core components include:

AGUI.Abstractions
AGUI.Formatting
AGUI.Client
AGUI.Server
AGUI.Protobuf

AGUI.Abstractions contains protocol types such as events, messages, tools, and serialization support.

AGUI.Formatting handles event-stream formatting, including Server-Sent Events.

AGUI.Client provides AGUIChatClient, an IChatClient implementation for connecting to AG-UI servers.

AGUI.Server provides server-side adapters for converting agent responses into AG-UI event streams.

AGUI.Protobuf provides optional Protobuf transport support.

This package separation is useful because applications do not necessarily need every part of the SDK.

Why .NET Developers Should Care

The .NET ecosystem already has strong abstractions around AI clients and agents through Microsoft.Extensions.AI.

The AG-UI .NET SDK builds on this model.

That means an application can work with familiar interfaces such as:

IChatClient
ChatMessage
ChatOptions
AIFunction

while using AG-UI for communication between the agent and the user-facing application.

The official SDK documentation describes AGUIChatClient as an IChatClient implementation. Microsoft Agent Framework also uses the same integration point when connecting agents to AG-UI.

This makes AG-UI particularly interesting for teams already building applications with ASP.NET Core, Microsoft Agent Framework, and Microsoft.Extensions.AI.

AG-UI Client and Server Architecture

A typical .NET application can be divided into two parts.

                HTTP
Client ----------------------> Server
  |                              |
  | AGUIChatClient                | AIAgent
  |                              |
  v                              v
User Interface              AI Model + Tools

The server hosts the agent.

The client connects to the AG-UI endpoint.

The server streams agent events back to the client.

The client then decides how those events should be displayed.

This separation means the same agent can potentially be consumed by different clients.

For example:

                 AG-UI Agent
                     |
          +----------+----------+
          |          |          |
          v          v          v
        Web        Mobile      CLI
       Client      Client     Client

The protocol is about the interaction stream, not a specific visual interface. AG-UI's documentation explicitly describes clients as potentially being web applications, terminal applications, mobile applications, or chat platforms.

Creating an AG-UI Server

An ASP.NET Core application can expose an agent through an AG-UI endpoint.

The server-side architecture is conceptually:

ASP.NET Core
     |
     v
AG-UI Endpoint
     |
     v
AIAgent
     |
     +-- Model
     +-- Tools
     +-- Memory
     +-- Business Logic

With the Microsoft Agent Framework integration, the current hosting API uses AddAGUIServer() and MapAGUIServer(). The hosting layer adapts an AIAgent to the AG-UI protocol and streams responses using AG-UI events.

A simplified server setup looks like this:

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAGUIServer();

AIAgent agent = CreateAgent();

var app = builder.Build();

app.MapAGUIServer("/", agent);

await app.RunAsync();

The exact agent creation code depends on the AI provider and agent framework being used.

The important part is that the application exposes an AG-UI-compatible endpoint instead of inventing its own streaming protocol.

Connecting From a .NET Client

The .NET SDK provides AGUIChatClient for consuming an AG-UI endpoint.

A simplified client can look like this:

using AGUI.Client;
using Microsoft.Extensions.AI;

using var httpClient = new HttpClient
{
    BaseAddress = new Uri("http://localhost:8888")
};

var chatClient = new AGUIChatClient(
    new AGUIChatClientOptions(
        httpClient,
        "/"));

var messages = new List<ChatMessage>
{
    new(
        ChatRole.User,
        "Explain dependency injection in ASP.NET Core.")
};

await foreach (var update in
    chatClient.GetStreamingResponseAsync(messages))
{
    foreach (var content in update.Contents)
    {
        if (content is TextContent text)
        {
            Console.Write(text.Text);
        }
    }
}

The important part is the streaming model.

The client does not have to wait for the complete response before receiving data.

That is useful for interactive applications because the UI can start displaying the response while the agent is still working.

Streaming Is a Core Part of the Experience

Without streaming, an AI interaction often looks like this:

User
 |
 v
Request
 |
 | wait
 | wait
 | wait
 v
Complete Response

With streaming:

User
 |
 v
Request
 |
 v
First Token
 |
 v
More Tokens
 |
 v
Tool Event
 |
 v
More Tokens
 |
 v
Complete

This makes a significant difference for agent applications.

A user can see that the system is working instead of staring at an empty screen until the entire operation finishes.

AG-UI's .NET implementation uses Server-Sent Events as the default wire format and also supports optional Protobuf transport.

Server-Sent Events in AG-UI

Server-Sent Events, commonly called SSE, are a natural fit for streaming agent responses from a server to a client.

The communication looks like:

Client
  |
  | HTTP Request
  v
AG-UI Server
  |
  | Event Stream
  v
Client

The server can send events as the agent progresses.

For example:

Event: TextMessageStart
Event: TextMessageContent
Event: TextMessageContent
Event: ToolCallStart
Event: ToolCallArgs
Event: ToolCallEnd
Event: TextMessageContent
Event: RunFinished

The exact event sequence depends on the agent's behavior.

The important design idea is that the client can react incrementally instead of receiving only a final result.

AG-UI and Tool Calls

Tool use is where agent applications become more interesting.

An agent may need to call:

• A database

• A REST API

• A search service

• An internal business system

• A calculator

• A repository

• A device API

A typical workflow looks like:

User
 |
 v
Agent
 |
 | Decide tool is required
 v
Tool Call
 |
 v
Tool Execution
 |
 v
Tool Result
 |
 v
Agent
 |
 v
Final Response

AG-UI can represent these interactions as events so the frontend can understand what is happening.

This can be useful for building interfaces where the user sees meaningful progress rather than only a final answer.

Backend Tools and Client Tools

One useful capability of the .NET SDK is support for tools that execute on different sides of the interaction.

A backend tool might access:

Database
Internal API
Enterprise Service
File Storage

A client-side tool might access:

Browser State
Local UI
Device API
User Selection
Local Application State

The AG-UI .NET SDK supports client-side tools through AIFunction and ChatOptions.Tools. The AGUIChatClient can execute the client tool and send its result back as part of the ongoing interaction.

This creates a useful architecture:

                  Agent
                    |
             Tool Requested
                    |
          +---------+---------+
          |                   |
          v                   v
      Server Tool         Client Tool
          |                   |
          v                   v
      Backend              Frontend

This separation is important because some information should never need to leave the client.

Example of a Client Tool

Suppose a desktop or frontend application has a selected project.

The agent might need to know which project the user currently has open.

A client-side tool can expose that information.

A simplified example is:

using System.ComponentModel;
using AGUI.Client;
using Microsoft.Extensions.AI;

[Description("Gets the project currently selected by the user.")]
static string GetSelectedProject()
{
    return "CustomerPortal";
}

var tool = AIFunctionFactory.Create(
    GetSelectedProject);

var options = new ChatOptions
{
    Tools = [tool]
};

await foreach (var update in
    chatClient.GetStreamingResponseAsync(
        messages,
        options))
{
    // Process streaming updates.
}

The exact client environment determines what local information can be exposed.

The important point is that the function executes on the client side rather than requiring the backend to independently access that state.

Human Approval and Agent Actions

An enterprise agent should not necessarily execute every requested operation automatically.

Consider an agent that can:

Create Pull Request
Delete File
Send Email
Approve Expense
Update Customer Record

Some operations should require user confirmation.

The AG-UI integration supports agent interactions that include tool approval requests and returning the user's decision to the agent. Microsoft describes this as one of the supported capabilities in the .NET integration.

A safe workflow can look like:

Agent
 |
 v
Tool Request
 |
 v
Approval Required
 |
 v
User
 |
 +---- Reject ----> Agent Stops / Adjusts
 |
 +---- Approve ---> Tool Executes

This is much safer than giving an agent unrestricted authority.

Shared State

Agent applications often need more than messages.

For example, a UI may maintain:

Current Account
Selected Project
Active Document
User Preferences
Workflow State

AG-UI supports state-related interactions, including state snapshots and deltas. The .NET integration exposes these capabilities when connecting Microsoft Agent Framework agents to AG-UI.

This allows the agent and frontend to maintain a more meaningful shared interaction model.

Instead of sending the entire application state on every interaction, a system can communicate relevant changes.

Multimodal Input

Modern agents often need to process more than text.

A user might upload:

• An image

• A PDF

• Audio

• A document

• Another binary file

The AG-UI .NET SDK supports multimodal content through the standard Microsoft.Extensions.AI content types.

For example:

using AGUI.Client;
using Microsoft.Extensions.AI;

byte[] imageBytes =
    await File.ReadAllBytesAsync("invoice.png");

var messages = new List<ChatMessage>
{
    new(
        ChatRole.User,
        [
            new TextContent("Review this invoice."),
            new DataContent(
                imageBytes,
                "image/png")
        ])
};

await foreach (var update in
    chatClient.GetStreamingResponseAsync(messages))
{
    // Process the response.
}

The SDK can carry these content parts across the AG-UI connection so the backend agent can process them when the underlying model supports the content type.

Protobuf Support

SSE is useful for many applications, but AG-UI's .NET SDK also provides an optional Protobuf transport.

The package structure separates this functionality into AGUI.Protobuf.

The server can negotiate the transport based on the client's accepted format, with SSE serving as the default and Protobuf available when configured.

A simplified architecture is:

Client
  |
  | Accept: AG-UI Format
  |
  v
Server
  |
  +---- SSE
  |
  +---- Protobuf

The benefit is that applications can use a more compact binary representation when that makes sense for their environment.

Developers should not automatically choose Protobuf simply because it is binary. SSE may be easier to inspect, debug, and integrate for many web applications.

AG-UI With Microsoft Agent Framework

The combination of AG-UI and Microsoft Agent Framework is particularly relevant to .NET developers.

The architecture looks like:

Frontend
   |
   | AG-UI
   v
ASP.NET Core
   |
   v
Microsoft Agent Framework
   |
   v
AIAgent
   |
   +-- Model
   +-- Tools
   +-- State
   +-- Approvals

Microsoft's current integration keeps AG-UI protocol functionality in the official AG-UI C# SDK while Microsoft Agent Framework provides the ASP.NET Core hosting layer. The earlier Microsoft.Agents.AI.AGUI package has been replaced by packages such as AGUI.Client, AGUI.Server, and AGUI.Abstractions.

This separation is important for developers upgrading older experimental integrations.

Migrating From Older Microsoft AG-UI Packages

Developers may find older examples using:

using Microsoft.Agents.AI.AGUI;

The current architecture has moved the protocol SDK into the official AG-UI C# packages.

The current package structure uses:

AGUI.Client
AGUI.Server
AGUI.Abstractions
AGUI.Formatting
AGUI.Protobuf

Microsoft's migration guidance also changes the hosting methods from:

builder.Services.AddAGUI();

app.MapAGUI("/", agent);

to:

builder.Services.AddAGUIServer();

app.MapAGUIServer("/", agent);

The AGUIChatClient construction also uses AGUIChatClientOptions.

This is important because developers copying older samples can otherwise end up using APIs that are no longer part of the current SDK structure.

AG-UI Is Not an AI Model

Another important distinction is that AG-UI is not an AI model.

It does not replace:

GPT
Claude
Gemini
Other LLMs

It also does not replace an agent framework.

Instead:

Model
  |
  v
Agent Framework
  |
  v
AG-UI
  |
  v
Frontend

The model performs AI reasoning.

The agent framework manages agent behavior.

AG-UI handles the interaction protocol between the agent and the user-facing application.

Keeping these responsibilities separate makes the architecture easier to understand.

Common Mistakes

Treating AG-UI as a UI Framework

AG-UI does not tell you whether your interface should use React, Blazor, Angular, MAUI, or another technology.

It defines the interaction protocol.

The client decides how events should be rendered.

Waiting for the Final Response

If the application ignores streaming events and waits for the complete response, it loses one of the main benefits of an agent interaction protocol.

Process events as they arrive when the user experience benefits from real-time feedback.

Giving Every Tool Backend Access

Not every tool needs to run on the server.

Client-only information should remain on the client when possible.

This reduces unnecessary data movement and can improve privacy.

Automatically Approving Dangerous Actions

A tool call should not automatically be trusted just because an AI model requested it.

Actions that change important data should have explicit controls.

Copying Outdated Examples

The AG-UI .NET ecosystem is evolving quickly.

Older examples may reference packages and APIs that have since moved into the official AG-UI SDK. Always check the current package structure before starting a new integration.

Best Practices

Keep the Agent Separate From the UI

The agent should contain reasoning, tools, and business logic.

The UI should focus on presenting the interaction and collecting user input.

AG-UI becomes the communication layer between them.

Stream Responses

Use streaming so users receive useful information as the agent works.

This is especially important for longer agent tasks.

Keep Tools Small

A tool should perform one well-defined operation.

For example:

Good:
GetCustomerOrders(customerId)

Less useful:
ManageEverything(customerId)

Smaller tools are easier for both the model and developers to reason about.

Protect Write Operations

Read operations and write operations should not automatically receive the same trust level.

Use approval workflows for operations that can change important data.

Keep Client Tools Local

If a piece of information only exists in the client, expose it through a client-side tool instead of copying the information into the backend through unrelated mechanisms.

Monitor Agent Runs

Production systems should capture enough operational information to diagnose failures.

Useful information can include:

• Run identifier

• Thread identifier

• Tool execution status

• Errors

• Response latency

• Approval decisions

• Cancellation

• Model failures

Avoid logging sensitive prompt content, credentials, or private user data unnecessarily.

Advantages

Standardized Agent-to-UI Communication

The biggest advantage of AG-UI is that developers do not have to invent a custom protocol for every agent application. A standardized event model provides a common way to communicate streaming responses, tool interactions, state updates, and other agent events between a backend and a client.

Strong Fit for the .NET AI Stack

The .NET SDK is built around Microsoft.Extensions.AI, which gives developers a familiar abstraction when building AI applications. AGUIChatClient implements IChatClient, making it easier to connect AG-UI communication with other .NET AI components.

Better Streaming Experiences

Agent tasks can take longer than a normal request-response operation. Streaming allows the application to show progress and partial output while the agent is still working, making the interaction feel more responsive and giving users visibility into ongoing work.

Support for Rich Agent Interactions

AG-UI goes beyond plain text. The protocol and .NET implementation can support tool calls, approvals, shared state, multimodal content, and different transport formats. This makes it more suitable for serious agent applications than a simple text-generation API.

Flexible Client Architecture

Because AG-UI describes an event stream rather than a particular rendering technology, the same agent interaction model can be consumed by different types of clients. This can be useful when an organization needs web, desktop, mobile, or command-line interfaces around the same backend agent.

Disadvantages

The Ecosystem Is Still Evolving

AG-UI and its .NET implementation are developing quickly. Package structures and APIs can change, as demonstrated by the migration from the older Microsoft AG-UI package to the official AG-UI C# SDK. Teams should therefore plan for SDK upgrades instead of assuming the initial integration will remain unchanged indefinitely.

It Adds Another Protocol Layer

An application using AG-UI has another abstraction between the agent and frontend. This can be beneficial for standardization, but it also introduces additional concepts that developers need to understand when troubleshooting streaming, serialization, transport negotiation, or event handling.

Debugging Distributed Agent Workflows Can Be Difficult

A single user request can involve the frontend, AG-UI transport, server, agent framework, model, and several tools. When something fails, developers need enough logging and tracing to determine which layer caused the problem.

Security Still Depends on the Application

AG-UI does not automatically make an agent safe. Tool permissions, authentication, authorization, sensitive data handling, approval policies, and business rules still belong to the application architecture.

Streaming Requires Careful Error Handling

Long-running streaming connections can fail because of network problems, client cancellation, server errors, or agent failures. Production applications need to handle partial responses and interrupted runs rather than assuming every stream reaches a clean completion event.

Troubleshooting

The Client Cannot Connect

Check the server URL, endpoint path, HTTP configuration, authentication requirements, and whether the AG-UI endpoint is actually running.

No Streaming Events Appear

Verify that the server is returning an AG-UI event stream and that the client is consuming the streaming API rather than waiting for a normal response.

A Tool Is Not Executing

Check whether the tool is registered with the appropriate ChatOptions, whether it is intended to run on the client or server, and whether the agent framework is configured to execute that tool.

A Client Tool Fails

Verify that the tool is available in the client application and that the function returns a result in the expected format. Client-side tools should not depend on server-only resources.

Older Code Does Not Compile

Check whether the sample uses the previous Microsoft.Agents.AI.AGUI package. Current integrations use the official AGUI.* packages, while ASP.NET Core hosting is provided separately by the Microsoft Agent Framework integration.

Multimodal Input Does Not Work

Check the content type and whether the underlying model supports the media being sent. A valid AG-UI message does not guarantee that every model can process every content type.

A Practical Architecture for Production

A production .NET agent application can be organized like this:

                         User
                          |
                          v
                  Web / Mobile / App
                          |
                          | AG-UI
                          v
                   ASP.NET Core API
                          |
                          v
                 Microsoft Agent Framework
                          |
              +-----------+-----------+
              |                       |
              v                       v
             Model                  Tools
                                      |
                         +------------+------------+
                         |            |             |
                         v            v             v
                      Database     APIs        Enterprise Systems

AG-UI should remain focused on the interaction boundary.

The business logic should remain inside the application and agent layers.

This separation makes it easier to change the frontend without rewriting the agent and easier to change the model without redesigning the UI protocol.

When Should You Use AG-UI?

AG-UI is a strong fit when an application needs more than a basic chatbot.

Consider it when your agent needs:

• Streaming responses

• Tool calls

• Human approval

• Shared state

• Multimodal input

• Long-running agent workflows

• Multiple frontend clients

• A standardized agent-to-UI protocol

For a very simple application that only sends a prompt and receives a completed string, AG-UI may be more infrastructure than you need.

The value increases as the interaction becomes more agentic.

Summary

The AG-UI .NET SDK gives .NET developers a standardized way to connect AI agents with user-facing applications. It brings AG-UI protocol support into the .NET ecosystem through packages such as AGUI.Client, AGUI.Server, and AGUI.Abstractions, while integrating naturally with Microsoft.Extensions.AI.

The most important capability is that AG-UI treats an agent interaction as an event stream rather than a single text response. That allows applications to handle streaming text, tool calls, approvals, state updates, and other events while an agent is working.

For .NET developers building serious AI applications, this creates a useful separation between the agent and the frontend. The agent can focus on reasoning and tools, while the client focuses on the user experience.

The SDK also supports more advanced scenarios such as client-side tools, multimodal messages, and optional Protobuf transport. These capabilities make AG-UI suitable for applications that are moving beyond basic chat and toward interactive agent workflows.

The main thing to remember is that AG-UI is an interaction protocol, not an AI model or a complete agent framework. It connects those pieces together.

For teams already building with ASP.NET Core and .NET AI abstractions, AG-UI provides a practical foundation for building agent applications where the UI needs to understand what the agent is doing, not just display its final answer.