---
title: "What is an A2A Agent Card? Fields and discovery"
description: "An Agent Card is the JSON document an A2A agent publishes to describe its skills, endpoints, and auth. See the well-known path, required fields, and signing."
type: "glossary-term"
canonical_url: "https://theaiengineering.com/glossary/agent-card"
markdown_url: "https://theaiengineering.com/glossary/agent-card.md"
topic: "Model Context Protocol"
author: "The AI Engineering Editors"
publisher: "The AI Engineering"
updated: "2026-11-06"
keywords: ["Agent Card","A2A Agent Card","agent-card.json"]
citation: "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"
---

# What is an A2A Agent Card? Fields and discovery

Also called A2A Agent Card, agent-card.json.

> **Definition of Agent Card:** 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](https://theaiengineering.com/glossary/a2a-protocol) server publishes so that client agents can decide whether and how to call it. The [A2A specification](https://a2a-protocol.org/latest/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](https://theaiengineering.com/glossary/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](https://theaiengineering.com/glossary/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](https://theaiengineering.com/glossary/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](https://theaiengineering.com/glossary/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](https://theaiengineering.com/articles/a2a-vs-mcp) includes a complete example card and shows how the card fits into a task flow.

## Related terms

- [A2A protocol](https://theaiengineering.com/glossary/a2a-protocol): The A2A (Agent2Agent) protocol is an open standard, introduced by Google in April 2025, that lets AI agents built on different frameworks discover each other, exchange messages, and delegate tasks.
- [JSON-RPC](https://theaiengineering.com/glossary/json-rpc): JSON-RPC is a lightweight, transport-agnostic remote procedure call protocol that encodes method calls, results, and errors as JSON objects; version 2.0 is the message format of MCP and A2A.
- [Multi-agent system](https://theaiengineering.com/glossary/multi-agent-system): A multi-agent system is an AI architecture in which several language-model agents, each with its own prompt, tools, and context, work on parts of a task and pass results to one another.
- [AI agent](https://theaiengineering.com/glossary/ai-agent): An AI agent is a software system in which a large language model runs in a loop, calling tools, reading their results, and repeating until the task is complete or a stop condition is reached.
- [Model Context Protocol (MCP)](https://theaiengineering.com/glossary/model-context-protocol): Model Context Protocol (MCP) is an open protocol, introduced by Anthropic in November 2024, that standardizes how AI applications connect to external tools, data sources, and prompts through MCP servers.

## Guides that cover agent card

- [A2A protocol vs MCP: differences and when to use each](https://theaiengineering.com/articles/a2a-vs-mcp): A2A protocol vs MCP: A2A connects AI agents to other agents, and MCP connects an agent to tools and data. Compare agent cards, tasks, transports, and security.

Part of the [Model Context Protocol](https://theaiengineering.com/topics/mcp) topic hub.

## 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: 2026-11-06
- URL: https://theaiengineering.com/glossary/agent-card
- Markdown: https://theaiengineering.com/glossary/agent-card.md
