What an agent card contains#
A machine-readable profile, served at a well-known path on the agent's domain. The fields that matter in practice:
| Field group | What it covers |
|---|---|
| Identity | Name, description, provider, version |
| Endpoints | Where to send requests |
| Skills | What the agent can do, described well enough to match against |
| Authentication | What credential is required, if any |
| Capabilities | Protocol features it supports, such as streaming |
The skills section is the interesting part and the hardest to get right. It is the only thing a calling agent has to decide whether this peer is suitable, and it is prose-shaped in a context where the reader is matching rather than reading.
What it is for#
Delegation. Agent A has a task it cannot do, knows agent B exists, and needs to decide whether B can help and how to ask.
The card answers that in one fetch, without a conversation, without documentation and without a human integration step. That is a real improvement over the alternative, which is reading a website.
A2A supports several discovery mechanisms, and the well-known URI is the primary one: agents serve their card at a standardised path under their domain.
Note
The filename changed during A2A's development, and a lot of published documentation points at the older path. The specification reached v1.0.0 in March 2026. If your card is not being read, check which path the client is looking for before assuming the client is broken.
Where it stops#
With a limitation its own critics state plainly: well-known discovery does not support finding agents by capability.
To read a card you need the domain. To get the domain you need to already know the agent exists. So the card answers "what can this agent do" and never "which agent can do this", which is the question a delegating agent actually has.
The specification acknowledges this and mentions DNS-based service discovery and registries as possible mechanisms, but neither is part of the core protocol. In practice capability discovery happens through registries and catalogues built outside the specification, which is the same shape the paid-service discovery problem has.
Should you trust a card?#
Only as far as a self-description from a stranger deserves.
A card is published by its subject. It asserts identity, capability and quality with nothing behind it. An agent that reads a card claiming expertise in something and delegates a paid task on that basis has trusted a marketing page written by the counterparty.
What raises the floor is evidence from outside the card:
- Has this agent been paid, by whom, over how long? Settlement history is not self-reported and not cheap to fake at breadth. Auditing a counterparty's traffic covers the checks.
- Is the identity registered on-chain? ERC-8004 gives agents a registry identity. Empirical work in 2026 found most registrations were placeholders, with only a small fraction exposing a live service endpoint, so registration is weak evidence on its own.
- Does the card match the live endpoint? A card describing skills the endpoint does not serve is a stale document or a false one, and you cannot tell which from outside.
How does this relate to x402?#
They compose cleanly and answer different questions.
The card says what a peer can do and how to reach it. x402 handles what the peer charges and how to pay, at the HTTP layer underneath. MCP, A2A and x402 as three layers sets out the whole stack. An agent can read a card, call the endpoint it names, receive a 402, pay, and get a result, with no account anywhere in the sequence.
The useful pairing is that the card is a claim and the settlement record is evidence. A peer whose card is impressive and whose receiving address has three counterparties and two weeks of history is telling you two different things, and the second one is the one it did not write.
Frequently asked questions#
Do I need a card if I only run an API?#
No. A card describes an agent; an API is described by an OpenAPI document and its priced terms. Which well-known files to publish sets out which applies to what.
Can a card carry a price?#
Not meaningfully. It is an identity and capability document. Prices belong in your 402 response and in catalogue registrations, where a buyer can act on them.
How do I make my card findable?#
You cannot, directly, which is the point of this article. Link it from your llms.txt, register in catalogues, and accept the card only helps agents that already have your domain.
Is A2A widely deployed?#
Less than MCP by a wide margin, and with much less independent measurement of real use. Treat adoption claims in this area with the same caution as volume claims elsewhere.
What stops someone publishing a false card?#
Nothing. There is no verification in the mechanism. That is why evidence from outside the card, particularly a payment history, is worth more than anything inside it.
Where to check this yourself#
/agents resolves on-chain agent identities and shows what each one has actually been observed doing, which is the half a self-published card cannot supply. Trust and reputation covers what registry identity does and does not establish.