ag-ui-protocol

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AG-UI Protocol

AG-UI协议

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

Agent-User Interaction（AG-UI）协议是一种开源、轻量的基于事件的协议，用于规范AI Agent与用户应用之间的连接方式。

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

在以下场景中使用本技能：

在代码中实现AG-UI协议事件
构建通过AG-UI与前端通信的Agent
理解事件类型及其结构
实现状态管理、工具调用或消息流式传输
调试AG-UI事件流

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

完整的AG-UI协议文档请查看

docs/2025-11-27/

```
introduction.md
```
- 协议概述与集成指南
```
concepts/architecture.md
```
- 核心架构与设计
```
concepts/events.md
```
- 事件类型与模式
```
concepts/messages.md
```
- 消息结构与类型
```
concepts/state.md
```
- 状态管理与同步
```
concepts/tools.md
```
- 工具定义与生命周期
```
concepts/agents.md
```
- Agent实现方案
```
concepts/middleware.md
```
- 中间件模式
```
concepts/serialization.md
```
- 事件序列化与压缩
```
quickstart/introduction.md
```
- 快速入门指南
```
quickstart/server.md
```
- 服务端实现教程
```
quickstart/clients.md
```
- 客户端实现教程

Quick Reference

快速参考

Event Types

事件类型

typescript

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",
}

typescript

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

事件模式

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

Start-Content-End：增量流式传输内容（文本、工具参数）
Snapshot-Delta：使用完整快照+JSON Patch更新实现状态同步
Lifecycle：通过强制的开始/结束事件监控运行状态

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

```
user
```
- 用户消息（文本与多模态）
```
assistant
```
- AI响应（文本与工具调用）
```
system
```
- 指令或上下文信息
```
tool
```
- 工具执行结果
```
activity
```
- 进度更新
```
developer
```
- 内部调试信息

Tool Definition Structure

工具定义结构

typescript

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

typescript

interface Tool {
  name: string;           // 唯一标识符
  description: string;    // 用途说明
  parameters: JSONSchema; // 接受的参数
}

Tool Call Lifecycle

工具调用生命周期

```
TOOL_CALL_START
```
- Initiates with unique ID
```
TOOL_CALL_ARGS
```
- Streams JSON arguments
```
TOOL_CALL_END
```
- Marks completion

```
TOOL_CALL_START
```
- 使用唯一ID初始化调用
```
TOOL_CALL_ARGS
```
- 流式传输JSON参数
```
TOOL_CALL_END
```
- 标记调用完成

State Synchronization

状态同步

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

STATE_SNAPSHOT - 完整状态替换
STATE_DELTA - 增量式JSON Patch（RFC 6902）更新

Source

来源

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

文档下载自：https://github.com/ag-ui-protocol/ag-ui/tree/main/docs