Schema 合规性（A2A v1.0）
对照 v1.0 规范检查必填字段：name、description、version、带有每接口 protocolBinding 和 protocolVersion 的 supportedInterfaces、capabilities、内容模式，以及至少一个带有必填标签的技能。
A2A Agent Card 校验器
Agent Card 校验器会对照 A2A v1.0 的发现要求，检查粘贴的 JSON、上传的 Agent Card 文件以及公开的智能体 URL。
使用 Agent Card 校验器
粘贴 JSON 或公开智能体 URL，或将 JSON 文件拖入编辑器。
Agent Card 校验器覆盖范围
在客户端发现你的智能体之前，Agent Card 校验器会检查什么。
Agent Card 校验器专为发布 A2A 智能体的开发者、审核智能体元数据的内部平台团队，以及检查提交的 Agent Card 是否包含足够信息以便可靠调用的市场运营方而设计。
开发期间粘贴本地 JSON 文档，从代码仓库上传 Agent Card，或者对已部署的域名使用实时 URL 校验来验证公开发现路径。
语义与迁移问题
检测 v1.0 之前的结构——顶层的 url、preferredTransport、protocolVersion、provider.name、stateTransitionHistory——并准确告诉你每个字段在 v1.0 中迁移到了何处。
安全与密钥扫描
验证非公开端点是否声明了 securitySchemes 和安全要求，标记非 HTTPS 的 URL，并扫描看起来像内嵌 API 密钥、JWT 或 bearer token 的值。
发现就绪性
从真实域名获取 /.well-known/agent-card.json 和旧版 /.well-known/agent.json，并确认两者都返回可解析的 Agent Card JSON。
校验适用于哪些环节
在每个阶段校验：编辑器、CI 流水线、生产域名。
上个月通过审核的 Agent Card 今天仍可能导致发现失败——端点变更、技能改变，或者一次重新部署丢失了 well-known 路由。平台团队和市场审核方将校验视为可重复的关卡，而不是一次性检查。
最简单的 CI 防护只需要 curl：在流量切换到新部署之前，确认 well-known 路径返回可解析的 JSON。
# deploy pipeline: fail if the published card breaks
curl -fsS https://your-domain/.well-known/agent-card.json \
| python3 -c '
import json, sys
card = json.load(sys.stdin)
assert card.get("name"), "name is required"
assert card.get("supportedInterfaces"), "supportedInterfaces missing"
assert card.get("skills"), "skills missing"
print("agent card OK:", card["name"])'修复指南
常见的 Agent Card 修复
先用 Agent Card 校验器的报告解决必填字段，再改善发现性、信任度和迁移细节。
把占位符端点 URL 替换为已部署的 HTTPS A2A 服务 URL。
把顶层的 url 和 preferredTransport 移入一个有序的 supportedInterfaces 数组——第一项是首选接口。
添加描述智能体本身所需的顶层 version 字段，并为每个技能添加标签。
将 provider.name 重命名为 provider.organization，并扩展简短的描述，让客户端知道何时调用该智能体。
只要智能体端点不是完全公开的，就声明安全元数据——并且永远不要嵌入凭据本身。
在 /.well-known/agent-card.json 发布同一份有效的 Agent Card（在客户端仍会检查两个路径期间，也发布到旧版 agent.json 路径）。
校验器针对哪个 A2A 版本？
检查遵循 A2A v1.0 的 Agent Card 结构——supportedInterfaces、每接口协议版本、必填的技能标签、provider.organization。v1.0 之前的 Agent Card 不会被直接拒绝：遗留字段会以警告形式出现，并给出确切的 v1.0 替代方案。
为什么要检查两个 well-known URL？
v1.0 规范注册了 /.well-known/agent-card.json，但更早的 A2A 实现使用的是 /.well-known/agent.json。同时检查两者能在客户端失败之前发现发现性缺口。
警告可以忽略吗？
警告不会阻塞式地报错，但通常指向能让智能体更容易被发现、信任和调用的元数据——或者指向较新客户端将不再读取的 v1.0 之前字段。
什么时候应该运行校验？
三个时刻：开发期间编辑 Agent Card 时、部署前作为 CI 关卡时，以及发布之后——粘贴生产服务 URL 以确认客户端实际从两个发现路径中获得的内容。
准备好校验
在客户端发现之前，校验你的 Agent Card。
在统一的校验器工作区中粘贴 JSON、放入 Agent Card 文件，或检查公开 URL。