--- title: "What is agent.json? And how it differs from agents.json" description: "agent.json is a contested filename, not one spec: three rival drafts (Agent Web Protocol, a payments manifest, an inbox protocol) all claim /.well-known/agent.json — the same path where A2A served its Agent Card before v0.3.0 renamed it to agent-card.json. None has measurable adoption, and all are one letter away from agents.json, Wildcard's OpenAPI-derived manifest that actually has tooling." last_updated: 2026-08-20 canonical_url: https://agent-ready.dev/what-is-agent-json --- # What is agent.json? > One filename, four incompatible meanings — and one letter away from a different spec entirely. ## At a glance agent.json (singular) is a contested filename, not a single specification. As of August 2026: | 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. agents.json (plural) is Wildcard's specification: a manifest built on top of an OpenAPI document you already have, grouping 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 in this family, and has working tooling — including Agent Ready's generator (), validator (), and scanner check C6. agent.json (singular) is the contested filename: three incompatible draft schemas plus a legacy A2A location. ## 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 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. Early adopters that never migrated still serve cards at the old path, so a JSON document found there today is at least as likely to be a stale A2A Agent Card as an implementation of any newer draft. ## The three rival drafts - **Agent Web Protocol (AWP)** — the most organised: MIT-licensed, community-governed, with a schema site, CLI, and MCP server. Draft v0.2 makes agent.json a meta-manifest that also declares which protocols a site speaks (MCP, A2A, AP2, x402). No corporate backer; one named live deployment. The one to watch. - **agent-json (payments)** — priced "intents" with a **required** crypto `payout_address`; an agent-economy niche the x402 and AP2 ecosystems already serve. No known deployments. - **agent.json (inbox)** — pairs the manifest with its own agent-to-site messaging protocol (POST to `/.agent/inbox`, then poll), competing head-on with the interaction layer MCP and A2A already won. No known deployments. ## Should I publish agent.json or agents.json? Publish artifacts that have consumers today, and skip the contested filename: an MCP server card for interactive tools; an A2A Agent Card at `/.well-known/agent-card.json` (the current path); an agents.json generated from your OpenAPI document if you want agents to drive your REST API. Leave `/.well-known/agent.json` unpublished — until one draft wins, anything there is ambiguous four ways. ## 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 countable in the wild; no agent.json draft clears that bar, and a probe of a four-way-ambiguous path could not even say which spec it was grading. The neighbours are covered: agents.json (check C6), the A2A Agent Card at its current path (C4, C5), and MCP server cards (C1, C2). ## 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). --- Read the full guide on the web: Generate an agents.json from your OpenAPI document: ## Sitemap See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.