[DevBlog MS] AG-UI Protocol now has a first-class .NET SDK

[xSicKxBot]

The .NET team is pleased to announce that we’ve contributed a .NET SDK for AG-UI in collaboration with CopilotKit. The AG-UI .NET SDK lives in the AG-UI repository alongside the TypeScript and Python SDKs, published on NuGet under the MIT license. Any .NET service can now speak AG-UI directly. The Microsoft Agent Framework (MAF) AG-UI support for .NET is now based on the AG-UI .NET SDK.

What is AG-UI?

Agents break the traditional request-and-response paradigm. They are long-running, stream tokens as they work, delegate to subagents, and invoke tools mid-response. Without a shared protocol, each agent framework or service can expose a different streaming format, leaving application developers to parse chunks, track state, and map framework-specific events to UI. This creates boilerplate that you must maintain, and it can break whenever the event format shifts.

AG-UI (Agent-User Interaction Protocol) standardizes how agents communicate with user-facing applications.



It streams the agent lifecycle as typed events, grouped into several categories. The frontend listens for

Code:

RUN_STARTED

,

Code:

TEXT_MESSAGE_CONTENT

,

Code:

STATE_DELTA

, and the other events without caring which framework produced them. State events keep the agent, the app, and the user in sync. How those events are displayed is the client’s choice, so the surface can be a web app, terminal, mobile app, or even a chat platform like Slack or Teams.

The .NET SDK brings that capability to C#. A backend emits those events natively, and a client consumes them from an agent written in any supported language.

Quickstart

The SDK works in both directions.

Code:

AGUI.Server

turns an agent into an AG-UI endpoint, and

Code:

AGUI.Client

lets a .NET application consume one. The server and client support is built on a common set of AG-UI primitives.

Code:

[code]dotnet add package AGUI.Server[/code]

Your agent is an

Code:

IChatClient

, the standard chat abstraction from

Code:

Microsoft.Extensions.AI

. Assuming your app defines a

Code:

CreateChatClient()

method that returns a configured

Code:

IChatClient

, register the client and the AG-UI serializer:

Code:

[code]using AGUI.Abstractions; using AGUI.Server; using Microsoft.AspNetCore.Http.Json; using Microsoft.Extensions.AI; using Microsoft.Extensions.Options; var builder = WebApplication.CreateBuilder(args); builder.Services.AddSingleton(CreateChatClient()); builder.Services.Configure<JsonOptions>(options => options.SerializerOptions.TypeInfoResolverChain.Insert( 0, AGUIJsonUtilities.DefaultTypeInfoResolver)); var app = builder.Build(); app.MapPost("/", ( RunAgentInput input, IChatClient chatClient, IOptions<JsonOptions> jsonOptions, CancellationToken cancellationToken) => { var context = input.ToChatRequestContext( jsonOptions.Value.SerializerOptions); var events = chatClient .GetStreamingResponseAsync( context.Messages, context.ChatOptions, cancellationToken) .AsAGUIEventStreamAsync(context, cancellationToken); return TypedResults.ServerSentEvents(events); }); await app.RunAsync();[/code]

Code:

ToChatRequestContext

unpacks the incoming

Code:

RunAgentInput

, the protocol’s request payload, into the messages and options your

Code:

IChatClient

expects.

Code:

AsAGUIEventStreamAsync

turns the response stream back into protocol events. It emits

Code:

RUN_STARTED

and

Code:

RUN_FINISHED

around the run, closes open text and reasoning blocks before switching to a different message or tool call, and collapses multiple interrupts into a single terminal

Code:

RUN_FINISHED

.

The SDK handles the protocol. The web server is yours, which is why Agent Framework’s ASP.NET Core package wraps these same primitives as

Code:

AddAGUIServer()

and

Code:

MapAGUIServer()

.

In Agent Framework, the same endpoint takes only a few lines. Given an existing

Code:

IChatClient

named

Code:

chatClient

, the following code creates and hosts the agent. Read the full walkthrough on Microsoft Learn for a complete server and client.

Code:

[code]dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prerelease[/code]

Code:

[code]using Microsoft.Agents.AI; using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore; using Microsoft.Extensions.AI; var builder = WebApplication.CreateBuilder(args); builder.Services.AddAGUIServer(); var app = builder.Build(); AIAgent agent = chatClient.AsAIAgent( name: "AGUIAssistant", instructions: "You are a helpful assistant."); app.MapAGUIServer("/", agent); await app.RunAsync();[/code]

