Protocol

AG-UI & A2UI Architecture

Two complementary systems power agent-driven UI: AG-UI for streaming communication and A2UI for declarative widget rendering.

Overview

AG-UI Protocol

Transport Layer - How agent and frontend communicate

• NDJSON event streaming
• JSON Patch (RFC 6902) for deltas
• Real-time state synchronization
• Node execution tracking

A2UI Widget System

Payload Layer - What the agent tells UI to render

• Zod-validated widget specs
• Component registry mapping
• Type-safe rendering
• Agent-agnostic patterns

TL;DR: AG-UI is the transport (events, streaming, state sync). A2UI is the payload (what widgets to render).

AG-UI Protocol

AG-UI (Agent-Generated UI Protocol) enables real-time bidirectional communication between agent backends and frontends using NDJSON streaming.

Event Types

type AGUIEventType =
  | 'RUN_STARTED'          // Agent execution begins
  | 'RUN_FINISHED'         // Agent execution completes
  | 'RUN_ERROR'            // Agent execution failed
  | 'STATE_SNAPSHOT'       // Full state sent at start
  | 'STATE_DELTA'          // Incremental update (JSON Patch)
  | 'TEXT_MESSAGE_START'   // Streaming text begins
  | 'TEXT_MESSAGE_CONTENT' // Text chunk
  | 'TEXT_MESSAGE_END'     // Streaming text ends
  | 'TOOL_CALL_START'      // Agent invoking a tool/node
  | 'TOOL_CALL_END';       // Tool/node completed

Event Flow Example

// Agent processes user request...

1. {"type":"RUN_STARTED","runId":"run_abc123"}
2. {"type":"STATE_SNAPSHOT","state":{"persona":"browsing",...}}
3. {"type":"TOOL_CALL_START","toolName":"load_inventory"}
4. {"type":"STATE_DELTA","delta":[{"op":"add","path":"/inventoryContext",...}]}
5. {"type":"TOOL_CALL_END","toolName":"load_inventory","success":true}
6. {"type":"TOOL_CALL_START","toolName":"generate_layout"}
7. {"type":"STATE_DELTA","delta":[{"op":"add","path":"/currentLayout",...}]}
8. {"type":"TOOL_CALL_END","toolName":"generate_layout","success":true}
9. {"type":"RUN_FINISHED","runId":"run_abc123"}

JSON Patch Operations

STATE_DELTA events use RFC 6902 JSON Patch for efficient incremental updates:

// Add a new section to layout
{ "op": "add", "path": "/currentLayout/sections/0", "value": {...} }

// Update agent status
{ "op": "replace", "path": "/agentStatus", "value": "generating" }

// Remove an item
{ "op": "remove", "path": "/refinementHistory/0" }

// Update inventory count
{ "op": "replace", "path": "/inventoryContext/prod_001", "value": 42 }

A2UI Widget System

A2UI (Agent-to-UI) is a declarative widget specification system. Agents return JSON widget specs that describe what to render, and a component registry maps those specs to React components.

Widget Types

product-card

Single product display

product-grid

Grid of products

hero-banner

Full-width featured

magazine-section

Editorial content

comparison-table

Product comparison

gift-collection

Curated gifts

info-banner

Info message

quick-action

Suggested action

Widget Spec Example

// Product Grid Widget Spec
{
  id: "grid_001",
  type: "product-grid",
  productIds: ["prod_001", "prod_002", "prod_003", "prod_004"],
  columns: "3",
  cardVariant: "quick-buy",
  title: "Recommended for You",
  description: "Based on your browsing history"
}

// Hero Banner Widget Spec
{
  id: "hero_001",
  type: "hero-banner",
  headline: "Winter Sale",
  subheadline: "Up to 50% off selected items",
  backgroundStyle: "gradient",
  mood: "energetic",
  featuredProductIds: ["prod_010", "prod_011"],
  ctaText: "Shop Now"
}

How They Work Together

Agent Decision

Agent decides: "Show 3-column product grid with 6 products"

A2UI Widget Spec (Payload)

Creates spec: { type: "product-grid", productIds: [...], columns: "3" }

AG-UI STATE_DELTA (Transport)

Emits: { op: "add", path: "/currentLayout/sections/0", value: {...} }

Frontend Receives & Renders

Applies JSON Patch, looks up product-grid in registry, renders component

Evolution from Custom Data Model

Before A2UI, the "what to render" specification was a custom data model tightly coupled to the merchandiser agent. A2UI extracts this into a reusable pattern.

Aspect	Before (Custom)	After (A2UI)
Coupling	Tightly coupled to merchandiser	Agent-agnostic
Registry	Implicit (switch in renderer)	Explicit component registry
Naming	Domain-specific (grid, hero)	Standardized (product-grid, hero-banner)
Extensibility	Edit schema + renderer	Register new widget type
Reusability	Single use case	Any agent can use

Debug & Visualization Tools

AG-UI includes comprehensive debugging tools for development and demos.

Cmd+Shift+DDebug Panel

Side panel with Events, State, Diff, and Timing tabs

Cmd+Shift+LTimeline

Horizontal timeline showing node execution spans

Cmd+Shift+CConsole

DevTools-style NDJSON log at bottom of page

Cmd+Shift+XClear All

Clear all debug logs and reset state

Try the Demo

Visit the demo page to see all visualization tools in action, including Story Mode for non-technical audiences.

Open Demo Experience

File Reference

AG-UI Files

src/lib/ag-ui/
├── events.ts           # Event type definitions
├── useAGUIAgent.ts     # Consumer hook for AG-UI streams
├── useAGUIDebugger.ts  # Debug event capture hook
└── index.ts            # Module exports

A2UI Files

src/lib/a2ui/
├── widget-specs.ts        # Zod schemas for widget specs
├── component-registry.tsx # Component registration system
└── index.ts               # Module exports

Debug Components

src/components/debug/
├── AGUIDebugProvider.tsx  # Context provider
├── AGUIDebugPanel.tsx     # Side panel
├── AGUITimeline.tsx       # Timeline overlay
├── AGUIConsole.tsx        # Console log
├── DemoSidebar.tsx        # Demo page sidebar
├── AgentGraphView.tsx     # Agent node visualization
├── StateInspector.tsx     # State tree viewer
└── EventList.tsx          # Event list component

Inventory Physics

Tradeoffs & Optimizations