If an AI agent is deciding whether to talk to your store, the first thing it looks for isn’t your homepage — it’s a JSON file at a fixed address. The Agent2Agent (A2A) protocol, the Linux Foundation-governed spec for how autonomous agents describe themselves to each other, requires exactly this: a machine-readable “business card” published at https://{your-domain}/.well-known/agent-card.json.

What the spec actually requires

A2A’s specification is direct about it: “A2A Servers MUST make an Agent Card available,” and the card “describes the server’s identity, capabilities, skills, and interaction requirements” so a client agent can decide whether it’s worth connecting at all (A2A specification, §8.1).

The primary discovery mechanism follows the well-known URI convention from RFC 8615: a client that knows your domain performs a plain HTTP GET on /.well-known/agent-card.json and, if the file exists, gets the card back as JSON — no prior handshake, no registry lookup required (A2A specification, §8.2; Agent Discovery guide). Two other discovery paths exist — curated registries and direct configuration — but the well-known URI is the one that requires nothing from the agent except your domain name, which makes it the default for public-facing sites.

What goes in the file

The spec’s sample card shows the shape (A2A specification, §8.5):

  • Identity — name, description, and a provider object (organization name and URL).
  • Endpoints — supportedInterfaces, an ordered list of transport/URL pairs (JSON-RPC, gRPC, HTTP+JSON) in preference order; the first entry is what a client tries first.
  • Capabilities — booleans like streaming and pushNotifications, plus whether an authenticated, more detailed “extended” card is available.
  • Security — securitySchemes and securityRequirements, declaring how a client authenticates (OAuth2, OpenID Connect, etc.).
  • Skills — an array of AgentSkill objects, each with an id, name, description, tags, and example inputs/outputs. This is the part a client actually searches over to decide if your agent can do what it needs.

Two details worth building for from day one. First, caching: the spec says card endpoints should send Cache-Control with a max-age and an ETag derived from the card’s version field, since well-behaved clients are expected to honor conditional requests rather than re-fetch on every call (§8.6). Second, signing: cards may carry a JWS signature over a canonicalized (RFC 8785) version of the JSON, letting a client verify the card hasn’t been tampered with and actually came from the claimed provider (§8.4). Neither is mandatory, but both are the difference between a card an automated client trusts on sight and one it has to treat cautiously.

The protocol itself is a moving target worth tracking, not a finished artifact: v1.0 shipped 2026-03-12 with breaking changes from v0.3 (enum casing, ID formats, field renames), and v1.0.1 followed 2026-05-26 with binding-level fixes — normal spec-maturation churn, but it means a card generated against an older SDK version can be stale (A2A CHANGELOG).

Where this fits for a store

An Agent Card answers “what is this and can I talk to it” — it’s a discovery and capability-declaration layer, the same job robots.txt and llms.txt do for crawlers, just structured for agent-to-agent negotiation instead of text ingestion. It’s also the building block one layer up: Google and Microsoft’s ai-catalog.json / Agentic Resource Discovery spec explicitly lists A2A agent cards as one of the resource types a site’s catalog can point to.

None of that gets a shopper’s order placed. A published, well-formed Agent Card tells an agent your store exists and what it claims to support — it says nothing about whether the checkout behind it actually completes a purchase, which runs on separate rails entirely (ACP and UCP). Discovery and transaction are different failure modes, and a store can ace one while failing the other completely — which is exactly the gap an AgentReady scan is built to catch.

Sources

As of August 2026, A2A is at v1.0.1. The spec repository is the source of truth for the current schema.