In a multi-agent ecosystem, the first challenge isn’t communication—it’s discovery. Before an agent can delegate work to another agent, it needs to know what agents exist, what they can do, what inputs they accept, and how to authenticate. Agent Cards are the A2A protocol’s answer to this problem: standardized JSON metadata documents that serve as a digital “business card” for every agent in the system.
Agent Cards enable capability discovery—the process by which client agents find and evaluate server agents at runtime. This is analogous to how DNS and service discovery work in microservices architecture, but tailored for the unique requirements of AI agents: advertising skills, specifying supported content types, and declaring authentication requirements.
Without a discovery mechanism, multi-agent systems would require hardcoded integrations between every pair of agents. Agent Cards make the system dynamic and extensible—new agents can join the ecosystem simply by publishing a card, and clients can find them automatically.
An Agent Card is a JSON document with a well-defined schema. It contains everything a client needs to decide whether to use an agent and how to communicate with it:
A JSON metadata document published by an A2A Server at a well-known URL, describing the agent’s identity, capabilities, skills, service endpoint, supported input/output modes, and authentication requirements. It is the foundation of all A2A interactions—no card, no communication.
The core fields of an Agent Card include:
name (required) — Human-readable name of the agent (e.g., “Invoice Processing Agent”)description — A natural language description of what the agent does, used by LLMs to decide when to invoke iturl (required) — The service endpoint where the agent accepts A2A requestsversion (required) — The A2A protocol version the agent supportsprovider — Organization information (name, URL) for the entity hosting the agentdocumentationUrl — Link to detailed agent documentationcapabilities (required) — Protocol features the agent supports (streaming, push notifications, state history)skills (required) — Array of specific tasks the agent can performdefaultInputModes / defaultOutputModes — MIME types the agent accepts and produces by defaultauthentication — Required auth schemes (Bearer, API key, OAuth, etc.)The skills array is where agents declare what they can actually do. Each skill is a discrete unit of capability with its own metadata:
{
"name": "Invoice Processing Agent",
"description": "Extracts, validates, and routes invoices from multiple formats",
"url": "https://agents.example.com/invoice",
"version": "0.3.0",
"provider": {
"organization": "Acme Corp",
"url": "https://acme.example.com"
},
"capabilities": {
"streaming": true,
"pushNotifications": false,
"stateTransitionHistory": true
},
"skills": [
{
"id": "extract-invoice-data",
"name": "Extract Invoice Data",
"description": "Extracts structured data from PDF, image, or email invoices",
"tags": ["invoice", "extraction", "ocr"],
"inputModes": ["application/pdf", "image/png", "text/plain"],
"outputModes": ["application/json"]
},
{
"id": "validate-invoice",
"name": "Validate Invoice",
"description": "Cross-checks extracted invoice data against vendor database and PO records",
"tags": ["invoice", "validation", "compliance"],
"inputModes": ["application/json"],
"outputModes": ["application/json"]
},
{
"id": "route-for-approval",
"name": "Route for Approval",
"description": "Routes validated invoices to the appropriate approver based on amount and department",
"tags": ["invoice", "routing", "approval"],
"inputModes": ["application/json"],
"outputModes": ["application/json", "text/plain"]
}
],
"defaultInputModes": ["text/plain", "application/json"],
"defaultOutputModes": ["application/json"],
"authentication": {
"schemes": ["Bearer"],
"credentials": null
}
}The tags field is particularly important for discovery—it enables semantic search across agent registries. A client looking for agents that can handle “invoice” or “ocr” tasks can filter the registry by these tags.
The A2A protocol supports several mechanisms for discovering Agent Cards:
The simplest method: agents publish their card at a standard path. Clients can retrieve any agent’s card with a simple HTTP GET request:
GET https://agents.example.com/.well-known/agent-card.json
# Response: the full Agent Card JSON documentThis follows the same pattern as /.well-known/openid-configuration in OAuth or /robots.txt in web crawling. It works well when you know the agent’s base URL but need to discover its capabilities.
For organizations with many agents, a central registry acts as a searchable catalog. Clients query the registry with criteria like skill tags, input/output types, or provider names:
// Query a registry for agents with specific capabilities
GET https://registry.example.com/agents?tags=invoice,extraction&inputModes=application/pdf
// Response: array of matching Agent Cards
[
{
"name": "Invoice Processing Agent",
"url": "https://agents.example.com/invoice",
"skills": [...]
},
{
"name": "Document Extraction Service",
"url": "https://docs.example.com/extract",
"skills": [...]
}
]Registries can be private (within an organization) or public (for agent marketplaces). They typically index Agent Cards and provide search, filtering, and ranking capabilities.
For tightly coupled systems, development environments, or private agents, clients can be directly configured with Agent Card information. This bypasses runtime discovery entirely:
# Configuration file pointing to known agents
agents:
- name: "Internal HR Agent"
card_url: "https://hr-agent.internal.corp/.well-known/agent-card.json"
- name: "Finance Agent"
card_url: "https://finance-agent.internal.corp/.well-known/agent-card.json"Discovery answers “what agents exist and what can they do?” while resolution answers “how do I reach a specific agent?” The well-known URL pattern handles both simultaneously, but in large-scale deployments these may be separate concerns—a registry handles discovery, while DNS/service mesh handles resolution.
Agent Cards declare what authentication is required to interact with the agent. This is critical for enterprise deployments where agents handle sensitive data:
The capabilities field enables feature negotiation between client and server. Before starting a long-running task, a client checks whether the server supports streaming (to avoid polling) or push notifications (to receive updates asynchronously). This prevents runtime failures from mismatched expectations.
In sophisticated orchestration systems, the orchestrator agent doesn’t use hardcoded routing logic. Instead, it fetches Agent Cards from a registry, feeds the card descriptions to its LLM, and lets the model decide which agent is best suited for a given subtask. The description and skills.description fields in Agent Cards are written in natural language specifically to support this pattern.
Large organizations deploying dozens of internal agents use a curated registry as an “agent catalog.” Teams register their agents with detailed skill descriptions and tags. When another team’s orchestrator needs a capability (e.g., “translate this document to Spanish”), it queries the catalog, finds the translation agent, reads its card, and delegates the work—all without any custom integration code.
In Kubernetes-based deployments, Agent Cards can be integrated with service mesh infrastructure. When a new agent instance spins up, it registers its card with the service mesh. Load balancers can use skill metadata to route requests to the most appropriate instance—for example, routing image-processing tasks only to GPU-equipped agent pods.
Agent Cards enable secure collaboration between organizations. A consulting firm’s agent can discover and invoke a client’s internal agents (or vice versa) through exchanged Agent Cards, with authentication requirements ensuring proper access control. Signed cards (v0.3+) provide cryptographic guarantees of agent identity.
skills array is the most important field: it declares specific capabilities with tags, input/output MIME types, and natural language descriptions that support LLM-driven agent selection./.well-known/agent-card.json), curated registries (searchable catalogs), and direct configuration (for known/private agents).capabilities field enables feature negotiation—clients check for streaming, push notification, or history support before initiating communication.