A2A Agent Card
Before writing code
Fetch live docs:
- Fetch
https://a2a-protocol.org/latest/specification/ and look for the Agent Card schema section
- Web-search
site:github.com a2aproject A2A agent card schema for the JSON Schema definition
- Web-search
site:github.com a2aproject a2a-samples agent-card for real-world Agent Card examples
- Fetch SDK docs for Agent Card builder/helper classes
Conceptual Architecture
What the Agent Card Is
The Agent Card is a JSON document that describes an A2A agent to potential clients. It's the discovery and capability advertisement mechanism — analogous to an OpenAPI spec for REST APIs, but for agent-to-agent communication.
Hosting
By convention, Agent Cards are served at:
{agent_base_url}/.well-known/agent-card.json
Agents can also be discovered via:
- Agent registries (centralized directories)
- Direct configuration (hard-coded URLs)
- Referral from other agents
Key Sections
Identity
- name — Human-readable name
- description — What the agent does
- url — The agent's A2A endpoint (where JSON-RPC requests go)
- version — Semantic version of the agent
- protocolVersion — The A2A protocol version the agent supports (required)
- provider — Optional organization/owner information
Capabilities
Declares what protocol features the agent supports:
- streaming — Can the agent handle
message/stream?
- pushNotifications — Can the agent send push notifications?
- stateTransitionHistory — Does the agent maintain full task state history?
Skills
Array of skills (capabilities) the agent offers:
- id — Unique skill identifier
- name — Human-readable skill name
- description — What the skill does
- tags — Categorization tags
- examples — Example inputs/prompts for this skill
Skills help client agents understand what tasks they can delegate.
Authentication
Declares required authentication via two top-level fields:
- securitySchemes — A map/object of named security scheme definitions (e.g.,
apiKey, http with scheme: bearer, oauth2, openIdConnect)
- security — An array of required scheme references (e.g.,
[{ "schemeName": [] }])
- Each scheme has type-specific configuration (header name, OAuth URLs, OIDC discovery URL, etc.)
Input/Output Modes
- defaultInputModes — MIME types the agent accepts (e.g.,
text/plain, application/json, image/png)
- defaultOutputModes — MIME types the agent can produce
Agent Card Design Principles
- Be specific in descriptions — Other agents (LLMs) will read this to decide whether to delegate tasks
- Skills should be granular — Each skill represents one capability, not the entire agent
- Examples are critical — They help client agents understand how to formulate requests
- Declare all required auth — Clients need to know upfront what credentials they need
- Version meaningfully — Update version when skills or capabilities change
Use Cases
- Public-facing agent discovery (web-crawlable Agent Cards)
- Internal agent registry for enterprise multi-agent systems
- Marketplace listings where agents advertise their skills
- Framework integration points (ADK, LangGraph, CrewAI read Agent Cards)
Best Practices
- Validate the Agent Card against the official JSON Schema
- Serve with appropriate CORS headers if agents run in browsers
- Include meaningful tags for skill categorization and search
- Keep descriptions concise but informative — they're read by LLMs
- Test that
/.well-known/agent-card.json is accessible from client agents
- Update the Agent Card when adding/removing skills or changing capabilities
Fetch the specification for the exact Agent Card JSON Schema, all field types, and required vs optional fields before implementing.
1---2name: a2a-agent-card3description: Create and configure A2A Agent Cards — the discovery document describing an agent's capabilities, skills, authentication, and endpoint. Use when defining what your agent exposes to other agents.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/a2a-agent-card7---89# A2A Agent Card1011## Before writing code1213**Fetch live docs**:141. Fetch `https://a2a-protocol.org/latest/specification/` and look for the Agent Card schema section152. Web-search `site:github.com a2aproject A2A agent card schema` for the JSON Schema definition163. Web-search `site:github.com a2aproject a2a-samples agent-card` for real-world Agent Card examples174. Fetch SDK docs for Agent Card builder/helper classes1819## Conceptual Architecture2021### What the Agent Card Is2223The Agent Card is a JSON document that describes an A2A agent to potential clients. It's the **discovery and capability advertisement mechanism** — analogous to an OpenAPI spec for REST APIs, but for agent-to-agent communication.2425### Hosting2627By convention, Agent Cards are served at:28```29{agent_base_url}/.well-known/agent-card.json30```3132Agents can also be discovered via:33- Agent registries (centralized directories)34- Direct configuration (hard-coded URLs)35- Referral from other agents3637### Key Sections3839#### Identity40- **name** — Human-readable name41- **description** — What the agent does42- **url** — The agent's A2A endpoint (where JSON-RPC requests go)43- **version** — Semantic version of the agent44- **protocolVersion** — The A2A protocol version the agent supports (required)45- **provider** — Optional organization/owner information4647#### Capabilities48Declares what protocol features the agent supports:49- **streaming** — Can the agent handle `message/stream`?50- **pushNotifications** — Can the agent send push notifications?51- **stateTransitionHistory** — Does the agent maintain full task state history?5253#### Skills54Array of skills (capabilities) the agent offers:55- **id** — Unique skill identifier56- **name** — Human-readable skill name57- **description** — What the skill does58- **tags** — Categorization tags59- **examples** — Example inputs/prompts for this skill6061Skills help client agents understand what tasks they can delegate.6263#### Authentication64Declares required authentication via two top-level fields:65- **securitySchemes** — A map/object of named security scheme definitions (e.g., `apiKey`, `http` with `scheme: bearer`, `oauth2`, `openIdConnect`)66- **security** — An array of required scheme references (e.g., `[{ "schemeName": [] }]`)67- Each scheme has type-specific configuration (header name, OAuth URLs, OIDC discovery URL, etc.)6869#### Input/Output Modes70- **defaultInputModes** — MIME types the agent accepts (e.g., `text/plain`, `application/json`, `image/png`)71- **defaultOutputModes** — MIME types the agent can produce7273### Agent Card Design Principles7475- **Be specific in descriptions** — Other agents (LLMs) will read this to decide whether to delegate tasks76- **Skills should be granular** — Each skill represents one capability, not the entire agent77- **Examples are critical** — They help client agents understand how to formulate requests78- **Declare all required auth** — Clients need to know upfront what credentials they need79- **Version meaningfully** — Update version when skills or capabilities change8081### Use Cases8283- Public-facing agent discovery (web-crawlable Agent Cards)84- Internal agent registry for enterprise multi-agent systems85- Marketplace listings where agents advertise their skills86- Framework integration points (ADK, LangGraph, CrewAI read Agent Cards)8788### Best Practices8990- Validate the Agent Card against the official JSON Schema91- Serve with appropriate CORS headers if agents run in browsers92- Include meaningful tags for skill categorization and search93- Keep descriptions concise but informative — they're read by LLMs94- Test that `/.well-known/agent-card.json` is accessible from client agents95- Update the Agent Card when adding/removing skills or changing capabilities9697Fetch the specification for the exact Agent Card JSON Schema, all field types, and required vs optional fields before implementing.