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:
| Result | Meaning |
|---|---|
| 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 intosupportedInterfacesto 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.