A2A Agent Cards: How AI Agents Discover Each Other's Capabilities

What an Agent Card Contains

An Agent Card is a structured JSON object with fields that fall into four categories: identity, capabilities, interaction modes, and security. Together, these fields give a client agent everything it needs to decide whether to connect, how to authenticate, and what tasks to send.

The identity fields include name (a human-readable agent name like "Financial Analysis Agent"), description (a paragraph explaining what the agent does and what it is best suited for), and url (the endpoint URL where the agent accepts A2A JSON-RPC requests). The description is particularly important because client agents and orchestrators use it to evaluate whether this agent is a good match for a specific task. A vague description leads to poor delegation decisions.

The capabilities section centers on the skills array, the most functionally important part of the Agent Card. Each skill represents a specific capability the agent offers, with its own name, description, and optional JSON Schema definitions for inputs and outputs. The skills array tells client agents exactly what tasks this server can handle and how to structure requests for each one.

Interaction mode fields declare what content types the agent can process and return. The supportedModes field indicates whether the agent handles text input, structured forms, file uploads, or other content types. The defaultInputModes and defaultOutputModes fields specify the agent's preferred formats. These declarations prevent mismatches where a client sends a file to an agent that only handles text, or expects structured JSON output from an agent that only returns prose.

The security section specifies authentication requirements. The authentication field declares what auth schemes the agent accepts (OAuth 2.0, API key, bearer token, none), along with configuration details like token endpoint URLs and required scopes for OAuth. By declaring auth requirements upfront, the Agent Card eliminates the discovery problem where clients send unauthenticated requests and receive opaque 401 errors.

The Skills Array in Detail

Skills are the heart of the Agent Card. Each skill object contains a id (a unique identifier like "analyze-dataset" or "generate-report"), a name (human-readable label), and a description (detailed explanation of what the skill does, what inputs it expects, and what outputs it produces).

Optional fields include inputSchema and outputSchema, both JSON Schema objects that formally define the structure of skill inputs and outputs. When these schemas are present, client agents can validate their requests before sending them, reducing errors and round trips. They also let orchestrators programmatically match skills to task requirements based on data structure compatibility.

A well-designed skills array follows several principles. Each skill should represent a distinct, well-defined capability rather than a broad category. "Analyze quarterly revenue data and produce trend analysis" is better than "do data analysis." Descriptions should be detailed enough for an LLM (powering the client agent) to understand when and how to use the skill. Include information about expected input format, processing time, output format, and any limitations.

Consider a financial analysis agent's skills array. Instead of a single skill called "financial-analysis," it might list: "revenue-trend-analysis" (analyzes revenue time series and identifies growth patterns), "cost-center-comparison" (compares spending across departments with variance analysis), "cash-flow-projection" (generates 12-month cash flow forecasts from historical data), and "financial-report" (produces formatted executive summaries of financial metrics). Each skill has a clear scope, and a client agent can match the right skill to the right task.

Example Agent Card

A realistic Agent Card for a data analysis agent might look like this in practice. The agent accepts OAuth 2.0 authentication, supports text and structured data input, and offers three distinct skills for different types of analysis work.

The top-level fields establish identity: name ("DataSense Analysis Agent"), description ("Specialized agent for statistical analysis, data visualization, and trend detection. Handles CSV, JSON, and SQL query results. Produces charts, summary statistics, and written analysis reports."), and url ("https://datasense.example.com/a2a"). The version field indicates which A2A protocol version this agent implements.

The skills array lists three entries. The first skill, "statistical-summary," accepts structured data and returns descriptive statistics including mean, median, standard deviation, quartiles, and distribution shape. The second skill, "trend-analysis," accepts time-series data and produces trend lines, seasonal decomposition, and growth rate calculations. The third skill, "visualization," accepts data and visualization parameters and returns chart images (PNG or SVG) with configurable chart types, colors, and labels.

The authentication section specifies OAuth 2.0 with a token endpoint URL and required scopes. The supportedModes section declares that the agent accepts text and structured data (DataPart) as inputs and can return text, structured data, and files (FilePart for charts) as outputs.

