A2A Agent Card 配置怎么写：从字段填写到端点验证
A2A 协议里，每个代理都要先发布一张 Agent Card，用 JSON 描述自己是谁、能做什么、任务提交到哪个地址。
配置卡片的本质不是写文档，而是让调用方能在不读源码的情况下发现你的代理并正确发起任务。
下面按字段、写法、验证三部分讲清楚。
先确认卡片放在哪里、由谁读取
Agent Card 通常是一个静态 JSON 文件，放在代理服务的公开路径下，例如：
https://your-agent.example.com/.well-known/agent-card.json路径本身没有强制规定，但客户端需要知道去哪里取。
常见做法是在代理根路径或 /.well-known/ 下暴露固定文件名，并在项目文档里写明。
配置前先确认两件事：
- 该路径能通过公网或内网被调用方访问，不需要登录。
- 返回的
Content-Type是application/json。
如果卡片放在需要鉴权的接口后面，调用方拿不到卡片，后续任务端点再正确也无法完成发现流程。
逐字段填写 Agent Card
一个最小可用的卡片至少包含代理标识、版本、能力和任务端点。
下面是一份示例，字段名按 A2A 协议常见写法组织，实际以你使用的 SDK 或规范版本为准：
{
"name": "order-query-agent",
"description": "查询订单状态与物流信息",
"version": "1.0.0",
"url": "https://your-agent.example.com/a2a",
"capabilities": {
"streaming": false,
"pushNotifications": false
},
"skills": [
{
"id": "query-order",
"name": "查询订单",
"description": "根据订单号返回状态",
"inputModes": ["text/plain"],
"outputModes": ["application/json"]
}
]
}几个容易填错的地方：
name和version用于调用方识别代理，改名或升级时同步更新，避免缓存旧卡片。url必须是任务实际接收地址，不能填前端页面或文档地址。capabilities声明要和服务端真实能力一致。声明了streaming却返回普通 JSON，客户端会按流式读取而失败。skills的id在同一张卡片内唯一，调用方可能按 id 选择技能。
端点地址与卡片声明保持一致
卡片里的 url 要和代理服务实际监听的路径对齐。
例如服务端路由是 /a2a，卡片就写 /a2a；
如果前面有反向代理做了路径重写，以外部可访问的最终地址为准。
配置完成后先在本机验证：
curl -i https://your-agent.example.com/.well-known/agent-card.json预期看到 200 OK、Content-Type: application/json，响应体能被 JSON 解析器正常解析。
再用同样的地址测试任务端点是否可达：
curl -i -X POST https://your-agent.example.com/a2a \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","method":"tasks/send","id":1,"params":{}}'这里只验证端点是否返回 JSON-RPC 结构，不要求业务参数完整。
如果返回 404 或 405，先检查反向代理转发规则和 HTTP 方法是否放行。
上线前检查这几项
- 卡片文件不要带 BOM，部分 JSON 解析器会因此报错。
- 修改卡片后确认 CDN 或代理缓存已刷新，否则调用方可能读到旧版本。
- 卡片中不要写入内部主机名、内网 IP 或测试凭据。
- 如果代理有多个环境，按环境分别发布卡片，避免测试地址混入生产。
常见疑问
Agent Card 必须放在 /.well-known/ 下吗？ 不是强制要求，但固定路径便于调用方发现。
关键是调用双方对地址有一致约定。
卡片里的 url 可以写相对路径吗？ 不建议。
调用方通常按绝对地址发起请求，相对路径容易因解析基准不同而指向错误位置。
修改能力声明后需要重启服务吗？ 卡片是静态文件时不需要重启，刷新文件即可；
如果卡片由服务动态生成，则按服务发布流程处理。
调用方报找不到代理，先查什么？ 先确认卡片 URL 能直接访问并返回 JSON，再核对卡片中的 url 与任务端点实际地址是否一致。
