AG-UI 跨语言测试固件解析:null 省略契约与 AgentCapabilities 模型如何锁死多 SDK 线上格式

原创2026-09-21 12:06:361,425 阅读
文章标签:人工智能AI AgentAgent 框架API设计后端前端MCP 服务AI 技能

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 里包含自己的用例,流程完全一致:

  1. 把 input 反序列化为 SDK 原生事件类型;
  2. 通过 SDK 的官方生产者路径(事件编码器 / SSE 格式化器)重新序列化;
  3. 断言产出的 JSON 解析后精确等于 expected。

因为 expected 是精确匹配,所以:多写一个多余的 null 会失败;契约要求携带的 null(比如元数据里的某个值、状态快照里的值、JSON Patch 操作里的值)缺失也会失败。

消费者一览

SDK 测试文件
TypeScript sdks/typescript/packages/encoder/src/tests/null-omission.test.ts
Python sdks/python/tests/test_null_omission.py
.NET sdks/dotnet/tests/AGUI.Abstractions.UnitTests/NullOmissionFixtureTest.cs

以 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)。

消费者一览

SDK 测试文件
TypeScript sdks/typescript/packages/core/src/tests/agent-capabilities-fixture.test.ts
Python sdks/python/tests/test_capabilities.py
.NET sdks/dotnet/tests/AGUI.Abstractions.UnitTests/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 的线上格式不是「三个各自以为正确的信念」,而是一条可验证、可追溯、经得起三方对账的单一契约。

登录后查看全文
ag-ui