A2A Agent Card

A2A Agent Card 是 Agent2Agent（A2A）server 发布的 JSON metadata 文档，告诉 client agent：远端 agent 是谁、service endpoint 在哪里、支持哪些 protocol interfaces 与 capabilities、提供哪些 skills，以及 client 应如何认证。

只有 card 后面真的存在 A2A 服务时，它才有价值。大多数 blog、营销站和普通 SaaS 文档站并不需要 Agent Card。

Card 描述哪些内容

实现应以实际支持的 A2A 规范版本为准。关键部分包括：

区域	作用
Identity	名称、description、provider 与 version
Service URL 与 interfaces	A2A client 从哪里、通过什么方式通信
Capabilities	streaming、push notifications 等可选能力
Skills	具名任务、description、modes 与 examples
Authentication	支持的 schemes 与凭据取得方式
Input/output modes	agent 可接收和返回的 media types

Card 只是能力声明，不能证明 server 行为正确。Client 与 server 仍需验证 requests、执行授权并处理不支持的 operations。

发现方式

当前 A2A discovery 指南记录了三类方式：

1. Well-known URI： 公开 server 可提供 https://example.com/.well-known/agent-card.json。
2. Registry 或 catalog： 企业或公共 registry 按自己的治理规则返回 cards。
3. Direct configuration： client 预先配置已知 card URL 或文档。

公开发现并不总是合适。如果 card 含敏感能力或组织信息，应保护 endpoint，或提供需认证、选择性披露的 card。JSON 内绝不能放静态 secrets。

网站什么时候真的需要它

以下条件同时成立时才应发布：

• 已部署 A2A server，并接受协议兼容交互。
• 至少一个 advertised skill 对应真实、受支持的任务。
• Authentication 与 authorization 已实施。
• Endpoint、protocol version、modes 与 capability flags 已测试。
• 有团队负责监控、更新与 incident response。

网站有 chatbot、API、MCP server 或 AI 文章，并不自动代表需要 A2A Agent Card；它们可能是完全不同的系统。

与相邻概念的区别

• Agent Skill package： 给兼容 runtime 的可复用 instructions。
• MCP server： 通过 MCP 暴露 tools 与 resources。
• OpenAPI description： 描述 HTTP operations。
• A2A Agent Card： 描述远端 A2A agent 以及交互方法。

应根据真实部署的服务选择接口，而不是把所有格式都发布一遍。

运营与安全评审

• Skill description 必须具体到 client 能拒绝不匹配任务。
• 只声明 server 真正实现的 capabilities。
• 使用最小权限 scopes，并逐项授权请求动作。
• 用 access control 保护 extended 或敏感 card。
• 适当设置 Cache-Control、ETag 等 HTTP caching headers。
• Interfaces、skills、认证或 version 改变时同步更新 card。
• 分开监测 card availability 与 task success。

完整决策框架见A2A Agent Card：网站何时需要 Agent-to-Agent Discovery。相关条目包括 Agent Skills Index、MCP Server Card 与 Auth.md 与 OAuth Metadata。

验证清单

1. 从文档化的发现位置获取 card。
2. 按实际支持的 A2A version 验证 JSON 与必需字段。
3. 确认 interfaces 和 modes 与 server 一致。
4. 为每个 published skill 测试一个 request。
5. 测试不支持的 capabilities 与授权失败。
6. 确认没有暴露 secrets 或私有信息。
7. 修改 version 后验证 cache refresh 行为。

一手来源

• A2A protocol specification
• A2A agent discovery guidance