Agent Card

An Agent Card is the JSON metadata document an A2A server publishes to describe its identity, service endpoints, capabilities, skills and authentication requirements. Every A2A server must make one available (specification section 8.1), and clients read it before they send a first request.

Discovery. The standard location is https://{server_domain}/.well-known/agent-card.json, registered as a well-known URI in section 14.3. Clients can also find cards through registries and catalogs, or be configured with a card URL or its content directly.

Contents. The normative definition is the AgentCard message in a2a.proto. In v1.0 the required fields are name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes and skills. Optional fields include provider, documentationUrl, iconUrl, securitySchemes, securityRequirements and signatures. The capabilities object declares optional features: streaming, pushNotifications, extendedAgentCard and supported extensions. Clients should check these flags first, because an agent must return an error for an operation that needs a capability it has not declared.

Illustrative v1.0 card:

{
  "name": "Parcel Status Agent",
  "description": "Answers shipment status questions for Example Freight customers.",
  "supportedInterfaces": [
    {"url": "https://agents.example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}
  ],
  "version": "1.0.0",
  "capabilities": {"streaming": false, "pushNotifications": false},
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {"id": "shipment-status", "name": "Shipment status", "description": "Looks up a shipment by tracking number.", "tags": ["shipping", "tracking"]}
  ]
}

Caching and exposure. Servers should send Cache-Control with a max-age and an ETag based on the card’s version or content, and clients should honour both (section 8.6). The card is public, so it should not contain credentials or internal implementation details.

Neighbouring terms. supportedInterfaces says where and how to connect. Each agent skill describes one capability. A signed Agent Card adds JWS signatures so clients can detect tampering. An extended Agent Card is a fuller version served only to authenticated clients. Older versions differ: v0.3 put the endpoint in a top-level url with preferredTransport, and v0.2 used the path /.well-known/agent.json.