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

> 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.

Guide: A2A in practice: agent-to-agent interoperability — part 2
Published: 2026-10-31 · Updated: 2026-10-31 · 1171 words · ~1557 tokens (estimate)
Canonical: https://changegamer.ai/articles/a2a-agent-card-design
JSON: https://changegamer.ai/api/articles/a2a-agent-card-design.json
Access: free — editorial guide, not part of the licensed corpus
Pillar: https://changegamer.ai/articles/a2a-protocol-in-practice.md

## 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.

---

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](/resources/a2a-protocol) (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](/articles/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](/articles/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:

- **name and description:** say what the agent is for in plain words, because both are read by machines deciding whether to delegate.
- **provider:** name the operator you are willing to be held to; the reference does not say this is verified by anyone.
- **version:** the field exists, so decide whether it tracks your agent's releases or your API's, and keep that choice consistent. This is a design judgment, not spec text.
- **documentationUrl and iconUrl:** point at pages you maintain, since a stale link is the first thing a human reviewing the card will notice.

## 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:

- identity fields that let a caller recognise you;
- `supportedInterfaces` for the endpoints you want discoverable;
- `securitySchemes` and requirements, since a client must learn how to authenticate before it can authenticate;
- `capabilities`, including `extendedAgentCard: true`, so the client knows a fuller card is available.

### 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.

```json
{
  "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](/articles/a2a-protocol-in-practice).

## 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](/articles/a2a-protocol-in-practice) 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](/articles/discoverability-for-paid-agent-apis).

Whether to run A2A at all is the question of [Do you need A2A?](/articles/do-you-need-a2a). The cluster's other articles take up [discovery](/articles/a2a-agent-discovery-without-a-registry), [authentication across hops](/articles/credential-propagation-across-agent-hops) and the [task lifecycle](/articles/a2a-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.


---

## The rest of this guide

- [The A2A Protocol in Practice: Agent Cards, Tasks, Auth and When You Need It](https://changegamer.ai/articles/a2a-protocol-in-practice.md): A practical guide to the A2A (Agent2Agent) protocol: what it standardizes, when it beats in-process subagents, how Agent Cards, task states, bindings and authentication work, how credentials cross agent hops, and how to launch it.
- [Do You Need A2A for a Multi-Agent System? A Decision Rule](https://changegamer.ai/articles/do-you-need-a2a.md): A decision rule for choosing between in-process subagents and the A2A protocol: start with one agent, add more only for a named failure, and cross the network with A2A only when a remote party, framework or trust boundary demands it.
- [A2A Task States and Operations: What Each State Means for an Orchestrator](https://changegamer.ai/articles/a2a-task-lifecycle.md): The eight A2A task states, the eleven operations that act on tasks, the difference between interrupted and terminal states, and an inference-labelled handler matrix for an orchestrator.
- [A2A JSON-RPC vs gRPC vs REST: What Differs Between the Three Bindings](https://changegamer.ai/articles/a2a-bindings-json-rpc-grpc-rest.md): The three A2A protocol bindings (JSON-RPC, gRPC, HTTP+JSON/REST): what the specification keeps identical, what differs on the wire, and an inference-labelled guide to picking one.
- [A2A Authentication Schemes: Which to Declare in Your Agent Card](https://changegamer.ai/articles/a2a-authentication-schemes.md): The five security scheme families an A2A Agent Card can declare (API key, HTTP auth, OAuth 2.0, OpenID Connect, mutual TLS), an inference-labelled rule for choosing one, and how a client handles auth-required tasks.
- [Credential Propagation Across Agent Hops: Exchange, Audience and Depth](https://changegamer.ai/articles/credential-propagation-across-agent-hops.md): How to carry authority through a chain of delegating agents: why forwarding a token fails, per-hop RFC 8693 exchange with act and may_act, RFC 8707 audience binding, a worked sequence and a failure walk-through.
- [How to Verify a Remote A2A Agent Before Delegating](https://changegamer.ai/articles/trusting-a-remote-agent.md): What a signed Agent Card proves and does not, how domain, key and ERC-8004 identity differ, where Web Bot Auth fits, and why card text and returned artifacts are untrusted input, ending in an ordered checklist.
- [How Do Agents Discover A2A Agents Without a Standard Registry?](https://changegamer.ai/articles/a2a-agent-discovery-without-a-registry.md): The three discovery strategies in the A2A documentation, why the spec prescribes no registry API, what vendor registries fill the gap, and how to choose between a well-known URI, a registry and direct configuration.
- [Migrate A2A v0.3 to v1.0: An Ordered Checklist for Clients and Servers](https://changegamer.ai/articles/a2a-v0-3-to-v1-0-migration.md): An ordered checklist for moving an A2A client or server from v0.3 to v1.0: the A2A-Version header rule, method names, Part shape, a runnable grep check, and symptom-to-cause pointers.
- [Does Your Agent Framework Really Support A2A? How to Read the Claim and What to Test](https://changegamer.ai/articles/agent-frameworks-with-a2a-support.md): Which agent frameworks list A2A support, what native, add-on, platform-gated and unrecorded mean, a short test checklist to run before you rely on it, and how that differs from the protocol's own SDKs.
- [Failed or Rejected Remote A2A Task: Retry, Degrade or Surface?](https://changegamer.ai/articles/failure-handling-across-agent-boundaries.md): How to decide what happens after a remote A2A task ends badly: the side-effects test that splits failed into retry or surface, why rejected is not a retry case, why input-required is not a failure, and a structured result for the caller.
- [A2A Production Launch Checklist: Gates to Pass Before You Ship](https://changegamer.ai/articles/a2a-production-launch-checklist.md): A go/no-go checklist for launching A2A agent-to-agent delegation, one line per gate, each pointing to the article that owns the detail: need, card, states, binding, auth, trust, versioning, failure.

## Reference resources

- https://changegamer.ai/resources/a2a-protocol.md
- https://changegamer.ai/resources/mcp-vs-a2a.md

All guides: https://changegamer.ai/api/articles.json · Reference corpus: https://changegamer.ai/llms.txt
Licensing: https://changegamer.ai/api/pricing.json (offer catalog) · https://changegamer.ai/api/payment.json (payment methods, HTTP 402 flow) · access guide: https://changegamer.ai/resources/access-and-pricing.md
