AG-UI Protocol：Agent 与前端通信的事件体系

AG-UI Protocol SDK 使用流式事件架构。事件是 Agent 与前端之间通信的基本单元。本文档涵盖事件类型及其属性。

EventType 枚举

系统定义了 26 种事件类型：

enum EventType {
  TEXT_MESSAGE_START = "TEXT_MESSAGE_START",
  TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT",
  TEXT_MESSAGE_END = "TEXT_MESSAGE_END",
  TOOL_CALL_START = "TOOL_CALL_START",
  TOOL_CALL_ARGS = "TOOL_CALL_ARGS",
  TOOL_CALL_END = "TOOL_CALL_END",
  TOOL_CALL_RESULT = "TOOL_CALL_RESULT",
  STATE_SNAPSHOT = "STATE_SNAPSHOT",
  STATE_DELTA = "STATE_DELTA",
  MESSAGES_SNAPSHOT = "MESSAGES_SNAPSHOT",
  ACTIVITY_SNAPSHOT = "ACTIVITY_SNAPSHOT",
  ACTIVITY_DELTA = "ACTIVITY_DELTA",
  RAW = "RAW",
  CUSTOM = "CUSTOM",
  RUN_STARTED = "RUN_STARTED",
  RUN_FINISHED = "RUN_FINISHED",
  RUN_ERROR = "RUN_ERROR",
  STEP_STARTED = "STEP_STARTED",
  STEP_FINISHED = "STEP_FINISHED",
  REASONING_START = "REASONING_START",
  REASONING_MESSAGE_START = "REASONING_MESSAGE_START",
  REASONING_MESSAGE_CONTENT = "REASONING_MESSAGE_CONTENT",
  REASONING_MESSAGE_END = "REASONING_MESSAGE_END",
  REASONING_MESSAGE_CHUNK = "REASONING_MESSAGE_CHUNK",
  REASONING_END = "REASONING_END",
  REASONING_ENCRYPTED_VALUE = "REASONING_ENCRYPTED_VALUE",
}

BaseEvent

所有事件继承自 BaseEvent，提供通用属性：

type BaseEvent = {
  type: EventType
  timestamp?: number
  rawEvent?: any
}

属性	类型	说明
`type`	`EventType`	事件类型（union 的 discriminator）
`timestamp`	`number` (optional)	事件创建时间戳
`rawEvent`	`any` (optional)	如果事件被转换，原始事件数据

生命周期事件

RunStartedEvent

信号 Agent run 开始。

type RunStartedEvent = BaseEvent & {
  type: EventType.RUN_STARTED
  threadId: string
  runId: string
  parentRunId?: string
  input?: RunAgentInput
}

属性	类型	说明
`threadId`	`string`	对话线程 ID
`runId`	`string`	Agent run ID
`parentRunId`	`string` (optional)	分支/时间旅行的 lineage 指针。如果存在，指向同一 thread 内的先前 run
`input`	`RunAgentInput` (optional)	发送给 Agent 的精确输入 payload。可能省略已在历史中的消息

parentRunId 支持 branching/time travel——这是 context forking 在协议层的体现。

RunFinishedEvent

信号 Agent run 成功完成。

type RunFinishedEvent = BaseEvent & {
  type: EventType.RUN_FINISHED
  threadId: string
  runId: string
  result?: any
}

RunErrorEvent

信号 Agent run 期间出错。

type RunErrorEvent = BaseEvent & {
  type: EventType.RUN_ERROR
  message: string
  code?: string
}

StepStartedEvent / StepFinishedEvent

信号 Agent run 内 step 的开始和完成。

type StepStartedEvent = BaseEvent & {
  type: EventType.STEP_STARTED
  stepName: string
}

type StepFinishedEvent = BaseEvent & {
  type: EventType.STEP_FINISHED
  stepName: string
}

文本消息事件

TextMessageStartEvent

信号文本消息开始。

type TextMessageStartEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_START
  messageId: string
  role: "assistant"
}

TextMessageContentEvent

流式文本消息的内容块。

type TextMessageContentEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_CONTENT
  messageId: string
  delta: string
}

TextMessageEndEvent

信号文本消息结束。

type TextMessageEndEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_END
  messageId: string
}

TextMessageChunkEvent（便捷事件）

自动在 JS/TS 客户端中展开为 TextMessageStart → TextMessageContent → TextMessageEnd。

type TextMessageChunkEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_CHUNK
  messageId?: string
  role?: "developer" | "system" | "assistant" | "user"
  delta?: string
}

行为：

省略 start/end：客户端把 chunk 序列转换成标准 start/content/end 三元组，无需手动 emit
第一个 chunk 要求：必须包含 messageId。role 省略时默认 "assistant"
流式：相同 messageId 的后续 chunk emit TextMessageContent 事件。不同消息开始或流完成时自动 emit TextMessageEnd

工具调用事件

ToolCallStartEvent

信号工具调用开始。

type ToolCallStartEvent = BaseEvent & {
  type: EventType.TOOL_CALL_START
  toolCallId: string
  toolCallName: string
  parentMessageId?: string
}

ToolCallArgsEvent

工具调用的参数数据块。

type ToolCallArgsEvent = BaseEvent & {
  type: EventType.TOOL_CALL_ARGS
  toolCallId: string
  delta: string
}

ToolCallEndEvent

信号工具调用结束。

type ToolCallEndEvent = BaseEvent & {
  type: EventType.TOOL_CALL_END
  toolCallId: string
}

ToolCallResultEvent

提供工具调用执行结果。

type ToolCallResultEvent = BaseEvent & {
  type: EventType.TOOL_CALL_RESULT
  messageId: string
  toolCallId: string
  content: string
  role?: "tool"
}

核心洞察

AG-UI Protocol 是 Agent 时代的通信基础设施。它定义了：

Agent 与前端如何对话 — 通过标准化事件流
思考过程如何可见 — REASONING_* 事件让前端能展示 Agent 的推理链
工具调用如何追踪 — TOOL_CALL_* 事件提供完整的调用生命周期
状态如何同步 — STATE_SNAPSHOT / STATE_DELTA 让前端与 Agent 状态保持一致
时间旅行如何工作 — parentRunId 支持在相同 thread 内回溯到先前 run

这是构建 Agent GUI 的底层协议。无论是 Claude Code 的 TUI、ChatGPT 的网页界面，还是自定义的 Agent 控制台，都可以基于此协议实现。