跳到主要内容

版本与兼容

1.0:与旧 peer 对话、什么可以丢弃,以及丢失内容何时必须警告。

同一条流上的两方很少同龄。本页陈述它们不同龄时彼此的义务。

默认:新增是安全的

协议通过新增成长——新事件类型、新可选字段、开放联合的新成员。每个此类新增 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。
  • 经受未识别的事件、属性与联合成员;对已知值的格式错误失败。
  • 在执行之前运行中间件,在应用代码之前运行执行。
  • 翻译丢失内容时发出警告。
  • 永不向应用代码呈现执行阶段本会移除的内容。

Type to search…

↑↓ navigate↵ selectEsc close