跳到主要内容

事件

@ag-ui/core 的事件:EventType 枚举、各类事件结构与 Zod 校验。

事件

Agent User Interaction Protocol SDK 采用流式事件架构。事件是智能体与前端之间通信的基本单位。

EventType 枚举

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",
  SUBAGENT_STARTED = "SUBAGENT_STARTED",
  SUBAGENT_FINISHED = "SUBAGENT_FINISHED",
  SUBAGENT_ERROR = "SUBAGENT_ERROR",
}

BaseEvent

所有事件都继承 BaseEvent:

type BaseEvent = {
  type: EventType
  timestamp?: number
  rawEvent?: any
  metadata?: Record<string, any>
}
属性 类型 说明
type EventType 事件类型(联合的判别字段)
timestamp number(可选) 事件创建时间
rawEvent any(可选) 事件经转换前的原始数据
metadata Record<string, any>(可选) 附在事件上的额外信息

metadata 按 key 开放:任意 JSON 值(含 null)。对象可缺省,但存在时永不为 null——显式 null 按缺省解析。ag-ui 键保留给 AG-UI 自用。可使用 @ag-ui/core 的 mergeMetadata 将事件 metadata 折入消息;规则见 Metadata。

生命周期事件

RunStartedEvent

type RunStartedEvent = BaseEvent & {
  type: EventType.RUN_STARTED
  threadId: string
  runId: string
  parentRunId?: string
  input?: RunAgentInput
}
属性 类型 说明
threadId string 会话线程 ID
runId string 运行 ID
parentRunId string(可选) 分支/时间旅行的谱系指针;若存在,指向同一线程中更早的运行
input RunAgentInput(可选) 本次运行发给智能体的确切输入载荷;可省略历史中已有的消息

TokenUsage

终态运行事件上携带的可复用、仅含数字的 token 用量摘要。它只包含提供方/模型标签与 token 计数——不含提示词、补全内容、消息或标识符。计数遵循协议的记账规则:输入与输出是总量,缓存与推理计数是其中的一部分,绝不叠加。

type TokenUsage = {
  provider?: string
  model?: string
  inputTokens?: number
  outputTokens?: number
  totalTokens?: number
  reasoningTokens?: number
  cachedInputTokens?: number
  cacheWriteInputTokens?: number
}

RunFinishedEvent

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

RunErrorEvent

type RunErrorEvent = BaseEvent & {
  type: EventType.RUN_ERROR
  message: string
  code?: string
  usage?: TokenUsage[]
}

usage 是已完成的模型调用产生的部分用量。

StepStartedEvent / StepFinishedEvent

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

文本消息事件

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

type TextMessageContentEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_CONTENT
  messageId: string
  delta: string // 非空字符串
}

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 // 消息的首个 chunk 必须提供
  role?: "developer" | "system" | "assistant" | "user"
  delta?: string
}

行为:

  • 省略 start/end:客户端把 chunk 序列转换为标准的 start/content/end 三元组,无需手工发出。
  • 首块要求:消息的第一个 chunk 必须包含 messageId;省略 role 时默认 assistant。
  • 流式:同一 messageId 的后续 chunk 发出 TextMessageContent;当另一条消息开始或流结束时,自动发出 TextMessageEnd。

工具调用事件

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

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

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

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

ToolCallChunkEvent

type ToolCallChunkEvent = BaseEvent & {
  type: EventType.TOOL_CALL_CHUNK
  toolCallId?: string   // 首块必须提供
  toolCallName?: string // 首块必须提供
  parentMessageId?: string
  delta?: string
}

行为:首块必须同时包含 toolCallId 与 toolCallName;parentMessageId 若提供会传播到 ToolCallStart;同一 toolCallId 的后续 chunk 发出 ToolCallArgs,工具调用变化或流结束时自动发出 ToolCallEnd。

状态管理事件

type StateSnapshotEvent = BaseEvent & {
  type: EventType.STATE_SNAPSHOT
  snapshot: any
}

type StateDeltaEvent = BaseEvent & {
  type: EventType.STATE_DELTA
  delta: any[] // JSON Patch 操作(RFC 6902)
}

type MessagesSnapshotEvent = BaseEvent & {
  type: EventType.MESSAGES_SNAPSHOT
  messages: Message[]
}

ActivitySnapshotEvent / ActivityDeltaEvent

type ActivitySnapshotEvent = BaseEvent & {
  type: EventType.ACTIVITY_SNAPSHOT
  messageId: string
  activityType: string
  content: Record<string, any>
  replace?: boolean // 默认 true;为 false 时若同 ID 消息已存在则忽略该快照
}

type ActivityDeltaEvent = BaseEvent & {
  type: EventType.ACTIVITY_DELTA
  messageId: string
  activityType: string
  patch: any[] // RFC 6902 JSON Patch
}

