The Agent Card: How AI Agents Discover Each Other

An Agent Card is a JSON document that describes an A2A agent: its identity, where to reach it, how to authenticate, and what it can do, expressed as a list of skills.

It is published at a well-known URL — /.well-known/agent-card.json — so any client can fetch it and learn how to work with the agent without a private arrangement.

Think of it as a business card and an API description combined. It is the first thing a client fetches and the contract it plans against.

Where to find it

By convention, an agent serves its card at a well-known path so clients can locate it predictably — the same idea as the web's well-known URLs. A client that knows an agent's base address can fetch its card and immediately learn how to work with it:

curl https://agent.example.com/.well-known/agent-card.json

That predictability is the whole point. No registry lookup required, no documentation to hunt down, no email to another team. If you know the host, you know the card.

What the card contains

• Identity — a name, description, provider, and version for the agent.
• Endpoint — the URL where the agent receives A2A requests.
• Skills — the discrete capabilities the agent offers, each with an id, description, and often example inputs and outputs.
• Authentication — the security schemes the agent requires, so a client knows how to authenticate before sending work.
• Capabilities — protocol features the agent supports, such as streaming or push notifications.

A minimal card

{
  "name": "Research Agent",
  "description": "Gathers and summarizes sources on a topic",
  "version": "1.2.0",
  "url": "https://agent.example.com/a2a",
  "skills": [
    { "id": "research", "description": "Research a topic and
      return a sourced summary" }
  ],
  "capabilities": { "streaming": true }
}

Why skills matter most

The skills list is the heart of the card. It is what lets a client — or an orchestrating agent choosing among many — decide whether this agent is the right one for a job.

A skill described as "processing" tells a caller nothing. One described as "extract line items from an invoice PDF and return them as structured data" tells a caller everything. Well-described skills make an agent discoverable and usable; vague ones make it invisible in practice.

• Give each skill a stable id and a plain-language description.
• State the inputs it expects and the shape of what it returns.
• Include a concrete example where the behavior is not obvious.

Treat your skill descriptions like public API docs.
To the rest of the ecosystem, that is exactly what they are.

Public and authenticated cards

An agent can expose a basic public card to anyone and a richer, authenticated card to clients that have proven their identity. The public card is enough to discover the agent and learn how to authenticate; the authenticated card can reveal additional skills or detail reserved for trusted callers.

This two-tier approach lets an agent be discoverable without exposing everything it can do to the entire world.

Signed cards

As the protocol matured, support for cryptographically signed Agent Cards was added, letting a client verify a card genuinely belongs to the agent it claims to. In any setting where trust matters — and especially across organizational boundaries — prefer verifiable cards over ones taken at face value.

Keeping cards current

An Agent Card is a living document. When you add a skill, change an endpoint, or alter your auth requirements, the card must move with the agent. A stale card sends clients to the wrong place or hides new capability.

Version your card alongside your agent, and treat a card change as part of shipping, not an afterthought. Clients read the version and capabilities you advertise, so keeping them honest is what keeps interoperability working.

Discovery at scale

As the number of agents grows, hard-coding endpoints stops scaling. This is where cards earn their keep: an orchestrator can select an agent by matching a task to advertised skills rather than by knowing a fixed address.

Registries and directories of A2A agents extend this further, letting systems find capable agents dynamically — the agent equivalent of service discovery in microservices. New agents join without rewiring the ones already running.

The most common first-run mistake

A running agent that does not serve its Agent Card at the well-known path cannot be discovered. It doesn't matter how good the agent is — to the ecosystem, it does not exist.

Confirm you can curl the card back before wiring up any client. It is the single most common thing people miss on a first implementation.