基础协议是每个实现无论使用哪些特性都要说的内容:
- 事件模型(本页):每个事件共享的信封、通用字段,以及把事件关联起来的标识符
- 运行输入:反向传输的唯一消息
- 元数据:一切之上的开放通道及合并规则
- 能力:智能体在运行前对自身的声明,以及声明带来的义务
- 事件模式:事件组合成流的方式
- 传输:流如何成帧与投递
- 处理模型:消费者遇到不认识内容时的行为
事件
每个事件都是一个共享同一信封的 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 胜出,本文档有缺陷。