三个事件族逐片流式传输长值:文本消息、工具调用与推理消息。三者都遵循同一模式,只是有两种拼写——显式的开–内容–关三件套,以及为否则需要缓冲的生产者准备的紧凑 chunk 形式。本页定义一次模式;各族页面只补充该族特有的内容。
开、内容、关
流式项由 *_START 开启,由零个或多个内容事件扩展,由 *_END 关闭,全部按项的标识符匹配(消息用 messageId,工具调用用 toolCallId)。
- 生产者 MUST NOT 开启标识符已处于开启状态的项。
- 生产者 MUST NOT 为未开启的标识符发送内容或结束事件。
- 生产者开启的每一项都 MUST 在运行结束前关闭。
开启事件携带描述该项的字段;内容事件只携带标识符与 delta。delta 按到达顺序拼接成项的值。
Producer → Consumer: TEXT_MESSAGE_START (messageId: "msg-1")
Producer → Consumer: TEXT_MESSAGE_CONTENT (delta: "Hello, ")
Producer → Consumer: TEXT_MESSAGE_CONTENT (delta: "world.")
Producer → Consumer: TEXT_MESSAGE_END (messageId: "msg-1")交错
消息、工具调用、推理消息与步骤彼此独立。生产者 MAY 自由交错——工具调用 MAY 在消息仍流式时开启——只要每一项遵守自己的开/关纪律。
独立事件(STATE_SNAPSHOT、STATE_DELTA、MESSAGES_SNAPSHOT、ACTIVITY_SNAPSHOT、ACTIVITY_DELTA、CUSTOM、RAW、REASONING_ENCRYPTED_VALUE)不开启也不关闭任何项,MAY 出现在开启运行内的任何位置。在 chunk 形式下,其中一些确实会结束打开的 chunk 流——它们的到达告诉消费者简写无法继续——见关闭 chunk 流。
chunk 形式
TEXT_MESSAGE_CHUNK、TOOL_CALL_CHUNK 与 REASONING_MESSAGE_CHUNK 是三件套的紧凑拼写。消费者 MUST 在验证之前、应用代码之前把它们展开为 start/content/end 形式,使三件套的每条规则适用于展开后的事件。展开相对执行与中间件的位置在处理模型中规定;每条路径都成立的不变式是:chunk 按其代表的事件判定——无论哪个阶段先遇到格式错误的 chunk,都拒绝而非修复。
Producer → Expansion: TOOL_CALL_CHUNK (toolCallId, toolCallName, delta)
Expansion → Consumer: TOOL_CALL_START
Expansion → Consumer: TOOL_CALL_ARGS
Producer → Expansion: TOOL_CALL_CHUNK (delta)
Expansion → Consumer: TOOL_CALL_ARGS
Producer → Expansion: RUN_FINISHED
Expansion → Consumer: TOOL_CALL_END
Expansion → Consumer: RUN_FINISHED两种拼写不能在同一项内混用。 由 chunk 开启的项以 chunk 形式延续与关闭——其 *_END 是合成的,永不发送;由 *_START 开启的项显式延续与关闭。携带 chunk 流正在组装的标识符的显式事件不是它的延续:它会结束简写,随后的内容按三件套规则判定——这使在同一项内混用形式成为生产者 MUST NOT 发射的格式错误序列。
首个 chunk
项的首个 chunk 携带开启它所需的内容;后续 chunk MAY 省略这些字段并延续已开启的内容。
- 一条消息的首个
TEXT_MESSAGE_CHUNKMUST 携带messageId。它 MAY 携带role;缺省 role 表示assistant,与TEXT_MESSAGE_START完全一致。 - 一条消息的首个
REASONING_MESSAGE_CHUNKMUST 携带messageId。 - 一次调用的首个
TOOL_CALL_CHUNKMUST 同时携带toolCallId与toolCallName。
消费者 MUST 把缺少必填字段的首个 chunk 视为协议违规,而不是自行发明标识符。
延续 chunk
- 携带标识符的后续 chunk MUST 携带它正在延续的同一标识符。命名不同标识符的 chunk 会开启新项,前一项先关闭。
- 延续 chunk MAY 重复开启者已确立的字段——文本消息的
role或name,工具调用的toolCallName或parentMessageId——但只能使用相同值。消费者 MUST 把冲突的重复视为协议违规。
这也包括与开启者通过省略确立的值冲突:未携带 role 开启的消息是一条 assistant 消息,后续 chunk 声称另一 role 就是与之矛盾。
冲突重复规则与子智能体归因规则对延续 chunk 在
subagentRunId上不一致的判定相同:生产者对同一项说了两件互不兼容的事,没有正确的选择方式。
关闭 chunk 流
chunk 形式没有显式结束事件,因此消费者在流无法继续时合成 *_END:
- 当同一 lane 中的 chunk 开启不同项时;
- 当该项 lane 中到达消息、工具调用、步骤、状态、custom 或推理事件时——但有四个例外不参与组装也不关闭任何东西:
RAW、ACTIVITY_SNAPSHOT、ACTIVITY_DELTA、REASONING_ENCRYPTED_VALUE(以及SUBAGENT_STARTED,它开启新 lane 而不触碰本 lane); - 当到达运行级事件——
RUN_STARTED、RUN_FINISHED、RUN_ERROR或MESSAGES_SNAPSHOT——它关闭所有 lane;或当项所归因的子智能体终止时,关闭该子智能体的 lane。
简写延续属于哪条 lane——父智能体的还是某个子智能体的——由归因规则决定;对于既无标识符也无标签的延续,则通过解析决定:若父智能体存在该类型的开放流,则延续它;否则延续该类型唯一的开放流。当多条 lane 都持有该类型的开放流且没有一条属于父智能体时,该延续没有唯一指称对象,MUST 作为歧义被拒绝——并行运行子智能体的生产者 MUST 为其延续添加归因。
chunk 流 MUST NOT 比其所有者存活更久:由子智能体开启的项最迟在该子智能体的终止事件处关闭。
chunk 元数据
chunk 的 metadata 适用于由该 chunk 合成的事件,并按元数据规则合并进该项。只携带元数据的延续 chunk——例如报告用量与结束原因的最后一块——是合法的:它不添加内容,其元数据仍会到达它所延续的项。