ChangeGamer

Designing an Agent Card: What Goes in the Public Card and What Waits

Part 2 of A2A in practice: agent-to-agent interoperability · 1,171 words · ~5 min read · published · updated · Markdown variant

How to design an A2A Agent Card: the field groups, the well-known path, optional signing, and a rule for splitting what the public card advertises from what an authenticated client fetches in the extended card.

In short

  • An A2A Agent Card is a JSON discovery document that the specification says an agent MUST publish at /.well-known/agent-card.json, a path renamed from agent.json in protocol version 0.3.0.
  • The A2A reference groups Agent Card fields into identity, supportedInterfaces, capabilities, skills and securitySchemes, and it does not state which individual fields are required, so check the specification before relying on any one.
  • Signing an A2A Agent Card with JSON Web Signature (RFC 7515) and RFC 8785 canonicalization is optional, and an unsigned card proves nothing about who published it.
  • When a card sets extendedAgentCard to true, an authenticated A2A client can fetch fuller details through GetExtendedAgentCard (GET /extendedAgentCard) and should replace its cached public card with the result.
  • A sensible split, offered as inference rather than spec text, is to keep in the public card only what a stranger needs to decide whether to authenticate, and to move everything else into the extended card.

Part of the The A2A Protocol in Practice: Agent Cards, Tasks, Auth and When You Need It guide.


An A2A Agent Card is the single document a remote agent reads before it decides whether to call you, so the design question is what to tell strangers and what to hold back for clients who have authenticated. The A2A protocol reference (updated 27 October 2026) defines the fields; this article is about choosing what to put in them. For the protocol overview, start with the A2A protocol in practice.

What does an Agent Card contain?

An Agent Card contains five field groups according to the A2A reference: identity, interfaces, capabilities, skills and security. The reference lists the names but does not say which individual fields are required, so this article makes no claim about that; confirm against the specification before you validate cards in a client.

Group Fields named in the reference Design question it raises
Identity name, description, provider, version, documentationUrl, iconUrl How much do you want an anonymous caller to learn about the operator?
Interfaces supportedInterfaces Which bindings and endpoints are safe to list publicly?
Capabilities streaming, pushNotifications, extensions, extendedAgentCard Which optional features do you actually run?
Skills skills How specific should the public description of abilities be?
Security securitySchemes plus security requirements Which ways of authenticating do you accept?

The reference lists these security schemes: API key, HTTP auth, OAuth 2.0, OpenID Connect and mutual TLS. How a client then authenticates is a separate topic, covered in A2A authentication schemes.

Where do you publish the Agent Card?

You publish the card at https://{server_domain}/.well-known/agent-card.json, a location the specification states as a MUST. Version 0.3.0 renamed the path from agent.json, so a client built against an older release may request the wrong filename and conclude you have no card.

One practical consequence follows: if some callers still use v0.3-era tooling, check which filename they request before you change anything. The reference describes no fallback path and no discovery step beyond this URL, so treat any claim of other discovery mechanisms as outside the sourced material.

What should a card carry for identity?

A card's identity fields tell a stranger who runs the agent and where to read more, and each one is a disclosure decision. Use the six names the reference lists as a checklist and answer each deliberately:

What belongs in the public card versus the extended card?

Put in the public card only what a stranger needs to decide whether to authenticate, and move the rest to the extended card. This rule is inference; the specification defines the mechanism but gives no guidance on content.

The mechanism is grounded. If extendedAgentCard is true, an authenticated client can fetch fuller details through GetExtendedAgentCard in JSON-RPC or GET /extendedAgentCard over HTTP+JSON, and it SHOULD replace its cached public card with that result. The sections below turn it into a working split.

What stays public

Keep these in the public card, because without them nobody can start:

What can wait for authentication

Candidates for the extended card are the finer-grained parts: detailed skills entries for capabilities you only offer to partners, and anything that would help an attacker map your service. That list is a recommendation, not a requirement of the protocol. A caller that cannot authenticate simply never sees the extra skills, which is the point.

