A2A 代理如何绑定 JSON-RPC 端点并完成联调

A2A 的 JSON-RPC 绑定配置，本质上是两件事：在代理卡（Agent Card）里把 url 指向真正接收请求的 HTTP 端点，并让这个端点按 JSON-RPC 2.0 的格式收发消息。
只要这两点对上，客户端就能发现代理并完成一次任务调用；
对不上时，通常表现为 404、方法不存在或响应解析失败。

本文按“先约定契约、再配端点、最后验证排错”的顺序展开，适合刚接触 A2A 协议、需要把代理接入客户端的运维和开发人员。

先明确绑定的边界

JSON-RPC 绑定不是配置一个数据库连接串，而是约定客户端和代理之间的通信契约。
需要先确认三件事：

• 代理对外暴露的基地址，例如 https://agent.example.org，以及 JSON-RPC 路径，例如 /a2a。
• 代理卡中声明的协议版本、能力（capabilities）与实际实现一致。
• 端点只接受 POST，请求体是 JSON，Content-Type 为 application/json。

代理卡里的 url 字段应当直接指向 JSON-RPC 端点，而不是站点首页。
如果客户端拿到代理卡后向首页发 POST，返回的往往是 HTML 或 405，而不是 JSON-RPC 响应。

代理卡中的端点声明

一个最小可用的声明片段如下，字段名以协议规范为准，实际字段可能随版本调整：

{
  "name": "demo-agent",
  "version": "1.0.0",
  "protocolVersion": "<对应协议版本>",
  "url": "https://agent.example.org/a2a",
  "capabilities": {},
  "skills": []
}

配置时重点检查 url：它必须和 Nginx、网关或应用实际监听的路径完全一致，包括是否带结尾斜杠。
路径不一致是最常见的绑定失败原因之一。

发出一个合法的 JSON-RPC 请求

JSON-RPC 2.0 请求体至少包含 jsonrpc、method、params、id 四个字段。
下面是一个用于验证端点是否在线的请求样例，方法名请替换为目标代理实际支持的方法：

curl -i -X POST https://agent.example.org/a2a \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"<代理支持的方法>","params":{}}'

预期结果是 HTTP 200，响应体为 JSON，并且带有与请求一致的 id。
如果返回 200 但内容是 HTML，说明请求被反向代理或前端路由拦截，没有到达 JSON-RPC 处理逻辑。

反向代理与路径的常见坑

很多绑定问题出在代理层而不是应用层，配置时需要留意：

• Nginx 的 location 必须把请求转发到后端应用，而不是静态目录；转发时保留原始路径，避免应用侧路由匹配不到。
• 如果启用了 HTTPS，确认客户端访问的是 https:// 且证书链完整，否则部分客户端会直接拒绝连接。
• 网关若做了请求体大小或超时限制，长任务可能被提前断开，需要按任务时长调整。
• 不要在代理层改写 Content-Type，否则应用可能把 JSON 当成表单处理。

修改代理配置后，先执行 nginx -t 检查语法，再平滑重载，避免直接重启造成中断。

验证绑定是否真正生效

联调阶段建议按顺序验证，而不是一上来就跑完整任务：

1. 用 curl 请求代理卡地址，确认能拿到 JSON 且 url 字段正确。
2. 对上一步拿到的 url 发一个最小 JSON-RPC 请求，确认返回 JSON 且 id 一致。
3. 逐步补充 params，直到能触发一次真实任务。
4. 检查服务端日志，确认请求确实进入了 JSON-RPC 处理方法，而不是被默认路由吞掉。

如果第二步就失败，问题基本在端点或代理层；
如果第二步通过、第三步失败，问题多在方法名、参数结构或任务处理逻辑。

常见报错怎么定位

• 404 Not Found：url 路径与实际路由不一致，检查结尾斜杠和前缀。
• 405 Method Not Allowed：端点只接受 POST，确认没有用 GET 测试。
• Method not found：method 名称拼写错误或代理未注册该方法，对照代理实现确认。
• Parse error：请求体不是合法 JSON，常见于命令行引号转义错误。
• 版本不匹配：代理卡声明的协议版本与端点实现不一致，按规范对齐后再重试。

排错时优先看服务端访问日志和错误日志，确认请求是否到达、以什么状态码返回，再决定改代理还是改应用。

绑定配置完成后，建议把代理卡地址和 JSON-RPC 端点路径记录在部署文档里，后续更换域名或调整路由时能快速定位影响范围。