A2A Agent Card: Structure, Discovery, and Signing

An Agent Card is the JSON document through which an A2A server describes itself: who it is, which interfaces it exposes, what it can do, and how clients must authenticate. A2A servers MUST make one available. Clients read it to decide whether an agent suits a task and how to talk to it.

Where clients find it

The specification lists three ways to obtain an Agent Card:

• Well-known URI: https://{server_domain}/.well-known/agent-card.json
• Registries or catalogs: curated collections of agents
• Direct configuration: a pre-configured Agent Card URL or the card content itself

Strategies and trade-offs are covered in Agent Discovery in A2A .

A minimal card

This is the example the specification uses to explain canonicalization:

{
  "name": "Example Agent",
  "description": "An example agent that echoes messages.",
  "supportedInterfaces": [
    {
      "url": "https://example.com/a2a/v1",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extensions": []
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "echo",
      "name": "Echo",
      "description": "Echoes the input.",
      "tags": ["echo"]
    }
  ]
}

In v1.0 the required fields are name, description, version, supportedInterfaces, capabilities, defaultInputModes, defaultOutputModes, and skills. Optional fields include provider, documentationUrl, iconUrl, securitySchemes, securityRequirements, and signatures.

Declaring interfaces

supportedInterfaces lists every combination of protocol binding and URL the agent supports, in preference order. The first entry is the preferred interface, and the same URL can be reused when several transports share one endpoint. This excerpt is from the specification’s sample card:

"supportedInterfaces": [
  {"url": "https://georoute-agent.example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"},
  {"url": "https://georoute-agent.example.com/a2a/grpc", "protocolBinding": "GRPC", "protocolVersion": "1.0"},
  {"url": "https://georoute-agent.example.com/a2a/json", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"}
]

Clients MUST follow these rules:

1. Parse supportedInterfaces and select the first transport the client supports.
2. Prefer earlier entries when several options are supported.
3. Use the URL that belongs to the selected transport.
4. Set tenant in every request message to exactly the value in the selected entry, and omit it if the entry has none. See Multi-Tenancy and Multi-Agent Routing .

Capabilities, modes, and skills

capabilities declares optional features:

• streaming: the agent supports streaming. Streaming operations require it to be true.
• pushNotifications: the agent can send webhook notifications. Push notification operations require it to be true.
• extendedAgentCard: an authenticated client can call GetExtendedAgentCard for a fuller card, which may add skills or settings the public card does not show. Clients SHOULD replace their cached public card with it for the authenticated session.
• extensions: the protocol extensions the agent supports. See Extensions in A2A .

defaultInputModes and defaultOutputModes are the media types the agent accepts and returns across all skills, and each skill can override them. A skill is described by id, name, description, and tags, plus optional examples, inputModes, outputModes, and securityRequirements; the full field list and rules are on the AgentSkill page. One skill from the specification’s sample card (the second example prompt is omitted here):

{
  "id": "route-optimizer-traffic",
  "name": "Traffic-Aware Route Optimizer",
  "description": "Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).",
  "tags": ["maps", "routing", "navigation", "directions", "traffic"],
  "examples": [
    "Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls."
  ],
  "inputModes": ["application/json", "text/plain"],
  "outputModes": ["application/json", "application/vnd.geo+json", "text/html"]
}

Security

securitySchemes is a map from a name you choose to a scheme definition, and securityRequirements states which schemes, and which scopes, a client must satisfy. The sample card uses OpenID Connect:

"securitySchemes": {
  "google": {
    "openIdConnectSecurityScheme": {
      "openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
    }
  }
},
"securityRequirements": [{ "schemes": { "google": { "list": ["openid", "profile", "email"] } } }]

The five scheme types are API key, HTTP authentication, OAuth 2.0, OpenID Connect, and mutual TLS; each one’s fields and the OAuth 2.0 flows are on the SecurityScheme page. A client reads the requirements from the card, obtains credentials out-of-band (for example through an OAuth 2.0 flow), and sends them in protocol-appropriate headers or metadata on every request. The server MUST authenticate every incoming request. See Enterprise Implementation of A2A .

Signing

An Agent Card MAY be signed so clients can check that it is authentic and unchanged:

• The card is canonicalized with the JSON Canonicalization Scheme (RFC 8785) and signed as a JSON Web Signature (RFC 7515). Before canonicalizing, fields that hold default values are removed unless they are required or marked optional; for the minimal card above that removes the empty extensions array. The signatures field is excluded from the signed content.
• Each entry in signatures has a base64url protected header, a base64url signature, and an optional unprotected header. The protected header must include alg and kid, and typ should be JOSE. It may include jku, the URL of the key set.
• Clients SHOULD verify at least one signature before trusting a card. Several signatures can be present to support key rotation, and expired or revoked keys MUST NOT be used.

The full procedure is in Agent Discovery and the Agent Card .

Caching

Agent Cards change rarely, so servers SHOULD send Cache-Control with a suitable max-age and an ETag. Clients SHOULD follow HTTP caching rules (RFC 9111) and use conditional requests, If-None-Match or If-Modified-Since, once a cached card expires.

Coming from v0.3?

The full list of changes is in What’s New in A2A Protocol v1.0 . The protobuf field numbers behind these changes, including where the extended Agent Card flag went, are in Agent Card Proto Field Numbers .

Related pages

• Agent Card Implementation Guide : the decisions behind each field, a runnable validator, and fixes for common failures.
• AgentSkill and SecurityScheme : the two objects that fill most of a card.
• Task and Message : what clients send once they have chosen an interface.
• Data Structures : every Agent Card field and the security scheme objects.

Source: A2A official specification: Agent Discovery Objects and Agent Discovery: The Agent Card