/.well-known/agent-card.json
A2A v1.0 规范注册的 well-known URI。新客户端会优先获取此路径；请以 application/a2a+json 内容类型提供服务。
发现工具 · A2A v1.0
检测 A2A Agent Card 发现 URL
A2A 客户端通过从 well-known URL 获取 JSON Agent Card 来发现智能体。在真实域名上同时检测两种命名约定，看看客户端实际会收到什么。
基于同一个根域名构建两个候选发现 URL。
获取返回的 JSON，并报告状态码和内容类型。
尽可能将响应解析为 Agent Card JSON。
对接口、技能、提供方、模式、能力与安全元数据运行就绪性检查。
检测一个公开的智能体域名
输入一个根域名。检测工具会获取两个发现路径、解析返回的 JSON，并运行 Agent Card 就绪性检查。
发现机制是如何工作的
一个 well-known URL，启动每一次 A2A 集成。
在另一个智能体调用你的服务之前，它会先从你域名下的 well-known URI（RFC 8615）获取 Agent Card，评估技能与安全要求，然后调用首选接口。如果 Agent Card 缺失、过期或被重定向隐藏，集成在开始之前就已经失败。
本站以身作则：AgentCard.net 在两个路径上都发布了自己的 Agent Card，右侧展示的就是真实文档。
查看我们的实时 Agent Cardagentcard.net discovery
GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "AgentCard.net Toolkit",
"version": "1.0.0",
"supportedInterfaces": [
{ "url": "https://www.agentcard.net/api/agent-card",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0" }
],
"skills": [
{ "id": "generate-agent-card", ... },
{ "id": "validate-agent-card", ... },
{ "id": "check-well-known-discovery", ... }
]
}发现路径
两种约定，同一份 Agent Card。
/.well-known/agent.json
早期 A2A 实现与代码实验示例使用此路径。许多已部署的客户端仍只检测这个路径，因此在此提供相同 Agent Card 是安全的过渡策略。
发布模式
让 Agent Card 发现更具韧性。
发现失败通常并不复杂：一次重定向、一个被缓存的错误页面，或者只部署了一个路径而忘记了另一个。这套发布流程能让两种约定始终提供同一份最新 Agent Card。
- 1
在标准路径上发布
在与 A2A 服务相同的域名上，通过 HTTPS 在 /.well-known/agent-card.json 提供经过审核的 Agent Card，内容类型为 application/a2a+json。
- 2
镜像旧版路径
在旧版客户端仍在使用期间，从 /.well-known/agent.json 返回完全相同的文档——两个路径上的 Agent Card 不一致会扰乱路由。
- 3
保持 Agent Card 同步
每当端点、技能、能力或身份验证发生变化时，更新 Agent Card、提升其 version 字段，并同时重新部署两个路径。
- 4
每次变更后重新检测
在部署、DNS 变更、网关迁移或市场资料编辑之后运行此检测工具。故障通常源于重定向、HTML 错误页面，或有一个路径被遗忘。
常见问题
Well-known Agent JSON 常见问题
该发布什么、发布在哪里，以及如何让两种约定的客户端都能正常工作。
应该使用哪个 well-known Agent Card 路径？
A2A v1.0 将 /.well-known/agent-card.json 注册为标准发现路径。旧版的 /.well-known/agent.json 早于 v1.0，但仍被许多已部署的客户端检测，因此在过渡期间在两个路径上发布同一份 Agent Card 是务实的选择。
两个路径应该返回完全相同的 JSON 吗？
应该。从两个路径返回同一份公开 Agent Card，可以让只支持其中一种约定的客户端保持一致。文档不一致会让智能体看起来因客户端获取的路径不同而不同。
Agent Card 应该以什么内容类型提供服务？
规范为 Agent Card 注册了 application/a2a+json。实践中普通的 application/json 也被广泛接受，但如果内容类型是 HTML，通常说明该路径返回的是错误页面而不是 Agent Card。
公开的 Agent Card 可以隐藏私有能力吗？
可以。在公开 Agent Card 中只发布对发现安全的元数据，将 capabilities.extendedAgentCard 设为 true，并通过经过身份验证的 GetExtendedAgentCard 操作暴露敏感技能。
为什么部署之后发现检测会失败？
常见原因包括重定向到登录页或营销页、以状态码 200 返回的 HTML 404 页面、CDN 缓存的过期 JSON，或者两个 well-known 路径中只部署了一个。检测工具会为每个路径报告状态码和内容类型，因此问题会立刻显现。