# What Is an Agent Card in the A2A Protocol?

> What an A2A Agent Card is: the JSON at /.well-known/agent-card.json with an agent's identity, skills and security, and how it gets signed.

URL: https://clione.ai/glossary/agent-card/
Lang: en

In the [A2A (Agent2Agent)](/glossary/a2a/) protocol, one [AI agent](/glossary/ai-agent/) hands tasks to another. Before handing over anything, it has to know what the other one can do, where it listens and how to identify itself, and that is what the Agent Card holds. The protocol's documentation calls it **an agent's digital business card**.[^a2a-discovery] It is not a payment card or a credential that lets an agent buy: it carries no money and authorizes nothing. In [agentic commerce](/glossary/agentic-commerce/), a store cares because it is the first thing an outside agent reads: if your platform or your provider publishes an A2A agent on your behalf, or your [UCP (Universal Commerce Protocol)](/glossary/ucp/) profile declares the A2A transport, the address it lists is that of an Agent Card.[^ucp-overview]

## What it contains

The 1.0.0 specification defines it as a manifest the agent publishes about itself, with its identity, its capabilities, its skills, the ways of communicating it supports and its security requirements.[^a2a-spec] These are its fields:

| Field                                     | Required | What it says                                                            |
| ----------------------------------------- | -------- | ----------------------------------------------------------------------- |
| `name`, `description`                     | Yes      | The agent's name and what it is for, readable by a person               |
| `version`                                 | Yes      | The agent's version, not the protocol's                                 |
| `supportedInterfaces`                     | Yes      | The addresses and protocol bindings it supports, in order of preference |
| `capabilities`                            | Yes      | Whether it supports live responses, notifications or an extended card   |
| `defaultInputModes`, `defaultOutputModes` | Yes      | The content types it accepts and returns                                |
| `skills`                                  | Yes      | Its skills                                                              |
| `provider`                                | No       | The organization that offers it                                         |
| `securitySchemes`, `securityRequirements` | No       | How to authenticate                                                     |
| `signatures`                              | No       | The signatures of the card itself                                       |
| `documentationUrl`, `iconUrl`             | No       | Documentation and icon                                                  |


**The interfaces come in order.** The first one in `supportedInterfaces` is the preferred one, and the client has to pick the first it knows how to use and call the address declared for that transport.[^a2a-spec] In version 1.0 the possible protocol bindings are JSON-RPC, gRPC and HTTP with JSON, and each interface carries its own `protocolVersion`.[^a2a-spec]

**The skills are the part people read.** Each skill carries an identifier, a name, a description and tags, all required, and it may carry example requests, its own input and output types and its own security requirements. The specification describes them as mostly descriptive: **the set of things the agent will probably do well**.[^a2a-spec] They are not an input-and-output contract like that of an [MCP (Model Context Protocol)](/glossary/mcp/) tool, which is why the A2A documentation only sees a fit between the two when the skill is well defined and can be called statelessly.[^a2a-mcp]

## How it is found, signed and maintained

**Three ways to find it.** At the well-known address `https://{domain}/.well-known/agent-card.json`, in an agent catalog or through direct configuration.[^a2a-spec] The first follows the convention of the [.well-known directory](/glossary/well-known/), and the specification includes its registration as a well-known URI, with the suffix `agent-card.json`.[^a2a-spec] The second depends on whoever maintains the catalog, because **the specification does not set a standard API for those catalogs**.[^a2a-discovery]

**The signature.** An Agent Card can be signed with JWS (JSON Web Signature) so the client can check that it has not been altered and that it comes from whoever says so. Before signing, the JSON is put in canonical form with the JCS scheme, so any implementation computes the same signature, and the client should verify at least one signature before trusting the card.[^a2a-spec]

**The extended version.** If the public card declares `capabilities.extendedAgentCard`, the agent offers a second version, only for clients authenticated with one of the schemes the public one declares. That version can include skills the public one does not show, usage limits or per-client configuration.[^a2a-spec]

**The cache.** A card changes rarely and is requested often, so the specification asks the server for a `Cache-Control` header with its `max-age` and an `ETag` derived from the version or a digest of the content, and asks the client for conditional requests when its stored copy expires.[^a2a-spec]

## In a store

Here is how a store's server responds when an agent asks for its card, with the cache headers the specification recommends.[^a2a-spec] It is a **fictitious example**: the domain, the version and the skill are made up, and the card is trimmed.

```http
GET /.well-known/agent-card.json HTTP/1.1
Host: northpack.example

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600
ETag: "1.4.0"

{
  "name": "Northpack Backpacks order agent",
  "description": "Checks the status of an order and shipping times.",
  "version": "1.4.0",
  "supportedInterfaces": [
    { "url": "https://northpack.example/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
  ],
  "capabilities": { "streaming": false, "extendedAgentCard": true },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "order-status",
      "name": "Order status",
      "description": "Says where an order is and when it will arrive.",
      "tags": ["orders", "shipping"],
      "examples": ["When will order 10482 arrive?"]
    }
  ]
}
```

A [shopping agent](/glossary/shopping-agent/) that reads this knows three things: that it can ask about orders in text, at which address and with which version of the protocol; that the store has an extended card, so **there are more skills for whoever authenticates**; and that it does not need to request the card again for an hour. The full example card, with its catalog, is in the entry on [A2A](/glossary/a2a/).


**The public card is no place for anything internal.** The specification asks that the Agent Card not include sensitive credentials or internal implementation details, and that it be served over HTTPS.[^a2a-spec] The discovery guide goes further: a card can inadvertently reveal addresses of internal or restricted agents and descriptions of sensitive skills, and for that it recommends the extended card with authentication and dynamic credentials obtained through another channel, never fixed secrets written into the card.[^a2a-discovery]


## How to check it

1. **Request the card.** `https://{domain}/.well-known/agent-card.json` has to return an AgentCard object.[^a2a-spec]
2. **Go through the required fields** in the table above and the `protocolVersion` of each interface; the current one is 1.0.[^a2a-spec]
3. **If it carries `signatures`, verify one**: the public key is obtained with the signature's `kid` and `jku` data, over HTTPS, and an expired or revoked key is no good.[^a2a-spec]
4. **Look at the response headers**: a `Cache-Control` with `max-age` and an `ETag` say the server follows the caching recommendation.[^a2a-spec]
5. **Look for what should not be there**: secrets, internal addresses or skills that only authenticated clients should see.[^a2a-discovery]

## Related concept: the UCP profile

The UCP profile is the document a merchant publishes at `/.well-known/ucp` to say which purchasing services and capabilities it offers and over which transports: REST, MCP, A2A or an embedded experience.[^ucp-overview] The Agent Card describes **an agent** and how to talk to it over A2A; the UCP profile describes **a merchant** and all the routes through which you can buy from it. They meet at one point: when the profile declares the `a2a` transport, its address is the URL of the Agent Card of the merchant's agent.[^ucp-overview] A buying agent can reach the card through the profile, or directly.

To go further, the [agentic commerce reading path](/learn/agentic-commerce/) orders the rest of the protocols, and the entry on the [protocol gateway](/glossary/protocol-gateway/) explains what happens when an A2A agent has to talk to something that only understands MCP.