以下事件字段、schema 与版本均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。AG-UI 事件字段以官方规范为准,但"新增必填字段破坏向后兼容、移除必填字段破坏向前兼容"这两条不变量不变。
6.1、6.2 讲了工具调用与 Agent 协作的协议。协议一旦上线,就要面对演进:schema 会加字段、改必填、删字段。这一节回答演进最关键的兼容性问题——两个方向的兼容不能混为一谈。
向后兼容与向前兼容经常被写反。向后兼容指新事件能被旧消费者处理;向前兼容指旧事件能被新消费者处理。一条规则对两个方向都不对称:新增可选字段双向兼容,新增必填字段破坏向后,移除必填字段破坏向前。 这一节用字段集合检查把两条不变量量化。
双向兼容的两条不变量
给定旧 schema 与新 schema,兼容性要看字段集合:
| 方向 | 定义 | 破坏条件 |
|---|---|---|
| 向后兼容 | 新事件能被旧消费者处理 | 新必填字段不在旧字段全集里 |
| 向前兼容 | 旧事件能被新消费者处理 | 旧必填字段不在新字段全集里 |
用集合语言写出来最清晰。设旧 schema 字段为 old_all,旧必填为 old_required,新字段为 new_all,新必填为 new_required:
- 向后:new_required ⊆ old_all。新加的字段必须是可选的,旧消费者才处理得了。
- 向前:old_required ⊆ new_all。旧必填字段不能被移除,新消费者才处理得了旧事件。
两条规则的不对称性值得强调:加字段只破坏向后,删字段只破坏向前。 一个 schema 演进可以同时对一个方向兼容、对另一个方向破坏——这正是必须双向检查的原因。
三种演进的兼容矩阵
| 演进 | 向后 | 向前 | 说明 |
|---|---|---|---|
| 新增可选字段 | 兼容 | 兼容 | 最安全 |
| 新增必填字段 | 破坏 | 兼容 | 旧消费者处理不了新事件 |
| 移除必填字段 | 兼容 | 破坏 | 新消费者处理不了旧事件 |
“新增必填字段"是最常见的破坏:工具方加了必填字段,觉得"反正新版本要它”,但旧消费者还在按旧 schema 解析,新事件在旧消费者那里缺字段。6.1 的 -32602 就可能是这类破坏的消费侧表现。
最小实验:字段集合双向检查
实验用字段集合({字段名: 是否必填})检查三种演进的双向兼容,并演示事件解析时缺失可选字段用默认值补齐。
# file: agp_lab/event_protocol.py | write
# tier: 3
# verify: python3 -m unittest tests.test_event_protocol
"""AG-UI/事件协议与版本兼容:字段演进与双向兼容。
事件 schema 会演进。向后兼容(backward)指新事件能被旧消费者
处理:新增字段必须是可选的。向前兼容(forward)指旧事件能被
新消费者处理:旧必填字段不能被移除。
本模块用字段集合检查双向兼容性,并演示事件解析时
缺失可选字段用默认值补齐。
"""
from __future__ import annotations
from typing import Any
def check_compat(old_fields: dict[str, bool], new_fields: dict[str, bool]) -> dict[str, bool]:
"""old/new_fields 为 {字段名: 是否必填}。
backward:新事件能被旧消费者处理 ⇔ new 的必填字段 ⊆ old 字段全集;
forward :旧事件能被新消费者处理 ⇔ old 的必填字段 ⊆ new 字段全集。
"""
old_all = set(old_fields)
new_all = set(new_fields)
old_required = {name for name, required in old_fields.items() if required}
new_required = {name for name, required in new_fields.items() if required}
return {
"backward": new_required <= old_all,
"forward": old_required <= new_all,
}
def parse_event(
event: dict[str, Any], schema: dict[str, bool], defaults: dict[str, Any]
) -> dict[str, Any]:
"""按 schema 解析事件;缺失可选字段用默认值补齐,缺失必填字段报错。"""
parsed: dict[str, Any] = {}
for name, required in schema.items():
if name in event:
parsed[name] = event[name]
elif required:
raise ValueError(f"missing required event field '{name}'")
else:
parsed[name] = defaults.get(name, None)
return parsed
def demo() -> dict[str, Any]:
v1 = {"id": True, "kind": True, "detail": False}
v2 = {"id": True, "kind": True, "detail": False, "trace_id": False}
v3 = {"id": True, "kind": True, "detail": False, "trace_id": True}
v4 = {"id": True} # 移除必填字段 kind
return {
"v1_v2_add_optional": check_compat(v1, v2),
"v1_v3_add_required": check_compat(v1, v3),
"v1_v4_remove_required": check_compat(v1, v4),
"parse_old_event_with_v2": parse_event(
{"id": "e1", "kind": "tool_call"}, v2, {"detail": "no", "trace_id": "none"}
),
}
if __name__ == "__main__":
for key, value in demo().items():
print(f"{key}: {value}")
运行:
cd private/labs/agp-lab
python3 -m agp_lab.event_protocol
输出:
v1_v2_add_optional: {'backward': True, 'forward': True}
v1_v3_add_required: {'backward': False, 'forward': True}
v1_v4_remove_required: {'backward': True, 'forward': False}
parse_old_event_with_v2: {'id': 'e1', 'kind': 'tool_call', 'detail': 'no', 'trace_id': 'none'}
四行输出对应四种场景:
- v1_v2_add_optional:v1(id/kind 必填、detail 可选)→ v2 加可选字段 trace_id。向后、向前都兼容——新增可选字段是唯一双向兼容的演进。
- v1_v3_add_required:v2 → v3 把 trace_id 改成必填。backward=False——旧消费者处理不了带必填 trace_id 的新事件;forward=True 不变。
- v1_v4_remove_required:v4 只留 id,删掉必填的 kind。backward=True;forward=False——新消费者处理不了旧事件,因为旧事件必填的 kind 在新 schema 里不存在。
- parse_old_event_with_v2:一条旧事件(id、kind)按 v2 schema 解析,缺失的可选字段 detail、trace_id 用默认值 ’no’/’none’ 补齐。这就是旧事件能在新消费者侧被处理的具体机制:可选字段缺失时给默认值,不让解析失败。
两个值得点破的细节:
- 双向不对称在输出里一目了然。 v1_v3 是
{'backward': False, 'forward': True},v1_v4 是{'backward': True, 'forward': False}——同样"不兼容",方向完全相反。这正是必须双向检查的原因:单测"有没有破坏"会漏掉一半。 - 默认值是向前兼容的实现前提。 新消费者能处理旧事件,不是因为旧事件字段齐全,而是因为缺失的可选字段有默认值。没有默认值,向前兼容就只能靠"新消费者接受缺字段",容易在解析层就崩。
事件 schema 的演进策略,生产里常见的做法是兼容演进优先,破坏演进显式化。绝大多数需求都能用"新增可选字段 + 默认值"满足,这两条一起保证双向兼容。破坏性演进(新增必填、移除必填)不是不能做,而是要做成显式事件:发布新版本、给旧调用方迁移窗口、跑兼容测试。
| 策略 | 适用 | 代价 |
|---|---|---|
| 新增可选 + 默认值 | 大多数演进 | 无 |
| 新增必填 | 新语义必须强要求 | 破坏向后,要迁移 |
| 移除必填 | 废弃旧字段 | 破坏向前,要兼容 |
还有一个实践细节:schema 版本号要写进事件本身。事件带上 schema_version 字段,消费者就能用版本号分派解析逻辑,而不是从字段形状反推版本。字段形状反推在字段增减频繁时会猜错,显式版本号没有歧义。
兼容测试也要自动化。给每个历史 schema 版本生成测试用例:旧事件按新 schema 解析必须成功、新事件按旧 schema 解析必须不崩溃(缺字段有默认值)。这套测试跑在每次 schema 变更时,破坏性演进在合并前就被拦住,而不是等线上消费者报错。
事件协议的投递语义是版本兼容之外的另一个设计面。一次投递可能丢失、可能重复:
| 语义 | 表现 | 实现 |
|---|---|---|
| at-most-once | 可能丢 | 发完即忘 |
| at-least-once | 可能重复 | 重试到确认 |
| exactly-once | 不丢不重 | 幂等消费 + 去重 |
大多数事件协议用 at-least-once 换取简单,然后用消费者幂等把重复变成无害。消费者的幂等靠事件本身携带的幂等键(如 event_id)——消费前先查重,重复事件直接忽略。去重表是 at-least-once 落地的另一半。
投递语义与 schema 兼容还要配合:事件升级版本后,旧消费者不能崩溃、新消费者要能处理旧事件——这依赖 6.3 的双向兼容检查。一个事件协议的可信度,由"投递不丢"与"解析不崩"两个维度共同构成。 两个维度各有各的机制:重试保证投递,默认值保证解析。
版本兼容的自动化还有一个实践:契约测试生成。 每次 schema 变更,从所有历史版本自动生成双向兼容测试——旧事件按新 schema 解析、新事件按旧 schema 解析,两个方向都要断言。生成而非手写,避免"这个历史版本太老,就不测了"的侥幸。
| 生成用例 | 输入 | 断言 |
|---|---|---|
| 旧事件→新 schema | 历史事件样例 | 解析成功或默认值补齐 |
| 新事件→旧 schema | 新 schema 样例 | 旧消费者能读(可选字段) |
| 破坏性变更 | 必填字段变化 | 显式失败并标记 breaking |
兼容性管理与发布流程绑定:schema 变更走"版本号递增 → 契约测试 → 灰度 → 全量"的路径。破坏性变更要单独发版、给迁移窗口、记录在事件流里。兼容性不是跑一次测试就完,是每次发布都要重新验证的持续约束。
还有一个边界认知:兼容检查保证"能解析",不保证"语义正确"。 新消费者能解析旧事件,不代表它理解旧语义——字段含义变了但名字没变,解析成功但业务解读错误。所以语义变更要走新字段/新版本,不在同名同字段下偷偷改含义。解析兼容是底线,语义兼容是纪律。
事件协议的消费者再投递(replay):消费端处理事件失败(解析失败、业务失败),怎么补偿?事件流留存历史(Kafka 一类),失败事件可以回溯再消费。再投递需要事件带"全局可重复的 ID"与"消费进度标记",才能精确重放到失败点。事件协议不只是"发出去了",还隐含"能重新处理"。
| 投递机制 | 防丢失 | 防重复 | 可回溯 |
|---|---|---|---|
| 发完即忘 | 否 | 是 | 否 |
| 确认+重试 | 部分 | 可能重复 | 部分 |
| 留存+再投递 | 是 | 幂等兜底 | 是 |
再投递与幂等消费是配套:重放历史事件时,消费者必须靠幂等键去重(见 6.3 投递语义),否则重放=重复副作用。“能重放"是事件协议的高阶能力,它依赖 at-least-once 的留存与 exactly-once 语义的幂等消费,两者缺一不可。
版本兼容的一个边界认知:兼容测试通过 ≠ 生产兼容。 契约测试保证"字段级解析兼容”,但生产兼容还依赖调用方的实际行为(消费者是否忽略未知字段、是否按默认值补齐)。兼容测试是底线,生产兼容要靠灰度验证——新版本先对部分消费者灰度,观察真实解析行为,再全量。
| 验证层次 | 内容 | 场景 |
|---|---|---|
| 契约测试 | 字段级解析 | CI 门禁 |
| 灰度 | 部分消费者真实解析 | 上线前 |
| 全量 | 全部消费者 | 稳定后 |
事件 schema 的文档化与版本化要同步:schema 变更后,事件文档(字段含义、示例)跟着更新,旧版本文档可查。schema 是代码,文档是它的发布产物——事件文档与 schema 脱节,消费者只能靠读代码猜语义。契约单一权威(5.1)在事件协议里同样适用:schema 源驱动,文档与测试从它生成。
事件协议的超时与重试语义也要写进规范:消费者多久没收到期待的事件算超时、超时后怎么处理(重试、补偿、放弃),双方要有共识。超时语义缺失,双方各自猜——生产里最典型的"消息静默丢失"多半是超时口径不一致。事件协议要连失败语义一起协议化。
版本兼容的"最终一致性"提醒:演进期新旧消费者并存,读到的事件版本不同,行为可能有短暂差异。这不是协议缺陷,是演进的常态——兼容协议接受"演进期不一致",只要两边解析都不崩、语义不冲突。评估兼容性时要有这个预期,别把演进期的正常差异当故障。
架构判据
事件 schema 演进是否合格,用五条判据检查:
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 双向检查 | 向后/向前分别验证 | 只测一个方向 |
| 新增可选 | 新字段可选,双向兼容 | 新字段必填,破坏向后 |
| 保留旧必填 | 旧必填字段不删 | 移除必填字段破坏向前 |
| 默认值补齐 | 缺失可选字段有默认值 | 缺字段直接解析失败 |
| 兼容门禁 | 破坏性演进被发布前检出 | 破坏上线后才暴露 |
判据第一条是本节核心:兼容性检查必须同时覆盖向后与向前两个方向。 判据第四条提醒:向前兼容不能只靠"接受缺字段",要真的给默认值,解析才能稳定。
小结
- 向后兼容指新事件能被旧消费者处理;向前兼容指旧事件能被新消费者处理;两个方向不能混。
- 新增可选字段双向兼容;新增必填字段破坏向后;移除必填字段破坏向前。
- 兼容检查要用字段集合分别验证两个方向,单测"有没有破坏"会漏一半。
- 缺失可选字段用默认值补齐,是向前兼容在解析层的实现机制。
阅读导航:上一节:6.2 A2A:Agent 间协作协议 · 下一节:7.1 上下文组装:系统、任务、记忆、工具 。
常见错误与边界
- 只测向后兼容。 移除必填字段只破坏向前;不测向前,删字段的破坏上线后才暴露。
- 新增字段必填。 新增必填字段破坏向后;新字段要么可选,要么当成破坏性版本处理。
- 删旧必填字段。 旧必填字段在新 schema 缺失,新消费者处理不了旧事件;要保留或给默认值。
- 默认值缺席。 可选字段没有默认值,解析缺字段就崩;向前兼容要真给默认值。
- 把"接受缺字段"当向前兼容。 新消费者要能处理旧事件,靠默认值而非容忍解析失败。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。