如何让 a2a-js 与 v0.3 旧版智能体双向兼容:legacyCompat 架构完整指南

原创2026-11-12 16:12:361,934 阅读

如何让 a2a-js 与 v0.3 旧版智能体双向兼容:legacyCompat 架构完整指南

a2a-js 是 A2A(Agent2Agent)协议的官方 JavaScript SDK,当前实现 A2A Protocol v1.0 规范。当你的服务已升级到 v1.0,但网络上仍有许多 v0.3 旧版智能体尚未迁移时,SDK 内置的 legacyCompat 兼容层 让你无需双份部署,即可与新旧两代客户端/服务端互相通信。本文面向新手,讲清楚这套兼容机制如何工作、如何开启、以及哪些数据在版本转换中会丢失。

一、为什么需要 v0.3 兼容层?

A2A 协议从 v0.3 升级到 v1.0 时,方法命名(如 message/send → SendMessage)、数据字段(如 content[] → parts[])、HTTP 头与 Content-Type 都发生了破坏性变化。实际迁移中,客户端群和服务端群很少"齐步走",典型场景有:

  • 🏢 你运行 v1.0 服务端,需要继续接受 v0.3 客户端的分阶段迁移流量
  • 📱 你写 v1.0 客户端,但要对讲的某些智能体仍在其 Agent Card 中声明 v0.3
  • 🚀 灰度发布:希望一个可部署产物同时处理两个版本,而不是跑两套二进制

兼容层是**按需开启(opt-in)**的迁移桥:开启 legacyCompat: { enabled: true } 后,SDK 会自动在"线上 v0.3 报文"和"进程内 v1.0 类型"之间来回翻译,你的 AgentExecutor 业务代码永远只面对 v1.0 类型。完整用户指南见 docs/compatibility-v0_3.md,架构级说明见 src/compat/v0_3/README.md。

二、兼容层整体架构:六个子路径入口

兼容层全部位于 src/compat/v0_3/ 目录下,按"每个入口只携带自己必需的 peer 依赖"的原则拆分为 6 个子路径导出。这样只需要 JSON-RPC 客户端兼容传输的 Cloudflare Workers 用户,永远不会被拖入 Node 专属模块:

子路径 用途 Peer 依赖
@a2a-js/sdk/compat/v0_3 v0.3 协议常量与方法名翻译器 无(Workers 安全)
@a2a-js/sdk/compat/v0_3/server 框架无关的传输处理器、推送通知工厂、LegacyA2AError 无
@a2a-js/sdk/compat/v0_3/server/express Express 路由(legacyAgentCardRouter、legacyRestRouter) express
@a2a-js/sdk/compat/v0_3/server/grpc legacyGrpcService + LegacyA2AService 描述符 @grpc/grpc-js
@a2a-js/sdk/compat/v0_3/client LegacyJsonRpcTransport、LegacyRestTransport、卡片解析助手 无
@a2a-js/sdk/compat/v0_3/client/grpc LegacyGrpcTransport(仅 Node,惰性加载) @grpc/grpc-js

核心内部结构分三块:

  1. types/ — v0.3 的三套数据表示:由 v0.3 JSON Schema 生成的 TypeScript 接口(types/types.ts)、仅含 JSON 转换的 protobuf 绑定(types/pb/a2a.ts,Workers 安全)、以及带 gRPC 编解码与服务绑定的运行时(grpc/pb/a2a.ts)。
  2. translate/ — v1.0 proto ↔ v0.3 JSON 的双向翻译器,按实体分组:parts.ts、messages.ts、tasks.ts、agent_card.ts、security.ts 等,统一从 translate/index.ts 导出。命名约定是方向锚定的:toCore<Entity> 表示 v0.3 → v1.0,toCompat<Entity> 表示 v1.0 → v0.3。
  3. 方法名映射表 — 定义在 constants.ts 中,例如:
v0.3 JSON-RPC 方法 v1.0 方法名 v0.3 gRPC 方法名
message/send SendMessage SendMessage
message/stream SendStreamingMessage SendStreamingMessage
tasks/get GetTask GetTask
tasks/resubscribe SubscribeToTask TaskSubscription
agent/getAuthenticatedExtendedCard GetExtendedAgentCard GetAgentCard

三、服务端兼容配置:让 v1.0 服务接受 v0.3 流量

在 v1.0 的 Express 处理器上设置 legacyCompat: { enabled: true } 即可,且粒度是逐处理器、逐传输的——你可以只让 JSON-RPC 接口兼容,而让 REST 保持严格 v1.0。开启后路由是全自动的,各传输的 v0.3 识别方式如下:

