/.well-known/agent-card.json: what the check tests and how to fix it

Looks for an A2A agent card at /.well-known/agent-card.json. Only sites running an A2A agent should publish one. A homepage-URL stub scores partial.

Agent Discovery · Weight 1 in the w2agent Score

How common is it?

1% of 1223 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

What this check tests

The audit requests /.well-known/agent-card.json on your site root. The response only counts when it is a 200 with a JSON content type and its body differs from what the site returns for a random path under /.well-known/ (so a catch-all that answers every path does not pass). The JSON object is then classified:

ResultMeaning
Pass (100)A valid A2A v1.0 card whose interface URL is not just your homepage
Partial (50)A v1.0 card whose interface URL is the site homepage, or a v0.3-style card with a top-level url
Fail (0)Missing, not JSON, or not shaped like an A2A card

For v1.0 the check requires name, description and version as non-empty strings; supportedInterfaces, a non-empty list where each entry has an absolute http(s) url, a protocolBinding and a protocolVersion; a capabilities object; defaultInputModes and defaultOutputModes as string arrays; and skills, where each skill has an id, name, description and tags array. The A2A specification marks the same top-level fields, and the skill fields, as required.

Why it matters to agents

The A2A discovery guide names https://{server_domain}/.well-known/agent-card.json as the standard location where a client agent finds an A2A server's card, then reads the card to learn the endpoint, supported bindings and skills. The card is only useful if that endpoint is real.

There is a tension to state plainly. A missing card fails this check, but a site with no A2A agent has no endpoint to describe, and a placeholder pointing at the homepage tells clients to talk to something that does not speak A2A. The audit's own fix text says sites without an A2A agent should not publish a card. If you do not run an agent, treat the fail as accurate, not as a to-do.

How to fix it

Only if you operate an A2A agent: serve a JSON card at the well-known path with Content-Type: application/json, where url is the live A2A endpoint, never the site homepage. This shape matches the specification's own examples:

{
  "name": "Example Support Agent",
  "description": "Answers questions about Example Co orders.",
  "version": "1.0.0",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/v1",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": { "streaming": false, "pushNotifications": false },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "order-status",
      "name": "Order status",
      "description": "Looks up the status of an order.",
      "tags": ["orders", "support"]
    }
  ]
}
  • If your card has a top-level url (the older v0.3 shape), move it into supportedInterfaces to get from partial to pass.
  • Confirm that a request for a nonsense path under /.well-known/ returns 404, not your card.

More background: what agent-card.json is. Related discovery files: MCP server card and Agent Skills index. Commerce sites can also publish a UCP profile, which can list an A2A transport that points to this card. For sign-in, see Client ID Metadata Documents.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →