If you have built a chat UI on top of an AI agent, you have probably written the same glue code more than once: parse a custom stream format, figure out when a tool call starts and ends, keep some piece of state in sync between the backend and the browser, and then rewrite all of it when you switch agent frameworks.

AG-UI (Agent-User Interaction Protocol) exists to remove that glue code. It is an open, MIT-licensed, event-based protocol that standardizes how an agent backend talks to a user-facing application.

This article covers what you actually need to know to use it: the mental model, the request and event formats, a minimal server and client, and the gotchas that are easy to miss.

The one-paragraph summary

Your frontend sends a single POST request describing the conversation (messages, state, available frontend tools, context). Your agent responds with a stream of typed JSON events: run lifecycle, streamed text, streamed tool calls, and state updates. Any frontend that understands those events can talk to any backend that emits them. That is the whole idea.

Where AG-UI fits next to MCP and A2A

There are now several "agent protocols," and it helps to know which problem each one solves:

Protocol Connects Purpose
MCP Agent to tools and data Gives agents access to tools and resources
A2A Agent to agent Lets agents communicate with each other
AG-UI Agent to user-facing app Streams agent activity into a UI and takes user input back

They are complementary, not competing. A single agent might use MCP to call tools, A2A to delegate to another agent, and AG-UI to show all of that to a user.

The mental model

There are three pieces:

  1. Client - your frontend. It uses something like HttpAgent from @ag-ui/client, or a higher-level library such as CopilotKit.
  2. Agent backend - any agent framework (LangGraph, CrewAI, Mastra, Pydantic AI, Google ADK, and so on) or your own code.
  3. Transport - how events travel. The reference implementation uses HTTP with Server-Sent Events (SSE), but the protocol is transport-agnostic. WebSockets, webhooks, or a binary Protocol Buffers encoding also work.

Each interaction is called a run. Runs belong to a thread (a conversation).

  • threadId stays the same for the whole conversation.
  • runId is new for every request.

The request: RunAgentInput

Every run starts with the client sending a RunAgentInput as the body of a POST request:

type RunAgentInput = { threadId: string // conversation ID, stable across runs runId: string // unique per run parentRunId?: string // optional, for branching state: any // shared app state the agent can read messages: Message[] // conversation history tools: Tool[] // tools the FRONTEND can execute context: Context[] // extra info: { description, value } forwardedProps: any // anything else you want to pass through } 

Two fields deserve attention:

  • tools are tools provided by the client for this run. Backend tools (database queries, API calls) stay configured in your agent. Frontend tools are things only the UI can do: open a modal, ask the user to confirm, read the current selection.
  • context is a simple way to give the agent information about what the user is looking at, without stuffing it into a message.

The response: a stream of events

The backend replies with a stream of events. Every event has a type, plus optional timestamp, rawEvent, and metadata. The events fall into a handful of groups.

Lifecycle events

  • RUN_STARTED, RUN_FINISHED, RUN_ERROR
  • STEP_STARTED, STEP_FINISHED (for multi-step agents, useful for progress indicators)

Text message events

These follow a start, content, end pattern:

  • TEXT_MESSAGE_START with messageId and role: "assistant"
  • TEXT_MESSAGE_CONTENT with messageId and a delta (a chunk of text)
  • TEXT_MESSAGE_END with messageId

Tool call events

Same pattern, with arguments streamed as JSON fragments:

  • TOOL_CALL_START with toolCallId and toolCallName
  • TOOL_CALL_ARGS with toolCallId and a delta
  • TOOL_CALL_END with toolCallId
  • TOOL_CALL_RESULT with messageId, toolCallId, and content

State events

  • STATE_SNAPSHOT sends the full state object.
  • STATE_DELTA sends only the changes, as an array of JSON Patch (RFC 6902) operations.
  • MESSAGES_SNAPSHOT sends the full message history, useful for resyncing.

Everything else

  • REASONING_* events for streaming model reasoning separately from the answer.
  • ACTIVITY_SNAPSHOT and ACTIVITY_DELTA for structured progress or activity UI.
  • CUSTOM (with name and value) for application-specific events.
  • RAW for passing through events from an external system untouched.

You do not need all of these on day one. A working chat needs only five: RUN_STARTED, TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END, and RUN_FINISHED.

What it looks like on the wire

With SSE, a simple "Hello world" run is just this:

data: {"type":"RUN_STARTED","threadId":"t1","runId":"r1"} data: {"type":"TEXT_MESSAGE_START","messageId":"m1","role":"assistant"} data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"Hello "} data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"world!"} data: {"type":"TEXT_MESSAGE_END","messageId":"m1"} data: {"type":"RUN_FINISHED","threadId":"t1","runId":"r1"} 

