AG-UI Protocol: The Missing Standard for Agent-to-User Communication
This article analyzes the AG-UI protocol for agent-to-user communication, contrasting it with A2A and MCP, detailing its 16 event types across five categories, the critical incremental-snapshot pairing for state synchronization, the necessary adaptation layer between runtime and frontend, capability negotiation, reverse interactions, and practical adoption criteria.
Aligning Key Terms
The article begins by defining core terminology:
AG-UI : An open protocol specifying how an agent backend streams its thoughts, tool calls, and output tokens to the frontend in real time.
A2A : An open protocol for agent-to-agent discovery, task delegation, and handoff.
Host : The shell that carries the conversation: web page, IM, IDE plugin, CLI, etc.
Presentation Layer : How the same answer looks in different hosts.
Adaptation Layer : The layer between runtime and host that translates raw upstream frames into unified events.
Normalized Event : A unified event type after adaptation, regardless of upstream naming.
Incremental Frame : A frame carrying only the new delta (e.g., three more characters).
Snapshot : A frame carrying the complete state up to that point, used for alignment, not display.
Capability Negotiation : The first frame declares which events and incremental modes are supported.
Reverse Interaction : Agent asking the user for confirmation, selection, or authorization.
(Common terms like MCP, SSE, JSON-RPC, WebSocket, DOM are used without explanation.)
01 | Three Protocols, Three Different Segments
AG-UI and A2A are not alternatives; they operate on different segments of the chain. Using a sports broadcast analogy:
Field : Container runtime where model and tool loops execute.
Control Room : Adapts multiple camera feeds into a single program signal.
Program Signal : The outbound stream.
TV / Phone App / Stadium Screen : Three different hosts rendering the same match differently.
Mapping the three protocols to the analogy:
MCP : Tools and data the agent uses — how cameras connect to the equipment library.
A2A : Agent-to-agent collaboration — how two control rooms talk and hand off feeds.
AG-UI : How the agent streams process to the user — the interface the TV uses to receive the signal.
Therefore, asking "AG-UI or A2A?" is the wrong question. One governs internal collaboration, the other external presentation. The real decision factors are: do you have multiple hosts, and do you want others to integrate your agent?
02 | What AG-UI Actually Specifies
AG-UI turns every agent action into a subscribable event; the frontend renders by listening to these events. It defines ~16 events across five categories:
Lifecycle : Run start, run end, error, step start/end — frontend knows when to show spinner and when to stop.
Text Message : Text start, text delta (incremental), text end — typewriter effect.
Tool Call : Call start, arguments delta, call end, result — show user what the agent is doing.
State Management : Full state snapshot, state delta, message history snapshot — re-align after reconnection .
Reasoning : Reasoning start, reasoning delta, reasoning end — separate "thoughts" into their own stream.
The most valuable design—and the one most often missed when building custom protocols—is that incremental frames and snapshots come as a pair .
Incremental frames provide smoothness: each character renders as it arrives.
Snapshots provide alignment: they carry the complete state so that after a disconnect, page refresh, or lost frame, the client can recover in one shot instead of replaying the entire history (expensive in long conversations).
Analogy: slow-motion replay is incremental; the post-match highlight reel is the snapshot. You need both.
// Illustrative TypeScript
// Rule: incremental for smoothness, snapshot for alignment — two separate concerns
type AgentEvent =
| { kind: "textDelta"; id: string; delta: string }
| { kind: "stateSnapshot"; id: string; full: ConversationState }
| { kind: "stateDelta"; id: string; patch: Partial<ConversationState> }
| { kind: "runFinished"; id: string };
function apply(acc: ConversationState, ev: AgentEvent): ConversationState {
if (ev.kind === "stateSnapshot") return ev.full; // snapshot replaces, no merge
if (ev.kind === "stateDelta") return { ...acc, ...ev.patch };
return acc;
}03 | The Real Pipeline: More Than Two Ends
AG-UI only defines the "agent backend to frontend" segment, but a real pipeline often has three stages:
Container Runtime : Emits raw frames: system init, content delta, tool call, tool result, full turn result, error. Events designed for "running the loop", not for "showing to humans".
Server Adaptation Layer : Translates raw frames into unified events; handles upstream duplicates and reordering. Upstream may send full-turn text after deltas — forwarding both duplicates the answer.
Host-Side Parser : Dispatches by frame type to the presentation layer. Each host expresses different capabilities.
Broadcast analogy: raw camera feeds cannot go straight to air. The control room cuts, adds captions, inserts replays — that's the adaptation layer. TV, phone, and stadium screen each render again — that's the presentation layer.
AG-UI defines "control room to TV". The missing "field to control room" segment is where the densest pitfalls live:
Upstream sends incremental deltas, then at the end sends the full turn text . The adapter must remember "already forwarded body for this turn" or the user sees the whole answer repeated.
Two distinct termination types: normal completion vs user stop . Conflating them leaves the frontend waiting forever for a closing frame after a stop.
When upstream result has empty body, the adapter must backfill with the text already forwarded this turn, otherwise the turn renders blank.
AG-UI mentions none of these because it sits downstream.
# Illustrative Python
# Rule: final full text and incremental are mutually exclusive; deduplicate via "turn already forwarded"
class TurnAdapter:
def __init__(self) -> None:
self.saw_text = False
self.answer_text = ""
def on_text_delta(self, chunk: str) -> list[dict]:
self.saw_text = True
self.answer_text += chunk
return [{"kind": "textDelta", "delta": chunk}]
def on_final_result(self, final_text: str) -> list[dict]:
# Upstream already sent deltas — do not forward full text again
if self.saw_text:
return [{"kind": "runFinished"}]
# Upstream result has no body; backfill with accumulated text
return [
{"kind": "textDelta", "delta": final_text or self.answer_text},
{"kind": "runFinished"}
]04 | What We Got Right: Capability Negotiation Upfront & Reverse Interaction as First-Class Events
First: Capability Negotiation in the Very First Frame
Our first frame carries:
Protocol version
Capability list (which events this turn supports)
Text incremental toggle
Reasoning incremental toggle
Value: the host doesn't guess. Third-party embedders know immediately what to listen for; adding a new event later won't break old hosts — they just skip unknown types per the capability list.
Broadcast analogy: pre-show handshake — does this match have slow-mo? Multi-cam? Which subtitle track? The TV decides decoding strategy upfront instead of discovering mid-stream it can't decode.
AG-UI lacks an explicit negotiation frame; it relies on event-type evolution and hosts skipping unknown events. That works, but you cannot know upfront whether a capability is supported — you only find out when you hit it.
Second: Treating "Agent Asks User" as First-Class Events
AG-UI folds reverse interaction mostly into tool-call confirmation. We split it into distinct events:
Question : Agent presents options for user to pick (not free text).
Auth Panel : Step requires user to grant authorization via a panel, not chat input.
Execution Status : Reports "what I'm doing now" with a human-readable hint.
Why split? Because hosts differ wildly in expressiveness . IDE plugins have real dialogs; web has modals; IM can only stuff text into a bubble. A single "ask user" event forces hosts to choose between faking a dialog or degrading to a text blob — exactly the pitfall covered in the dual-host article.
We also model multi-agent collaboration as events: speaker change, task dispatch, lateral handoff, agent finished, whole conversation migration. This is internal, finer-grained than A2A — A2A governs cross-platform agent dialogue; we govern how multiple agents take turns speaking within one conversation and how that process is shown to the user.
AG-UI covers neither, because it assumes a single agent facing the frontend.
05 | Our Real Gap: The Snapshot Pair
This is a genuine functional gap, not a style difference .
In our events, the "incremental" flag lives per event type: text frames carry "I'm incremental", reasoning frames also carry "I'm incremental". There is no generic "here is the complete state so far" mechanism.
Three concrete consequences:
Reconnection relies on full replay. On disconnect, recovery means re-fetching and re-rendering all history. Fine for short chats; noticeable lag in long ones.
"Replace" requires a special flag. Reasoning content sometimes needs full replacement instead of append. We patched by adding a "this frame replaces" flag on reasoning frames. It works, but it's a patch, not a mechanism.
Lost mid-stream frame is unrecoverable. Incremental is cumulative; miss one frame and that segment is gone forever — and the UI shows no sign except slightly fewer characters.
Broadcast analogy: we only ever send slow-mo replays, never the scoreboard. As long as the signal holds, it looks fine; once it drops for three seconds, reconnection leaves you clueless about the score — you wait for the next highlight reel or rewatch from the start.
AG-UI's STATE_SNAPSHOT / STATE_DELTA pair solves exactly this:
Keep sending incrementals, but periodically (or at key points) emit a full state snapshot.
Snapshot application is full replacement , not continued appending, so lost frames don't matter — the next snapshot pulls you back to correct state.
We must add this pair. One critical detail: snapshots must carry a comparable sequence number or version , otherwise you cannot distinguish a fresh snapshot from a stale late-arriving one. Stale snapshots overwriting newer state cause the UI to jump backward — a known issue.
// Illustrative TypeScript
// Rule: snapshot must be able to judge freshness; late stale snapshot must not overwrite newer state
type Snapshot = { seq: number; full: ConversationState };
function mergeSnapshot(current: Snapshot, incoming: Snapshot): Snapshot {
// Drop late stale snapshot, otherwise UI jumps backward
return incoming.seq > current.seq ? incoming : current;
}06 | One Conversation Walk-Through
Stringing the pieces into a timeline with decision points:
Pre-chat (runtime side) : Container ready, connection pre-warmed. (Covered in the first-response article.)
First Frame : Server emits frame with protocol version and capability list. Decision: Host uses capability list to decide which events to listen to; unknown ones skipped.
System Init : Carries conversation ID. Decision: Anchor for "which conversation this turn belongs to"; all subsequent frames hang on it.
Reasoning Stream : Reasoning deltas arrive, may be full replacement. Decision: Replacement flag means full overwrite, not append.
Text Stream : Incremental deltas, typewriter rendering. Decision: Adapter remembers body already forwarded this turn; final full text not forwarded again.
Tool Call & Result : Paired by call ID. Decision: Result may arrive late; UI must show "executing" instead of staying blank.
Artifacts : Generated files go through a separate channel, not the event stream. Decision: Large files in the stream would crowd out text byte budget — the "soup and noodles separate boxes" conclusion from the dual-host article.
Reverse Interaction (may occur): Question, Auth Panel. Decision: Degrade per host capability; hosts without dialogs turn it into a replyable message.
Multi-Agent Collaboration (may occur): Speaker change, dispatch, handoff, agent done. Decision: Each speaker starts a new block; don't mix into one block.
Teardown : Normal completion or user stop — two distinct termination markers. Decision: On stop marker, frontend closes immediately, stops waiting for a closing frame.
The only acceptance criterion: every frame the user sees maps to a specific step in the pipeline. If not, some intermediate layer ate information.
07 | When to Adopt AG-UI, When Not To
Single host (e.g., only IM) : Don't adopt ; custom events are lighter. Protocol value comes from "multiple implementers"; with one implementer it's just constraint.
Multiple proprietary hosts (web + IDE + CLI) : Worth referencing , not mandatory full compliance. Copy its event taxonomy and snapshot mechanism; saves each host defining its own.
Open to third-party integration : Adopt . Third parties won't speak your custom protocol; they speak standards.
Want to plug other agents into your UI : Adopt . AG-UI's strongest use case: swap backend without changing frontend.
Pipeline has gateways and multiple adaptation hops : Adopt, but fill the middle yourself . AG-UI only defines the two ends; the middle hops are out of scope.
Final broadcast verdict: If you only have one TV at home, you don't care about the broadcast standard; but if you're launching a TV network, the standard is your lifeline.
Suggested two-step approach: first, add the incremental + snapshot pair to your own event stream — this is worth doing regardless of protocol adoption, because it solves a real problem. Aligning event names with AG-UI can wait until a third party actually needs to integrate; by then you'll find only names change, not structure.
08 | Four Common Pitfalls
Pitfall 1: Thinking Adopting the Protocol Eliminates the Adaptation Layer
Temptation: Seeing a complete event spec, assume upstream can emit protocol events directly and delete the adapter.
Wrong Fix: Force runtime to output protocol-named events; remove adaptation layer.
Right Fix: Adapter cannot be removed. Upstream events are designed for "running the loop"; protocol events are designed for "showing to humans". The semantics differ; a translation layer is mandatory. The extra hop isn't waste — it's layering.
Pitfall 2: Only Incrementals, No Snapshots
Short conversations work; long conversations and weak networks break: reconnection yields blank UI or full replay taking seconds. We are currently in this state. When adding snapshots, remember two things — snapshots are full replacement , not continued appending, and they must carry a comparable sequence number , otherwise late stale snapshots pull the UI backward.
Pitfall 3: Treating Termination as a Single Type
Normal completion and user stop are different. One version merged them into a single "end" marker; result: user hit stop, frontend kept spinning waiting for a closing frame that never came. Must separate from the start; on stop, frontend closes immediately.
Pitfall 4: Defining Only One "Ask Confirmation" for Reverse Interaction
Sending the same confirmation event to all hosts: dialog-capable hosts can pop up; IM hosts can only drop a "reply yes" text blob. User types "yes" in IM, but the agent wasn't listening for that. Correct approach: branch by declared capability — first frame declares whether this host supports dialogs; if not, downgrade confirmation to an option message from the start, don't wait to remediate after sending.
Summary
AG-UI governs agent-to-human, A2A governs agent-to-agent, MCP governs agent-to-tool — three distinct segments.
The protocol's most valuable design isn't the event catalog, but the "incremental + snapshot" pair: incremental for smoothness, snapshot for alignment.
The real pipeline has more than two ends; the middle adaptation layer is unavoidable, and that's exactly where the protocol has no coverage and the densest pitfalls live.
Capability negotiation in the very first frame beats making hosts guess later.
Reverse interaction must branch by host capability; a single confirmation event guarantees failure on hosts without dialogs.
Single host? Skip the protocol. Opening to third parties or plugging external agents? Adopt when the need is real.
AG-UI fills "how the agent hands process to the human", but the truly hard parts often live in the hops it doesn't cover — who deduplicates incrementals, how many termination types exist, what aligns state after a disconnect.
This is a side note; the main series continues — next up: Container Recycling: Who Gets Recycled, When, and What Happens to the Data .
Follow me, James's Growth Diary, for continuous practical shares to help you take fewer detours in the AI era.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
