Before an agent can ask another agent for help, it needs to know what that service does, where to reach it, and how to connect. An Agent Card puts those answers in a document that software can read.
Imagine a purchasing assistant looking for a specialist to compare vendor quotes. A name in a directory is insufficient: the assistant needs an endpoint, a compatible protocol, accepted input formats, and access requirements. An A2A Agent Card supplies that introduction. The comparison itself happens in the interaction that follows.
Technical reference: A2A v1.0.1, using wire version 1.0. Checked September 7, 2026. 日本語原稿を読む
What is an Agent Card?
An Agent Card, named AgentCard in the protocol definition, describes an agent service that participates in the Agent2Agent protocol. A2A standardizes communication between agents; the card is its discovery document. A client reads the card before choosing how to interact with the remote service. The provider may implement that service using its own models, tools, and orchestration. A2A discovery specification.
Think of our fictional quote comparison service. Its card can advertise text input, a comparison skill, streaming responses, and Bearer authentication. Those declarations help a purchasing assistant decide whether the service is a plausible match. They do not reveal its full implementation or establish the quality of its recommendations.
| Question | Fields | How to read them |
|---|---|---|
| Who is offering the service? | name, description, provider, version | A declared identity, purpose, optional provider, and service release. |
| Where and how can I call it? | supportedInterfaces | An ordered list of endpoint URLs, protocol bindings, and protocol versions. |
| Which protocol features work? | capabilities | Optional features such as streaming, push notifications, extensions, or an extended card. |
| What work and formats fit? | skills, defaultInputModes, defaultOutputModes | Described abilities and media types. Individual skills can override default formats. |
| How is access protected? | securitySchemes, securityRequirements | Named authentication mechanisms and the requirements that refer to them. |
| Can I check a signed copy? | signatures | Optional JWS signatures to verify with an appropriately trusted key. |
Field names above follow the v1.0.1 protocol definition. A capability such as streaming describes a communication feature. A skill such as quote comparison describes work the agent offers. Keeping these concepts separate makes a card much easier to read.
Read a card, one part at a time
Select a group below to inspect the corresponding fields, or choose Full JSON to see the complete document. This is an original, fictional example with placeholder addresses. It describes a service that compares supplied quotes and does not place orders.
Which service is introducing itself?
The name and provider identify the declared service. version is the provider’s release number: 2.1.0 here. It is separate from the A2A protocol version, and does not identify the model running behind the service.
{
"name": "Quote Comparison Agent",
"description": "Compares supplied vendor quotes and explains trade-offs. Does not place orders.",
"provider": {
"organization": "Example Procurement Services",
"url": "https://example.com"
},
"version": "2.1.0"
}Notice the two version numbers: version: "2.1.0" is the service's own release, while protocolVersion: "1.0" belongs to its A2A interface. Neither is a model identifier. The specification release used for this article, v1.0.1, is a third concept; the interface advertises the protocol's major and minor version. Protocol versioning.
The skill's id also deserves care. It identifies a described skill; it does not automatically define a callable function or a JSON Schema for its arguments. A2A has its own operations for sending messages and managing tasks. Any more specific input contract needs to be established by the service's documentation or an agreed extension. Agent discovery data model.
From discovery to the first task
- Find the card.Retrieve a known discovery URL, consult a registry, or use private configuration.
- Choose an interface.Match the offered skill and media types, then select a compatible binding and version.
- Establish access.Obtain the required credentials and satisfy the service's authorization policy.
- Send the request.Call the selected A2A endpoint and handle its message or task response.
1. Retrieve the discovery document
For a service using the well-known discovery path, the initial request looks like this. This HTTP example uses the fictional domain from our card; it is not a live endpoint.
GET /.well-known/agent-card.json HTTP/1.1
Host: quotes.example.comThe well-known location helps once the client knows a domain. It does not tell the client which domains exist. The official discovery guidance also describes registries and direct configuration, and does not prescribe a universal registry API. Private deployments may protect the card itself with access controls. Discovery strategies.
2. Select a compatible service interface
Read supportedInterfaces in its declared preference order and choose the first interface your client supports, checking its protocol version as well as its binding. A client that understands only HTTP+JSON cannot use a JSON-RPC endpoint merely because both run over HTTP. If no compatible interface is available, report that mismatch instead of guessing a request format.
In this example, the next request goes to https://quotes.example.com/a2a. The discovery URL and the task endpoint serve different purposes. For a multi-tenant interface, also preserve the selected interface's declared tenant value in requests; our example does not declare one. Client protocol selection.
3. Obtain credentials and apply authorization
Our card names a Bearer authentication scheme and refers to it in securityRequirements. The client obtains a suitable credential through a separate process and sends it in the appropriate transport header or metadata. The card supplies no token. The service then authenticates the caller and authorizes the requested work under its own policies. Authentication and authorization.
For the purchasing assistant, permission to request a comparison should be evaluated separately from permission to place an order. Writing “does not place orders” in a description helps communicate intent; enforcing that boundary requires actual server and tool permissions. This is an implementation recommendation for our example.
4. Send an A2A message
Once access is established, this illustrative JSON-RPC request body sends the comparison request to the advertised endpoint. The HTTP request would also carry Content-Type: application/json, A2A-Version: 1.0, and the required authorization header. Its credential is intentionally absent from the example.
Inspect the SendMessage request
{
"jsonrpc": "2.0",
"id": "quote-request-001",
"method": "SendMessage",
"params": {
"message": {
"messageId": "quote-message-001",
"role": "ROLE_USER",
"parts": [
{
"text": "Compare these quotes: A costs 100 plus 10 delivery, arrives in 3 days; B costs 105 including delivery, arrives in 5 days. Explain the trade-off. Do not place an order."
}
]
}
}
}SendMessage can return a direct Message or a tracked Task. When work is represented as a task, the client can use its identifier to retrieve state and results. Streaming and push notifications provide other update mechanisms when supported. A discovered card is therefore the beginning of the workflow; the task carries execution state and may include output artifacts. Send Message; JSON-RPC binding.
How does this relate to MCP and model cards?
A2A and MCP can appear in the same application. Our purchasing assistant could delegate the comparison to an A2A service, while that service uses MCP tools to retrieve permitted supplier records. The Agent Card introduces the service. MCP describes the separate interaction with its tools and resources. The A2A project presents these protocols as complementary. A2A and MCP.
A model card has a different subject: the model artifact and its documented properties. An Agent Card describes a running service's public interface. One service could change models without changing its comparison skill, and many services could use the same model. For the implications of that distinction, see Open Weights Move the Trust Boundary.
Why older examples look different
Search results and SDK examples can refer to different A2A versions. Check the target version before copying their JSON. The v1.0 migration guide documents the following structural changes from v0.3.0; the security row follows the v1.0.1 protocol definition. Migration guide; protocol definition.
| Concept | v0.3 examples | v1.0 structure |
|---|---|---|
| Endpoints and bindings | url, preferredTransport, additionalInterfaces | supportedInterfaces[] with url and protocolBinding |
| Protocol version | Top-level protocolVersion | protocolVersion on each interface |
| Extended card support | supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard |
| Security requirements | security and direct scope arrays | securityRequirements, with schemes mapping names to StringList objects |
In the v1.0 structure, a nonempty scope list is represented as an object with a list property. Our Bearer example uses an empty object because it specifies no OAuth scopes. A security scheme is also wrapped in its typed field, here httpAuthSecurityScheme. Some illustrative snippets retain older spellings; consult the pinned protocol definition when exact serialization matters, and verify the version implemented by your SDK.
Cards have a lifecycle
A signature checks the document's integrity
A2A supports optional JWS signatures. Verification uses the card's canonical representation, with the signatures excluded and the specification's field-presence rules applied. It is more involved than signing an arbitrary JSON.stringify result. The verifier also needs an appropriate trust relationship with the key; expired or revoked keys must not be accepted. Agent Card signing.
Our example is unsigned. A real signature would provide evidence about the signed document and its signer, while the accuracy of a comparison, the caller's mandate, and the independence of a vendor still need their own evidence.
An extended card can reveal permitted details
When capabilities.extendedAgentCard is true, the service supports retrieving an authenticated extended card. This allows a public introduction to remain limited while an authorized caller obtains more detailed capabilities. The retrieval operation must use the selected binding: JSON-RPC uses GetExtendedAgentCard; the HTTP+JSON binding defines GET /extendedAgentCard. Extended card operation.
In a quote service, the extended card might describe a private catalog available to a particular customer. That is a hypothetical use case. As a design recommendation, keep such descriptions scoped to the authenticated customer and prevent one customer's cached card from being reused for another. Our Field Note on selective disclosure examines this boundary.
Refresh metadata as the service changes
Endpoints, capabilities, and access requirements can change. The specification recommends HTTP caching controls and validators such as ETag, with conditional requests to refresh an expired card efficiently. A service release number alone is not permission to retain metadata forever. Agent Card caching.
For an audit, we recommend recording which card informed an interaction, when it was obtained, and which endpoint and interface were selected. Keep this evidence appropriately redacted. It can help explain why a task was routed to a service after its description or deployment changed. See Agent Card Caches Can Outlive Trust.
Put the card to work
For our purchasing assistant, the useful sequence is concrete: find the quote service, confirm its comparison skill and text input, select its JSON-RPC 1.0 interface, authenticate, and send the request. Then inspect the returned comparison and preserve the evidence needed for the purchasing decision. Each step answers a different question.
This separation matters to AgentCollusion's research. Several services can publish plausible cards while sharing an operator, supplier relationship, or incentive. The card gives us a declared starting point. Observing how those services interact helps us study the collective outcomes that discovery metadata alone cannot explain.
Sources and further reading
- A2A v1.0.1 protocol definition: AgentCard, AgentInterface, AgentSkill, and security objects
- A2A v1.0.1 specification: discovery, operations, authentication, signing, and caching
- What changed in A2A v1.0
- Official discovery guidance
- Official A2A and MCP comparison
- Agent Cards in our four-agent A2A procurement pilot
Protocol facts are linked to primary sources. The quote service and its requests are fictional teaching examples; the operational recommendations are AgentCollusion's analysis. Read the Japanese manuscript (Markdown).
