AG-UI protocol in .NET: typed events for agent UIs

The AG-UI protocol gives your frontend named events instead of opaque chunks: RUN_STARTED, TEXT_MESSAGE_CONTENT, STATE_DELTA, RUN_FINISHED. Microsoft has now shipped a first-class .NET SDK for it — five MIT-licensed NuGet packages, built with CopilotKit, with no Semantic Kernel or agent framework required. If you have a .NET backend inventing its own streaming shape, this is the thing to look at.

The interesting part is not the packages. It is what a typed lifecycle stream removes from your frontend, and the cases where it is still overkill.

What the AG-UI protocol actually standardises

AG-UI — the Agent-User Interaction Protocol — is an open, lightweight, event-based protocol for connecting agents to user-facing applications. It sits alongside MCP (agent to tools and data) and A2A (agent to agent), covering the third edge: agent to user.

The protocol streams the agent lifecycle as typed events in categories: lifecycle, text message, tool call, state management, activity, reasoning, subagent, and special events. Every run is bounded — it starts with RunStarted, may contain optional StepStarted/StepFinished pairs, and terminates with either RunFinished or RunError. Those boundaries are mandatory, which is precisely what lets a frontend implement loading states, progress and error recovery without guessing.

Two details are worth reading before you design around it. RunFinished carries an optional discriminated outcome, which can be interrupt with a non-empty interrupts array — a run that paused for human input is a first-class terminal state, not an error. And most events accept an optional subagentRunId; an event without one belongs to the parent agent. Delegation is in the wire format, not bolted on.

The five .NET packages and what each is for

The SDK is deliberately split so protocol types, wire formats, client and server can be adopted independently. All five are published on NuGet under the MIT licence at 1.0.0.

Package	Use it for	Typical consumer
AGUI.Abstractions	Protocol events, messages, tools, capabilities, interrupts, JSON serialization	Pulled in transitively by client and server
AGUI.Formatting	Event-stream formatter contract and Server-Sent Events support	Anything emitting the wire format
AGUI.Protobuf	Binary event-stream formatting for the proto-supported subset	Bandwidth-sensitive transports
AGUI.Client	HTTP client and an IChatClient implementation for consuming endpoints	A .NET app talking to any AG-UI agent
AGUI.Server	Framework-agnostic adapter from chat streams to AG-UI events	Your ASP.NET Core endpoint

JSON over Server-Sent Events is the full-fidelity event stream. Protobuf covers a subset: the .NET docs note that over protobuf, metadata is a google.protobuf.Struct, so integers beyond 2^53 lose precision and several event types have no protobuf representation at all. Use JSON for archival, protobuf only where the wire cost justifies the narrower surface.

AGUI.Abstractions targets net10.0 through netstandard2.0 and net472, and is AOT-compatible via a source-generated serializer context. The Microsoft post is explicit that you can consume AG-UI from .NET Framework 4.7.2 and later while exposing an endpoint from current .NET — which matters more than it sounds for enterprise application development where the client is older than the service.

How AddAGUIServer and MapAGUIServer fit an ASP.NET Core app

The integration point is IChatClient, the standard chat abstraction from Microsoft.Extensions.AI. Your agent is already one, or wraps one. On the server side, Microsoft shows ToChatRequestContext unpacking the incoming RunAgentInput into messages and options, and AsAGUIEventStreamAsync turning the response stream back into protocol events — emitting RUN_STARTED and RUN_FINISHED around the run, closing open text and reasoning blocks before switching to a different message or tool call, and collapsing multiple interrupts into a single terminal RUN_FINISHED.

That last behaviour is the sort of thing every hand-rolled streaming endpoint gets wrong on the third iteration. Closing blocks correctly when the agent switches mid-stream is not hard; remembering to do it everywhere is.

Microsoft Agent Framework's ASP.NET Core package wraps the same primitives as AddAGUIServer() and MapAGUIServer(), so a hosted agent endpoint is a service registration and a map call. On the client side, AGUIChatClient is itself an IChatClient, so it drops into code that already takes one — and the agent on the other end can be written in Python, TypeScript or C# without your code changing. Agent Framework used to carry its own AG-UI implementation and now depends on the AGUI.* packages instead; the event format is unchanged, so existing frontends keep working against an upgraded backend.

When a plain streaming endpoint is still the right choice

Adopt a protocol when you have more than one thing on each side of it. AG-UI pays when one backend serves several surfaces — web, terminal, mobile, Slack or Teams — or when your frontend must consume agents written in more than one language, or when the agent delegates to subagents, pauses for human approval, or shares state with the UI.

It does not pay for a single chat box in front of a single agent that only streams text. A plain SSE endpoint emitting token deltas is less code, has no protocol version to track, and is genuinely easier to debug. Adding five packages and a typed event vocabulary to serve one TEXT_MESSAGE_CONTENT-shaped stream is ceremony. The honest test is whether you already find yourself inventing event names — tool_started, step_done, awaiting_approval — because that is the moment you have started writing AG-UI badly.

Two limits worth naming. The protocol standardises the event stream, not the transport session: how you handle reconnection, replay and persistence is still yours, which is the same boundary we walked through on servers that no longer need sticky sessions. And a typed stream does not give you memory — what an agent carries across turns is a separate design problem, and we have written about what does not carry over between turns. AG-UI's state events keep the app and the agent in sync during a run; they are not a persistence layer.

If you are building the chat surface itself rather than the protocol underneath it, the trade is different again — a vendor chat UI hands you the frontend and leaves the server to you, which is close to the mirror image of what AG-UI does.

The next decision is small and concrete. Look at your current agent endpoint and count the event names your frontend already switches on. If it is one, leave it alone. If it is five and two of them are ambiguous, add AGUI.Server behind the same route, keep the old one for a release, and let the frontend migrate on its own schedule — the wire compatibility across the C#, TypeScript and Python SDKs is what makes that a low-risk change rather than a rewrite. In the systems we build, that is usually the point where API design and integration work stops being about endpoints and starts being about event contracts.