Agents stream tokens, pause for tool calls, spawn subagents, and wait for human input. Traditional request/response patterns break under this workload. Every agent framework (LangChain, CrewAI, Mastra, Google ADK, Microsoft Agent Framework, Pydantic AI) implements its own streaming format, and every frontend team writes custom adapters to consume it.
AG-UI is a bidirectional event protocol that standardizes agent-to-client communication. The agent emits typed events (token deltas, tool invocations, state transitions, human-in-the-loop pauses), and any client (web, mobile, terminal, Slack) can render them without knowing which framework produced the agent. The same agent can power multiple surfaces without rewiring.
The protocol has 19,683 GitHub stars and is trending #1 for TypeScript. It ships as @ag-ui/core on npm and ag-ui-protocol on PyPI.
Why Agents Break Request/Response
A typical REST or GraphQL call expects one request and one response. Agents produce a stream of partial outputs:
- Token streaming: LLM responses arrive token by token.
- Mid-stream tool calls: The agent pauses generation, invokes a tool, resumes with the result.
- State updates: Shared context (conversation history, user preferences, session metadata) changes during execution.
- Human-in-the-loop pauses: The agent blocks until the user approves a destructive action or provides missing input.
- Subagent spawning: A parent agent delegates a subtask to a child agent, which emits its own event stream.
Each framework handles this differently. LangChain uses StreamingStdOutCallbackHandler and custom event schemas. CrewAI emits task updates via a proprietary callback system. Mastra has its own streaming API. Clients that support multiple frameworks end up with a branching adapter layer that translates each format into a common UI state model.
AG-UI eliminates the adapter layer by defining a canonical event set that all frameworks can emit.
Protocol Architecture
AG-UI is a typed event stream over WebSocket, Server-Sent Events, or any bidirectional transport. The protocol defines:
- Agent-to-client events:
token,tool_call,tool_result,state_update,pause,resume,error,done. - Client-to-agent events:
user_message,approval,cancellation,state_patch. - Event schema: JSON payloads with a
typefield and typeddataobject.
Event Flow for a Tool-Calling Agent
Client Agent
| |
|--- user_message: "Book a flight to SFO" --->|
| |
|<--- token: "I'll search for flights" -------|
|<--- token: " to San Francisco" -------------|
|<--- tool_call: search_flights(SFO) ---------|
| | (agent pauses)
|<--- pause: awaiting_tool_result ------------|
| | (tool executes)
|<--- tool_result: [{flight: UA123}] ---------|
|<--- token: "Found UA123 for $450" ----------|
|<--- pause: awaiting_approval ---------------|
| |
|--- approval: {confirmed: true} ------------->|
| |
|<--- token: "Booking confirmed" -------------|
|<--- done -----------------------------------|
The client does not need to know whether the agent is built with LangChain or Mastra. It subscribes to the event stream and updates the UI when events arrive.
Handling Out-of-Order Events and Reconnection
AG-UI events carry a sequence_id field. Clients maintain a local event log and discard duplicates. If the WebSocket drops, the client reconnects and sends a resume_from message with the last received sequence ID. The agent replays missed events from its own event log.
For long-running agents, the protocol supports checkpointing. The agent emits a checkpoint event with a serialized state snapshot. The client stores the checkpoint in IndexedDB or local storage. On reconnection, the client sends the checkpoint ID, and the agent resumes from that point without replaying the entire history.
Framework Integration Points
AG-UI provides adapters for six frameworks. Each adapter translates framework-specific callbacks into AG-UI events.
| Framework | Integration Method | Event Mapping |
|---|---|---|
| LangChain | AGUICallbackHandler wraps BaseCallbackHandler | on_llm_new_token → token, on_tool_start → tool_call |
| CrewAI | AGUITaskObserver hooks into Task.execute() | Task start → state_update, task result → tool_result |
| Mastra | AGUIStream wraps agent.run() | Native stream events map 1:1 to AG-UI events |
| Google ADK | AGUIPlugin registers as an ADK plugin | ADK events → AG-UI events via plugin API |
| Microsoft Agent Framework | AGUIAdapter implements IActivityHandler | Activity messages → AG-UI events |
| Pydantic AI | AGUIObserver uses Pydantic’s event hooks | Model validation → state_update, tool call → tool_call |
The adapter layer is thin. Most frameworks already emit structured events internally; the adapter just renames fields and adds sequence IDs.
Code Example: LangChain Adapter
from langchain.callbacks.base import BaseCallbackHandler
from ag_ui_protocol import AGUIEmitter
class AGUICallbackHandler(BaseCallbackHandler):
def __init__(self, emitter: AGUIEmitter):
self.emitter = emitter
self.sequence = 0
def on_llm_new_token(self, token: str, **kwargs):
self.emitter.emit({
"type": "token",
"sequence_id": self.sequence,
"data": {"delta": token}
})
self.sequence += 1
def on_tool_start(self, tool: str, input_str: str, **kwargs):
self.emitter.emit({
"type": "tool_call",
"sequence_id": self.sequence,
"data": {"tool": tool, "input": input_str}
})
self.sequence += 1
def on_tool_end(self, output: str, **kwargs):
self.emitter.emit({
"type": "tool_result",
"sequence_id": self.sequence,
"data": {"output": output}
})
self.sequence += 1
The client subscribes to the emitter’s WebSocket endpoint and renders events as they arrive.
Client-Side State Management
AG-UI clients maintain three state buckets:
- Event log: Append-only list of all received events, indexed by
sequence_id. - Derived UI state: Current message list, tool call status, pending approvals.
- Checkpoint snapshots: Periodic serialized states for fast recovery.
When a token event arrives, the client appends the delta to the current message. When a tool_call event arrives, the client renders a “Tool executing…” indicator. When a pause event arrives with reason: awaiting_approval, the client shows an approval button.
The protocol does not dictate UI behavior. It only defines the event schema. One client might render tool calls as collapsible cards; another might show a terminal-style log.
Handling Subagent Spawning
When a parent agent spawns a subagent, it emits a subagent_start event with a subagent_id. Subsequent events from the subagent carry the same subagent_id in their metadata. The client can nest the subagent’s UI under the parent’s message or render it in a separate pane.
When the subagent completes, the parent emits a subagent_done event. The client merges the subagent’s final output into the parent’s message thread.
Security Boundaries
AG-UI does not define authentication or authorization. It assumes the transport layer (WebSocket, SSE) is already secured with TLS and bearer tokens.
The protocol does include a user_id field in client-to-agent events. The agent can use this to enforce per-user rate limits, access control, or audit logging. The client must not trust the user_id field; the server should validate it against the session token.
For multi-tenant deployments, the agent should namespace event logs and checkpoints by tenant_id. This prevents one tenant from resuming another tenant’s session.
Observability and Debugging
AG-UI events are structured JSON. You can pipe them to any log aggregator (Datadog, Grafana Loki, CloudWatch) without custom parsing.
For debugging, the protocol defines a debug event type. Agents can emit debug events with stack traces, intermediate reasoning steps, or tool execution timings. Clients can toggle a debug panel that renders these events.
The event log also serves as a replay buffer. If a user reports a bug, you can export the event log, replay it in a local client, and reproduce the exact UI state.
Deployment Shapes
AG-UI supports three deployment patterns:
- Serverless functions: The agent runs in a Lambda or Cloud Function. The client opens a WebSocket to an API Gateway, which proxies events to the function. The function emits events via a streaming response.
- Long-running servers: The agent runs in a persistent process (Kubernetes pod, ECS task). The client connects directly to the agent’s WebSocket endpoint.
- Edge workers: The agent runs in a Cloudflare Worker or Vercel Edge Function. The client connects via SSE, and the worker streams events over HTTP.
For serverless deployments, you need a durable event log. The agent writes events to DynamoDB or S3, and the client polls for new events. This adds latency but avoids keeping the function alive for the entire session.
Failure Modes
| Failure | Symptom | Mitigation |
|---|---|---|
| WebSocket drops mid-stream | Client stops receiving events | Client reconnects, sends resume_from with last sequence ID |
Agent crashes before emitting done | Client waits indefinitely | Client sets a timeout, emits error event locally |
| Tool execution hangs | Agent emits tool_call but never emits tool_result | Agent sets per-tool timeout, emits error event on timeout |
| Out-of-order events | Client receives sequence 5 before sequence 4 | Client buffers events, processes in sequence order |
| Checkpoint corruption | Client sends invalid checkpoint ID | Agent rejects checkpoint, forces full replay from sequence 0 |
The protocol does not define retry semantics. Clients and agents must implement exponential backoff and circuit breakers themselves.
When to Use AG-UI
Use AG-UI when:
- You build agents with multiple frameworks and want one client codebase.
- You need to expose the same agent via web, mobile, Slack, and terminal.
- You want structured event logs for debugging and compliance.
- You need human-in-the-loop pauses without polling.
Avoid AG-UI when:
- Your agent is a simple chatbot with no tool calls or state updates. A basic SSE stream is simpler.
- You control both the agent and the client and can use a custom protocol.
- You need sub-100ms latency. The event schema adds serialization overhead.
- Your agent emits thousands of events per second. The protocol is designed for human-scale interactions, not high-frequency data streams.
Technical Verdict
AG-UI solves the impedance mismatch between streaming agent execution and frontend rendering. It is a good fit for multi-framework deployments, multi-surface clients, and teams that want to avoid custom adapter layers. The protocol is young (launched in 2026), so expect breaking changes in the event schema as the community converges on best practices.
The main risk is fragmentation. If frameworks add custom event types outside the spec, clients will need adapters again. The protocol needs governance to prevent this.
For production deployments, pair AG-UI with a durable event log (Kafka, DynamoDB Streams) and a replay mechanism. The protocol assumes reliable delivery, but networks are not reliable.