AG-UI Protocol

When to Use This Skill

• Implementing AG-UI protocol events in your code
• Building agents that communicate with frontends via AG-UI
• Understanding the event types and their structure
• Implementing state management, tool calls, or message streaming
• Debugging AG-UI event flows

Documentation

docs/2025-11-27/

• introduction.md

  - Protocol overview and integrations

• concepts/architecture.md

  - Core architecture and design

• concepts/events.md

  - Event types and patterns

• concepts/messages.md

  - Message structure and types

• concepts/state.md

  - State management and synchronization

• concepts/tools.md

  - Tool definitions and lifecycle

• concepts/agents.md

  - Agent implementation

• concepts/middleware.md

  - Middleware patterns

• concepts/serialization.md

  - Event serialization and compaction

• quickstart/introduction.md

  - Getting started guide

• quickstart/server.md

  - Server implementation

• quickstart/clients.md

  - Client implementation

Quick Reference

Event Types

enum EventType {
  // Lifecycle
  RUN_STARTED = "RUN_STARTED",
  RUN_FINISHED = "RUN_FINISHED",
  RUN_ERROR = "RUN_ERROR",
  STEP_STARTED = "STEP_STARTED",
  STEP_FINISHED = "STEP_FINISHED",

  // Text Messages
  TEXT_MESSAGE_START = "TEXT_MESSAGE_START",
  TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT",
  TEXT_MESSAGE_END = "TEXT_MESSAGE_END",

  // Tool Calls
  TOOL_CALL_START = "TOOL_CALL_START",
  TOOL_CALL_ARGS = "TOOL_CALL_ARGS",
  TOOL_CALL_END = "TOOL_CALL_END",

  // State
  STATE_SNAPSHOT = "STATE_SNAPSHOT",
  STATE_DELTA = "STATE_DELTA",
  MESSAGES_SNAPSHOT = "MESSAGES_SNAPSHOT",

  // Custom
  RAW = "RAW",
  CUSTOM = "CUSTOM",
}

Event Patterns

1. Start-Content-End: Streams content incrementally (text, tool arguments)
2. Snapshot-Delta: State synchronization using complete snapshots + JSON Patch updates
3. Lifecycle: Run monitoring with mandatory start/end events

Message Roles

• user

  - User messages (text and multimodal)

• assistant

  - AI responses (text and tool calls)

• system

  - Instructions or context

• tool

  - Tool execution results

• activity

  - Progress updates

• developer

  - Internal debugging

Tool Definition Structure

interface Tool {
  name: string;           // Unique identifier
  description: string;    // Purpose explanation
  parameters: JSONSchema; // Accepted arguments
}

Tool Call Lifecycle

1. TOOL_CALL_START

   - Initiates with unique ID

2. TOOL_CALL_ARGS

   - Streams JSON arguments

3. TOOL_CALL_END

   - Marks completion

State Synchronization

• STATE_SNAPSHOT - Complete state replacement
• STATE_DELTA - Incremental JSON Patch (RFC 6902) updates

Source