One caution: the extended card is not a secrecy mechanism for credentials. The reference describes it as fuller details for an authenticated client, so never place keys or tokens in either card.

An illustrative public card

This placeholder card on example.com uses only field names from the reference. Its values are invented for illustration, and it is not a complete or validated card.

{
  "name": "Example Invoice Agent",
  "description": "Answers questions about invoices for Example Corp customers.",
  "provider": "Example Corp",
  "version": "1.2.0",
  "documentationUrl": "https://example.com/docs/invoice-agent",
  "iconUrl": "https://example.com/icon.png",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": true
  },
  "skills": [{ "id": "invoice-lookup", "name": "Invoice lookup" }]
}

The public card above stays short on purpose; the interface and security entries are omitted here only to keep the sketch small, and a card that is useful to a client should include them (design judgment, not spec text).

Should you sign the card?

As a design judgment, not spec text: sign the card if callers will act on it without other evidence of who you are, because an unsigned card proves nothing about who published it. The A2A reference says signing uses JSON Web Signature (RFC 7515) with RFC 8785 canonicalization, and that signing is optional.

The reference says nothing about how a caller obtains the verification key, so key distribution is not covered here. Treat what a verifier should do with an unsigned card as your own policy question, and see the caller-side treatment in the cluster overview.

Should skill text be trusted by the caller?

No. As an inference rather than spec text, a caller should treat a card's skill descriptions as untrusted input to its model, because the publisher writes them. The A2A reference labels the same point as inference too, and adds that verifying a signed card before delegating is preferable. As a publisher, the consequence is to write skill descriptions as plain statements of ability, not instructions addressed to the calling model.

Does ChangeGamer publish an Agent Card?

No. As of 31 October 2026, ChangeGamer publishes no Agent Card, because the site speaks MCP, not A2A; src/pages/.well-known and public/.well-known hold no agent-card.json, and the MCP server card at /.well-known/mcp/server-card.json is the equivalent. The cluster overview gives the full listing and the 16 September 2026 backlog decision: a card would advertise an endpoint the site does not operate.

That is the rule to take from it: publish a card only for an A2A endpoint you actually serve. For the human, crawler and API-discovery side of the same problem, see discoverability for paid agent APIs.

Whether to run A2A at all is the question of Do you need A2A?. The cluster's other articles take up discovery, authentication across hops and the task lifecycle.

Frequently asked questions

Where does an A2A Agent Card live?
An A2A agent must publish its Agent Card at https://{server_domain}/.well-known/agent-card.json. Version 0.3.0 of the protocol renamed that path from agent.json, so older tools and posts may still request the previous filename.
Does an A2A Agent Card have to be signed?
No. The A2A specification says a card may be signed with JSON Web Signature (RFC 7515) using RFC 8785 canonicalization, but signing is optional. Because it is optional, an unsigned card proves nothing about who published it.
What is the difference between the public card and the extended Agent Card?
The public card is served at the well-known path to anyone, while the extended card is fetched by an authenticated client when the public card sets extendedAgentCard to true. The client should replace its cached public card with the extended one.
Is an Agent Card the same thing as an MCP server card?
No. An Agent Card describes a peer agent that speaks A2A, while an MCP server card describes a tool server. Publishing one does not imply the other, and each document should only exist where the protocol behind it is actually served.

#a2a #agent-card #discovery #agent2agent #well-known #design

Put this corpus inside your own agents

This guide is free and stays free. The reference corpus behind it — machine-readable contracts, verified primary sources, continuously refreshed — is the paid product: a €5 starter key unlocks every premium reference for one agent via API; a €25 corpus license delivers the full corpus as RAG / fine-tuning data with an explicit AI-use grant; the €150 enterprise license adds commercial redistribution rights.

Agents: this page as Markdown · JSON · offers at /api/pricing.json · payment methods at /api/payment.json · single-resource access via HTTP 402 (how that works)