AG-UI Explained: The Protocol That Connects AI Agents to Your Frontend
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:
- 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:
- Client - your frontend. It uses something like
HttpAgentfrom@ag-ui/client, or a higher-level library such as CopilotKit. - Agent backend - any agent framework (LangGraph, CrewAI, Mastra, Pydantic AI, Google ADK, and so on) or your own code.
- 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_ERRORSTEP_STARTED,STEP_FINISHED(for multi-step agents, useful for progress indicators)
Text message events:
These follow a start, content, end pattern:
TEXT_MESSAGE_STARTwithmessageIdandrole: "assistant"TEXT_MESSAGE_CONTENTwithmessageIdand adelta(a chunk of text)TEXT_MESSAGE_ENDwithmessageId
Tool call events:
Same pattern, with arguments streamed as JSON fragments:
TOOL_CALL_STARTwithtoolCallIdandtoolCallNameTOOL_CALL_ARGSwithtoolCallIdand adeltaTOOL_CALL_ENDwithtoolCallIdTOOL_CALL_RESULTwithmessageId,toolCallId, andcontent
State events:
STATE_SNAPSHOTsends the full state object.STATE_DELTAsends only the changes, as an array of JSON Patch (RFC 6902) operations.MESSAGES_SNAPSHOTsends the full message history, useful for resyncing.
Everything else:
REASONING_*events for streaming model reasoning separately from the answer.ACTIVITY_SNAPSHOTandACTIVITY_DELTAfor structured progress or activity UI.CUSTOM(withnameandvalue) for application-specific events.RAWfor 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:
onMessagesChangedandonStateChanged, 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:
- The client sends a run with a frontend tool, for example
confirmPurchase. - The agent decides to call it and streams
TOOL_CALL_START,TOOL_CALL_ARGS,TOOL_CALL_END. - The frontend executes the tool. This can be anything, including showing a dialog and waiting for the user to click "Approve."
- 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:
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.
Read the docs, especially the events and types reference for your SDK language. 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 wor
Comments
No comments yet. Start the discussion.