发现工具 · 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 Card
agentcard.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。

打开完整校验器
A2A v1.0 标准

/.well-known/agent-card.json

A2A v1.0 规范注册的 well-known URI。新客户端会优先获取此路径；请以 application/a2a+json 内容类型提供服务。

旧版（v1.0 之前）

/.well-known/agent.json

早期 A2A 实现与代码实验示例使用此路径。许多已部署的客户端仍只检测这个路径，因此在此提供相同 Agent Card 是安全的过渡策略。

发布模式

让 Agent Card 发现更具韧性。

发现失败通常并不复杂：一次重定向、一个被缓存的错误页面，或者只部署了一个路径而忘记了另一个。这套发布流程能让两种约定始终提供同一份最新 Agent Card。

  1. 1

    在标准路径上发布

    在与 A2A 服务相同的域名上，通过 HTTPS 在 /.well-known/agent-card.json 提供经过审核的 Agent Card，内容类型为 application/a2a+json。

  2. 2

    镜像旧版路径

    在旧版客户端仍在使用期间，从 /.well-known/agent.json 返回完全相同的文档——两个路径上的 Agent Card 不一致会扰乱路由。

  3. 3

    保持 Agent Card 同步

    每当端点、技能、能力或身份验证发生变化时，更新 Agent Card、提升其 version 字段，并同时重新部署两个路径。

  4. 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 路径中只部署了一个。检测工具会为每个路径报告状态码和内容类型，因此问题会立刻显现。

发布之前

先校验 Agent Card，再检测 URL。

先让 JSON 通过完整校验器，在两个 well-known 路径上都发布它，再用本工具确认发现是否成功。

打开校验器生成 Agent Card

来自博客

面向 A2A 发现机制的实践指南，依据 v1.0 规范撰写。

全部文章
Comparison

A2A vs MCP: two protocols solving two different problems

Compare A2A vs MCP: what each protocol connects, where they overlap, and why production AI agent systems often use both for tools and agent collaboration.

9 min read阅读指南How-to

How to create an agent.json file for A2A v1.0

Learn how to create an agent.json file for A2A v1.0, including required Agent Card fields, the well-known URL, response headers, and common mistakes.

11 min read阅读指南Integration

Publishing an Agent Card from ADK, LangGraph, CrewAI or Semantic Kernel

Learn how to publish an A2A Agent Card from Google ADK, LangGraph, CrewAI, or Semantic Kernel by mapping framework concepts to standard discovery fields.

10 min read阅读指南

文章以英文发布。