Why does /.well-known/agent.json sometimes contain an A2A Agent Card?

Because that was the A2A protocol's official Agent Card location before A2A v0.3.0 (July 30, 2025) renamed the well-known URI to /.well-known/agent-card.json as a breaking change. Sites that adopted A2A early and never migrated still serve their Agent Card at the old path. This makes the path genuinely ambiguous: a JSON file at /.well-known/agent.json may be a stale A2A card rather than an implementation of any of the newer agent.json drafts.

Which agent.json specification should I follow?

For now, none of them. The three drafts are mutually incompatible, none has a standards body or a large backer, and between them they have roughly one known live deployment (a demo storefront). Publishing /.well-known/agent.json today means an agent that fetches it cannot even know which schema you intended — four-way ambiguity with the legacy A2A path included. If you want to declare agent-facing capabilities today, use the artifacts with tooling and consumers: an MCP server card for interactive tools, an A2A Agent Card at /.well-known/agent-card.json (the current path) for agent-to-agent interop, and agents.json if you already have an OpenAPI spec to project.

How widely adopted is agent.json?

Effectively not at all. As of August 2026 the three draft repos hold single-digit GitHub stars between them, and the Agent Web Protocol — the most organised of the three, with an org, a schema site, and a CLI — lists one live deployment, an agent-only demo storefront. For scale: agents.json, the far better-known plural spec, itself shows genuine third-party adoption on under 1% of the 1,100+ domains the Agent Ready scanner has assessed. Specs a further two orders of magnitude smaller are not yet signals an agent can rely on.

Does Agent Ready validate agent.json?

No — deliberately. Agent Ready adds a scanner check only when a spec has either a real organisation or standards body behind it and independent adopters that can be counted in the wild. No agent.json draft clears that bar, and because three incompatible schemas plus the legacy A2A card all share one path, a pass/fail probe of /.well-known/agent.json could not even say what it was grading. Agent Ready tracks the drafts and validates the neighbours instead: agents.json (check C6), the A2A Agent Card at its current agent-card.json path (C4, C5), and MCP server cards (C1, C2).

What is agent.json? And how it differs from agents.json

What is agent.json?

agent.json is a contested filename, not a single specification. As of August 2026, three independent draft specs claim /.well-known/agent.json: the Agent Web Protocol’s capability manifest, a payments-focused manifest that makes a crypto payout address a required field, and an inbox-style draft that pairs the manifest with its own messaging protocol. The same path also carries history: the A2A protocol served its Agent Card there until mid-2025.

And all of this is one letter away from agents.json — Wildcard’s older, OpenAPI-derived manifest, which is a different specification with different tooling. The two names are routinely conflated; this page untangles them.

At a glance

Claimant	Backed by	Path	Declares	Status (Aug 2026)
agents.json (plural)	Wildcard AI (company)	`/agents.json` or `/.well-known/agents.json`	Agent-executable flows projected from an OpenAPI spec	v0.1.0, ~1.3k GitHub stars, real tooling
A2A Agent Card (legacy)	Google / Linux Foundation	`/.well-known/agent.json` before v0.3.0	An agent’s identity, skills, and JSON-RPC endpoint	Superseded — renamed to agent-card.json July 2025
Agent Web Protocol	Community org (no backer)	`/.well-known/agent.json`	Site capabilities, auth, errors, and which protocols the site speaks	Draft v0.2, one live deployment
agent-json (payments)	Single author	`/.well-known/agent.json`	Priced intents with a required payout address	Draft, no known deployments
agent.json (inbox)	Single author	`/.well-known/agent.json`	Actions plus its own message-inbox interaction protocol	Draft, no known deployments

Is agent.json the same as agents.json?

No — and this is the confusion worth clearing up first. agents.json (plural) is Wildcard’s specification: it sits on top of an OpenAPI document you already have and groups its operations into agent-executable flows, served at /agents.json or /.well-known/agents.json. It predates the agent.json drafts, has the largest community of any spec in this family, and has working tooling — including Agent Ready’s generator, validator, and scanner check C6.

