如何让 a2a-js 与 v0.3 旧版智能体双向兼容:legacyCompat 架构完整指南
如何让 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 |
核心内部结构分三块:
types/— v0.3 的三套数据表示:由 v0.3 JSON Schema 生成的 TypeScript 接口(types/types.ts)、仅含 JSON 转换的 protobuf 绑定(types/pb/a2a.ts,Workers 安全)、以及带 gRPC 编解码与服务绑定的运行时(grpc/pb/a2a.ts)。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。- 方法名映射表 — 定义在 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 服务器都"开箱即用"
开启后两件事自动发生:
- 卡片自动识别与归一化。
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。 - 传输工厂按版本选择实现。每个工厂的
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,保持严格模式就是最简单的部署。