An agent card is a machine-readable JSON metadata document in which an AI agent publishes who it is, what it can do, where it can be reached and how clients must authenticate. In the field of AI agents within artificial intelligence, the term comes from the Agent2Agent (A2A) protocol, where the card serves as the agent’s public business card for discovery and is therefore also called an A2A agent card.
Before one agent delegates a task to another, it needs to know whether the remote agent is capable, trustworthy and reachable. The agent card answers those questions before any task is sent, which allows independent agents built with different frameworks and vendors to interoperate without custom integration code.
What an agent card contains
An agent card contains a fixed set of descriptive fields defined by the A2A specification, grouped into identity, connectivity, capabilities, skills and security. A client reads these fields to decide whether and how to interact with the agent.
The identity fields name the agent, describe its purpose in natural language, state its version and identify the provider organization. The connectivity fields give the service endpoint, the protocol version and the preferred transport binding, such as JSON-RPC over HTTP, gRPC or HTTP with JSON. The skills list is the functional heart of the card: each skill has an identifier, a name, a description, tags, example prompts and the input and output media types it accepts.
The following table summarizes the principal fields and what a client uses each one for.
| Field group | Typical fields | What the client uses it for |
|---|---|---|
| Identity | name, description, version, provider | Recognizing and selecting the agent |
| Connectivity | url, protocolVersion, preferredTransport | Opening a compatible connection |
| Capabilities | streaming, pushNotifications | Choosing the interaction pattern |
| Skills | id, description, tags, examples | Matching tasks to abilities |
| Media modes | defaultInputModes, defaultOutputModes | Formatting requests and parsing replies |
| Security | securitySchemes, security | Obtaining the right credentials |
How agents discover and use an agent card
A client agent discovers an agent card by fetching it from a known location, consulting a registry or receiving it through configuration. The standard convention is a well-known URI on the agent’s domain, /.well-known/agent-card.json, following the same pattern that web standards use for security policies and service metadata.
After retrieval, the client parses the card, checks protocol compatibility and compares the advertised skills with the task at hand. An orchestrator in a multi-agent system may cache many cards and use skill descriptions and tags to route subtasks, much as a planner chooses tools by reading their tool schemas. The client then authenticates according to the declared scheme and sends the first message to the endpoint.
| Discovery method | How it works | Best suited for |
|---|---|---|
| Well-known URI | Client requests a fixed path on the agent’s domain | Public or partner-facing agents |
| Curated registry | Central catalog stores and indexes cards | Enterprises with many internal agents |
| Direct configuration | Card or its location is set in client settings | Tightly coupled or private deployments |
| Authenticated extended card | Richer card returned after login | Skills visible only to authorized clients |
The authenticated extended card deserves attention: the public card can expose only a minimal description, while sensitive skills and details are revealed only to authenticated callers. This separation limits what an anonymous party learns about internal capabilities.
Agent card compared with related descriptors
An agent card describes an autonomous peer agent, whereas related descriptors describe tools, servers or programming interfaces. The distinction matters because a peer agent negotiates and executes whole tasks with its own reasoning, while a tool performs a single, well-defined function.
| Descriptor | Describes | Granularity | Typical consumer |
|---|---|---|---|
| Agent card | An opaque, autonomous agent | Skills and whole tasks | Other agents via A2A |
| Tool schema | A single callable function | Parameters of one call | A model using tool calling |
| MCP server manifest | Tools, resources and prompts | Individual capabilities | An MCP client inside an agent |
| OpenAPI document | A REST interface | Endpoints and payloads | Developers and code generators |
In practice the protocols are complementary rather than competing: an agent often uses MCP to reach its own tools and data, while it advertises itself to other agents through an agent card. The card deliberately keeps the agent opaque, revealing what it can do without exposing its internal prompts, memory or tool chain.
Writing a useful agent card
A useful agent card is specific, honest and testable, because both human developers and language models read it to decide whether to delegate work. Vague skill descriptions lead to wrong routing, and inflated claims lead to failed tasks.
- Write one skill per distinct capability rather than a single catch-all skill, and give each a concrete description.
- Provide realistic example prompts so that routing models can match user intent to the right skill.
- Declare accurate media types, for example
application/pdfortext/plain, so that clients do not send unsupported content. - Advertise streaming or push notifications only when the server actually supports them.
- Increment the version field whenever skills or behavior change, so cached copies can be refreshed.
The decision table below shows how common design questions are usually resolved.
| Situation | Recommended choice | Reason |
|---|---|---|
| Long-running tasks of minutes or hours | Enable push notifications | Client need not hold a connection open |
| Incremental output such as drafts | Enable streaming | Partial results arrive early |
| Sensitive internal skills | Use an extended card | Public card stays minimal |
| Agent used by many organizations | Sign the card | Clients can verify its origin |
Security risks and limitations
An agent card is a self-declaration, so it states what an agent claims rather than proving what it does. Clients must treat the content as untrusted input until its origin and the agent’s behavior are verified.
| Risk | Example | Mitigation |
|---|---|---|
| Agent impersonation | Spoofed card mimics a trusted vendor | Card signatures and domain verification |
| Prompt injection via description | Skill text contains hidden instructions | Treat card text as data, never as instructions |
| Capability overstatement | Card lists skills the agent handles poorly | Agent evaluation before production use |
| Stale metadata | Cached card points to a retired endpoint | Respect versioning and refresh caches |
| Information leakage | Public card reveals internal systems | Minimal public card, extended card after login |
A further limitation is that the format specifies description, not quality: two agents may advertise identical skills with very different reliability. Mature deployments therefore combine agent cards with agent observability, evaluation and registry governance.
Explained without jargon
Think of an agent card as the profile page of a digital assistant. It says the assistant’s name, what jobs it can do, how to contact it and what kind of identification it expects before it starts working.
When one assistant wants help from another, it reads that profile first, just as a project manager checks a contractor’s listing before hiring. The key idea is that assistants can find and hire each other without a person wiring them together by hand.
A typical use case
A logistics company runs a customer service agent that answers shipment questions. Some requests involve customs paperwork, which a separate compliance agent, built by another team on a different framework, handles. Instead of writing a custom integration, the compliance team publishes an agent card listing two skills: classifying goods by tariff code and checking export documents, both accepting PDF input and returning JSON.
The customer service agent fetches the card from the compliance agent’s well-known URI, sees that the card requires OAuth 2.0 client credentials and supports push notifications, and stores it in its local cache. When a customer uploads an invoice and asks whether a pallet will clear customs, the orchestrator matches the request to the document-checking skill and delegates the task.
Because the check can take several minutes, the compliance agent reports completion through a push notification. The result is a working cross-team handoff in days rather than weeks, and the compliance team can add skills later by updating the card and its version number.