agent.json (singular) is the contested filename described on this page: three incompatible draft schemas plus a legacy A2A location. If you have seen “agent.json” cited as “the standard for AI agent API discovery”, check which spec the author actually meant — in our experience the claims usually describe agents.json features, attributed to the wrong filename. For how agents.json compares with MCP and A2A, see MCP vs A2A vs agents.json.

Why might /.well-known/agent.json already contain an A2A Agent Card?

Because the path used to belong to A2A. Google’s Agent2Agent protocol originally published its Agent Card — the JSON document describing an agent’s identity, skills, and endpoint — at /.well-known/agent.json. A2A v0.3.0 (July 30, 2025) renamed the well-known URI to /.well-known/agent-card.json as a breaking change, and that is the path the current specification defines.

Early A2A adopters that never migrated still serve cards at the old path. The practical consequence: a JSON document found at /.well-known/agent.json today is at least as likely to be a stale A2A Agent Card as an implementation of any of the newer drafts — a consumer has to sniff the schema to know what it is holding.

What is the Agent Web Protocol’s agent.json?

The Agent Web Protocol (AWP) is the most organised of the three drafts: an MIT-licensed, community-governed spec with a schema site, a CLI (npx agent-json validate), and an MCP server. Its agent.json declares a site’s actions with inputs and endpoints, its authentication contract, and machine-readable error recovery; draft v0.2 repositions the file as a meta-manifest that also declares which agent protocols the site speaks — MCP, A2A, AP2, x402. It has no corporate or standards-body backer and, as of August 2026, one named live deployment (an agent-only demo storefront). Of the three claimants it is the one to watch: the “front door that lists your protocols” idea is genuinely useful — it is the same gap the AI Catalog draft addresses (agent-ready.dev publishes its own) — but the spec has not yet earned the adoption that would make publishing it meaningful.

What is the payments-focused agent-json?

The agent-json draft is an agent-economy play: a manifest of priced “intents” — name, endpoint, parameters, price — in which payout_address is a required core field, alongside optional bounty and incentive metadata. Making a crypto payout address mandatory caps its audience at sites that want machine-payable endpoints, a niche the x402 and AP2 ecosystems already serve with far more momentum. It ships an npm validator and solid examples, but has no known deployments.

What is the inbox-protocol agent.json?

The third draft goes further than discovery: after an agent fetches the manifest, it interacts by POSTing messages to a /.agent/inbox endpoint and polling for responses — a bespoke agent-to-site messaging protocol. That places it in direct competition with the interaction layer MCP and A2A have already won, which is the hardest possible position for a single-author draft. It ships a reference implementation as a Cloudflare Worker and has no known deployments.

How widely adopted are these specs?

Honestly: not at all, and the gap between “written about” and “published in the wild” is the story. The three agent.json repos hold single-digit GitHub stars between them and roughly one live deployment. agents.json — the plural spec with a company behind it and ~1.3k stars — is itself published by under 1% of the 1,100+ domains the Agent Ready scanner has assessed, once you exclude self-scans. A spec two orders of magnitude smaller than that is not yet a signal an agent can rely on.

This is worth keeping in mind when reading third-party writeups that call agent.json “the standard for AI agent API discovery” or describe it as rapidly adopted. As of August 2026 no measurement we can make supports that — and most such claims do not say which of the three incompatible agent.json specs they mean.

Should I publish agent.json or agents.json?

Publish the artifacts that have consumers today, and skip the contested filename:

Interactive tools for AI clients: publish an MCP server card — MCP has the strongest client adoption of any agent protocol.
Agent-to-agent interop: publish an A2A Agent Card at /.well-known/agent-card.json — the current path, not the legacy one. Our agent card generator builds one.
A REST API you want agents to drive: generate an agents.json from your OpenAPI document — the plural spec, the one with tooling.
/.well-known/agent.json: leave it unpublished for now. Until one draft wins, anything you put there is ambiguous four ways, and an early A2A consumer may even misread it as an Agent Card.

