AI Agent Engineer

AI Agent Engineer

离线 A2A 合同验证项目

6 min read

离线 A2A 合同验证项目

项目目标

构建一个只依赖 Python 标准库的验证器，对教学 fixture 执行三类检查：

  1. A2A 1.0 Agent Card 的必需字段、接口版本与 Part/Skill 基线；
  2. Task 快照序列的 ID、Context、状态转换和完成 Artifact；
  3. 对 0.3 结构混入、终态回退和 Part one-of 错误的失败关闭。

证据边界

本项目只验证课程明确实现的结构和本地状态策略。它没有启动官方 SDK，没有验证 JSON-RPC/gRPC/HTTP+JSON wire 行为、TLS、JWS、OAuth、webhook、流式顺序、真实 TCK 或跨供应商互操作，因此不能称为 A2A conformance test。

项目文件

  • examples/a2a_contract_validator.py：合同与状态验证器；
  • examples/a2a_cases.json：一组有效与三组故意失败用例；
  • examples/test_a2a_contract_validator.py：离线回归测试。

运行方式

从仓库根目录执行：

python -B "docs\A2A\examples\a2a_contract_validator.py" --cases "docs\A2A\examples\a2a_cases.json" # 用离线场景验证 Agent Card、Task 与 Artifact 合同；-B 不生成缓存
python -B "docs\A2A\examples\test_a2a_contract_validator.py" # 运行 A2A validator 的回归测试，检查正负向合同边界

不需要安装依赖、联网、密钥或付费账户。成功时 CLI 会逐项打印 PASS，测试应报告 10 个用例通过。

有效 Agent Card 的本地基线

验证器要求：

  • name、description、Agent version 非空；
  • supportedInterfaces 至少一项，生产 URL 使用 HTTPS；
  • 每个接口声明 JSONRPC、GRPC、HTTP+JSON，或使用绝对 HTTP(S) URI 标识自定义 binding；后者是本项目为便于安全检查采用的更窄策略，官方规范本身要求使用 URI 标识；
  • 本课程基线固定 protocolVersion: "1.0"；
  • capabilities 为对象；
  • 默认输入/输出媒体类型和 skills 非空；
  • 每个 skill 具有 id/name/description/tags。

部分要求是 A2A 1.0 必需字段，HTTPS 与固定 1.0 也是本项目的部署/教学策略。验证错误会明确标注是本地基线，避免把项目策略伪装成协议原文。

输入读取还会拒绝重复 JSON 字段与非标准数值；Part 的 raw 成员必须是可解码的 Base64。这样能避免解析器静默覆盖前值，也避免把“非空字符串”误当成已经验证的字节载荷。

Task 快照策略

fixture 使用同一 Task 的连续快照演示状态变化。验证器要求：

  • Task ID 和 contextId 在序列中不变化；
  • 状态必须使用 A2A 1.0 枚举；
  • 终态不能回到工作态；
  • COMPLETED 至少有一个 Artifact；
  • Artifact 有 ID 与 Part；
  • 每个 Part 只设置 text/raw/url/data 之一。

真实协议并不要求客户端把全部状态保存成这类 JSON 数组；这是为了让状态与负向测试可以离线复现。

四类 fixture

用例预期验证重点
valid-v1-contract通过1.0 Card、工作→完成、结构化 Artifact
reject-v03-shape失败顶层 URL、旧小写状态和 kind Part
reject-terminal-regression失败COMPLETED 后回到 WORKING
reject-ambiguous-part失败同一 Part 同时含 text 与 data

为什么测试错误信息

只断言“返回失败”容易让实现用错误原因碰巧通过。fixture 还声明 expectedErrors，CLI 与测试会确认相应错误片段确实出现。例如 reject-v03-shape 必须同时暴露接口结构、状态枚举和旧 Part 三类迁移问题。

扩展练习

  1. 增加 securitySchemes/securityRequirements 的本地部署策略，但标明哪些不是协议必需字段；
  2. 增加流事件 one-of、Artifact chunk 聚合和重复事件测试；
  3. 为 URL Part 增加 scheme、域名、解析 IP 和重定向策略；
  4. 用两个不同语言的官方 SDK 建立客户端/服务端矩阵，并把结果与本项目离线验证分开报告；
  5. 接入官方 Inspector/TCK 时，保存工具版本、规范版本、命令与原始结果摘要。

掌握检查

  • 能说明本地策略与规范强制要求的差别；
  • 能解释每个负向 fixture 阻止了什么迁移或安全问题；
  • 能新增错误用例而不放宽已有失败关闭；
  • 能列出从本项目升级到真实互操作测试仍缺少的证据。

参考资料

Backlinks