> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent cards

> Learn how A2A agent cards enable discovery and describe an agent's capabilities, skills, and supported protocol bindings.

An agent card is a JSON document that describes an agent's identity, capabilities, skills, and supported protocol bindings. It serves as a machine-readable business card that lets clients discover agents and determine how to communicate with them.

Agent cards follow the A2A v1.0 specification and are served at the standard `.well-known` location.

## Retrieve an agent card

Every agent exposes its card at:

```
GET /v2/agentic/agents/{agentId}/.well-known/agent-card.json
```

This endpoint requires authentication (bearer token and tenant header), same as all other v2 API endpoints.

The response includes an `A2A-Version: 1.0` header indicating the protocol version the server uses.

## Card structure

| Field                 | Type      | Description                                                                 |
| --------------------- | --------- | --------------------------------------------------------------------------- |
| `name`                | string    | Agent display name                                                          |
| `description`         | string    | What the agent does                                                         |
| `version`             | string    | Agent card version (SemVer)                                                 |
| `capabilities`        | object    | Capability flags: `streaming`, `pushNotifications`                          |
| `defaultInputModes`   | string\[] | Default input media types (e.g. `text/plain`)                               |
| `defaultOutputModes`  | string\[] | Default output media types                                                  |
| `provider`            | object    | Publishing organization and URL                                             |
| `skills`              | object\[] | Skills the agent exposes, each with `id`, `name`, `description`, and `tags` |
| `supportedInterfaces` | object\[] | A2A protocol bindings the agent supports                                    |
| `documentationUrl`    | string    | URL providing additional documentation about the agent                      |
| `iconUrl`             | string    | Optional URL to an icon for the agent                                       |

### Capabilities

The `capabilities` object advertises what the agent can do:

* **`streaming`**: Whether the agent supports streaming responses via SSE. If `true`, you can use `message:stream` and `tasks:subscribe`.
* **`pushNotifications`**: Whether the agent can push task updates to a client-supplied webhook.

<Note>`pushNotifications` is future scope. The `tasks/pushNotificationConfig/*` management endpoints are not yet implemented. Expect this field to be `false` until they ship.</Note>

### Supported interfaces

Each entry in `supportedInterfaces` declares one A2A protocol binding:

| Property          | Description                                 |
| ----------------- | ------------------------------------------- |
| `protocolBinding` | The binding type: `JSONRPC` or `HTTP+JSON`  |
| `protocolVersion` | Always `1.0` (Corti supports A2A v1.0 only) |
| `url`             | The endpoint URL for this binding           |

Both bindings share the same base URL (`/v2/agentic/agents/{agentId}/a2a`). The `JSONRPC` binding sends a JSON-RPC envelope; the `HTTP+JSON` binding uses path-suffixed endpoints like `message:send` and `message:stream`. See [A2A protocol](/agentic/a2a-protocol) for details.

### Skills

Each skill in the `skills` array represents a capability the agent exposes through its connectors. The `id` is a bare UUID (the connector's external ID). Skills help clients understand what an agent can do before sending a message.

## Using cards for discovery

Agent cards enable a discovery workflow:

1. A client fetches the card from a known agent URL.
2. The client inspects `supportedInterfaces` to determine which protocol binding to use.
3. The client checks `capabilities.streaming` to decide whether to use blocking or streaming calls.
4. The client reviews `skills` to understand what the agent can do.
5. The client sends a message using the appropriate binding.

<Info>Retrieving an agent card requires the same authentication as any other v2 API request. You need a valid bearer token and tenant header.</Info>

## Card example

The following is a typical agent card for a coding agent:

```json theme={null}
{
  "name": "coder",
  "description": "Returns ICD-10 codes for a clinical encounter.",
  "version": "0.1.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "provider": {
    "organization": "Corti",
    "url": "https://corti.ai"
  },
  "skills": [
    {
      "id": "con.0192f4c8-7baf-7083-a46f-81d2bd70cf95",
      "name": "coding-expert",
      "description": "ICD-10 coding.",
      "tags": ["expert"]
    }
  ],
  "supportedInterfaces": [
    {
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0",
      "url": "https://api.eu.corti.app/v2/agentic/agents/agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40/a2a"
    },
    {
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0",
      "url": "https://api.eu.corti.app/v2/agentic/agents/agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40/a2a"
    }
  ]
}
```

## Next steps

* Learn about [connectors](/agentic/connectors), which power the skills advertised in the card
* Read the [A2A protocol](/agentic/a2a-protocol) page for details on the two protocol bindings
* Follow the [quickstart](/agentic/quickstart) to create an agent and retrieve its card