mech.app

The mech.app newsletter

Agentic AI, minus the noise.

Get practical field notes on AI agents, automation, developer tools and security delivered to your inbox.

No spam. Unsubscribe anytime.

Dev Tools

AG-UI Protocol: How Event-Based Streaming Replaces Request/Response for Agent-to-Frontend Communication

AG-UI defines a bidirectional event protocol that lets any agent framework stream tokens, tool calls, and state updates to any client without custom wir...

Source: github.com
AG-UI Protocol: How Event-Based Streaming Replaces Request/Response for Agent-to-Frontend Communication

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:

  1. Agent-to-client events: token, tool_call, tool_result, state_update, pause, resume, error, done.
  2. Client-to-agent events: user_message, approval, cancellation, state_patch.
  3. Event schema: JSON payloads with a type field and typed data object.

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.

FrameworkIntegration MethodEvent Mapping
LangChainAGUICallbackHandler wraps BaseCallbackHandleron_llm_new_token → token, on_tool_start → tool_call
CrewAIAGUITaskObserver hooks into Task.execute()Task start → state_update, task result → tool_result
MastraAGUIStream wraps agent.run()Native stream events map 1:1 to AG-UI events
Google ADKAGUIPlugin registers as an ADK pluginADK events → AG-UI events via plugin API
Microsoft Agent FrameworkAGUIAdapter implements IActivityHandlerActivity messages → AG-UI events
Pydantic AIAGUIObserver uses Pydantic’s event hooksModel 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:

  1. Event log: Append-only list of all received events, indexed by sequence_id.
  2. Derived UI state: Current message list, tool call status, pending approvals.
  3. 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:

  1. 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.
  2. Long-running servers: The agent runs in a persistent process (Kubernetes pod, ECS task). The client connects directly to the agent’s WebSocket endpoint.
  3. 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

FailureSymptomMitigation
WebSocket drops mid-streamClient stops receiving eventsClient reconnects, sends resume_from with last sequence ID
Agent crashes before emitting doneClient waits indefinitelyClient sets a timeout, emits error event locally
Tool execution hangsAgent emits tool_call but never emits tool_resultAgent sets per-tool timeout, emits error event on timeout
Out-of-order eventsClient receives sequence 5 before sequence 4Client buffers events, processes in sequence order
Checkpoint corruptionClient sends invalid checkpoint IDAgent 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.