A2A agent card: example and the mistakes real cards make

An agent card is the JSON an A2A agent publishes at /.well-known/agent-card.json: who it is, where to call it, and what it can do. Of 4,438 A2A cards brick.blue reads, 1,614 (36%) break the spec. The commonest: skills[].tags missing (REQUIRED) (872 cards); defaultInputModes missing (REQUIRED) (703 cards); defaultOutputModes missing (REQUIRED) (703 cards).

A card that passes

{
  "name": "Weather Agent",
  "description": "Forecasts and current conditions for any city.",
  "version": "1.2.0",
  "provider": { "organization": "Example Inc.", "url": "https://example.com" },
  "supportedInterfaces": [
    { "url": "https://example.com/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
  ],
  "capabilities": { "streaming": false },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "forecast",
      "name": "Forecast",
      "description": "Seven-day forecast for a named city.",
      "tags": ["weather", "forecast"]
    }
  ]
}

A full, signed example in production: brick.blue's own card.

What published cards leave out

Counted over 4,438 A2A cards the crawler reads; a card missing tags on several skills counts once.

Check yours

curl "https://brick.blue/api/v1/verify?url=https://example.com"

It reads your card and checks the endpoint it declares: does it answer, what does it demand, does it address the agent reading it. The answer links your agent's page in the registry, which lists every spec violation the crawler found. Then claim the listing the registry already made of your agent.

Questions

Where does an A2A agent card live?

At /.well-known/agent-card.json on the agent's own origin, served as JSON. Clients and registries fetch it there before calling the agent.

What do A2A agent cards most often get wrong?

Of 4,438 A2A cards brick.blue reads, 1,614 (36%) break the spec. The commonest: skills[].tags missing (REQUIRED) (872 cards); defaultInputModes missing (REQUIRED) (703 cards); defaultOutputModes missing (REQUIRED) (703 cards).

How do I check my agent card?

GET https://brick.blue/api/v1/verify?url=<your origin> reads the card and checks that the endpoint it declares answers, what it demands and whether it carries text aimed at the reading agent; the answer links the agent's page, which lists every spec violation the crawler found (also cardViolations in GET /api/v1/agents/{id}).