What is an A2A Agent Card? Fields and discovery
Also called A2A Agent Card, agent-card.json
Definition
An Agent Card is a JSON document that an A2A server publishes, usually at /.well-known/agent-card.json, describing the agent's identity, endpoints, capabilities, skills, and authentication requirements.
An Agent Card is the JSON metadata document that an A2A server publishes so that client agents can decide whether and how to call it. The A2A specification, whose latest released version is 1.0.0, states that A2A servers must make an Agent Card available and that the card describes the server's identity, capabilities, skills, and interaction requirements. A client reads the card before it sends any task, so the card is the remote agent's contract with every caller in a multi-agent system.
Agent Card fields#
Version 1.0 of the A2A specification requires eight Agent Card fields: name, description, version, supportedInterfaces, capabilities, defaultInputModes, defaultOutputModes, and skills. Optional fields cover the provider, documentation and icon URLs, security schemes and requirements, and JWS signatures. Each skill needs an id, name, description, and tags.
| Field | Required | What it holds |
|---|---|---|
name, description, version |
Yes | The agent's identity and the card's version |
supportedInterfaces |
Yes | One entry per endpoint: url, protocolBinding (JSONRPC, GRPC, or HTTP+JSON), and protocolVersion |
capabilities |
Yes | Flags such as streaming, pushNotifications, and extendedAgentCard, plus supported extensions |
defaultInputModes, defaultOutputModes |
Yes | Media types the agent accepts and returns, such as text/plain |
skills |
Yes | What the agent can do, each with optional examples, input and output modes, and security requirements |
securitySchemes, securityRequirements |
No | How a client must authenticate |
provider, documentationUrl, iconUrl |
No | The publishing organization and supporting links |
signatures |
No | JWS signatures over the card |
Order matters in supportedInterfaces: the specification says the first entry is the preferred interface, and clients should prefer earlier entries when they support several. An agent that offers both a JSON-RPC endpoint and a gRPC endpoint lists them in the order it wants clients to try.
How clients discover and trust an Agent Card#
Clients find Agent Cards in three ways that the specification lists: fetching https://{server_domain}/.well-known/agent-card.json, querying a curated registry or catalog, or using a preconfigured card URL or card content. The well-known path changed in version 0.3.0; version 0.2.6 used /.well-known/agent.json, which older tutorials still show.
Cards are cached like web resources. Servers should send a Cache-Control header with max-age and an ETag, and clients should revalidate an expired card with a conditional request such as If-None-Match.
The specification gives cards these trust and disclosure controls:
- Signing: a card may carry JSON Web Signatures (RFC 7515). The card is canonicalized with the JSON Canonicalization Scheme (RFC 8785) before signing, with the
signaturesfield excluded, so a client can verify that the card is unaltered and comes from the claimed provider. - Extended card: when
capabilities.extendedAgentCardistrue, an authenticated client can callGetExtendedAgentCardfor a more detailed card and should replace its cached public card with it. Skills meant only for authenticated callers belong there. - Security declarations:
securitySchemesandsecurityRequirementstell the client which credentials to obtain before it sends a message.
Skill names and descriptions are text that a client agent's model may read when it chooses whom to delegate to. Treat cards from unknown agents as untrusted input, the same caution that applies to MCP tool descriptions and tool poisoning.
Agent Card vs MCP tool list#
An Agent Card and an MCP tool list both tell a caller what a remote party offers, at different levels of detail. A card is a static document at a URL that describes an opaque agent's skills in natural language. An MCP tool list is the response to a tools/list call and describes each tool's arguments with a JSON Schema.
The difference follows from what sits on the other side. A skill accepts a goal in a message and the remote agent decides how to carry it out, so the card needs examples and tags, not argument types. A Model Context Protocol tool runs exactly the call the model emits, so its schema must be precise. Caching differs too: a card relies on HTTP caching headers, while MCP list results carry their own ttlMs and cacheScope fields.
A2A vs MCP includes a complete example card and shows how the card fits into a task flow.
Related terms
Guides that cover agent card
Cite this definition
The AI Engineering Editors. "What is an A2A Agent Card? Fields and discovery." The AI Engineering, updated Nov 06, 2026. https://theaiengineering.com/glossary/agent-card
- Title
- What is an A2A Agent Card? Fields and discovery
- Author
- The AI Engineering Editors
- Publisher
- The AI Engineering
- Updated