Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 11 of 16

Agent cards

0 of 16 complete

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

Fetch the claim, match the skill, then delegateInteractive

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

Step 1/4 · discover
GET /.well-known/agent-card.jsoncall · Planner → Card host
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.

  1. Publish the card at the well-known path for the domain, served over HTTPS with a stable URL.
  2. Describe identity, provider, version and a contact, so a caller can attribute the agent and report abuse.
  3. Define skills with an id, name, description, examples and the input and output modes the agent accepts.
  4. Declare supported transports, endpoints and authentication schemes, including which scopes are required per skill.
  5. Keep secrets out of the card and treat every field as public, because discovery is unauthenticated by design.
  6. Version the card and keep old versions reachable long enough for cached callers to refresh.

Trade-offs

ChoiceGood forCostFails when
Unauthenticated public cardSimple discoveryReveals capability and architecture to anyoneThe agent serves only internal callers
Authenticated cardLimits reconnaissanceCallers cannot discover how to authenticatePartners need out-of-band onboarding
Rich skill descriptionsBetter selection by a plannerLonger fetch and more prompt contextThe caller has a small context budget
Short cache TTLFresh capabilitiesMore fetches and latencyThe card changes rarely
Trade-off mapInteractive

Good for

Simple discovery

Cost

Reveals capability and architecture to anyone

Fails when

The agent serves only internal callers

  1. The agent serves only internal callers
  2. Partners need out-of-band onboarding
  3. The caller has a small context budget
  4. 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