The Agent Card is how an A2A agent describes itself to the world. It's a small JSON document that every A2A-compliant agent must publish at /.well-known/agent.json. Clients read it before sending any task.

Get the fields right and clients discover you automatically. Get them wrong and you'll silently fail capability matching. Here's every field, what it does, and what the spec doesn't tell you.

Advertisement

Minimal example

{
  "name": "Currency Agent",
  "description": "Converts between currencies using live rates",
  "url": "https://currency.example.com/a2a",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    { "id": "convert", "name": "Convert currency",
      "tags": ["currency", "exchange"] }
  ]
}

Nine fields. That's the whole spec — everything else is extensions.

The identity fields

  • name — human-readable label. Shows up in discovery UIs.
  • description — one paragraph explaining what the agent does. Used by LLM-based routers.
  • url — the base URL for the A2A JSON-RPC endpoint.
  • version — semver of the agent implementation. Bump on any behavior change.
Advertisement

Capabilities

The capabilities object announces protocol features the agent supports:

  • streaming — supports tasks/sendSubscribe for incremental updates.
  • pushNotifications — can push completion events to a webhook.
  • stateHistory — retains task state across sessions.

Clients read capabilities before deciding how to invoke you. Advertising a capability you don't actually support is a hard bug.

Skills

The skills array is what makes discovery work. Each entry:

{
  "id": "unique_skill_id",
  "name": "Human-readable name",
  "description": "What the skill does",
  "tags": ["category", "keyword"],
  "examples": ["Convert 100 USD to EUR", "What is 50 GBP in INR?"]
}

examples is optional but powerful — LLM-based orchestrators use it to match user intents to your skill.

Auth + security fields

Extended agent cards may include:

  • auth — required authentication scheme (OAuth2, API key, mTLS).
  • rateLimits — advertised limits so clients can back off proactively.
  • defaultInputModes / defaultOutputModes — text, file, structured data.

Where to publish it

Publish at https://your-domain/.well-known/agent.json. This is the discovery contract. Any client that speaks A2A knows to look there. Add cache headers with a short TTL (max-age=300) — Agent Card content is stable but not immutable, and version bumps should propagate in minutes not days.

Write the Agent Card first. Every A2A design decision falls out of what capabilities and skills you advertise.