The A2A Agent Card: what it must contain

An Agent Card is a JSON document in which an A2A server describes itself: who it is, where it can be reached, which features it supports, what it can do and how a caller must authenticate. The specification says that every A2A server must make one available (A2A specification). Clients read it before they send a single task, so a card with a missing field, a wrong name or an optimistic feature flag causes failures that look like network or protocol bugs. This guide lists what the card must contain, where it lives, and the slips that most often make a client misread it.

What the card is for

The card is a manifest, not a conversation. A client uses it to decide whether an agent is suitable, to build requests in a form the agent accepts, and to set up secure communication (A2A discovery guide). Nothing in it is executed. That is why accuracy matters more than completeness: a client will trust what it reads, and the server then has to live up to it.

The fields that are required

According to the data model in the specification, the required top-level fields are eight: a name, a description, a list of supported interfaces, a version, a capabilities object, default input modes, default output modes and a list of skills (A2A specification). Everything else at the top level is optional: the provider, a documentation link, an icon link, security schemes, security requirements and signatures.

Two points are easy to miss. The version field describes the agent, so it changes when the agent changes, and the protocol version lives somewhere else, as described next. And the capabilities object is required even if every feature inside it is off; an empty object is valid, a missing one is not.

Interfaces: where and how to call

Each entry in supportedInterfaces has three required parts: the address, the protocolBinding and the protocol version it speaks. The address of an HTTP-based binding is expected to be a full HTTPS URL in production. The binding is an open string, and the specification names three core values: JSONRPC, GRPC and HTTP+JSON. The version is meant to be the latest supported minor version for each major version, and the examples in the specification are given in the "1.0" style, major and minor only (A2A specification). An optional tenant string exists for setups where several agents sit behind one endpoint.

The order matters. The specification tells servers to list every supported combination in order of preference, and tells clients to take the first entry they can use. The same URL may appear twice when two bindings share one endpoint. Listing a binding the server does not really answer, or putting the least useful entry first, makes clients choose badly, with no error on the server side.

Capabilities: promise only what works

The capabilities object holds optional flags for streaming, push notifications and an extended card, plus a list of extensions. The specification attaches real behaviour to them. If streaming is false or absent, an attempt to stream must be answered with an unsupported-operation error. If push notifications are false or absent, the calls that manage them must return the push-notification error. The extended-card method follows the same pattern (A2A specification).

So the flags are a contract in both directions. Setting one to true for a feature the server has not built means clients will try it and fail. Leaving it false for a feature that works means clients will never use it. Extensions are declared with a URI and may be marked as required, in which case clients are expected to understand and follow them. Mark an extension required only when the agent truly cannot work without it.

Skills: descriptions that help a caller decide

Each skill needs an identifier, a name, a description and a set of tags; all four are required. Optional parts are example prompts, input and output modes that override the card defaults, and security requirements for that skill alone (A2A specification). The specification describes skills as largely descriptive: they tell a caller what the agent is likely to do well, and are not a strict list of callable functions.

In practice the description and the examples decide whether another agent picks yours. Vague text such as "handles requests" gives a caller nothing to match against. Write what goes in, what comes out, and one or two concrete sample requests. Tags should be short keywords a caller might search for, and the list should not be left empty.

Security: declare it once, require it where needed

Authentication is described in two optional but linked fields. The security schemes map defines how authentication works, and the security requirements list says which of those schemes a caller must satisfy. A scheme that is defined but never required, or a requirement that points to a name that was never defined, leaves clients guessing. Requirements can also be set per skill. The specification additionally allows the card to be signed as a JSON Web Signature, after the content is put into a canonical form, so that a client can check it was not altered (A2A specification). Signing is optional and is worth considering when cards are copied through registries.

If the public card should show only part of the story, the extended-card flag lets an authenticated client fetch a fuller version afterwards. Do not rely on this to hide secrets in the public card; anything in the public document is public.

Where the card lives

The standard location is the path /.well-known/agent-card.json, served from the domain that hosts the agent; a plain GET request to it must return the card as JSON. The discovery guide recommends this for public agents and ties it to the general well-known URI convention. Cards can also be found through registries or be configured directly in the client (A2A specification).

Caching is covered too. The specification expects card content to change rarely compared with how often clients fetch it, and recommends that the endpoint send a cache lifetime and an entity tag, which can be derived from the card version or from a digest of its text. Clients are encouraged to use conditional requests once their copy expires. If the entity tag is built from the version field, remember to bump the version whenever the card changes, otherwise clients keep an outdated copy.

Slips to look for

These are common causes of misread cards. Only the first is drawn from the specification; the rest are general practice, not statements from it.

• Writing the card in the shape of an older protocol revision. The data model above uses one ordered list of interfaces, and a client written for the current revision may not understand an older layout. The specification also says an empty version header is read as the older revision, so requests should name the version they speak.
• Leaving out a required field because it looks redundant, for example the default modes when every skill already has its own.
• Using a skill without tags, or with an empty tag list (the specification requires the field; an empty list is poor practice).
• Declaring a security scheme and forgetting the requirement that uses it.
• An interface address whose host or route differs from what the server really serves, which often happens behind proxies and preview deployments.
• Changing the agent without changing version while the entity tag depends on it.
• Serving the file with a content type or redirect that makes automatic discovery fail, even though it opens fine in a browser.

A check that can fail

Fetch the card the way a client would: a plain GET to the well-known path on the real domain, with no cookies. Then run through these questions and treat any "no" as a defect.

1. Does the response parse as JSON, and does it contain all eight required top-level fields?
2. Does every interface have an address, a binding and a protocol version, and is the first one really the best choice?
3. Does every skill have an identifier, name, description and a non-empty tag list?
4. For each capability set to true, can you actually call the matching method and get a real answer?
5. For each capability left out or false, does the server refuse the matching call with the error the specification names?
6. Does every name used in the security requirements exist in the security schemes?

The fourth and fifth questions are the ones a quick look misses, because they need a real request. They are also the ones that catch a card describing an agent that does not exist yet.

When this does not apply

Covered here is only the Agent Card as the current specification describes it. It does not cover older revisions of the protocol, whose card layout differs, nor the message and task formats that come after discovery. Private agents that are configured directly in a client may never publish a well-known card, though the data model is still the one in use. Libraries and frameworks often generate the card for you, and the output of a particular library may differ from what is described here, so check the generated file, not the library's documentation. The specification also changes, so confirm each field against the page cited above before relying on this list. No client was run against live servers for this text; it restates the specification and general practice.

Publishing a card also means exposing an address to the open web, and the same care applies to any public endpoint; our guide to cross-origin settings that expose an API shows how a permissive default can hand data to the wrong caller.

Writing the card with a skill

If you would like a ready-made helper for this, our a2a-agent-card skill writes the card and the related JSON-RPC requests and replies for the current protocol revision, using the current field names rather than the older ones. It answers with JSON only, covers the interface list, the capability flags, skills, security schemes and requirements, and gives the error codes the specification defines. It does not host the file or run a server: you still publish the result at the standard path and test it as described above.