Glossary

What is an agent card?

Definition

An agent card is a JSON document, defined by the Agent2Agent (A2A) protocol, that describes an AI agent: its name, what it does, the skills it offers, where to reach it and how to authenticate. Other agents read it to discover what the agent can do. It is usually published at /.well-known/agent-card.json and can be digitally signed.

Why it matters

An agent card is how an AI agent introduces itself to other agents. If a shopper's assistant wants to know what your store's agent can do, the card is where it looks. It lists the skills on offer, such as answering product questions or checking an order, and the address to send requests to.

For a site owner, it is one of a few public files that make a business easier for AI agents to work with, alongside llms.txt and an MCP server.

How it works

The A2A specification defines an agent card as "A JSON metadata document published by an A2A Server, describing its identity, capabilities, skills, service endpoint" and related details. It says "A2A Servers MUST make an Agent Card available."

Required fields include the agent's name, description and version, its capabilities, its skills, its default input and output formats, and supportedInterfaces, an ordered list of the endpoints and transports it accepts. Optional fields include the provider, security schemes and signatures.

The specification lists three ways to find a card:

  • Well-known URI: https://{server_domain}/.well-known/agent-card.json
  • Registries/Catalogs: "Querying curated catalogs of agents"
  • Direct Configuration: "Pre-configured Agent Card URLs or content"

Cards "MAY be digitally signed using JSON Web Signature (JWS)", and the specification says "Clients SHOULD verify signatures when present to ensure the Agent Card has not been tampered with". It also says a card "SHOULD NOT include sensitive credentials or internal implementation details". An agent can offer a more detailed extended card to clients that have authenticated.

Example

A shopper's assistant wants to check stock at your store. It requests:

GET /.well-known/agent-card.json HTTP/1.1
Host: example.com

The card names your store's agent, lists a skill for product availability and gives the endpoint for it. The assistant verifies the card's signature, then sends its stock question to that endpoint. On Cloudflare Worker installs, Sill serves an A2A-compatible agent card at /.well-known/agent-card.json on the store's own domain. For how A2A fits with other standards, see agentic commerce protocols explained.

Also called: AgentCard, A2A agent card, agent-card.json

Sources

  1. A2A Protocol: Specification · checked 17 Nov 2026

The Sill Signals Team · Updated 17 Nov 2026

See which AI agents visit your site, and decide what they may do.

Scan your site free