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 signatures field excluded, so a client can verify that the card is unaltered and comes from the claimed provider.
  • Extended card: when capabilities.extendedAgentCard is true, an authenticated client can call GetExtendedAgentCard for a more detailed card and should replace its cached public card with it. Skills meant only for authenticated callers belong there.
  • Security declarations: securitySchemes and securityRequirements tell 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.

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
View as Markdown

Part of the Model Context Protocol hub · Updated