AG-UI
4 min read
AG-UI is an open, lightweight, event-based protocol for bidirectional communication between user-facing applications and agent backends. It standardizes how a frontend starts an agent run and receives structured events while that run progresses.
AG-UI addresses one edge of an agent system. It is not the universal event boundary, a workflow engine, an execution ledger, or a learning system.
Protocol position
Section titled “Protocol position”AG-UI sits between the application and the agent runtime:
flowchart LR
U["User-facing application"] <-->|"AG-UI events"| A["Agent backend"]
A <-->|"MCP or native APIs"| T["Tools and data"]
A <-->|"A2A or native protocols"| O["Other agents"]
This separates it from two adjacent protocol concerns:
- MCP connects an agent to tools and data.
- A2A and related protocols connect agents to other agents.
- AG-UI connects an agent backend to a user-facing application.
These protocols may coexist, but they do not replace one another.
Event model
Section titled “Event model”AG-UI uses typed events organized around a few repeatable patterns:
| Category | Purpose | Typical events |
|---|---|---|
| Lifecycle | Mark run and step boundaries | RUN_STARTED, RUN_FINISHED, RUN_ERROR, STEP_STARTED, STEP_FINISHED |
| Messages | Stream assistant text | TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END |
| Tool calls | Stream tool selection and arguments | TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT |
| State | Synchronize application and agent state | STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT |
| Activity | Expose structured work in progress | activity snapshots and deltas |
| Extension | Carry implementation-specific data | RAW, CUSTOM |
Lifecycle events follow a start-to-finish pattern. Messages and tool arguments stream as start, content, and end events. State uses snapshots plus JSON Patch deltas. These structures let a frontend render progress without parsing one unstructured text stream.
The protocol is transport-agnostic. Implementations can carry events over SSE, WebSockets, webhooks, binary HTTP, or another suitable transport.
What AG-UI enables
Section titled “What AG-UI enables”AG-UI gives applications a vendor-neutral contract for several common interaction requirements:
- stream text, activity, and tool calls in real time
- synchronize shared application and agent state
- expose run and step lifecycle to the interface
- carry human input back to the agent
- adapt different agent runtimes behind one client contract
- extend the stream with documented raw or custom events
That contract can reduce custom frontend integration for each agent framework. It also makes agent activity more visible to the user, which supports approval and correction workflows.
What remains outside AG-UI
Section titled “What remains outside AG-UI”AG-UI does not provide several responsibilities that a production agent system still needs:
- Durable execution. The protocol does not persist a workflow, replay history, schedule retries, or resume after a worker crash.
- Exactly-once effects. Event types do not make tool calls idempotent or prevent duplicate writes.
- Authorization. The application must authenticate actors and decide who may approve or resume work.
- Long-term storage. State snapshots and event streams are not substitutes for an Execution Ledger.
- Ambient instrumentation. The protocol does not automatically observe browser clicks, edits, corrections, or final outcomes.
- Learning semantics. It does not decide which user action is a label, how a lesson is scoped, or whether a proposed change passes evaluation.
A product can use AG-UI as one interaction boundary while using a workflow engine for durability, an event or telemetry pipeline for correlation, and a ledger for durable history. It can also choose a different application-to-agent contract entirely.
Relationship to self-learning agents
Section titled “Relationship to self-learning agents”AG-UI can carry part of the evidence needed by Self-Learning Agents: agent lifecycle, messages, tool calls, shared state, and explicit user responses. Custom events can carry product-specific corrections or outcomes when the team defines them.
The product must still instrument those signals deliberately. It must attach run, actor, artifact, consent, and state-version identifiers, then join the protocol stream with the durable execution trace. AG-UI can participate in the boundary. It is not the boundary by definition.