传输 v0.3 流量的识别方式
JSON-RPC 检查请求体 method 字段:PascalCase 的 v1.0 方法名(SendMessage 等)走 v1.0 分发器;其余一切——kebab 风格 v0.3 名称(message/send)、未知方法、甚至没有 method 字段——都路由到 v0.3 分发器,让错误请求暴露 v0.3 形态的错误码
REST v0.3 路由位于 /v1/... 前缀下,v1.0 路由直接用 /<operation>,Express 前缀匹配天然消歧
gRPC 两个版本是独立的服务描述符(A2AService vs LegacyA2AService),客户端连哪个就是哪个,无需嗅探
Agent Card 读取 A2A-Version 请求头(缺失时默认按 v0.3 处理),返回对应形态的卡片,并附带 Vary: A2A-Version 响应头

⚠️ 一个易错点:gRPC 的 v1.0 工厂刻意不提供 legacyCompat 选项。v0.3 gRPC 客户端需要单独导入 legacyGrpcService,与 v1.0 grpcService 并排注册在同一个 gRPC Server 上。这样做是为了让纯 v1.0 部署者不把 @grpc/grpc-js 拉进依赖图。REST 处理器的兼容路由器挂载逻辑见 rest_handler.ts。

v0.3 广播是逐接口声明的:某个绑定只有在 Agent Card 中以 protocolVersion: '0.3' 声明了对应的 AgentInterface,v0.3 客户端才能访问它。推荐用 duplicateInterfacesForLegacy 助手把每个绑定在 v1.0 和 v0.3 各声明一次(幂等,支持选择性地排除某些绑定,比如 gRPC 只留 v1.0),定义在 translate/agent_card.ts。

另外,你传给处理器的 contextBuilder(租户、鉴权、请求 ID 注入)对每个请求都会执行,无论线上走的是 v1.0 还是 v0.3,业务代码完全无感。

四、客户端兼容配置:让 v1.0 客户端连通 v0.3 服务器

客户端侧使用同一个 legacyCompat: { enabled: true } 标志,但要分别设在每个传输工厂和卡片解析器上(ClientFactory 本身不接收该选项,刻意与服务端逐处理器开关的设计保持镜像):

const factory = new ClientFactory(
  ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
    cardResolver: new DefaultAgentCardResolver({ legacyCompat: { enabled: true } }),
    transports: [
      new JsonRpcTransportFactory({ legacyCompat: { enabled: true } }),
      new RestTransportFactory({ legacyCompat: { enabled: true } }),
      new GrpcTransportFactory({ legacyCompat: { enabled: true } }),
    ],
  })
);
const client = await factory.createFromUrl(serverUrl); // 对 v1.0 / v0.3 服务器都"开箱即用"

