AG-UI 跨语言测试固件解析:null 省略契约与 AgentCapabilities 模型如何锁死多 SDK 线上格式
AG-UI 跨语言测试固件解析:null 省略契约与 AgentCapabilities 模型如何锁死多 SDK 线上格式
导读
AG-UI(Agent-User Interaction Protocol)同时维护着 TypeScript、Python、.NET 三套官方 SDK,而它们各自又有自己偏好的序列化行为——最典型的差异是:TypeScript 的 JSON.stringify 天然丢弃 undefined,Python 与 .NET 的序列化器却默认写出 null。如果每一套 SDK 各写各的测试,线上格式的分歧只会越漂越远。本文要讲的 sdks/fixtures/ 目录,就是 AG-UI 为这个跨语言一致性问题给出的答案:把一份「线上格式期望」只写一次,让三个 SDK 的测试全部去消费同一份 JSON 文本。读完本文,你将掌握 AG-UI 的 null 省略(null omission)契约、AgentCapabilities 模型的生成与收敛机制,以及如何为这套跨语言测试体系接入新的消费者。
目录:为什么要有跨语言固件
sdks/fixtures/ 下的固件(fixture)被多于一个 AG-UI SDK 共享。它们的定位写得很直白:一份线上格式(wire-format)期望只书写一次,每个 SDK 都被同一段文本约束,而不是每个 SDK 在自家测试树里保存一份会逐渐漂移的副本(见 sdks/fixtures/README.md)。
固件的形态是不带任何语言假设的纯 JSON。只服务于单一实现、永远不会被别的 SDK 消费的固件,仍然留在各自 SDK 的测试目录里。当前目录下只有两个固件文件,各自锁定协议中最容易产生分歧的两类问题:
| 文件 | 锁定的问题 |
|---|---|
| null-omission.json | 生产者无值时必须省略字段,而不是写 null |
| agent-capabilities.json | 由单一 schema 生成的能力模型,三个 SDK 的线上形状必须一致 |
null-omission.json:一份写了三遍代价的契约
契约内容与由来
null-omission.json 规定的契约是:生产者没有值时,要把该字段从 JSON 中省略,而不是写成 null。
这条规则之所以值得用固件钉死,是因为三个 SDK 在这件事上天生不对称:
- TypeScript「免费」获得该行为——
JSON.stringify会自动丢弃undefined; - Python 与 .NET 默认的序列化器都会写出
null,需要显式处理。
README 里记录了一段真实的历史教训:这个分歧曾迫使协议侧连续打了三个接收端容忍补丁才在源头修复——TOOL_CALL_START.parentMessageId、TOOL_CALL_CHUNK.parentMessageId、RUN_FINISHED.outcome 至今仍兼容 null,以照顾仍在发送 null 的老生产者。固件的作用就是把正确行为钉死,避免再出现第四个补丁。
固件结构
每个用例是一条 { name, producedBy, note, input, expected } 记录,多个用例按时间顺序组成 stream,可以当作一段连贯的事件流自上而下阅读:
{
"stream": [
{
"name": "run_finished_without_result_or_outcome",
"producedBy": ["typescript", "python", "dotnet"],
"note": "why this case is here",
"input": {
"type": "RUN_FINISHED",
"threadId": "thread_1",
"runId": "run_1"
},
"expected": {
"type": "RUN_FINISHED",
"threadId": "thread_1",
"runId": "run_1"
}
}
]
}
字段语义:
name:用例名,同时作为各 SDK 测试中子测试的标题;producedBy:声明哪些 SDK 执行该用例。它只服务于某个 SDK 确实没有实现的事件类型,绝不是某个 SDK 用例失败的逃生舱。当前null-omission.json的全部 32 个用例都把三个 SDK 列全了——chunk 事件曾是最后的例外,如今 .NET 也已经实现。如果确实需要缩短列表,必须在note里写清缺失 SDK 到底缺什么,以便它补齐后删除该条目;note:解释这个用例为什么存在,是维护者之间沟通意图的载体;input:生产者侧的输入;expected:经过官方生产路径(事件编码器 / SSE 格式化器)重新序列化后,必须逐字节等价的 JSON。
每个 SDK 如何执行这份固件
各 SDK 测试遍历 stream,只处理 producedBy 里包含自己的用例,流程完全一致:
- 把
input反序列化为 SDK 原生事件类型; - 通过 SDK 的官方生产者路径(事件编码器 / SSE 格式化器)重新序列化;
- 断言产出的 JSON 解析后精确等于
expected。
因为 expected 是精确匹配,所以:多写一个多余的 null 会失败;契约要求携带的 null(比如元数据里的某个值、状态快照里的值、JSON Patch 操作里的值)缺失也会失败。
消费者一览
以 TypeScript 侧实现为例,它先用 omitOptionalNulls(entry.input, "Event") 按已知协议形状预处理输入,再经 EventSchemas.parse 校验、EventEncoder().encode 编码,最后把 SSE 帧载荷 data: ... 解析出来与 expected 比对(null-omission.test.ts):
const event = EventSchemas.parse(omitOptionalNulls(entry.input, "Event"));
const encoded = new EventEncoder().encode(event);
const payload = JSON.parse(encoded.slice("data: ".length, -"\n\n".length));
expect(payload).toEqual(entry.expected);
固件之外的「全量扫描」:两种测试抓不同的东西
值得注意:跑固件只是检查了点名的字段。每个 SDK 还额外拥有一套反射驱动的全量测试——遍历 SDK 定义的所有线上类型(wire type),对任何契约不允许的 null 直接失败。这套测试故意不维护字段清单:一个新可选字段声明的那一刻,它就被自动覆盖了。
Python 侧的 TestNullOmissionSweep 是典型实现(test_null_omission.py):它反射收集 types_module、events_module、capabilities_module 里所有 ConfiguredBaseModel 子类,为每个模型构造「只填必填字段」的探针实例,序列化后扫描所有 JSON 路径上的 null,再减去契约允许保留 null 的必填任意-JSON 字段路径。更妙的是配套的 TestNullOmissionIsTheBaseModelsDoing——它通过覆写某个类的 wrap serializer 把省略行为「还原」掉,验证 parentMessageId: null 立刻回归,从而证明全量扫描之所以通过,确实是基类序列化器在起作用,而不是测试本身空转(test_null_omission.py)。
README 的结论很明确:新增一个固件用例不能替代全量扫描——「两者抓的是不同的东西」。固件验证各 SDK 相互一致,全量扫描验证协议自身没有漏洞。
为固件接入新消费者:构建系统与 CI 的双重接线
固件目录位于每个 SDK 项目目录之外,这会带来两个隐蔽的工程问题,README 花了专门篇幅说明。
问题一:构建缓存看不见目录变化
只按项目目录决定重跑范围的构建系统,不会注意到目录外的固件被修改——如果处理不当,一次固件编辑会留下「过期的绿色结果」(stale green)。三种 SDK 的处理方式各不同:
- .NET:把固件作为
EmbeddedResource链接进测试项目(见AGUI.Abstractions.UnitTests.csproj)。MSBuild 会跟踪EmbeddedResource项,变更能被感知; - Python:由
unittest直接运行,没有缓存层,无需处理; - TypeScript:运行在 Nx 之下,而 Nx 只对
{projectRoot}/**/*做test目标缓存,本目录不在其中。因此@ag-ui/encoder在自己的package.json中把nx.targets.test.cache设为false——该套件运行不足一秒,永远重跑比承担过期缓存的风险更划算。这一点可在 sdks/typescript/packages/encoder/package.json 中直接看到"cache": false的实际配置。
README 还记录了一个被验证失败的替代方案:把 {workspaceRoot}/sdks/fixtures/**/* 加进 nx.json 中 test 目标的 inputs——在 Nx 22.5.0 下 {workspaceRoot} 输入无法到达哈希器,作者用仓库根目录的受控对照文件验证过:改了文件任务哈希却不变。所以结论是不要再在这条路上浪费时间,直接关掉消费项目的缓存。
问题二:CI 触发器的缺失
固件目录同样不在 .github/workflows/unit-*.yml 的任何路径列表里。曾经存在过一个真实的坑:某次 PR 只改了固件,结果没有任何 SDK 的测试 job 被触发——不是完全没有 job,typecheck-typescript.yml 通过通配的 sdks/** 条目匹配到了目录并编译了整个工作区,但编译不可能因固件内容失败,真正会执行这些文档的测试一个都没跑。修复方式是三个 unit workflow 的 push 与 pull_request 过滤器都显式加上 sdks/fixtures/**;新增第四种 workflow 的消费者时,需要同样的配置行。
省略与保留的分界线:整字段 null 与嵌套 null
null-omission.json 把「省略」规则精确化为三层,这是理解整个契约的钥匙:
第一层:可选整字段为 null = 不存在,必须省略
一个整个可选字段被设为 null 表示「不存在」,包括可选的任意-JSON 载荷。生产者必须省略该字段,schema 要求省略而非显式 null。适用范围包括:rawEvent、run 与 subagent 的 result、工具 parameters、resume payload、run 输入里的 state 与 forwardedProps、media-part 的 metadata。这条规则在三个 SDK 中一致。
对应的固件用例 run_started_input_with_bare_null_state_converges_on_omission 验证:RUN_STARTED.input.state: null 读取为「无状态」,三个 SDK 都重新输出为省略——这是所有表示法共用的唯一拼写。
第二层:必填任意-JSON 字段保留整个 null 值
必填的任意-JSON 字段允许携带完整的 null 值:STATE_SNAPSHOT.snapshot、RAW.event、CUSTOM.value,以及 JSON Patch add/replace/test 操作的 value。.NET 的 CUSTOM.value 即使类型可空,也不改变这个要求——其序列化器显式保留 null。而 ACTIVITY_SNAPSHOT.content 是必填对象,任何 SDK 写出整字段 null 都是非法的。
固件中 state_snapshot_that_is_entirely_null_stays_null 与 raw_event_payload_that_is_entirely_null_stays_null 两个用例专门钉死这一点。README 点出关键认知:规则锚定在「可选性」上,而不是「值是否为 null」上——snapshot 是必填字段,所以 snapshot: null 是生产者断言的取值;省略它反而会丢一个必填键。
第三层:允许对象/数组内部的 null 是数据,原样保留
任何允许位置内嵌套的 null 仍然是数据,必须存活。例如:可选的 result: null 被省略,而 result: {"selectedId": null} 被完整保留;同样的区分适用于 metadata 键下的 null、状态对象/数组内部的 null。state_snapshot_keeps_nulls_inside_the_snapshot、state_delta_keeps_a_null_patch_value(RFC 6902 用 replace-with-null 清空字段)、run_finished_with_explicit_optional_nulls 等用例都验证了这层行为。
值得一提的反向用例是 activity_snapshot_with_replace_set:它验证的不是 null 省略,而是 replace 字段的显式书写——三个 SDK 对「缺失的 replace 是否在线上默认 true」有分歧,这是与 null 省略正交的另一个一致性问题,同样被固件锁死。
agent-capabilities.json:能力模型的去漂移之锚
从手写副本漂移到单一 schema 生成
AgentCapabilities 在 spec/1.0/schema.json 中只定义一次,为每个 SDK 生成。在 1.0 之前,各 SDK 各自维护手写副本,已经出现三处分歧:
- .NET 把
identity.metadata和custom类型化为字典,而其他 SDK 携带开放的 JSON; - 三个 SDK 都把子代理列表拼成
subAgents,而协议其余部分(如subagentRunId)统一用单词subagent拼写。
固件钉住生成模型的线上形状,让三者无法再次漂移。
固件结构
结构与 null 固件同构,cases 数组下每条是 { name, producedBy, note, input, expected }:
{
"cases": [
{
"name": "partial_as_a_real_producer_declares",
"producedBy": ["typescript", "python", "dotnet"],
"note": "why this case is here",
"input": {
"identity": { "type": "langgraph" },
"transport": { "streaming": true }
},
"expected": {
"identity": { "type": "langgraph" },
"transport": { "streaming": true }
}
}
]
}
执行协议同样是三步:解析 input 为 SDK 的 AgentCapabilities 模型 → 走 SDK 官方 JSON 路径序列化 → 断言结果精确等于 expected。expected 是精确的,因此:未设置的可选成员以 null 出现会失败;任何 SDK 为输入遗漏的组「发明」一个值也会失败——省略意味着未声明(undeclared),任何 SDK 都不得填充。
四个用例与 spec 固件的双向映射
固件的四个用例不是随手写的,它们与 spec/1.0/fixtures/AgentCapabilities/valid/ 下的四个文档一一对应,由 spec/harness/fixtures.test.ts 中的 SPEC_FIXTURE_FOR 映射表在双向断言:
| 共享固件用例 | spec 固件文档 | 验证重点 |
|---|---|---|
full_every_group_populated |
full.json | 每个组、每个字段,包括两个开放 JSON 成员(identity.metadata、custom)和单词 subagents 键 |
minimal_nothing_declared |
minimal.json | 什么也不声明的声明是合规的;未声明≠不支持 |
partial_as_a_real_producer_declares |
partial.json | langgraph 集成的真实声明:四个组,其余保持沉默 |
open_values_may_be_null |
open-values-null.json | 开放键成员下的 null 值是数据,必须原样保留 |
partial.json 的内容即为 langgraph 集成实际声明的样子(identity、humanInTheLoop、state、transport 四组,其余完全不出现):
{
"identity": { "type": "langgraph" },
"humanInTheLoop": {
"supported": true,
"interrupts": true,
"approveWithEdits": true
},
"state": { "snapshots": true, "deltas": false, "persistentState": true },
"transport": { "streaming": true }
}
fixtures.test.ts 的关键断言是:共享固件的每个 input/expected 与 spec 固件解析后值完全相等——expect(c.input).toEqual(spec)——允许两份副本的格式与键序不同,但任何值都不得不同。此外它还断言映射是双向满射:共享固件用例集合与 SPEC_FIXTURE_FOR 的键集合排序后相等,spec 目录下的文件名集合与值集合排序后相等,杜绝任一侧漂移。
开放键成员的特殊处理
AgentCapabilities 里有两类成员性质完全不同:
identity.metadata与custom是按键开放(open-by-key)的成员:null作为这些成员下的值是数据,协议要求 MUST 保留,open_values_may_be_null用例把三个 SDK 都约束在「原样携带」上。但成员本身(custom: null这种)永远不允许为 null——schema 把它们类型化为「可缺席但出现时绝不 null」的对象。- 其余所有位置:null 只可能是「未设置的可选成员拼写错误」,任何
expected文档中出现都直接失败。
三个 SDK 的测试都实现了这个区分。TypeScript 侧用 OPEN_BY_KEY = new Set(<a href="https://link.gitcode.com/i/55725b94f7a475a821fd92da609f3875" target="_blank">"metadata", "custom"]) 跳过对开放成员的递归扫描,同时仍检查成员本身是否为 null,并用三个控制用例钉死该分支([agent-capabilities-fixture.test.ts)。.NET 侧的 AssertNoNulls 遍历同样跳过 metadata/custom 键,并对「开放键位置出现 null」抛出异常(AgentCapabilitiesFixtureTest.cs)。
消费者一览
几个值得注意的实现细节:
- .NET 走 AOT 序列化路径:用例通过 source-generated 的
AGUIJsonSerializerContext(SSE 格式化器、protobuf 格式化器、HTTP 传输共用的 AOT 路径)反序列化与序列化,并单独跑一遍仅以DefaultTypeInfoResolver为唯一解析器的通道——让能力类型缺失时抛异常而非悄悄退回反射,避免产生「无法通过裁剪测试的绿色结果」(AgentCapabilitiesFixtureTest.cs)。 - Python 侧锁死 camelCase 与单词语法:
test_capabilities.py断言所有线上键都是 camelCase、无任何下划线泄漏,multiAgent是整体单词而非multiModal,子代理列表是单词subagents(旧的subAgents键与sub_agents属性均不复存在,只保留类名SubAgentInfo作为一版内的弃用别名)(test_capabilities.py)。 - 省略锚定 None 而非假值:
ExecutionCapabilities(code_execution=False, max_iterations=0)序列化后codeExecution: false与maxIterations: 0必须保留——省略只针对None,false和0是真实取值(test_capabilities.py)。
固件的反真空(anti-vacuity)设计
这套测试体系有一个贯穿始终的设计原则:防止固件悄悄变空或失效。空固件会让所有 [Theory]/it.each 用例「因从不运行而通过」,这是测试体系最大的假阳性来源:
- null 固件的每个 SDK 测试都断言用例数
> 15; - capabilities 固件的每个 SDK 测试都断言所有用例都覆盖本 SDK(
producedBy不能遗漏),且expected文档中不存在任何 null; spec/harness/fixtures.test.ts额外维护了一份提交在仓库里的MANIFEST.txt清单,双向断言固件目录的实际文件集合与清单完全一致——删除固件会成为 diff,新增固件漏登记也会失败(fixtures.test.ts);- 还有针对关闭对象(
unevaluatedProperties: false)定义的 closure probe:给已验证通过的文档加一个协议未声明的属性,必须被拒绝(fixtures.test.ts)。
如何查看与运行这套测试
仓库只读,你可以在本地查看与运行这些固件测试来验证跨语言一致性:
- TypeScript:
sdks/typescript/packages/encoder与sdks/typescript/packages/core下运行测试套件(Nx 工作区中对应项目的test目标,encoder 因固件在项目目录外已显式关闭缓存); - Python:
sdks/python下执行python -m unittest tests.test_null_omission tests.test_capabilities(或经uv/pytest 运行); - .NET:在
sdks/dotnet下运行AGUI.Abstractions.UnitTests项目,NullOmissionFixtureTest与AgentCapabilitiesFixtureTest会通过EmbeddedResource读取固件; - spec 侧:
spec/harness下的fixtures.test.ts负责校验固件与 spec 文档的双向映射。
小结
sdks/fixtures/ 用两个文件回答了两个跨语言难题:null-omission.json 把「无值即省略」的契约连同三层边界(可选整字段省略、必填任意-JSON 字段保留 null、嵌套 null 是数据)固化下来,终结了「三个接收端容忍补丁」的历史;agent-capabilities.json 把由单一 schema 生成的模型锁死在同一份线上形状上,并保持与 spec/1.0/fixtures/AgentCapabilities/valid/ 的四文档双向映射。再加上构建缓存接线、CI 触发器、反射全量扫描与反真空断言,这套体系保证了三个 SDK 的线上格式不是「三个各自以为正确的信念」,而是一条可验证、可追溯、经得起三方对账的单一契约。