跳到主要内容

事件模型

1.0 基础协议:事件信封、通用字段、标识符与全部事件地图。

基础协议是每个实现无论使用哪些特性都要说的内容:

  • 事件模型(本页):每个事件共享的信封、通用字段,以及把事件关联起来的标识符
  • 运行输入:反向传输的唯一消息
  • 元数据:一切之上的开放通道及合并规则
  • 能力:智能体在运行前对自身的声明,以及声明带来的义务
  • 事件模式:事件组合成流的方式
  • 传输:流如何成帧与投递
  • 处理模型:消费者遇到不认识内容时的行为

事件

每个事件都是一个共享同一信封的 JSON 对象,schema 中定义为 BaseEvent:

  • type —— REQUIRED。判别符,EventType 的 31 个值之一。本规范的每条规则都通过该字段附着到事件上。
  • timestamp —— OPTIONAL。事件创建时间。信息性的:消费者 MUST NOT 用它排序事件——到达顺序才是协议的顺序。约定单位为 Unix 纪元毫秒。
  • rawEvent —— OPTIONAL。该事件翻译自的提供商原生事件,原样携带。消费者 MUST NOT 从中推导协议行为。
  • metadata —— OPTIONAL。见通用字段。

通用字段

metadata

一切之上的开放通道:按 key 开放、key 下允许任何 JSON 值、在构建同一项的事件之间累积——逐 key、最后写入胜出、不递归——按族指定合并目标,并保留 ag-ui key。详见元数据。

缺省即缺省

这适用于每个可选字段,包括携带任意 JSON 的字段,如 rawEvent、RUN_FINISHED.result 与 forwardedProps。整个可选字段被设为 null 时必须省略。 必填 JSON 载荷可以是 null,例如 CUSTOM.value 或 STATE_SNAPSHOT.snapshot。

标识符

  • threadId 标识一段会话。由应用铸造,跨运行稳定。
  • runId 标识一次运行。MUST NOT 在同一线程的另一次运行中复用。
  • messageId 标识一条消息。它跨越运行边界——后续运行中的快照 MAY 按 id 重述一条消息——因此它 MUST 在其线程内唯一。
  • toolCallId 标识一次工具调用,并把其结果以及任何关于它的中断关联回该调用。
  • subagentRunId 是子智能体一次调用的不透明句柄,不是可复用的定义名:同一子智能体的两次调用携带两个不同的值。

所有标识符都是不透明字符串:消费者 MUST NOT 从中解析结构。

事件

31 种事件类型,分属八个族:

族 事件 模式
运行与步骤 RUN_STARTED RUN_FINISHED RUN_ERROR STEP_STARTED STEP_FINISHED 生命周期
文本消息 TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END TEXT_MESSAGE_CHUNK 流式
工具调用 TOOL_CALL_START TOOL_CALL_ARGS TOOL_CALL_END TOOL_CALL_CHUNK TOOL_CALL_RESULT 流式
推理 REASONING_START REASONING_END REASONING_MESSAGE_START REASONING_MESSAGE_CONTENT REASONING_MESSAGE_END REASONING_MESSAGE_CHUNK REASONING_ENCRYPTED_VALUE 流式
状态 STATE_SNAPSHOT STATE_DELTA MESSAGES_SNAPSHOT 快照–增量
活动 ACTIVITY_SNAPSHOT ACTIVITY_DELTA 快照–增量
子智能体 SUBAGENT_STARTED SUBAGENT_FINISHED SUBAGENT_ERROR 生命周期
透传 RAW CUSTOM 独立

Schema

协议的完整结构由 /spec/1-0/schema.json 中的 JSON Schema 定义。它是唯一事实来源:TypeScript、Python 与 .NET 模型都由它生成。本文档提到某个字段时,是在命名 schema 定义的东西,而非重述其形状。

schema 刻意不表达本文档所说的内容:顺序、生命周期、归因、错误处理与兼容性属于行为,schema 无法表达。若两者在结构上冲突,schema 胜出,本文档有缺陷。

Type to search…

↑↓ navigate↵ selectEsc close