agentsready
API / Auth / MCP Hard

A2A Agent Card: your agent's card for orchestrators

What an A2A Agent Card (Google A2A Protocol) is, why it matters for agent-to-agent comms, an example, right vs wrong, mistakes, and how to verify.

Updated:

What it is

An A2A Agent Card is a JSON document at /.well-known/agent.json describing your AI agent’s capabilities in Google’s Agent-to-Agent (A2A) Protocol format. Other agents and orchestrators use it to discover and invoke your agent without manual configuration. Where an MCP Server Card describes tools, an A2A Agent Card describes the agent’s high-level skills.

Why it matters for AI agents

A2A (2025) is a standard for agent-to-agent communication. Without an Agent Card your agent lives “in the dark” — it can only be wired up by hand. With the card, an orchestrator (Claude, Gemini, a third-party agent) finds a specialised agent by its description and folds it into a composite workflow — delegation becomes automatic.

Minimal working example

{
  "name": "My Data Agent",
  "description": "Provides data analysis and reporting",
  "version": "2.0.0",
  "url": "https://api.example.com/a2a",
  "capabilities": { "streaming": true, "pushNotifications": false },
  "skills": [
    {
      "id": "analyze",
      "name": "Analyze Dataset",
      "description": "Run statistical analysis on a CSV",
      "inputModes": ["file", "text"],
      "outputModes": ["text", "json"]
    }
  ]
}

Right vs wrong

RightWrong
Served at /.well-known/agent.json, application/jsonAn arbitrary path
Has name, version, urlMissing required fields
A skills array with id + name eachEmpty/missing skills — nothing to delegate
url points to a working A2A endpointA broken/placeholder URL

Common mistakes

  • Invalid JSON or missing required name/version.
  • No skills — the orchestrator can’t tell what the agent does.
  • Skills without clear descriptions — task-based agent selection fails.
  • Confusing it with ai-agent.json — different files; A2A uses /.well-known/agent.json.

How to verify

The scanner GETs /.well-known/agent.json and checks the JSON, the name/version fields, and the skills array (at least one with id + name). Manually:

curl -s https://example.com/.well-known/agent.json | jq '.name, .version, .skills'

Sources