消费者发送 RunAgentInput;生产者以携带一次或多次运行的事件流作答——被请求的运行,可能前面还有重放的历史。本页陈述运行何时开始与结束、这些边界意味着什么;运行内部的顺序规则属于事件模式。
运行
流 MUST 以 RUN_STARTED 或 RUN_ERROR 开始。生产者 MUST NOT 先发射任何其他事件,消费者 MUST 把以其他事件开始的流视为协议违规。RUN_ERROR 可以先出现,因为运行可能在开始前就失败——无法到达智能体的传输有失败要报告,却没有运行可供挂载。
[*] --RUN_STARTED--> Active
[*] --RUN_ERROR--> Failed
Active --RUN_FINISHED--> Closed
Active --RUN_ERROR--> Failed
Closed --RUN_STARTED--> Active (新运行)
Closed --RUN_ERROR--> Failed (迟到失败)
Failed --RUN_STARTED--> Active (新运行)RUN_STARTED
开启运行。它携带运行的标识符、生产者自己的 protocolVersion 声明(按版本规则),并 MAY 回显启动该运行的输入,使未发起请求的消费者也能看到智能体被问了什么。parentRunId 命名派生本次运行的那次运行——当智能体把另一个智能体作为独立运行而非同一运行内的子智能体调用时。
RUN_FINISHED
关闭未失败的运行,并报告它如何结束:
- 其
outcome区分完成的运行、等待外部输入而中断的运行,以及完成前被停止的运行;缺省 outcome 表示成功。中断结果及其后续见中断与恢复;取消结果见下文。outcome 报告生产者对运行结束原因所知的内容:因前端工具调用而停止的运行是已完成的运行,其成功结果 MAY 在pendingToolCallIds中命名未回答的调用,因为应用在这样一次调用之后是否继续线程是应用的决定,不是生产者的。 - 生产者 MUST NOT 发送 schema 未描述的 outcome 值。
result是 OPTIONAL,携带运行的返回值(若有)。usage是 OPTIONAL,按提供商与模型各一条报告 token 用量,遵循下文记账。只想要总量的消费者对各条目求和。
消费者不认识的 outcome 与其他未识别内容一样,按同样条件被剥离。剥离可选字段使其缺省,而缺省 outcome 表示成功——因此消费者不必区分完成的运行与因在该消费者发布之后命名的原因而结束的运行。
这限制了 outcome 集合能有用增长的程度。后续版本新增的终止状态会以成功运行到达旧消费者,因此需要旧消费者注意到新结束方式的版本,不能仅通过
outcome表达——它需要一个旧消费者已视为重要的载体。这也是取消结果在 1.0 就命名的原因:若之后添加,被取消的运行会以已完成运行到达每个 1.0 消费者。
已取消的运行
运行可以在完成前被有意停止——由它为之运行的人、由应用自己的代码、由生产者执行的限制。它没有失败,也没有在等待任何内容,但也没有完成;无法把它与已完成运行区分的消费者会把部分工作当作全部呈现。取消结果命名这种结束。
- 在完成前停止运行、且原因不是失败的生产者 MUST 以携带取消结果的
RUN_FINISHED关闭它。MUST NOT 把被停止的运行报告为成功——既不以成功结果,也不通过省略 outcome。 - 已关闭运行的一切在此成立。生产者 MUST 在取消它的
RUN_FINISHED之前关闭运行开启的内容——消息、工具调用、步骤、子智能体——与成功前完全一样。关闭工具调用确立的是其参数文本完整,不是有效,因此参数中途被截断的调用照常关闭,如何处理无法解析的参数是应用的决定,按工具调用规则。无法按序关闭的生产者——停止把流从它下面拆掉——改为报告RUN_ERROR:该运行没有干净结束,而RUN_ERROR正是为没有干净结束的运行准备的。 - 被取消的运行没有返回值:
resultSHOULD 缺省。usageMAY 报告停止前累积的 token。 - 被取消的运行不等待任何东西。其 outcome 不携带中断,线程上的下一次运行是普通新运行,不是恢复。
- 消费者 MUST NOT 把被取消的运行呈现为成功,也 MUST NOT 呈现为失败——用户要求的停止不是要展示给他的错误。
停止前投递的一切仍然有效,与 RUN_ERROR 之后一样。除此之外如何呈现停止是消费者的事。
取消是生产者对其所运行运行的报告。放弃流的消费者——关闭连接、停止读取——拥有的是截断运行,不是被取消的运行:它 MUST NOT 为从未收到结束的运行合成 RUN_FINISHED,无论取消与否。
RUN_ERROR
结束失败的运行。message 说明出了什么问题,供人阅读;code 是 OPTIONAL 且机器可读,是协议未定义词汇的开放字符串;usage MAY 按与 RUN_FINISHED 相同的记账报告失败前累积的 token。
RUN_ERROR 是格式良好的事件:生产者在报告自己的失败,而不是发送消费者应拒绝的内容。把运行视为失败意味着消费者 MUST 把失败暴露给应用代码,并 MUST NOT 报告运行成功。它不规定如何——启动运行的那个调用是抛错、以失败 resolve,还是通过回调报告,都是实现的事,两个一致消费者可以不同。
token 用量
RUN_FINISHED 与 RUN_ERROR 上的 usage 报告运行中模型调用的成本,按提供商与模型各一条 TokenUsage。各提供商计数方式不同——有的把缓存提示 token 折进输入计数,有的并列报告,有的把推理与其余输出分开——因此协议固定一种记账,生产者负责翻译进去。每个计数要么是总量,要么是总量的具名部分:
inputTokens是该调用被计费的每个提示 token:缓存与否、写入缓存与否、文本与否。outputTokens是每个生成的 token,含推理。cachedInputTokens(缓存读)、cacheWriteInputTokens(缓存写)与reasoningTokens是这些总量的部分,绝不是附加量。两个缓存计数互斥。提供商在较小总量旁报告其中之一的,生产者 MUST 在发射条目前把它加进总量;提供商已包含它的,生产者 MUST NOT 重复添加。totalTokens是inputTokens加outputTokens。生产者 MAY 自行计算而非复制提供商总量,且 MUST NOT 复制计数方式不同的提供商总量。- 缺失计数表示提供商未报告;零表示它报告了零。生产者 MUST NOT 为没有数据的计数发射零,消费者 MUST NOT 把缺失计数读作零。
运行是记账边界:
- 用量覆盖运行内发起的每一次模型调用,包括其子智能体发起的调用:子智能体事件不携带自己的用量,子智能体的调用属于该运行。
- 作为独立运行被调用的智能体——由
parentRunId命名——在自己的终止事件上报告自己的用量,派生它的运行 MUST NOT 把该用量计入自身。 - 恢复被中断运行的运行只报告它自己发起的调用。被中断运行已报告了自己的,想要线程总量的消费者跨线程各运行求和。
在此记账下,只想要总量的消费者对各条目与各运行的 totalTokens 求和;计算成本的消费者拥有按各自费率计价缓存读、缓存写与推理所需的每个部分,且不会重复计算。
运行关闭之后
运行以 RUN_FINISHED 或 RUN_ERROR 结束,之后即为已关闭。一旦运行关闭:
- 生产者 MUST NOT 为该运行发射任何进一步事件,除了下面两条。
- 生产者 MAY 发射
RUN_STARTED以在同一流上开始新运行。 - 生产者 MAY 在
RUN_FINISHED之后发射RUN_ERROR,报告在已报告成功之后浮现的失败——例如刷新时的传输错误。此时消费者 MUST 把运行视为失败。 - 生产者 MUST NOT 在
RUN_ERROR之后发射除RUN_STARTED外的任何内容。
消费者 MUST 拒绝运行关闭后到达的任何其他事件。
单流多运行
单条流 MAY 按序携带多次运行——重放线程是常见情形。生产者 MUST 在开启下一次运行前关闭当前运行:运行仍活跃时出现 RUN_STARTED 是违规。
流内跨运行,消息累积,状态持续存在,除非某事件替换它。重述历史的生产者——重放消费者输入已携带内容的线程——MUST 以快照重述:MESSAGES_SNAPSHOT 按 id 协调,STATE_SNAPSHOT 替换,因此消费者已持有的重述是幂等的。重新流式传输消费者已持有的消息会追加而非重述,这就是流式三件套只用于新内容的原因。
运行作用域的跟踪——打开的消息、打开的工具调用、打开的步骤、活跃子智能体——不跨越边界:RUN_FINISHED 要求运行开启的一切已关闭,RUN_ERROR 随运行结束任何仍打开的内容。新运行以没有任何打开项开始。
步骤
步骤标记运行的阶段,供显示进度的 UI 使用。STEP_STARTED 开启步骤,STEP_FINISHED 关闭它,按 stepName 匹配。
- 生产者 MUST NOT 开启名称已打开的步骤,MUST NOT 关闭从未开启的步骤。
- 生产者开启的每个步骤 MUST 在运行结束前关闭。
- 步骤 MAY 彼此重叠,也可与运行中其他内容重叠;步骤是流上一段区间的标签,不是容器。
数据类型
事件形状由 schema 参考定义:RunStartedEvent、RunFinishedEvent(含 RunFinishedOutcome)、RunErrorEvent、StepStartedEvent、StepFinishedEvent 与 TokenUsage。
错误处理
有两件不同的事会让运行糟糕地结束,消费者要把它们分开。
消费者拒绝的流是它检测到的协议违规:本页生产者 MUST NOT 做的每件事在被消费者看到时都是致命的——RUN_STARTED 之前的事件、关闭后除允许的两条之外的事件、嵌套 RUN_STARTED、不平衡的步骤,或 RUN_FINISHED 时仍打开的任何内容。生产者有过错,流不可信。
用 RUN_ERROR 报告自身失败的运行正相反:一致生产者在说它的工作没有成功。流格式良好,消费者按上述规则接受它。
消费者 MUST NOT 把两者互相呈现。任一种失败都保留失败前投递的一切——RUN_ERROR 说的是运行没有完成,不是它的事件没有发生。