Does Agent Ready check for agent.json?

No — deliberately. Agent Ready adds a scanner check only when a spec has a real organisation or standards body behind it and independent adopters we can count in the wild. No agent.json draft clears that bar yet, and because three incompatible schemas plus the legacy A2A card share one path, a probe of /.well-known/agent.json could not even say which spec it was grading.

The neighbours are covered: agents.json is validated by check C6, the A2A Agent Card at its current path by C4 and C5, and MCP server cards by C1 and C2. See the full mapping in the spec registry. If an agent.json draft earns real adoption, this page and the registry will say so.

Frequently asked questions

What is agent.json?: agent.json is a contested filename, not a single specification. As of August 2026, three independent draft specs claim it: the Agent Web Protocol's agent.json (a capability manifest that also declares which agent protocols a site speaks), a payments-focused agent-json draft (which makes a crypto payout address a required field), and an inbox-style draft that pairs the manifest with its own agent-to-site messaging protocol. The same well-known path also carries history: the A2A protocol served its Agent Card at /.well-known/agent.json until v0.3.0 (July 2025) renamed it to agent-card.json. A file found at that path today could be any of the four.
Is agent.json the same as agents.json?: No. agents.json (plural) is Wildcard's specification: a manifest built on top of an existing OpenAPI document that groups API operations into agent-executable flows, served at /agents.json or /.well-known/agents.json. It predates all three agent.json drafts, has the largest community (about 1.3k GitHub stars versus single digits for each agent.json repo, August 2026), and has real tooling — including Agent Ready's own generator, validator, and scanner check C6. agent.json (singular) is the contested filename with three incompatible draft meanings and no measurable adoption.
Why does /.well-known/agent.json sometimes contain an A2A Agent Card?: Because that was the A2A protocol's official Agent Card location before A2A v0.3.0 (July 30, 2025) renamed the well-known URI to /.well-known/agent-card.json as a breaking change. Sites that adopted A2A early and never migrated still serve their Agent Card at the old path. This makes the path genuinely ambiguous: a JSON file at /.well-known/agent.json may be a stale A2A card rather than an implementation of any of the newer agent.json drafts.
Which agent.json specification should I follow?: For now, none of them. The three drafts are mutually incompatible, none has a standards body or a large backer, and between them they have roughly one known live deployment (a demo storefront). Publishing /.well-known/agent.json today means an agent that fetches it cannot even know which schema you intended — four-way ambiguity with the legacy A2A path included. If you want to declare agent-facing capabilities today, use the artifacts with tooling and consumers: an MCP server card for interactive tools, an A2A Agent Card at /.well-known/agent-card.json (the current path) for agent-to-agent interop, and agents.json if you already have an OpenAPI spec to project.
How widely adopted is agent.json?: Effectively not at all. As of August 2026 the three draft repos hold single-digit GitHub stars between them, and the Agent Web Protocol — the most organised of the three, with an org, a schema site, and a CLI — lists one live deployment, an agent-only demo storefront. For scale: agents.json, the far better-known plural spec, itself shows genuine third-party adoption on under 1% of the 1,100+ domains the Agent Ready scanner has assessed. Specs a further two orders of magnitude smaller are not yet signals an agent can rely on.
Does Agent Ready validate agent.json?: No — deliberately. Agent Ready adds a scanner check only when a spec has either a real organisation or standards body behind it and independent adopters that can be counted in the wild. No agent.json draft clears that bar, and because three incompatible schemas plus the legacy A2A card all share one path, a pass/fail probe of /.well-known/agent.json could not even say what it was grading. Agent Ready tracks the drafts and validates the neighbours instead: agents.json (check C6), the A2A Agent Card at its current agent-card.json path (C4, C5), and MCP server cards (C1, C2).