Why it matters
An agent that wants to delegate work needs three answers before it can act: what the other agent can do, where to send the request and how to authenticate. Without a standard document, every integration is a conversation between teams. A card makes those answers machine-readable, which lets a planner select a partner agent at runtime. It also creates a new attack surface, because the document is fetched from a URL the caller does not control.
Mental model
An agent card is a business card with a services list on the back: who they are, what they do and how to reach them. The metaphor breaks because the card can be updated by the holder at any time, and the caller may cache an old version or fetch a forged one.
How it works
A2A 1.0.0 discovery: unauthenticated fetch, then an authenticated SendMessage to the interface the card declares. The card's provider URL is the identity the planner pins.
Planner
caller
Card host
well-known path
Remote
agent endpoint
GET https://billing.example
/.well-known/agent-card.json
Accept: application/json
A2A-Version: 1.0
No credential: discovery happens before
the caller knows which scheme to use.Step 1: discover. Hover, tap or tab to any message to inspect its payload.
Figure. The card is a discovery document, not documentation: a planner fetches an A2A 1.0 card without credentials, matches a required skill against the declared skill and scopes, and only then sends work to the advertised interface with the advertised auth scheme. Capability and credentials are discovered in that order, never assumed.
What to notice. The failure is trust in a claim. A spoofed card from a look-alike domain sends credentials to the wrong agent, and card drift advertises a skill the endpoint has already removed. The card is unauthenticated by design, so it must carry no secrets and must be pinned to the provider URL it declares.
Text version
Sequence across Planner, Card host and Remote agent. Step 1, discover: Planner to Card host GET /.well-known/agent-card.json with A2A-Version 1.0. Step 2, fetch card: Card host to Planner an A2A 1.0 card with description, version, supportedInterfaces url and JSONRPC binding, provider organization and url, capabilities, default input and output modes, a skill with name and tags, and a typed oauth2SecurityScheme with clientCredentials flows and scopes. Step 3, match: an in-process self step on Planner compares the required skill invoice.reconcile with the declared skill, tags, scope invoices.write, provider URL https://acme.example and text/plain input mode; all must match. Step 4, delegate: Planner to Remote SendMessage on the card's interface URL with A2A-Version 1.0, application/json, a bearer token for the declared scope, and a message with messageId, ROLE_USER and a text part; Remote to Planner a task in TASK_STATE_SUBMITTED. The card supplied the interface and the auth scheme; it supplied no credential.
- Publish the card at the well-known path for the domain, served over HTTPS with a stable URL.
- Describe identity, provider, version and a contact, so a caller can attribute the agent and report abuse.
- Define skills with an id, name, description, examples and the input and output modes the agent accepts.
- Declare supported transports, endpoints and authentication schemes, including which scopes are required per skill.
- Keep secrets out of the card and treat every field as public, because discovery is unauthenticated by design.
- Version the card and keep old versions reachable long enough for cached callers to refresh.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Unauthenticated public card | Simple discovery | Reveals capability and architecture to anyone | The agent serves only internal callers |
| Authenticated card | Limits reconnaissance | Callers cannot discover how to authenticate | Partners need out-of-band onboarding |
| Rich skill descriptions | Better selection by a planner | Longer fetch and more prompt context | The caller has a small context budget |
| Short cache TTL | Fresh capabilities | More fetches and latency | The card changes rarely |
Good for
Simple discovery
Cost
Reveals capability and architecture to anyone
Fails when
The agent serves only internal callers
- The agent serves only internal callers
- Partners need out-of-band onboarding
- The caller has a small context budget
- The card changes rarely
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Unauthenticated public card is good for Simple discovery, costs Reveals capability and architecture to anyone, and fails when The agent serves only internal callers. Authenticated card is good for Limits reconnaissance, costs Callers cannot discover how to authenticate, and fails when Partners need out-of-band onboarding. Rich skill descriptions is good for Better selection by a planner, costs Longer fetch and more prompt context, and fails when The caller has a small context budget. Short cache TTL is good for Fresh capabilities, costs More fetches and latency, and fails when The card changes rarely
Failure modes
- Spoofed card. A caller fetches a card from a look-alike domain and sends credentials to the wrong agent. Debug: pin the expected domain and verify the card's provider identity before authenticating.
- Card drift. The card lists a skill that was removed, and the caller's plan fails at execution. Debug: run a smoke test per skill against the live endpoint on a schedule.
- Secret in the card. A callback URL with an embedded token is published in the card. Debug: scan the served document for token patterns and high-entropy strings.
In production
Monitor card fetch failures and version changes per partner, and alert on a card whose endpoint or auth scheme changes unexpectedly. The specification fixes the required fields and discovery path, while caching and signing are additions implementations choose, so serve the card from the same infrastructure as the agent.
Common misconceptions
People think: The card is documentation for humans.
Actually: It is a discovery input for other agents, so field names and skill descriptions affect selection directly.
People think: Publishing a card exposes the agent's tools.
Actually: It exposes declared skills and endpoints; internal tools and prompts should stay behind the boundary.
Interview angle
A strong answer covers discovery, skills, auth schemes and the trust problem of fetching a document from an untrusted host. It also mentions caching and versioning. Weak answers treat the card as a README.
Sources
- A2A specification, Agent Discovery — the agent card schema and its fields.
- RFC 8615, Well-Known Uniform Resource Identifiers — the convention for a stable discovery path.
- A2A documentation — publishing and consuming agent cards.