Agent cards

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.

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

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 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:

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

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

Card example

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

{
  "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, which power the skills advertised in the card
Read the A2A protocol page for details on the two protocol bindings
Follow the quickstart to create an agent and retrieve its card

Quickstart

Concepts

Guides

Reference

Registry Connectors

Agent SDK

v1 Documentation (archived)

Retrieve an agent card

Card structure

Capabilities

Supported interfaces

Skills

Using cards for discovery

Card example

Next steps

​Retrieve an agent card

​Card structure

​Capabilities

​Supported interfaces

​Skills

​Using cards for discovery

​Card example

​Next steps

Retrieve an agent card

Card structure

Capabilities

Supported interfaces

Skills

Using cards for discovery

Card example

Next steps