AG-UI Protocol Deep Dive: Event-Driven Architecture, 17 Event Types, and Production Practices

Forum topic · 小凯 · 2026-03-29

Summary

This article provides an in-depth technical breakdown of AG-UI (Agent-User Interaction Protocol), an open, lightweight, event-based protocol launched by the CopilotKit team in May 2025 to standardize real-time communication between AI agents and user interfaces. It covers the protocol's design philosophy (event-driven, streaming-first, framework- and transport-agnostic), its complete set of 17 standard event types across five categories (lifecycle, text message, tool call, state management, and special events), and its state synchronization mechanism built on JSON Patch (RFC 6902) and event sourcing. The post compares AG-UI with MCP (Anthropic) for tool access and A2A (Google) for agent-to-agent collaboration, positioning AG-UI as the agent-to-UI layer of the emerging agent protocol stack. It includes production-ready code examples in Python/FastAPI, TypeScript, and React, covering SSE/WebSocket transports, human-in-the-loop workflows, performance optimization (event batching, delta merging, sub-100ms first-token latency), and security practices such as event validation and sensitive data redaction.

Overview

AG-UI (Agent-User Interaction Protocol) is an open, lightweight, event-based protocol for standardizing real-time communication between AI agents and user interfaces. It was initiated and open-sourced by the CopilotKit team in May 2025.

Key points

Design principles: event-driven (all communication via events, not request-response), streaming-first (latency under ~100ms), "state as stream" (state changes propagate via event streams), framework-agnostic, and transport-agnostic (SSE, WebSocket, HTTP/2).
Positioning in the agent protocol stack:
MCP (Anthropic): Agent ↔ tools/data
A2A (Google): Agent ↔ Agent collaboration
AG-UI (CopilotKit): Agent ↔ user interface
Event envelope: every event carries protocol, type, timestamp, runId, threadId, payload, and optional extensions.

The 17 standard event types

Divided into five categories:

1. Lifecycle events: RUN_STARTED, STEP_STARTED, STEP_FINISHED, RUN_FINISHED, RUN_ERROR — for progress tracking, loading states, and error handling. 2. Text message events: TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END — token-level streaming output. 3. Tool call events: TOOL_CALL_START, TOOL_CALL_ARGS (streamed deltas), TOOL_CALL_END, TOOL_CALL_RESULT — full visibility into agent tool usage in the UI. 4. State management events: STATE_SNAPSHOT (full snapshot), STATE_DELTA (JSON Patch increments), MESSAGES_SNAPSHOT (conversation history) — the protocol's most distinctive design. 5. Special events: HUMAN_IN_THE_LOOP / INTERRUPT, HUMAN_RESPONSE, CUSTOM (e.g., agent handoffs), RAW (passthrough for third-party integration).

State synchronization: JSON Patch + Event Sourcing

Incremental state uses JSON Patch (RFC 6902) with operations like replace, add, remove, move, and test. Compared to full snapshots, this reduces bandwidth (reported ~92% savings in a genome-alignment use case), lowers latency, supports offline patch queues, and enables audit trails.
State management borrows from event sourcing: current state = fold of all events, enabling time-travel debugging, Google Docs-style collaborative editing, and offline-first apps.
Frontend pattern: apply STATE_SNAPSHOT to reset state, apply STATE_DELTA via a JSON Patch library (e.g., fast-json-patch), and support time travel by replaying the event log.

Transport layer

SSE is the recommended transport (HTTP-based, built-in auto-reconnect, firewall-friendly, low complexity); WebSocket suits bidirectional high-frequency scenarios; HTTP long-polling serves as a fallback.
Reference backend implementation uses FastAPI StreamingResponse with media_type="text/event-stream", encoding events through the AG-UI EventEncoder.

AG-UI vs MCP vs A2A (vs A2UI)

| Dimension | AG-UI | MCP | A2A | |---|---|---|---| | Origin | CopilotKit (2025) | Anthropic (2024) | Google (2025) | | Core problem | Agent ↔ UI interaction | Agent ↔ tools/data | Agent ↔ Agent | | Communication | One-way event stream | Request-response | Request-response + push | | Transport | SSE/WebSocket/HTTP | stdio/SSE/HTTP | HTTP/SSE | | State | Event sourcing | Stateless | Stateful tasks |

The protocols are complementary, not competing: use AG-UI for UI interaction, MCP for tool/API access, A2A for multi-agent orchestration — or all three together. Note also A2UI (Google), a UI-description spec ("what to show", analogous to HTML) that AG-UI ("how to transport", analogous to HTTP) can carry in its payload.

Implementation highlights

Minimal example: FastAPI backend streams RUN_STARTED → TEXT_MESSAGE_START → token-level TEXT_MESSAGE_CONTENT → TEXT_MESSAGE_END → RUN_FINISHED; a React frontend consumes it via an useAGUI hook.
Framework integration: LangGraph nodes emit STEP_STARTED/STEP_FINISHED and STATE_DELTA events as planning/execution progresses.
Human-in-the-loop: agent emits an interrupt event, awaits a response via a keyed asyncio.Future with timeout, then resumes execution.
Error handling: wrap execution in a context manager that emits RUN_ERROR with error code, message, and a recoverable flag.

Performance and security best practices

Targets: first-token latency <100ms, per-event frontend handling <10ms, 90%+ bandwidth reduction vs snapshots, 10K+ concurrent connections per server.
Optimizations: batch small token chunks (e.g., flush every 5 tokens or 50ms), gzip+base64 compress large snapshots, merge high-frequency state deltas in a batcher, reuse frontend connections via a pool.
Security: validate event types (e.g., Pydantic validator), rate-limit event emission, and redact sensitive keys (password, token, secret, api_key) from event payloads.