ag-ui-protocol（ag 用户界面协议）

AG-UI Protocol

The Agent-User Interaction (AG-UI) Protocol is an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications.

When to Use This Skill

Use this skill when:

• 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

See the docs/2025-11-27/ directory for complete AG-UI protocol documentation:

• 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

Documentation downloaded from: https://github.com/ag-ui-protocol/ag-ui/tree/main/docs