The Agent Descriptor and the A2A card
The A2A Agent Card answers how to call an agent, so it carries the agent's endpoint and its authentication schemes, and it stays authoritative for protocol capabilities. The Agent Descriptor answers what you will get if you do, and most of its members have no card equivalent. The two do not compete: in this family the card is generated from the Descriptor as its A2A-facing projection.
1. Two different questions
A caller who has never met an agent needs two things: a way to reach it, and an account of what it does, takes, returns, and refuses. The card was built for the first and carries a summary of the second. The Descriptor was built for the second and deliberately carries none of the first, because endpoints and credentials are bindings, and the Descriptor holds shapes only.
2. Side by side
| Dimension | A2A Agent Card | Agent Descriptor |
|---|---|---|
| Purpose | Discovery plus connection: enough to find the agent and call it over A2A. | Description: the operator's full standing account of the agent. |
| Author | The operator. | The operator. |
| Position here | A projection of the Descriptor, in A2A's format at A2A's address. | The primary source. A fact appears here once. |
| Address | /.well-known/agent-card.json, fixed by the A2A specification. | Servable anywhere and carried on the manifest. The address is not part of the format. |
| Identity | Name, provider organization, url. | Subject key and handle, anchored to the registrar's card. |
| Endpoint | Carries the service endpoint URL, which is its job. | Carries no endpoints. Shapes only, bindings never. |
| Security | securitySchemes and security: how a caller authenticates. | Not a member. Access stays on the card and the manifest. |
| What it does | A description string. | One sentence for the agent, and one per offering. |
| Units of work | Skills: id, name, description, tags, examples. | Offerings: id, name, sentence, and typed inputs and outputs. |
| Inputs and outputs | Media-type lists: defaultInputModes and defaultOutputModes, per skill or card-wide. | Per offering, per input: name, kind, required, external. Deliverables with name, kind, and when. |
| Who drives it | Not expressible. | interaction: a person attends it, or it runs on its own. |
| Refusals | Not expressible. | A prose member, elevated further by SoW clauses and role contracts. |
| Roles and interfaces | Not expressible beyond skill naming. | Declared by name. The definitions stay at the registry. |
| Runtime shape | Not expressible. | Harness, model, steps, memory, runtime tools, fleet. |
| Hosting location | Not expressible. | hosted_in: regions, never addresses. |
| Per-caller limits | Not expressible. | Requests per hour, model budget, and what happens past them. |
| Standing systems | Not expressible. | Role, access level, and what the access is for. |
| Versioning | A version string. | Two members: the format version and the agent's own version. Replaced whole, and referenced at a digest so signatures cannot drift. |
| Protocol capabilities | Streaming, push notifications, state history. | Not a member. Protocol features belong to the protocol-facing card. |
| Extensibility | An extensions mechanism. | Core members plus named extensions. |
3. How they work together
An operator authors the Descriptor. The card is generated from it: the one-sentence description, the offerings as skills, and the input and output kinds coarsened to media-type modes, with the endpoint and authentication added by the machinery that serves the card, since those are connection facts the Descriptor never holds. A caller who starts from the card can follow it back to the Descriptor for everything the card cannot carry, and an AgentDoc assembles both, citing each as a source.
Nothing about this changes what the card is elsewhere. An agent that lives only on A2A keeps a valid card with no Descriptor behind it; a Descriptor simply gives its operator one place to write, and every other format one place to read.