A2A Agent Cards Sample: JSON Example & Field Guide
A complete guide to A2A Agent Cards: what they are, a full v1.0 JSON sample, field-by-field breakdown, and how to create and host one for your agent.
Key takeaways
- An A2A Agent Card is a JSON document that acts as a machine-readable identity and capability profile for an AI agent. It is the actual mechanism that makes discovery possible.
- Without a published Agent Card, no A2A-compliant client can find, evaluate, or communicate with your agent.
- Agent Cards must be publicly accessible via an unauthenticated HTTP GET request. Placing the card behind authentication will silently break discovery.
- Skills are the most important section for routing. Vague or missing skill descriptions cause orchestrators to skip your agent entirely.
An A2A Agent Card is a JSON file that describes an AI agent's identity, capabilities, skills, and authentication requirements. It is hosted at /.well-known/agent-card.json and acts as the discovery entry point for any A2A-compliant client looking to communicate with that agent.
This guide covers the complete v1.0 structure with a working JSON sample, a field-by-field explanation, step-by-step creation instructions, and the most common mistakes to avoid.
What Is an A2A Agent Card?
| Quick answer: An A2A Agent Card is the standardized JSON document that makes an AI agent discoverable and usable by other agents or orchestration systems, without any prior configuration or manual integration. |
Think of it as a machine-readable business card. Before any two agents can communicate, one needs to know what the other can do, how to reach it, and how to authenticate. The Agent Card answers all three questions in a single file.
According to the A2A Protocol specification, the Agent Card is a JSON document that serves as a digital "business card" for an A2A Server. It defines what an agent offers, and various discovery strategies exist for client agents depending on the deployment environment and security requirements.
The file is served at a predictable path:
https://<your-domain>/.well-known/agent-card.json
This follows RFC 8615, which reserves the /.well-known/ path for service metadata. Any A2A client knows to look here first.
How it fits into the A2A workflow:
- Client agent sends an HTTP GET to /.well-known/agent-card.json
- Parses the returned JSON to understand the agent's skills and capabilities
- Evaluates whether the agent fits the current task
- Sends a task request to the declared endpoint using the specified authentication
A2A Agent Card Sample JSON (v1.0)
| In short: The sample below is a complete, working v1.0 Agent Card. It includes all required fields and the most commonly used optional fields, with inline comments explaining each section. |
Author's note: What is often overlooked is that the Agent Card is the contract that governs every interaction before a single task is ever sent. Getting the skills array right is more consequential than any other field: an orchestrator with ten agents available will route tasks based entirely on what skills are described here. A vague description like "does AI things" is functionally invisible. A precise description like "Extracts line items and totals from PDF invoices in English, Spanish, and French" tells a routing system exactly when to call you. The card is your agent's voice before it ever speaks.
A2A Agent Card Field-by-Field Breakdown
The v1.0 Agent Card organizes its fields into four logical groups: identity, interfaces, capabilities, and skills.
Identity and Service Information
These fields describe who the agent is and where to find more information about it.
Field | Required | Type | Purpose |
| name | Yes | string | Human-readable display name. Used in UIs, logs, and orchestrator interfaces. Keep it specific: "Invoice Parser Agent" is more useful than "AI Assistant". |
| description | Yes | string | What the agent does and when another agent should call it. This is the primary signal for LLM-based routers deciding whether your agent fits a task. |
| version | Yes | string | Semantic version of the agent (e.g., 1.2.0). Follow MAJOR.MINOR.PATCH rules. |
| provider | Recommended | object | Organization name, homepage URL, and support contact. |
| documentationUrl | Optional | string | Link to human-readable API documentation. |
| iconUrl | Optional | string | URL to an icon image for the agent. Used in marketplace listings. |
Capabilities
The capabilities object and supportedInterfaces array tell clients how to technically connect to the agent.
supportedInterfaces (required in v1.0)
This is the most structurally significant change from v0.3. Instead of a single top-level url field, v1.0 uses an array of interface objects, each declaring its own endpoint, protocol binding, and version.
capabilities object fields:
Field | Type | Default | Description |
| streaming | boolean | false | Agent supports Server-Sent Events for streaming responses. |
| pushNotifications | boolean | false | Agent can push task status updates proactively. |
| extendedAgentCard | boolean | false | Authenticated clients can fetch a richer card via GetExtendedAgentCard. |
defaultInputModes and defaultOutputModes declare the MIME types the agent accepts and produces. In v1.0, these are required fields. Common values:
- Input: text/plain, application/pdf, image/png, application/json
- Output: application/json, text/plain, text/html
Skills
The skills array is the most operationally important section of the card. Orchestrators use skill descriptions to decide which agent to route a task to. Missing or vague skills effectively make an agent invisible to automated routing.
Each skill object supports the following fields:
Field | Required | Description |
| id | Yes | Machine-readable unique identifier (e.g., extract-invoice-data). Use kebab-case. |
| name | Yes | Short human-readable label. |
| description | Yes | What this skill does, in enough detail for an LLM router to match it against a task. Be specific about inputs, outputs, and supported formats. |
| tags | Yes (v1.0) | Array of keywords for searchability (e.g., ["invoice", "pdf", "finance"]). |
| examples | Optional | Sample user utterances that this skill handles. Helps routing systems match intent. |
A useful rule for descriptions: write the skill description as if you are answering the question "when should I call this skill instead of doing it myself?" If the description cannot answer that question, it needs to be rewritten.
Authentication and Security
The Agent Card declares its authentication requirements through securitySchemes and security. A client agent reads these fields before it ever attempts to send a task.
securitySchemes defines one or more available authentication methods:
security specifies which schemes are required for all endpoints:
Important: The securitySchemes block should never contain actual credentials. It declares the structure and type of authentication required. Credentials are exchanged out-of-band.
How to Create an A2A Agent Card
Creating an Agent Card is a structured process. Each step maps directly to a section of the final JSON file.
Step 1: Define Your Agent's Identity
Start with the four fields that every consumer of your card will read first:
Step 2: Add the Agent Endpoint
Declare where clients should send tasks using supportedInterfaces:
You can list multiple interfaces if your agent supports more than one protocol binding (e.g., both JSONRPC and gRPC). Clients select the first entry they support.
Step 3: Declare Supported Capabilities
Add the capabilities block, defaultInputModes, and defaultOutputModes:
Step 4: Define Agent Skills
Write at least one skill. For each skill, fill all required fields and add at least three examples:
Step 5: Configure Authentication
Add securitySchemes and security to declare how clients should authenticate:
Step 6: Host and Register Your Agent Card
Save the completed JSON as agent-card.json and serve it at:
https://your-domain/.well-known/agent-card.json
Hosting requirements:
- Must respond to unauthenticated HTTP GET requests
- Content-Type header must be application/json or application/a2a+json
- Must include CORS headers if clients may fetch from a browser context: Access-Control-Allow-Origin: *
According to Google Cloud's Agent Registry documentation, you can also register your card with Google Cloud Agent Registry by submitting your agent-card.json payload. This makes your agent discoverable by orchestrators that query the registry.
After publishing, verify reachability by running:
A2A Agent Card v0.3 vs v1.0: What Changed?
| In short: The core difference is how endpoints are declared. In v0.3, the agent's endpoint was a flat top-level field. In v1.0, it moved into a supportedInterfaces array to support multiple transport protocols per agent. |
Key structural differences:
Area | v0.3 | v1.0 |
| Endpoint declaration | Top-level url field | supportedInterfaces[] array |
| Protocol version | Top-level protocolVersion field | Per-interface protocolVersion inside each supportedInterfaces entry |
| capabilities | Optional | Required |
| defaultInputModes / defaultOutputModes | Optional | Required |
| skills[].tags | Optional | Required |
| Signed cards | Not supported | Supported via signatures[] |
According to the official A2A v1.0 migration notes, protocolVersion was removed from the AgentCard top level and is now declared per interface entry within supportedInterfaces.
Backward compatibility: If you need a v1.0 server to accept connections from v0.3 clients, the official Python SDK supports an enable_v0_3_compat flag. With this flag enabled and a v0.3-format AgentInterface added to supported_interfaces, both client versions can connect to the same server.
Common Mistakes to Avoid
Most Agent Card failures fall into a small number of repeatable patterns.
1. Putting the card behind authentication
According to A2A protocol guidance, if the Agent Card file is behind authentication, discovery fails. The card itself must be publicly readable. It is the credentials within it that are protected, not the card file.
2. Using a localhost or internal URL in supportedInterfaces
The url field inside supportedInterfaces must be the externally reachable HTTPS address. An internal bind address (e.g., http://localhost:8000) is unreachable by any external client.
3. Vague or missing skill descriptions
A skill described as "Helps with documents" gives an orchestrator nothing to route on. According to production best practices, each skill should be explicitly defined with id, name, description, tags, and input/output schema where applicable.
4. Skipping required v1.0 fields
Fields that were optional in v0.3 (capabilities, defaultInputModes, defaultOutputModes, skills[].tags) are required in v1.0. Cards missing these fields will fail schema validation.
5. Not versioning the card
When you change an endpoint URL, remove a skill, or alter your authentication scheme, bump the version field. Consuming agents may cache cards. A version change signals that they need to re-fetch.
6. Stale capability claims
According to A2A security guidance, if an Agent Card advertises deprecated skills, outdated endpoint URLs, or revoked authentication schemes, client agents may route tasks incorrectly or attempt authentication methods that no longer work. Keep the card in sync with the actual agent behavior.
Sources and Further Reading
- Wikipedia – "Agent2Agent Protocol" https://en.wikipedia.org/wiki/Agent2Agent
- A2A Protocol – "Official Specification" https://a2a-protocol.org/latest/specification/
- A2A Project GitHub – "What's New in v1.0" https://github.com/a2aproject/A2A/blob/main/docs/whats-new-v1.md
- A2A Project GitHub – "Agent Discovery" https://github.com/a2aproject/A2A/blob/main/docs/topics/agent-discovery.md
- A2A Python SDK GitHub – "v1.0 Migration Guide" https://github.com/a2aproject/a2a-python/blob/main/docs/migrations/v1_0/README.md
- A2A .NET SDK GitHub – "Migration Guide v1" https://github.com/a2aproject/a2a-dotnet/blob/main/docs/migration-guide-v1.md
- Google Cloud Documentation – "A2A Agent Card JSON Schemas" https://docs.cloud.google.com/agent-registry/json-schemas
- Microsoft Learn – "A2A SDK v1 Migration Guide" https://learn.microsoft.com/en-us/agent-framework/migration-guide/agent-to-agent-sdk-v1
FAQs About A2A Agent Cards Sample
No. MCP and A2A solve different layers of the same problem. MCP governs how an agent accesses tools and data internally. The Agent Card is how an external client learns about the agent. It can point to an MCP server in its documentation, but the two are separate artifacts serving separate functions.
