If you publish an A2A Agent Card for your store, the protocol’s own docs now say where to put it: an AI Catalog at /.well-known/ai-catalog.json is the preferred route, and /.well-known/agent-card.json stays valid but limited. The change landed in the A2A repository on 2026-10-22 and is part of the v1.1.0-rc release candidate, not yet a final release.

What changed in the A2A docs

The commit, 8faec73 (“update agent discovery to prefer AI Catalog over well-known URI”), gives its reason in the description: agent-card.json “only supports advertising a single Agent Card per domain”, which breaks multi-agent and multi-tenant deployments.

In the discovery guide at the v1.1.0-rc tag, read from a clone on 2026-11-03:

  • Option 1, /.well-known/agent-card.json: “A simple option for single-agent deployments.” The guide lists one limitation in bold: one Agent Card per domain.
  • Option 2, /.well-known/ai-catalog.json: headed “Preferred”. A host publishes an AI Catalog document whose entries list one or more Agent Cards.
  • Entry format: each entry has a type of application/a2a-agent-card+json and either a url pointing at the card or the card embedded inline in data, not both.
  • Catalog location: the guide says the catalog can be served from any URL, for example an authenticated endpoint that returns only the agents a given caller may see.

The IANA registration text for the well-known URI in the spec now also notes the single-card limit.

What it means for a store

Most stores run one storefront and would publish one card, so the old path still works. The preferred path matters in three cases:

  • You run several agents on one domain (a shopping assistant plus a support agent, say).
  • Different callers should see different agents, such as wholesale buyers versus the public.
  • You are an agency or platform hosting many merchants behind one domain.

For a single-store setup, the catalog’s inline form means one JSON file can carry the card without a second URL to host.

A caveat: two catalog specs are not aligned

The A2A docs point to ai-catalog.json. A separate project, the Agentic Resource Discovery (ARD) spec, moved its manifest from that path to /.well-known/ard.json in v0.91; we covered that in ai-catalog.json is now ard.json. Both are drafts. We have not found a source that reconciles the two, so a store that wants to be found by either family of client may need to watch both.

Existing guidance in our Agent Card explainer on what the card must contain is unchanged by this commit; only where it is discovered moved.

FAQ

Do I have to move my agent-card.json to ai-catalog.json?

No. The A2A discovery guide at v1.1.0-rc keeps /.well-known/agent-card.json as a valid option for single-agent deployments. It marks AI Catalog as preferred, mainly for hosts with several agents or per-caller visibility.

Is A2A v1.1.0-rc final?

No. It is a release candidate tag. The change is also on the repository’s development branches, but the previous tag, v1.0.1, does not contain it, so the guidance may still change before a final 1.1 release.

What does an AI Catalog entry for an Agent Card look like?

It is a JSON object in the catalog’s entries array with an identifier, a type of application/a2a-agent-card+json, and a url to the card. An entry can instead embed the card inline in a data field, so no second fetch is needed.

Sources

Agents can only buy from a store they can discover and read, which is why where your machine-readable card lives is part of auditing the transaction.