开启后两件事自动发生:

  1. 卡片自动识别与归一化。DefaultAgentCardResolver 用启发式判断卡片形态:纯 v0.3 卡片(顶层有 url 而无 supportedInterfaces<a href="https://link.gitcode.com/i/a529872f6dba3a02d1cadf1502e09997" target="_blank">],或 protocolVersion 落在 [0.3, 1.0) 区间)会被翻译成 v1.0 表示,且每个合成的 AgentInterface 都打上 protocolVersion: '0.3' 戳记;混合卡片(同时有 v0.3 顶层字段和 supportedInterfaces[])则直接按 v1.0 处理,避免不必要的降级。检测逻辑见 [card-resolver.ts。
  2. 传输工厂按版本选择实现。每个工厂的 create() 查看匹配接口的 protocolVersion,若落在 <a href="https://link.gitcode.com/i/aad398705ec34596900ab7307fb71822" target="_blank">0.3, 1.0) 区间就实例化对应的 Legacy 传输(如 [LegacyJsonRpcTransport 分支),否则使用原生 v1.0 传输。标志关闭时,Legacy 传输在运行时根本不会被构造。

版本判断的唯一权威实现是 isLegacyVersion:空值/空白版本按 v0.3 处理(对应 A2A 规范 §3.6.2 "无版本头即 v0.3" 的规则),否则解析版本号并与 [0.3, 1.0) 区间比较。

五、推送通知兼容:按 webhook 注册版本路由

推送通知是兼容层中最精细的部分。规则:webhook 收到什么形态的报文,取决于它注册时的线上版本,而不是触发事件的那次请求的版本。

webhook 注册时的版本 报文形态 Content-Type
1.0 StreamResponse 信封 application/a2a+json
0.3(或注册时无 A2A-Version 头) 完整的 v0.3 Task 快照(状态/产物触发)或裸 v0.3 Message,按 kind 字段区分 application/json

实现上由两部分协作(见 push_notification 目录):

  • 存储层记录版本:InMemoryPushNotificationStore 在 save() 时读取 context.requestedVersion,与配置一起持久化,并通过可选的 loadWithMetadata 方法暴露出来。
  • 发送端按版本路由:用 createLegacyAwarePushNotificationSender 构建发送器(它会预注册 V03PushNotificationSerializer 到 '0.3' 键),替代直接构造默认发送器。

⚠️ 自定义 PushNotificationStore 的坑:loadWithMetadata 是可选方法。如果你的自定义 store 没实现它,发送端会退化为"用触发请求的版本"来决定报文形态——这意味着 v0.3 客户端注册的 webhook 可能收到 v1.0 报文(反之亦然)。照抄 InMemoryPushNotificationStore 的三行实现即可修复。另外注意:v0.3 的状态/产物触发会合并为当前 Task 快照下发(与 v0.3 规范 §9.5 的示例一致),而不是裸的 TaskStatusUpdateEvent。

六、兼容边界:哪些数据过不了"往返"

即使开启兼容层,两个版本也并非字节等价。以下是开启前必须知道的取舍(详见 兼容性指南 的 Caveats 章节):

v1.0 字段/能力 v1.0 → v0.3 转换行为
ListTasks 方法 ❌ v0.3 完全没有此 RPC,调用直接失败为 UnsupportedOperationError(JSON-RPC 码 -32004)。需要跨版本任务枚举时,用 transport.protocolVersion 判断后再决定调用
OAuthFlows.deviceCode 静默丢弃(v0.3 无对应概念);若它是唯一声明的流,v0.3 卡片收到空的 OAuthFlows 对象
PushNotificationAuthenticationInfo.schemes(数组) v0.3 → v1.0 方向只保留第一个元素并给出警告;反方向单值包装为单元素数组
TaskStatusUpdateEvent.final(v1.0 已移除) v1.0 → v0.3 方向按状态计算:completed/canceled/failed/rejected 为 true,其余为 false
returnImmediately ↔ blocking 极性反转:returnImmediately: true ↔ blocking: false
Part.content.$case 判别字段 翻译为 v0.3 各 Part 上的 kind: 判别(text/file/data),文件 URI 与字节字段一一对应

REST 线上形态也有细微差别:v0.3 请求体字段是 request、消息负载是 content[]、Content-Type 为 application/json;v1.0 分别是 message、parts[]、application/a2a+json。还有两个行为约定值得记住:

  • 📡 tasks/resubscribe 永远以 SSE(text/event-stream + HTTP 200)应答,即使底层调用立即失败——错误会作为流内 SSE 错误事件发出,因为严格的 v0.3 客户端拒绝其他形态;
  • 版本头缺失时一律按 v0.3 处理(规范 §3.6.2),这正是兼容层默认兜底 v0.3 的原因。

七、相关示例与延伸阅读

项目内有两个可直接运行的完整示例,值得动手跑一遍:

  • 服务端全家桶:compat-v1-server — 一个共享 DefaultRequestHandler 同时挂在 JSON-RPC、REST、gRPC(A2AService 与 LegacyA2AService 并排注册)、Agent Card 端点及推送通知之后,卡片用 duplicateInterfacesForLegacy 双重声明绑定
  • 客户端双版本对接:compat-v1-client — 同一进程内同时跑 v1.0 与 mock-v0.3 对端,演示混合卡片优先读 supportedInterfaces[] 的接收逻辑

延伸阅读(均为仓库内文档,建议配合阅读):

资料 路径
用户视角兼容性指南 docs/compatibility-v0_3.md
兼容层架构级说明 src/compat/v0_3/README.md
v0.3 旧版 gRPC 绑定构建说明 src/compat/v0_3/grpc/README.md
v0.3 → v1.0 迁移指南 docs/migration-guide.md

📌 最后的提醒:兼容层是按需开启的临时桥梁,一旦存量 v0.3 客户端全部迁移到 v1.0,即可(也应当)关闭它——关闭后 v0.3 代码路径会退出你的依赖图与测试矩阵。如果你的所有对端都已说 v1.0,保持严格模式就是最简单的部署。

登录后查看全文
a2a-js