同一条流上的两方很少同龄。本页陈述它们不同龄时彼此的义务。
默认:新增是安全的
协议通过新增成长——新事件类型、新可选字段、开放联合的新成员。每个此类新增 MUST 对旧参与方安全,因为未识别内容会存活而不会中止运行。
由此可知,生产者 MUST NOT 把协议已有描述位置的内容仅放进新增里。具体而言:运行的 outcome、消息的内容、工具调用的身份及其结果,MUST 在 schema 为它们描述的字段中传输,绝不能只放在旧消费者会丢弃的新事件类型或新属性里。
降级
知道自己 peer 更旧的参与方 MAY 把流翻译成 peer 理解的形式。降级移除或重塑已有内容;它 MUST NOT 发明含义。为旧 schema 必填字段提供空值——内容现在缺省处提供空字符串——是重塑,允许;提供生产者从未发送的非空值则是发明含义,禁止。
降级 MUST NOT 顺路修复格式错误的值。已知字段携带 schema 拒绝的值是致命的,把它变成可接受内容的 shim 会隐藏本应被报告的缺陷。
降级分两类,差别决定是否必须告知:
无损。 移除的内容不增加旧参与方可据以行动的信息。为没有子智能体概念的 peer 剥离 subagentRunId 在此意义上是无损的:事件仍到达,只是扁平化为一条线程。无损降级 MAY 静默。
有损。 携带含义的内容被丢弃或降级。移除生命周期事件、丢弃 peer 无法表示的内容部分,或把结构化值折叠为更低级形式,都会丢失读者本会看到的内容。有损降级 MUST 发出警告,指明丢失了什么及原因。
警告是给开发者而非最终用户的。它 MUST 指明被丢弃的形状,SHOULD 说明升级到什么可消除它。实现 MAY 提供静默这些警告的方式,且 MUST NOT 默认静默。
退役形状
协议曾经描述、现在不再描述的形状是退役(retired)。退役不是删除:旧生产者仍会发送它,简单丢弃的消费者会破坏可工作的集成。
- 退役形状 MUST 记录在弃用注册表中,连同其替代、翻译所在位置,以及翻译本身的过期时间。
- 消费者 SHOULD 把退役形状翻译为其替代,而不是丢弃。
- 该翻译 MUST 作为中间件运行——在执行之前——因为执行按当前协议判定,退役形状在其中只是未识别。
- 翻译过程中丢失内容的,MUST 按上述规则警告。
退役形状的过期时间过去后,实现 MAY 移除翻译,之后该形状与其他未识别内容一样。
版本协商
版本带内传输,位于开启交换两侧的两条消息上,使录制的交换保持自描述,且无需任何传输携带它:
- 消费者在
RunAgentInput.protocolVersion声明它所说的协议版本。 - 生产者在
RUN_STARTED.protocolVersion声明它自己所说的版本——自己的,绝不是输入的回显。这一对就是全部协商:每侧声明一次,消费者在降级发生的瞬间就能看到。 - 两个字段在 schema 中都是可选的,因为缺失意味着某件事:协议携带版本之前的 peer。本版本的实现 MUST 发送其声明,除非消费者知道 peer 早于该字段并省略它,以免把未知输入成员交给旧解析器。
- 值是本规范发布的版本标识符——冻结版本所在的分段,
MAJOR.MINOR,按分量数值比较(因此1.10比1.9新)。无法解读的声明按更新版本处理:继续,并 SHOULD 警告。 - 遇到自己所实现系列更新小版本的生产者 MUST 服务该运行——新增是安全的——用自己的版本作答,并 SHOULD 警告。它 MAY 仅在
RUN_STARTED之前拒绝来自未实现主系列的声明;自己系列的更新小版本按构造即可服务,MUST NOT 因版本被拒绝。消费者遇到更新的生产者声明时,按处理模型继续,并 SHOULD 警告。 - 声明命名的是该运行的流所说的版本,不是谁在转发它:未翻译转发运行的代理声明原始生产者的版本;翻译的代理声明它发射的版本。在携带多次运行的流上,每次运行的
RUN_STARTED声明自己的运行,这是混合年龄历史回放得以真实的原因;实时生成运行的生产者不会在流中途改变它所说的版本。 - 传输 MAY 把声明镜像到自己的信封——例如媒体类型参数——供无法读取主体的中间层使用。带内字段是权威的;镜像的绑定需定义如何处理不一致。
参与方在知道对方版本时——带内声明或配置——MAY 据此选择降级。不知道时 MUST 按 peer 为当前版本处理:向下猜测会无端降级流。
按版本选择的降级 MUST 是流的纯变换。它 MUST NOT 改变运行 outcome、更改标识符或重排事件。
生产者的义务
- 在
RUN_STARTED上声明它所说的协议版本。 - 只发射当前协议描述的形状。
- 省略无值的可选字段,而不是发送
null。 - 永不依赖消费者理解新增。
消费者的义务
- 在运行输入上声明它所说的协议版本,除非面对已知早于该字段的 peer。
- 经受未识别的事件、属性与联合成员;对已知值的格式错误失败。
- 在执行之前运行中间件,在应用代码之前运行执行。
- 翻译丢失内容时发出警告。
- 永不向应用代码呈现执行阶段本会移除的内容。