Agent card

Also known as: A2A agent card

On this page 7

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 groupTypical fieldsWhat the client uses it for
Identityname, description, version, providerRecognizing and selecting the agent
Connectivityurl, protocolVersion, preferredTransportOpening a compatible connection
Capabilitiesstreaming, pushNotificationsChoosing the interaction pattern
Skillsid, description, tags, examplesMatching tasks to abilities
Media modesdefaultInputModes, defaultOutputModesFormatting requests and parsing replies
SecuritysecuritySchemes, securityObtaining the right credentials
Principal fields of an agent card

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 methodHow it worksBest suited for
Well-known URIClient requests a fixed path on the agent’s domainPublic or partner-facing agents
Curated registryCentral catalog stores and indexes cardsEnterprises with many internal agents
Direct configurationCard or its location is set in client settingsTightly coupled or private deployments
Authenticated extended cardRicher card returned after loginSkills visible only to authorized clients
Discovery methods for agent cards

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.

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.

DescriptorDescribesGranularityTypical consumer
Agent cardAn opaque, autonomous agentSkills and whole tasksOther agents via A2A
Tool schemaA single callable functionParameters of one callA model using tool calling
MCP server manifestTools, resources and promptsIndividual capabilitiesAn MCP client inside an agent
OpenAPI documentA REST interfaceEndpoints and payloadsDevelopers and code generators
Agent card and similar metadata formats

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/pdf or text/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.

SituationRecommended choiceReason
Long-running tasks of minutes or hoursEnable push notificationsClient need not hold a connection open
Incremental output such as draftsEnable streamingPartial results arrive early
Sensitive internal skillsUse an extended cardPublic card stays minimal
Agent used by many organizationsSign the cardClients can verify its origin
Agent card design decisions

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.

RiskExampleMitigation
Agent impersonationSpoofed card mimics a trusted vendorCard signatures and domain verification
Prompt injection via descriptionSkill text contains hidden instructionsTreat card text as data, never as instructions
Capability overstatementCard lists skills the agent handles poorlyAgent evaluation before production use
Stale metadataCached card points to a retired endpointRespect versioning and refresh caches
Information leakagePublic card reveals internal systemsMinimal public card, extended card after login
Risks associated with agent cards

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.