The Well-Known URL Convention

Every A2A agent serves its Agent Card at the path /.well-known/agent.json relative to the agent's domain. This follows the IETF well-known URI convention (RFC 8615) used by other standards like OAuth discovery documents and security.txt files. A client that knows an agent's domain can always find its Agent Card at a predictable URL without needing any prior configuration.

For example, an agent running at https://analytics.example.com serves its Agent Card at https://analytics.example.com/.well-known/agent.json. The A2A endpoint URL specified in the card might be the same domain (https://analytics.example.com/a2a) or a different host entirely, depending on the deployment architecture. The well-known URL is just for discovery, not for A2A protocol operations.

The Agent Card is served as a standard HTTP GET response with Content-Type: application/json. No authentication is required to fetch the card itself, even if the agent's A2A endpoint requires authentication. This is intentional: clients need to read the card to learn the authentication requirements, so the card must be accessible without authentication. Sensitive information (internal architecture details, private configurations) should never appear in the Agent Card.

Discovery Strategies

The well-known URL convention handles point-to-point discovery when a client already knows the server's domain. For broader discovery, where a client needs to find the best agent for a task from a pool of candidates, several strategies exist.

Static configuration. The simplest approach. A system administrator maintains a list of known agent URLs in the client's configuration. The client fetches Agent Cards from these URLs at startup and caches them. This works well for closed enterprise environments with a fixed set of internal agents.

Registry services. A central registry stores Agent Cards from multiple agents and provides search capabilities. Clients query the registry for agents matching specific criteria (skills, content types, authentication compatibility) and receive a list of matching Agent Card URLs. Several open-source A2A registry implementations are available, and cloud providers are building managed registry services.

Orchestrator-driven discovery. A master orchestrator agent maintains knowledge of available agents and handles delegation decisions. Other agents in the system do not discover peers directly but instead ask the orchestrator to route tasks to the appropriate agent. The orchestrator fetches and caches Agent Cards, evaluates skill matches, handles load balancing, and manages failover.

DNS-based discovery. For organizations that deploy multiple agents across subdomains, DNS SRV records or TXT records can point to Agent Card URLs. This leverages existing DNS infrastructure for discovery without requiring a separate registry service. A client resolving _a2a._tcp.example.com receives a list of agent endpoints to query.

Agent Card Best Practices

Writing effective Agent Cards is partly technical and partly communicative. The card must be valid JSON that conforms to the A2A specification, but it also must effectively communicate the agent's capabilities to both human developers and LLM-powered client agents that will read the descriptions programmatically.

Write descriptions for LLMs. The agent and skill descriptions will often be processed by the LLM powering the client agent as part of its decision about which agent to delegate to. Write descriptions that are clear, specific, and free of jargon that might confuse a language model. Include concrete examples of what the agent does well and what it does not handle. "Produces statistical analysis of tabular data including regression, correlation, and time-series decomposition" is better than "does analytics stuff."

Scope skills narrowly. Many small, well-defined skills are more useful than a few broad ones. A client agent can match narrow skills precisely to specific tasks, while broad skills create ambiguity about what the agent will actually do. If your agent handles both data analysis and report generation, list them as separate skills rather than combining them into one "analyze-and-report" skill.

Include input and output schemas. JSON Schema definitions for skill inputs and outputs enable automated validation, help LLMs generate correctly structured requests, and make the Agent Card machine-readable for orchestrators that need to match skills based on data compatibility. Schemas add verbosity to the card but dramatically reduce integration errors.

Version your Agent Card. Include a version field and update it when skills change, authentication requirements evolve, or the endpoint URL moves. Clients can cache Agent Cards and check the version to detect changes without re-parsing the entire card.

Keep the card lightweight. The Agent Card should contain only information needed for discovery and connection. Internal configuration, implementation details, and operational parameters belong in the agent's own configuration, not in the publicly accessible card. A bloated Agent Card is harder to parse, slower to transfer, and risks exposing information that should remain private.