PromptMaster

Posted on Jul 18

The Agent Card: How AI Agents Discover Each Other

#ai #agents #api #json

Before one agent can delegate to another, it has to find it and know what it can do. The Agent Card is how.

The Agent Card is a JSON document that describes an A2A agent: its identity, endpoint, authentication requirements, and — most importantly — the skills it offers.

It is published at a well-known path, /.well-known/agent-card.json, so any client that knows an agent's base address can fetch it and immediately learn how to work with that agent.

It is the first thing a client fetches and the contract it plans against. An agent that doesn't serve a card is undiscoverable; an agent whose skills are described vaguely is undiscoverable in practice.

Why discovery has to come first

Before a client can send any work, it needs to know three things: that a remote agent exists, what it is capable of, and how to talk to it. Without a standard way to answer those questions, you're back to hard-coding endpoints and reading someone else's documentation by hand.

The Agent Card answers all three in one fetch. It is a JSON document the remote agent publishes so that any client — including one built by a team that has never spoken to yours — can read its identity and capabilities without a private arrangement.

Where the card lives

By convention, an agent serves its card at a well-known path, the same idea as the web's well-known URLs. This is what makes discovery predictable rather than a matter of asking around:

# fetch a remote agent's public card
curl https://agent.example.com/.well-known/agent-card.json

If you can't curl the card back, nothing else works. This is the single most common first-run mistake: a perfectly good agent, running fine, that no client can find because the card isn't served where clients look.

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 }
}

Skills are the part that matters 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. The difference is whether your agent gets used.

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 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 internet.

Signed cards and trust

As the protocol matured, support for cryptographically signed Agent Cards was added, letting a client verify that a card genuinely belongs to the agent it claims to.

This matters more than it sounds. A card tells a client where to send work and how to authenticate — an attacker who can serve a convincing card can redirect that work. In any setting where trust matters, 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. The practical upshot: a new specialist agent can join your system without anyone editing the orchestrator.

Frequently asked questions

What is an A2A Agent Card?
A JSON document describing an A2A agent's identity, endpoint, authentication requirements, and skills. It's published at /.well-known/agent-card.json so any client can discover the agent and learn how to work with it.

Where is the Agent Card served?
At the well-known path /.well-known/agent-card.json on the agent's host, following the same convention as other well-known URLs on the web.

What happens if my agent doesn't serve a card?
It's undiscoverable. Clients look at the well-known path; if there's nothing there, they can't find the agent, learn its skills, or know how to authenticate — no matter how well the agent works internally.

What is a signed Agent Card?
A cryptographically signed card that lets a client verify it genuinely belongs to the agent it claims to. Since a card tells clients where to send work, verification matters wherever trust does.

How do I write good skill descriptions?
Like public API documentation: a stable id, a plain-language description of what the skill does, the inputs it expects, the shape of what it returns, and a concrete example when behavior isn't obvious. Vague skills make an agent invisible in practice.

Want to go deeper?

I wrote two guides on this.

A2A Quick-Start — free, 6 pages. The Agent2Agent protocol in 15 minutes: what it is, the five building blocks, the task lifecycle, and where MCP fits.

A2A: The Complete Guide — 42 pages. 15 chapters, 5 appendices. Discovery, security, building your first agent with the SDK, orchestration patterns, extensions and AP2, production and scaling — plus a full worked example of two agents talking and a 30-day adoption path.

Independent educational content. Not affiliated with, endorsed by, or sponsored by Google, the Linux Foundation, Anthropic, or any vendor named. A2A and MCP are evolving specifications — confirm details against the official specification for your target version.

DEV Community