Code:

AGUI.Client

handles the other direction, connecting a .NET application to any AG-UI agent.

Code:

[code]dotnet add package AGUI.Client[/code]

Code:

[code]using AGUI.Client; using var httpClient = new HttpClient(); var chatClient = new AGUIChatClient( new(httpClient, "http://localhost:5001"));[/code]

Code:

AGUIChatClient

is an

Code:

IChatClient

, so it works anywhere your code already takes an

Code:

IChatClient

. The agent on the other end can be written in Python, TypeScript, or C#, and your code does not change.

Once your endpoint speaks AG-UI, any AG-UI client can drive it: a .NET application through

Code:

AGUI.Client

, or a React frontend through CopilotKit. The CopilotKit Interactive Dojo has running examples against a .NET backend.

The repository has worked examples for each part of the protocol. There is one client and server pair per step, covering chat, backend and frontend tools, human in the loop, shared state, reasoning, multimodal input, interrupts, parallel tool calls, protobuf, and telemetry.

Architecture

Here is how everything works together. A request arrives from any AG-UI client, the endpoint hands it to your agent in Microsoft Agent Framework or your own agent code, and the response streams back as protocol events while the agent calls your tools and the model.



The packages

The SDK ships as five packages on NuGet: protocol types, wire formatters, protobuf support, an HTTP client, and a framework-agnostic server adapter built on

Code:

Microsoft.Extensions.AI

.

Package
What it is

Code:

AGUI.Abstractions

Protocol model: events, messages, tools, capabilities, interrupts, state, and the source-generated serializer

Code:

AGUI.Formatting

Wire format abstraction and the default Server-Sent Events implementation

Code:

AGUI.Protobuf

Opt-in protobuf codec generated from the TypeScript

Code:

.proto

definitions. It covers a subset of event types. SSE is the default and carries all of them

Code:

AGUI.Client

Consumes AG-UI

Code:

AGUI.Server

Produces AG-UI

The client and server packages pull in the abstractions they need, so most applications reference one of them.

What this means for Microsoft Agent Framework

Agent Framework, our SDK for building AI agents in .NET and Python, used to include its own implementation of the AG-UI protocol. It now depends on the

Code:

AGUI.*

packages from NuGet and keeps the ASP.NET Core integration that turns an agent into an endpoint.

The protocol is maintained in the AG-UI C# SDK and stays wire-compatible with the TypeScript and Python SDKs. See the migration notice for full details.

For existing Agent Framework users, the programming model is unchanged, though a few APIs were renamed:

Before
Now

Code:

AddAGUI()

,

Code:

MapAGUI()

Code:

AddAGUIServer()

,

Code:

MapAGUIServer()

Code:

Microsoft.Agents.AI.AGUI

namespace

Code:

AGUI.Client

,

Code:

AGUI.Server

,

Code:

AGUI.Abstractions

Code:

AGUIChatClient

positional constructor
Options-based constructor

Reading the originating request

Code:

chatOptions.TryGetRunAgentInput(out RunAgentInput? agentInput)

The event format is unchanged, so existing frontends keep working against an upgraded backend without changes of their own.

Why this matters

Any .NET backend can speak the protocol. A worker service, internal API, or existing line-of-business application can expose an agent over AG-UI on its own. No agent framework is required.

One backend can serve many surfaces. The client decides how to render the events, so the same endpoint serves a web app, terminal, mobile client, or chat platform like Slack and Teams.

Your existing code remains the same.

Code:

IChatClient

is the only integration point. You can consume AG-UI from .NET Framework 4.7.2 and later, and expose an endpoint from current .NET.

Interoperate across languages. The shared wire protocol keeps the C#, TypeScript, and Python SDKs compatible, so a .NET backend can work with clients built using any of them.

Get started

The AG-UI .NET SDK provides one C# implementation of AG-UI, published on NuGet and usable from any .NET service. Agent Framework consumes it, and so can you.

• AG-UI .NET SDK source and samples
  
  
• AG-UI documentation
  
  
• CopilotKit’s AG-UI .NET SDK post
  
  
• Agent Framework AG-UI documentation on Microsoft Learn
  
  
• Microsoft Agent Framework migration notes
  
  

Questions and feedback about the SDK are welcome in the AG-UI repository. For MAF integration questions, use the Microsoft Agent Framework discussion boards.

The post AG-UI Protocol now has a first-class .NET SDK appeared first on .NET Blog.