# Agent cards (/docs/concepts/agent-cards)



An **agent card** is the public description of your agent. Clients fetch it to learn what the agent is called, what it can do, and where to send requests.

```bash
curl -s http://localhost:3000/.well-known/agent-card.json | jq .
```

## Configuring the card [#configuring-the-card]

The card is generated from the `agentCard` and `server` blocks of your config:

```json
{
  "agentCard": {
    "name": "Claude Workspace Engineer",
    "description": "A repository-scoped software engineering agent backed by Claude.",
    "version": "1.0.0",
    "protocolVersion": "0.3.0",
    "streaming": true,
    "defaultInputModes": ["text"],
    "defaultOutputModes": ["text"],
    "skills": [
      {
        "id": "workspace-engineering",
        "name": "Workspace Engineering",
        "description": "Inspect, modify, and validate code within the configured workspace.",
        "tags": ["code", "repository", "tests"]
      }
    ]
  },
  "server": {
    "port": 3030,
    "hostname": "127.0.0.1",
    "advertiseHost": "localhost",
    "advertiseProtocol": "http"
  }
}
```

| Field                                       | Purpose                                                                                                           |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `agentCard.name`, `description`             | What callers see first. Write them for orchestrators deciding whether to route work to you                        |
| `agentCard.skills`                          | Advertised capabilities (`id`, `name`, `description`, `tags`, optional `examples`)                                |
| `server.port`, `server.hostname`            | Where the server listens. `hostname` defaults to `0.0.0.0`, see the [security guide](/docs/guides/security)       |
| `server.advertiseHost`, `advertiseProtocol` | The host and protocol written into the card's endpoint URLs. Set these when running behind Docker, a proxy or TLS |

<Callout>
  `advertiseHost` only changes the URLs in the card. It does not restrict who can connect. Use `hostname` and your network for that.
</Callout>

## Skills: card versus memory [#skills-card-versus-memory]

Two similarly named concepts are easy to confuse:

* **`agentCard.skills`** is protocol metadata shown to callers. It describes what the agent can do at a high level, for discovery and routing.
* **`memory.skills`** is instructions written into the agent's workspace for the model. It is never exposed externally.

See [memory and skills](/docs/concepts/memory-and-skills).

## Version-aware responses [#version-aware-responses]

The card endpoint reads the caller's `A2A-Version` header:

* `1.0` returns the native v1.0 card with `supportedInterfaces[]`.
* `0.3`, `0.3.0` or no header returns a v0.3-shaped legacy card (`url`, `protocolVersion: "0.3.0"`).

So old and new clients both work with no extra configuration. Details in [protocol versions](/docs/concepts/protocol-versions).

## Signed agent cards [#signed-agent-cards]

A2A v1.0 supports JWS-signed cards (RFC 7515). This is opt-in: pass `ServerOptions.agentCardSigning`, or set `AgentCardConfig.signing` with the private key read from an environment variable holding a JWK. The card's `signatures` field is then populated automatically. Unsigned cards simply omit it.

## Trace extension [#trace-extension]

Cards declare the `urn:x-a2a:trace:v1` extension, which tells orchestrators the agent can emit [sideband trace artifacts](/docs/concepts/observability). It is optional for callers to use.