推理事件

推理事件让智能体把内部思考过程暴露给前端,生成角色为 "reasoning" 的 ReasoningMessage 并保留在消息历史中。

type ReasoningStartEvent = BaseEvent & {
  type: EventType.REASONING_START
  messageId: string
}

type ReasoningMessageStartEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_START
  messageId: string
  role: "reasoning"
}

type ReasoningMessageContentEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_CONTENT
  messageId: string
  delta: string
}

type ReasoningMessageEndEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_END
  messageId: string
}

type ReasoningEndEvent = BaseEvent & {
  type: EventType.REASONING_END
  messageId: string
}

REASONING_START 与 REASONING_END 是直通事件:通知订阅者,但不创建消息。

ReasoningMessageChunkEvent

type ReasoningMessageChunkEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_CHUNK
  messageId?: string
  delta?: string
}

ReasoningEncryptedValueEvent

找到 entityId 引用的实体,写入其 encryptedValue 字段。

type ReasoningEncryptedValueEvent = BaseEvent & {
  type: EventType.REASONING_ENCRYPTED_VALUE
  subtype: "tool-call" | "message"
  entityId: string
  encryptedValue: string
}

子智能体事件

subagentRunId 标识一次调用,而不是可复用的子智能体定义——同一子智能体运行两次会得到两个不同的值。完整模型见子智能体。

type SubagentStartedEvent = BaseEvent & {
  type: EventType.SUBAGENT_STARTED
  subagentRunId: string
  name: string
  description?: string
  parentSubagentRunId?: string
  parentToolCallId?: string
  parentMessageId?: string
}

type SubagentFinishedEvent = BaseEvent & {
  type: EventType.SUBAGENT_FINISHED
  subagentRunId: string
  result?: any
  outcome?: { type: "success" } | { type: "suspended"; interruptIds?: string[] }
}

type SubagentErrorEvent = BaseEvent & {
  type: EventType.SUBAGENT_ERROR
  subagentRunId: string
  message: string
  code?: string
}

其它事件上的归因

大多数事件类型接受可选的 subagentRunId。不带该字段的事件属于父智能体,因此从不设置它的流与子智能体出现之前的行为完全一致。

RunStartedEvent、RunFinishedEvent、RunErrorEvent 不可归因——它们描述整个运行。MessagesSnapshotEvent 改为逐消息携带归因,因为一份快照可能混合多个生产者的消息。StateSnapshotEvent 与 StateDeltaEvent 可以归因,但归因表示来源而非所有权:状态是运行级的,带归因的快照或增量与不带归因的一样应用到该运行唯一的状态文档。

订阅者可通过 onSubagentStartedEvent、onSubagentFinishedEvent、onSubagentErrorEvent 直接响应生命周期。

特殊事件

type RawEvent = BaseEvent & {
  type: EventType.RAW
  event: any
  source?: string
}

type CustomEvent = BaseEvent & {
  type: EventType.CUSTOM
  name: string
  value: any
}

已弃用事件

警告: THINKING_* 事件已弃用,将在 1.0.0 中移除。新实现请使用 REASONING_*。

已弃用 替代
THINKING_START REASONING_START
THINKING_END REASONING_END
THINKING_TEXT_MESSAGE_START REASONING_MESSAGE_START
THINKING_TEXT_MESSAGE_CONTENT REASONING_MESSAGE_CONTENT
THINKING_TEXT_MESSAGE_END REASONING_MESSAGE_END

迁移指引见推理:从 Thinking 事件迁移。

事件 Schema

SDK 使用 Zod schema 校验事件,并提供 TypeScript 类型推断:

const EventSchemas = z.discriminatedUnion("type", [
  TextMessageStartEventSchema,
  TextMessageContentEventSchema,
  TextMessageEndEventSchema,
  ToolCallStartEventSchema,
  ToolCallArgsEventSchema,
  ToolCallEndEventSchema,
  ToolCallResultEventSchema,
  StateSnapshotEventSchema,
  StateDeltaEventSchema,
  MessagesSnapshotEventSchema,
  ActivitySnapshotEventSchema,
  ActivityDeltaEventSchema,
  RawEventSchema,
  CustomEventSchema,
  RunStartedEventSchema,
  RunFinishedEventSchema,
  RunErrorEventSchema,
  StepStartedEventSchema,
  StepFinishedEventSchema,
  ReasoningStartEventSchema,
  ReasoningMessageStartEventSchema,
  ReasoningMessageContentEventSchema,
  ReasoningMessageEndEventSchema,
  ReasoningMessageChunkEventSchema,
  ReasoningEndEventSchema,
  ReasoningEncryptedValueEventSchema,
])

Type to search…

↑↓ navigate↵ selectEsc close