Discovery tool · A2A v1.0

Check A2A Agent Card discovery URLs

A2A clients discover an agent by fetching its JSON Agent Card from a well-known URL. Test both naming conventions on a live domain and see exactly what clients receive.

Builds both candidate discovery URLs from the same base domain.

Fetches the returned JSON and reports status code and content type.

Parses the response as Agent Card JSON when possible.

Runs readiness checks for interfaces, skills, provider, modes, capabilities, and security metadata.

Check a public agent domain

Enter a base domain. The checker fetches both discovery paths, parses returned JSON, and runs Agent Card readiness checks.

How discovery works

One well-known URL starts every A2A integration.

Before another agent can call yours, it fetches the Agent Card from a well-known URI (RFC 8615) on your domain, evaluates the skills and security requirements, and then calls the preferred interface. If the Agent Card is missing, stale, or hidden behind a redirect, the integration ends before it begins.

This site practices what it checks: AgentCard.net publishes its own Agent Card at both paths, and the example on the right is the live document.

View our live 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", ... }
  ]
}

Discovery paths

Two conventions, one Agent Card.

Open full validator
A2A v1.0 standard

/.well-known/agent-card.json

The well-known URI registered by the A2A v1.0 specification. New clients fetch this path first; serve it with content type application/a2a+json.

Legacy (pre-1.0)

/.well-known/agent.json

Used by early A2A implementations and codelab examples. Many deployed clients still check only this path, so serving the same Agent Card here is a safe transition strategy.

Publishing pattern

Make Agent Card discovery resilient.

Discovery failures are rarely exotic: a redirect, a cached error page, or one path deployed and the other forgotten. This publishing routine keeps both conventions serving the same, current Agent Card.

  1. 1

    Publish at the standard path

    Serve the reviewed Agent Card at /.well-known/agent-card.json over HTTPS on the same domain as the A2A service, with content type application/a2a+json.

  2. 2

    Mirror the legacy path

    Return the identical document from /.well-known/agent.json while older clients are still in circulation — divergent Agent Cards on the two paths confuse routing.

  3. 3

    Keep the Agent Card synchronized

    Whenever endpoints, skills, capabilities, or authentication change, update the Agent Card, bump its version field, and redeploy both paths together.

  4. 4

    Re-check after every change

    Run this checker after deployments, DNS changes, gateway migrations, or marketplace edits. Failures usually trace to redirects, HTML error pages, or one forgotten path.

FAQ

Well-known Agent JSON questions

What to publish, where to publish it, and how to keep clients on either convention working.

Which well-known Agent Card path should I use?

A2A v1.0 registers /.well-known/agent-card.json as the standard discovery path. The legacy /.well-known/agent.json predates v1.0 but is still checked by many deployed clients, so publishing the same Agent Card at both paths is the pragmatic choice during the transition.

Should both paths return identical JSON?

Yes. Returning the same public Agent Card from both paths keeps clients that support only one convention consistent. Divergent documents make the agent look different depending on which path a client happens to fetch.

What content type should the Agent Card be served with?

The specification registers application/a2a+json for Agent Cards. Plain application/json is widely accepted in practice, but an HTML content type is a reliable sign the path is returning an error page instead of the Agent Card.

Can the public Agent Card hide private capabilities?

Yes. Publish only discovery-safe metadata in the public Agent Card, set capabilities.extendedAgentCard to true, and expose sensitive skills through the authenticated GetExtendedAgentCard operation.

Why do discovery checks fail after a deployment?

The usual causes are redirects to a login or marketing page, HTML 404 pages returned with status 200, stale JSON cached at a CDN, or only one of the two well-known paths being deployed. The checker reports status code and content type for each path so the failure is visible immediately.

Before you publish

Validate the Agent Card, then check the URLs.

Run the JSON through the full validator first, publish it at both well-known paths, and confirm discovery with this checker.

Open the validatorGenerate an Agent Card