AgentCard

An AgentCard is the discovery primitive of the A2A protocol. It is a JSON document published by a Remote Agent at the well-known URL /.well-known/agent-card.json on its domain (per RFC 8615). The card describes the agent's identity (name, description, provider), service endpoint URL, declared capabilities (streaming, push notifications, extended cards), security requirements (Bearer, OAuth2, API key), and a list of skills with their input and output modes plus example invocations. Client Agents fetch this card to decide whether the Remote Agent is suitable for a given task and how to authenticate before sending requests.

AgentCards eliminate the need for a central agent registry. Any agent that wants to be discoverable just publishes its card at the standard path on its domain. Cards can be cryptographically signed using JWS (the AgentCardSignature field) so clients can verify the agent has not been tampered with. Authenticated clients can also call the GetExtendedAgentCard method to fetch private skills not listed in the public card. This pattern mirrors well-known files like /.well-known/openid-configuration and /robots.txt and inherits the same operational simplicity.

// AgentCard published at https://invoices.example.com/.well-known/agent-card.json
{
  "name": "Invoice Processing Agent",
  "description": "Extracts structured data from invoice PDFs",
  "provider": { "organization": "ExampleCorp" },
  "url": "https://invoices.example.com/a2a",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": true
  },
  "securitySchemes": { "bearer": { "type": "http", "scheme": "Bearer" } },
  "skills": [{
    "id": "extract_invoice",
    "name": "Extract invoice data",
    "description": "Parses an invoice PDF and returns line items",
    "inputModes": ["application/pdf"],
    "outputModes": ["application/json"]
  }]
}

A typical AgentCard. The Client Agent reads this to decide if the Remote Agent can handle its task.

Every A2A Remote Agent must publish an AgentCard. As a builder, you maintain it as your agent's capabilities evolve. As a Client Agent author, you fetch and parse cards before sending Tasks.

• A2A Agent Discovery docs
• A2A Key Concepts
• A2A spec §4 (AgentCard)

Related Terms