A2A Agent Card

An A2A Agent Card is a JSON metadata document published by an Agent2Agent (A2A) server. It tells a client agent what the remote agent is, where its service endpoint is, which protocol interfaces and capabilities it supports, what skills it advertises, and how clients should authenticate.

An Agent Card is useful only when a real A2A service exists behind it. Most blogs, marketing sites, and ordinary SaaS documentation sites do not need one.

What The Card Describes

An implementation should follow the version of the A2A specification it supports. Important concepts include:

Area	Purpose
Identity	Human-readable name, description, provider, and version
Service URL and interfaces	Where and how the A2A client communicates
Capabilities	Optional features such as streaming or push notifications
Skills	Bounded task types with descriptions, modes, and examples
Authentication	Supported schemes and how credentials are obtained
Input/output modes	Media types the agent can receive and produce

The card is a capability declaration, not proof that the server behaves correctly. The client and server must still validate requests, enforce authorization, and handle unsupported operations.

Discovery Options

The current A2A discovery guidance documents three broad patterns:

1. Well-known URI: public servers can expose https://example.com/.well-known/agent-card.json.
2. Registry or catalog: enterprise or public registries can return cards under their own governance rules.
3. Direct configuration: a client can be configured with a known card URL or document.

Public discovery is not always appropriate. If the card contains sensitive capabilities or organization details, protect the endpoint and use an authenticated or selectively disclosed card. Never embed static secrets in the JSON.

When A Website Needs One

Publish an Agent Card when all of these are true:

• An A2A server is deployed and accepts protocol-compatible interactions.
• At least one advertised skill maps to a real, supported task.
• Authentication and authorization behavior are implemented.
• The endpoint, protocol version, modes, and capability flags have been tested.
• A team owns monitoring, updates, and incident response.

Do not publish one merely because the site has a chatbot, an API, an MCP server, or AI-related content. Those may be separate systems.

Agent Card Versus Nearby Concepts

• An Agent Skill package gives a compatible runtime reusable instructions.
• An MCP server exposes tools and resources through MCP.
• An OpenAPI description documents HTTP operations.
• An A2A Agent Card describes a remote A2A agent and how to interact with it.

Choose the interface that matches the deployed service rather than publishing every format.

Operational And Security Review

• Keep skill descriptions specific enough for a client to reject mismatched tasks.
• Declare only capabilities the server actually implements.
• Use least-privilege scopes and authorize each requested action.
• Protect extended or sensitive cards with access controls.
• Use standard HTTP caching headers and validators such as ETag where appropriate.
• Update the card when interfaces, skills, authentication, or versions change.
• Monitor card availability separately from task success.

For an implementation decision framework, see A2A Agent Card: When Your Website Needs Agent-to-Agent Discovery. Related entries include Agent Skills Index, MCP Server Card, and Auth.md and OAuth Metadata.

Validation Checklist

1. Fetch the card from the documented discovery method.
2. Validate JSON and required fields against the supported A2A version.
3. Check that advertised interfaces and modes match the server.
4. Test one request for every published skill.
5. Test unsupported capabilities and authorization failures.
6. Confirm no secrets or private-only details are exposed.
7. Verify cache refresh behavior after a version change.

Primary Sources

• A2A protocol specification
• A2A agent discovery guidance