A2A HTTP+JSON 绑定怎么配：代理卡端点与调用验证
A2A 的 HTTP+JSON 绑定，核心只有一件事：让代理卡（Agent Card）里声明的端点地址，真正能接收符合 A2A 消息格式的 POST JSON 请求，并返回任务状态。
配置是否正确，不靠看文档判断，靠一次实际请求验证。
下面按“先定端点、再写服务、最后联调”的顺序说明。
适合已经有一张 Agent Card、准备接入 HTTP 传输的代理服务，不涉及从零实现整个 A2A 协议栈。
先确认代理卡里的端点声明
A2A 代理卡用 JSON 描述代理身份和通信方式。
HTTP+JSON 绑定下，需要关注两个字段：
url：客户端实际 POST 的地址，必须是完整可访问 URL，例如https://agent.example.com/a2a。protocolBinding或传输声明：标明使用 HTTP+JSON，不同实现字段名可能略有差异，以你使用的 SDK 或规范版本为准。
一个最小化的端点声明示意：
{
"name": "demo-agent",
"url": "https://agent.example.com/a2a",
"protocolBinding": "HTTP+JSON",
"capabilities": {}
}易错点：url 不要写成相对路径，也不要带尾部斜杠后又在服务端做重定向。
客户端通常不会跟随 301/302 重新 POST，容易表现为 404 或空响应。
服务端要处理的请求格式
HTTP+JSON 绑定要求客户端以 Content-Type: application/json 发送 POST 请求，请求体至少包含任务消息。
不同 A2A 版本字段结构可能不同，但联调时可以先抓一个最小请求体：
{
"jsonrpc": "2.0",
"id": "req-001",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{ "type": "text", "text": "你好" }]
}
}
}如果你的实现不是 JSON-RPC 风格，而是直接 POST 任务对象，则以实际 SDK 为准。
关键是服务端路由要能解析这个 JSON，并返回 JSON 响应，而不是 HTML 错误页。
服务端路由注册示例（以常见 Web 框架伪代码表示，路径与你的代理卡 url 保持一致）：
POST /a2a -> a2a_handler
Content-Type 必须为 application/json处理函数里先读取请求体，校验 message 字段是否存在，再交给代理业务逻辑。
不要在这一层做重定向或返回 204 空响应，否则客户端拿不到任务状态。
用 curl 验证绑定是否生效
配置完成后，不要直接接客户端，先用 curl 发一次请求。
把地址换成你代理卡里的 url：
curl -i -X POST 'https://agent.example.com/a2a' \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":"req-001","method":"message/send","params":{"message":{"role":"user","parts":[{"type":"text","text":"ping"}]}}}'预期结果是 HTTP 200 或 202，响应体为 JSON，包含任务 ID 或消息回执。
如果返回 404，说明路径没对上；
返回 415，说明服务端没接受 application/json；
返回 422 或 400，通常是请求体字段缺失。
验证通过的标准：状态码在 2xx，响应 Content-Type 为 JSON，且响应体里能看到与请求 id 对应的结果或任务标识。
三者缺一，都不算绑定完成。
联调时最容易踩的三个坑
第一个坑是代理卡 url 和实际路由不一致。
改完服务端路径后忘了同步更新代理卡，客户端仍请求旧地址。
排查时直接看代理卡 JSON 里的 url，再对照服务端访问日志。
第二个坑是反向代理截断了请求体。
Nginx 默认 client_max_body_size 可能偏小，消息体较大时返回 413。
可以在对应 location 中调大限制并重载：
location /a2a {
client_max_body_size 10m;
proxy_pass http://127.0.0.1:8080;
}第三个坑是服务端把 JSON 解析错误包装成 500。
联调阶段建议在服务端日志中记录原始请求体长度和解析异常，但不要记录完整敏感内容。
看到 500 时先查应用日志，而不是反复改客户端。
配置完成后的复查清单
- 代理卡
url是完整 HTTPS 地址，且与服务端路由一致。 - 服务端只接受 POST，并正确解析
application/json。 - curl 请求返回 2xx 且响应体为 JSON。
- 反向代理没有改写路径或拦截请求体。
- 客户端使用的端点来自代理卡，而不是硬编码的另一份地址。
如果以上都通过，HTTP+JSON 绑定基本可用。
后续再接入真实客户端时，保持同一份代理卡和同一套请求格式，就能减少环境差异带来的问题。
