_ guides / A2A agent card counted just now

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 7,482 A2A cards brick.blue reads, 2,644 (35%) break the spec. The commonest: skills[].tags missing (REQUIRED) (1,572 cards); defaultInputModes missing (REQUIRED) (982 cards); defaultOutputModes missing (REQUIRED) (982 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

violationcards
skills[].tags missing (REQUIRED)1,572
defaultInputModes missing (REQUIRED)982
defaultOutputModes missing (REQUIRED)982
description missing (REQUIRED)682
skills missing (REQUIRED)501
version missing (REQUIRED)402
supportedInterfaces[].protocolBinding missing285
no usable endpoint declared173

Counted over 7,482 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 7,482 A2A cards brick.blue reads, 2,644 (35%) break the spec. The commonest: skills[].tags missing (REQUIRED) (1,572 cards); defaultInputModes missing (REQUIRED) (982 cards); defaultOutputModes missing (REQUIRED) (982 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}).