What Are Agent Cards?

An Agent Card is the structured JSON document that an AI agent publishes to advertise its identity, capabilities, and contact information to other agents in the A2A Protocol ecosystem. Think of it as a machine-readable business card — one that an orchestrator agent can read, parse, and use to decide whether to delegate a task to that agent.

Published at the standardized URI /.well-known/agent.json, an Agent Card makes agent discovery automatic and protocol-agnostic. Rather than requiring a registry or manual configuration, any agent that knows a peer's domain can retrieve its capabilities at a predictable URL.

Why Agent Cards Exist#

In a multi-agent system, the coordinating orchestrator needs to answer a fundamental question before delegating work: can this agent handle this task? Without a standardized discovery mechanism, developers are forced to hard-code capability knowledge into orchestrators, creating brittle integrations that break when downstream agents are updated.

Agent Cards solve this by externalizing capability metadata. An orchestrator can dynamically retrieve and cache Agent Cards, reason over them with an LLM, and make delegation decisions without any prior coding of downstream capabilities. This is the architectural foundation for true agent interoperability.

The approach mirrors established web standards: just as CORS policies live at a well-known location and OAuth metadata is discoverable at /.well-known/openid-configuration, agent capabilities follow the same pattern. This lets agents integrate into existing HTTP infrastructure without new discovery protocols.

Anatomy of an Agent Card#

A complete Agent Card is a JSON object with several key sections. Here is a representative example:

{
  "name": "Invoice Processing Agent",
  "description": "Processes and validates invoice documents, extracts line items, matches against purchase orders, and triggers approval workflows.",
  "url": "https://invoice-agent.example.com/a2a",
  "version": "1.2.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["text/plain", "application/pdf"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "authentication": {
    "schemes": ["oauth2"],
    "credentials": "https://invoice-agent.example.com/.well-known/oauth-authorization-server"
  },
  "skills": [
    {
      "id": "extract-line-items",
      "name": "Extract Invoice Line Items",
      "description": "Parses an invoice PDF or image and returns structured line item data including quantities, unit prices, and totals.",
      "inputModes": ["application/pdf", "image/png", "image/jpeg"],
      "outputModes": ["application/json"],
      "examples": [
        "Extract all line items from this invoice PDF",
        "Parse the quantities and prices from this invoice"
      ]
    },
    {
      "id": "po-matching",
      "name": "Purchase Order Matching",
      "description": "Matches invoice line items against open purchase orders and flags discrepancies.",
      "inputModes": ["application/json"],
      "outputModes": ["application/json"],
      "tags": ["finance", "procurement", "validation"]
    }
  ]
}

Core Fields#

name and description: These are the fields an orchestrating LLM reads to determine whether this agent is relevant. Keep descriptions precise and actionable — vague descriptions lead to incorrect delegation decisions.

url: The base endpoint where the A2A server accepts task submissions. This is where tasks/send and tasks/get requests are directed.

version: Semantic versioning of the agent. Orchestrators can cache Agent Cards and use the version field to detect when capabilities have changed.

capabilities: A structured object declaring runtime features. streaming: true means the agent supports Server-Sent Events for real-time task updates. pushNotifications indicates whether the agent can proactively notify the client of state changes via webhook. stateTransitionHistory means the agent retains and can return a full history of task state transitions.

The skills Array#

The skills array is the most operationally significant part of an Agent Card. Each skill represents a discrete capability the agent can execute. Orchestrators use skill descriptions — combined with their own LLM reasoning — to select the appropriate agent and skill for a given subtask.

Effective skill descriptions follow these principles:

• Action-oriented: Start with a verb that describes what the agent does ("Extracts", "Validates", "Generates")
• Specific inputs and outputs: Include what the agent consumes and produces, not just what it does
• Domain context: Mention relevant industry or domain terms that help LLM routing (e.g., "purchase orders", "DICOM images", "SEC filings")
• Example queries: Populate the examples field with real prompts a user or orchestrator might send

Authentication Configuration#

The authentication field declares how calling agents must authenticate. The A2A Protocol recommends OAuth 2.1 as the primary authentication mechanism. The credentials URL points to an OAuth authorization server metadata document (RFC 8414), which the calling agent fetches to obtain token endpoints and supported scopes.

API key authentication is also supported for simpler deployments:

"authentication": {
  "schemes": ["apiKey"],
  "credentials": null
}

For production enterprise deployments, always use OAuth 2.1 with properly scoped tokens. See the agent audit trail glossary entry for why authentication logging matters for compliance.

Agent Card Lifecycle#

Agent Cards are not static documents. As an agent evolves — gaining new skills, changing authentication requirements, or modifying supported input types — its card must be updated. Orchestrators that cache cards should implement cache invalidation based on the version field and optionally use HTTP cache headers like Cache-Control and ETag to stay current.

In a microservices environment, Agent Card updates should be treated like API contract changes: versioned, documented in a changelog, and communicated to dependent orchestrators. Breaking changes (removing a skill or changing the url) require a version bump and a deprecation period.

Agent Cards in Multi-Agent Pipelines#

When building multi-agent systems with Google ADK or the A2A Python SDK, Agent Cards serve as the entry point for dynamic agent routing. An orchestrator agent can:

1. Maintain a registry of known Agent Card URLs for trusted agents
2. Retrieve and parse each card at startup (or on-demand)
3. Use its LLM to match incoming task descriptions against skill descriptions
4. Delegate tasks to the best-matched agent using the A2A task protocol

This pattern keeps orchestrator logic decoupled from downstream agent implementations, enabling the kind of plug-and-play agent composition that A2A agent discovery was designed for.

Relationship to MCP#

Agent Cards are specific to the A2A Protocol. The Model Context Protocol (MCP) has its own server discovery mechanism, separate from Agent Cards. The two protocols are complementary: MCP handles agent-to-tool communication (connecting agents to data sources and external APIs), while A2A with Agent Cards handles agent-to-agent communication. A well-designed agent may implement both — publishing an Agent Card for peer agents while also acting as an MCP client to access tools.

See the MCP vs A2A Protocol comparison for a detailed breakdown of when to use each.

Best Practices for Agent Card Design#

• Keep descriptions grounded: Write skill descriptions that match how orchestrator LLMs will phrase delegation requests
• Enumerate input/output MIME types completely: Incomplete type lists cause silent routing failures
• Use semantic versioning rigorously: Major version bumps for breaking changes, minor for new skills
• Secure the /.well-known/agent.json endpoint: While it should be publicly readable, protect it against modification and ensure it's served over HTTPS only
• Validate cards against the A2A JSON Schema: The A2A SDK provides schema validation utilities
• Include operational metadata: Response time SLAs, rate limits, and geographic availability help orchestrators make better delegation decisions

Agent Cards are deceptively simple documents with significant architectural implications. Investing time in well-crafted skill descriptions and complete capability metadata pays dividends in orchestrator routing accuracy and system reliability.

More Resources#

Browse the complete AI agent glossary for more AI agent terminology.