AG-UI Protocol

Overview

While MCP connects agents to tools and A2A enables agent-to-agent communication, AG-UI addresses the user-facing layer: how do agents interact with humans through modern applications?

AG-UI streams structured events between agent backends and frontends, enabling rich, interactive experiences.

The Protocol Stack

┌─────────────────────────────────────────┐
│           User Interface (AG-UI)        │
└────────────────────┬────────────────────┘
                     │
┌────────────────────┴────────────────────┐
│              Agent Backend              │
├─────────────────┬───────────────────────┤
│   Tools (MCP)   │   Other Agents (A2A)  │
└─────────────────┴───────────────────────┘

Core Event Types (~17 total)

Message Events

• TEXT_MESSAGE_START: Begin streaming
• TEXT_MESSAGE_CONTENT: Token chunks
• TEXT_MESSAGE_END: Complete message

Tool Events

• TOOL_CALL: Request tool execution
• TOOL_RESULT: Return results

State Events

• STATE_DELTA: Incremental patches
• STATE_SNAPSHOT: Full sync

Control Events

• INTERRUPT: Pause for user confirmation
• ERROR: Report failures
• LIFECYCLE: Start/stop signals

Key Features

Real-Time Streaming

Tokens stream as generated. Works over SSE, WebSockets, or webhooks.

Shared State

Using STATE_DELTA, agents and frontends stay synchronized with minimal data transfer.

Human-in-the-Loop

The INTERRUPT event enables safety-critical patterns:

{
  "type": "INTERRUPT",
  "action": "delete_all_records",
  "message": "Are you sure?",
  "options": ["approve", "deny"]
}

Framework Support

First-party integrations:

• Microsoft Agent Framework
• Google ADK
• AWS Strands Agents
• LangGraph
• CrewAI

Adoption

• 619K+ Python downloads/week
• 178K+ JavaScript downloads/week
• Oracle adopted for Agent Spec

When to Use AG-UI

Use AG-UI for:

• Chat interfaces with streaming
• Collaborative AI editing
• Human-in-the-loop workflows
• Real-time dashboards

Don't use AG-UI for:

• Backend orchestration (use A2A)
• Tool calling (use MCP)

// React AG-UI Integration
import { useAgent } from '@ag-ui/react';

function ChatInterface() {
  const { messages, sendMessage, interrupt } = useAgent({
    endpoint: '/api/agent',
    onInterrupt: async (action) => {
      const approved = await showConfirmation(action);
      return approved ? 'approve' : 'deny';
    }
  });

  return (
    <div>
      {messages.map(msg => (
        <Message key={msg.id} content={msg.content} />
      ))}
      <Input onSubmit={sendMessage} />
      {interrupt && <InterruptDialog action={interrupt} />}
    </div>
  );
}