Readable, debuggable with curl, and easy to produce from any language.

A minimal AG-UI server in Python

Install the Python SDK:

pip install ag-ui-protocol fastapi uvicorn 

Then write an endpoint that accepts RunAgentInput and streams events back:

import uuid from fastapi import FastAPI, Request from fastapi.responses import StreamingResponse from ag_ui.core import ( RunAgentInput, EventType, RunStartedEvent, RunFinishedEvent, RunErrorEvent, TextMessageStartEvent, TextMessageContentEvent, TextMessageEndEvent, ) from ag_ui.encoder import EventEncoder app = FastAPI() @app.post("/agent") async def run_agent(input_data: RunAgentInput, request: Request): # The encoder picks the output format based on the Accept header encoder = EventEncoder(accept=request.headers.get("accept")) async def event_stream(): yield encoder.encode(RunStartedEvent( type=EventType.RUN_STARTED, thread_id=input_data.thread_id, run_id=input_data.run_id, )) try: message_id = str(uuid.uuid4()) yield encoder.encode(TextMessageStartEvent( type=EventType.TEXT_MESSAGE_START, message_id=message_id, role="assistant", )) # Replace this loop with tokens from your LLM for chunk in ["Hello ", "from ", "AG-UI!"]: yield encoder.encode(TextMessageContentEvent( type=EventType.TEXT_MESSAGE_CONTENT, message_id=message_id, delta=chunk, )) yield encoder.encode(TextMessageEndEvent( type=EventType.TEXT_MESSAGE_END, message_id=message_id, )) yield encoder.encode(RunFinishedEvent( type=EventType.RUN_FINISHED, thread_id=input_data.thread_id, run_id=input_data.run_id, )) except Exception as e: yield encoder.encode(RunErrorEvent( type=EventType.RUN_ERROR, message=str(e), )) return StreamingResponse(event_stream(), media_type=encoder.get_content_type()) 

Run it with uvicorn main:app --reload.

Note that the Python SDK uses snake_case (thread_id, message_id) but serializes to camelCase on the wire, so a JavaScript client sees threadId and messageId.

In practice, you often will not write this by hand. Many frameworks ship adapters that emit AG-UI events for you. Pydantic AI, for example, can expose an agent as an AG-UI endpoint directly, and LangGraph has the @ag-ui/langgraph adapter.

A minimal client in TypeScript

Install the client:

npm install @ag-ui/client 

Connect to the server and subscribe to events:

import { HttpAgent } from "@ag-ui/client" const agent = new HttpAgent({ url: "http://localhost:8000/agent", // headers: { Authorization: "Bearer ..." }, }) agent.addMessage({ id: crypto.randomUUID(), role: "user", content: "Say hello", }) await agent.runAgent( {}, { onTextMessageContentEvent({ event }) { process.stdout.write(event.delta) }, onToolCallStartEvent({ event }) { console.log(`\n[tool] ${event.toolCallName}`) }, onStateChanged({ state }) { console.log("\n[state]", state) }, onRunFailed({ error }) { console.error("Run failed:", error) }, } ) 

Notice what you did not have to do: parse SSE lines, buffer partial JSON for tool arguments, apply state patches, or track message history. HttpAgent handles that and keeps agent.messages and agent.state up to date.

The subscriber gives you hooks at two levels:

  • Event-level: onTextMessageContentEvent, onToolCallStartEvent, onToolCallArgsEvent, onToolCallEndEvent, onToolCallResultEvent, onStateSnapshotEvent, onStateDeltaEvent, onCustomEvent, and more.
  • High-level: onMessagesChanged and onStateChanged, which fire after the client has applied the changes. These are usually what you want for rendering.

You can attach a subscriber for a single run (as above) or permanently with agent.subscribe(subscriber), which returns an object with unsubscribe().

Shared state: the feature that makes agents feel native

Chat is only part of an agent UI. Often the agent is editing something the user can see: a document, a form, a trip itinerary, a list of search results. AG-UI handles this with bi-directional shared state.

The client sends the current state in RunAgentInput. The agent sends updates back. For large state, sending the whole object on every change is wasteful, so you send a snapshot once and then deltas:

{ "type": "STATE_SNAPSHOT", "snapshot": { "itinerary": { "city": "Lisbon", "days": [] } } } 
{ "type": "STATE_DELTA", "delta": [ { "op": "add", "path": "/itinerary/days/-", "value": { "title": "Old town walk" } } ] } 

The client applies the patch and fires onStateChanged, so your UI re-renders with the new day added while the agent is still working.

Frontend tools and human-in-the-loop

This is the part that is easiest to overlook and most useful in practice.

When the client lists a tool in tools, it is saying "I can run this, in the browser." The flow is:

  1. The client sends a run with a frontend tool, for example confirmPurchase.
  2. The agent decides to call it and streams TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END.
  3. The frontend executes the tool. This can be anything, including showing a dialog and waiting for the user to click "Approve."
  4. The frontend adds the result as a tool message and starts a new run. The agent continues from there.
const confirmPurchase = { name: "confirmPurchase", description: "Ask the user to approve a purchase before it is placed", parameters: { type: "object", properties: { item: { type: "string" }, price: { type: "number" }, }, required: ["item", "price"], }, } await agent.runAgent({ tools: [confirmPurchase] }) 

This gives you human-in-the-loop approval without any special protocol extension. The pause is just a tool call that the UI resolves.

Things that are easy to get wrong

Pair your start and end events. Every TEXT_MESSAGE_START needs a matching TEXT_MESSAGE_END with the same messageId. The same applies to tool calls and toolCallId. Clients rely on this pairing to know when a message is complete.

Do not send empty deltas. TEXT_MESSAGE_CONTENT.delta must be a non-empty string. Filter out empty chunks from your LLM stream before emitting them.

Tool arguments are streamed as string fragments. Each TOOL_CALL_ARGS.delta is a piece of a JSON string, not a parsed object. Only after TOOL_CALL_END do you have complete, parseable arguments. The client SDK handles the buffering if you use it.

Always end a run. Emit RUN_FINISHED on success or RUN_ERROR on failure. A stream that just stops leaves the UI spinning.

Keep threadId stable. Generate it once per conversation and reuse it. Generate a fresh runId per request. If you mix these up, server-side session handling and debugging tools get confused.

Know which side owns each tool. Backend tools are configured in the agent and never appear in RunAgentInput.tools. Frontend tools are sent by the client per run. Mixing these up is a common source of "the agent called a tool nobody implemented."

Use snapshots to recover. If a client reconnects or gets out of sync, STATE_SNAPSHOT and MESSAGES_SNAPSHOT let the server reset it to a known-good state instead of trying to replay every delta.

Consider the binary encoding for heavy traffic. The encoder supports content negotiation. Clients that send Accept: application/vnd.ag-ui.event+proto get Protocol Buffers instead of JSON over SSE, and it falls back to SSE when that is not supported.

Ecosystem: what already speaks AG-UI

You may not need to build an adapter yourself. According to the repository, integrations exist for:

  • Agent frameworks: LangGraph, CrewAI, Microsoft Agent Framework, Google ADK, AWS Strands Agents, Mastra, Pydantic AI, Agno, LlamaIndex, AG2, and community integrations such as the Claude Agent SDK and Langroid. Others, including the OpenAI Agent SDK and Cloudflare Agents, are in progress.
  • Protocols and platforms: A2A, Amazon Bedrock AgentCore, Oracle Agent Spec, and MCP Apps for generative UI.
  • SDKs: TypeScript and Python as the core, plus Kotlin, Go, Dart, Java, Rust, Ruby, C++, and .NET.
  • Clients: CopilotKit, terminal clients, React Native, and chat platforms such as Slack and Microsoft Teams.

Check the repository README for the current list, since it changes often.

Getting started

The fastest path is the scaffolding command:

npx create-ag-ui-app my-agent-app 

Then:

  1. Open the AG-UI Dojo. It has small, focused examples (roughly 50 to 200 lines each) for agentic chat, shared state, generative UI, and human-in-the-loop, across many frameworks. Reading the source of one Dojo example is the quickest way to see a real event flow.
  2. Read the docs, especially the events and types reference for your SDK language.
  3. If you are writing your own backend, start with the five core events above, test with curl -N, and add tool calls and state once text streaming works.

Closing:
If your team maintains more than one agent UI, or expects to change agent frameworks, standardizing on AG-UI now will save you a lot of rework later.

Links