网站可以描述内容、API 和工具，但这不代表网站本身就是一个 agent。
只有当产品运营一个可被其他 agent 发现、评估并派发任务的 remote agent 时，A2A Agent Card 才真正有意义。例如能够解决工单的客服 agent、完成预订的 booking agent，或创建交付物并返回 artifacts 的 workflow agent。
如果 card 背后没有真实可用的 A2A 服务，发布它只会制造虚假的 capability signal。
这篇指南把 A2A Agent Card wiki 扩展成实施与复查流程，并连接 API Catalog SEO、Auth.md 与 OAuth Metadata、Agent Skills Index 和 Agent SEO audit。
Agent Card 到底做什么
A2A specification 把 Agent Card 定义为 A2A server 的公开说明。兼容客户端用它判断 remote agent 是否适合某项任务，以及应该如何与它通信。
当前公共 discovery 地址是：
https://agent.example.com/.well-known/agent-card.json
官方项目在 0.3 版本线把旧的 /.well-known/agent.json 改为 /.well-known/agent-card.json。新实现不应继续复制旧示例。
一份 Agent Card 应回答五个实际问题：
| 问题 | Card 区域 | 实际意义 |
|---|---|---|
| 谁在运营这个 agent？ | 名称、description、provider、文档 | 客户端能确认服务身份并找到人工支持 |
| 它在哪里接收任务？ | supportedInterfaces | 客户端能选择兼容的 protocol binding 与 endpoint |
| 它能做什么？ | Capabilities 与 skills | 客户端能把任务匹配到已声明能力 |
| 它接收和返回什么格式？ | Input 与 output modes | 客户端能准备 message 与预期 artifact |
| 访问需要什么条件？ | Security schemes 与 requirements | 客户端能通过正确的外部流程取得凭证 |
Card 是 discovery metadata，不是 agent 实现、权限授予或任务一定成功的证明。
发布前先做适用性判断
添加 Agent Card 之前，先使用这张决策表：
| 产品情况 | A2A 适用度 | 更应该先做什么 |
|---|---|---|
| 只有文章、没有 callable agent 的内容站 | 低 | 维护 crawlability、sitemap、内链和可读文档 |
| 有普通 REST API，但没有 A2A task endpoint 的 SaaS | 低 | 视情况发布 API docs、OpenAPI 与 API catalog |
| 有可复用 prompts 或能力，但没有 remote A2A server | 低到中 | 先用 Agent Skills Index 描述能力 |
| 能接收 inter-agent tasks 的客服、预订、commerce 或 workflow agent | 高 | 实现 A2A 服务并发布 Agent Card |
| 仅供指定合作方使用的企业私有 agent | 高 | 使用直接配置或私有 registry，并落实 access control |
公共发现上线前，应同时满足三个条件：
- Publisher 已部署并拥有真实 A2A endpoint。
- 每项 skill 都有支持的 task path、输入契约与失败处理。
- Authentication、authorization、rate limit、日志和人工升级路径已经能处理外部调用。
只要有一项不满足，就先修服务。Metadata 无法让不安全或未完成的 agent 自动 ready。
建立保守的 Public Card
准确 schema 应跟随当前 A2A 规范，并使用最新官方 SDK 生成或验证。简化后的公共 card 可以是：
{
"name": "Example Support Agent",
"description": "Handles order-status questions and creates support cases.",
"version": "1.4.0",
"documentationUrl": "https://example.com/docs/support-agent",
"supportedInterfaces": [
{
"url": "https://agent.example.com/a2a/v1",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0"
}
],
"capabilities": {
"streaming": false,
"pushNotifications": false,
"extendedAgentCard": true
},
"defaultInputModes": ["text/plain", "application/json"],
"defaultOutputModes": ["text/plain", "application/json"],
"skills": [
{
"id": "create-support-case",
"name": "Create a support case",
"description": "Creates a case after the user confirms the summary.",
"tags": ["support", "case-management"],
"examples": ["Open a case for my damaged delivery"]
}
]
}
这只是编辑示例，不能替代 schema validation。协议字段会演进，线上服务必须与 card 完全一致。
避免“什么都能处理”或“自动化你的业务”这类模糊 skill。描述应围绕可观察的任务边界，让客户端知道需要什么资料、可能执行什么操作，以及何时必须取得用户确认。
分开 Public 与 Extended Capabilities
Public card 是可以直接获取的 discovery metadata。不要把 credentials、内部 hostname、隐藏工具、客户 identifier、private prompt 或 privileged workflow 放进去。
A2A 规范支持 authenticated extended Agent Card。当 capabilities.extendedAgentCard 为 true 时，已认证客户端可以在通过声明的 security scheme 获取凭证后，请求内容更丰富的 card。
两层信息应有明确边界：
| Public card | Authenticated extended card |
|---|---|
| 服务身份和公开文档 | 合作方或角色专属 skills |
| 公共 protocol interfaces | 受保护 workflow details |
| 安全的 capability 摘要 | 认证后可见的附加限制或配置 |
| Authentication requirements | 授权给当前客户端的信息 |
Authentication 不能替代 authorization。服务仍需检查 scopes、tenant 边界、task ownership，以及调用方是否有权执行每个动作。Card 应连接 Auth.md 与 OAuth Metadata 中的标准发现机制，而不是嵌入 secrets。
发布、缓存与验证
使用四阶段流程：
- Inventory。 记录 live endpoint、protocol binding 与版本、skills、modes、security requirements、文档 owner 和 escalation path。
- Publish。 在 A2A server domain 通过 HTTPS 的
/.well-known/agent-card.json提供公共 JSON。 - Protect。 不把敏感能力放进 public card，在服务端实施 authentication 与 authorization；只有存在真实 access-control model 时才使用 extended card。
- Revalidate。 每次 endpoint、skill、protocol、authentication 或部署变化后重新测试 card。
规范建议使用普通 HTTP caching。设置合理的 Cache-Control 与 ETag，客户端就能用 conditional request 避免反复下载未变化的 card。
curl -i https://agent.example.com/.well-known/agent-card.json
curl -I https://agent.example.com/.well-known/agent-card.json
确认以下项目全部通过：
- URL 通过 HTTPS 正常返回 JSON。
- Response 通过当前 Agent Card schema validation。
- 每个
supportedInterfacesURL 都能连接到声明的 A2A service。 - Protocol bindings 与 versions 和线上实现一致。
- Skills 描述真实支持的任务，而不是 roadmap promise。
- Security schemes 与线上 authorization 配置一致。
- Public card 中没有 secret 或内部实现细节。
Cache-Control、ETag和更新行为符合预期。- 文档和人工 escalation routes 可用。
Agent Card 也可以使用 JWS 签名。如果启用签名，应遵循规范的 canonicalization 与 verification 要求；客户端无法验证的装饰性 signature field 不会增加信任。
对 SEO 团队意味着什么
Agent Card 能让兼容客户端更容易发现真实 A2A 服务。这是 infrastructure outcome，不是 SEO ranking claim。
它不会：
- 保证 Google 收录、排名、AI 引用或 referral traffic；
- 自动让普通网站内容更容易理解；
- 替代 sitemap、内链、结构化内容、API 文档或 technical SEO；
- 把普通 chatbot widget 变成 A2A server；
- 证明声明的 agent 安全、准确或已获授权。
SEO 和内容团队仍有明确职责：让公共文档可发现，把 discovery asset 链接到正确产品页面，避免 capability claim 过期，并把协议变化交给 engineering 与 security owners。
用 Technical SEO 和 Bot Simulator 检查更广泛的公共表面；用 Agent SEO audit 盘点 discovery signals，然后用 protocol-aware 与 security tests 单独验证 A2A 服务。
下一步行动
如果产品已有 live remote agent，安排 product、engineering、security 与 content 联合复查：
- 确认 agent 确实接收 A2A tasks。
- 把每个 public skill 映射到已经测试的 workflow 与 owner。
- 在当前 well-known URI 发布最小且准确的 public card。
- 把 privileged capabilities 放在 authenticated discovery 与 authorization 后面。
- 加入 deployment checks，避免 card 与服务发生 drift。
如果产品没有运营 A2A server，就停在清晰文档这一步。不要为了显得 agent-ready 而发布 Agent Card。
Sources
- A2A Protocol Specification
- A2A Agent Discovery Guide
- A2A Project Releases
- RFC 8615: Well-Known Uniform Resource Identifiers
- RFC 7515: JSON Web Signature
- RFC 9111: HTTP Caching
问答
每个网站都需要 A2A Agent Card 吗？
不需要。只有产品运营能接收其他 agents 任务的 A2A 兼容 agent 时，它才有意义。纯内容站应优先做好普通 crawlability 与文档。
A2A Agent Card 应发布在哪里？
当前 A2A 规范使用 https://{server-domain}/.well-known/agent-card.json 做公共发现。使用 /.well-known/agent.json 的旧示例属于 legacy pattern。
Agent Card 会提升 SEO 排名或 AI 引用吗？
不会。Agent Card 是供兼容 A2A 客户端使用的协议发现文档，不保证收录、排名、引用、流量或 agent adoption。
