Guides

What is agent.json? The file name five different standards are fighting over

Search for "agent.json" and you will find at least four unrelated specifications answering to a similar name. This guide untangles them, explains what a business actually needs to publish, and shows the shape a good one takes.

Updated August 12, 2026 · 10 min read

There is no single agent.json standard. That is the honest answer, and most explainers skip it because it is a less satisfying place to start than a clean definition. In reality, agent.json (and its close cousins agents.json, ai-agent.json, and agent-card.json) is a name that at least four unrelated groups have independently reached for in 2026, each describing a different kind of file for a different purpose. If you have read one explainer and then a second that seems to contradict it, you did not misread either one. They are describing different things.

The common thread across all of them, and the reason the name keeps getting reused, is worth holding onto: a JSON file, usually at a predictable well-known location, that lets a machine understand what a website, API, or agent can do without a human reading prose first. That idea is sound and increasingly necessary. This guide maps the actual landscape as of August 2026, tells you which file solves which problem, and shows what a commerce-oriented agent.json (the kind a business actually needs) looks like in practice.

The naming collision, mapped honestly

Here is what is actually out there, each with a different author, a different purpose, and a different level of adoption. None of these is a W3C or IETF ratified standard as of this writing.

Two of these solve genuinely different problems that only look similar because they share three letters. agents.json and ai-catalog.json describe what a system can DO (actions, APIs, tool catalogs). ai-agent.json and agent-card.json describe what an autonomous agent IS (identity, so other agents know who they are talking to). The commerce manifest pattern in the last row is closer to the first group: it describes what a business sells and how to buy it, using agent.json as a plain, memorable filename rather than a claim to any particular spec.

Which one should a business actually care about

If you are a business owner rather than someone building an autonomous agent, the identity-card formats (ai-agent.json, agent-card.json) mostly do not apply to you; those describe agents, and your business is not an agent. What applies is the commerce manifest pattern: a machine-readable file describing your business, your offers, and how an agent can act on them (check availability, get a quote, complete a purchase or booking). That is the "agent.json" this guide focuses on from here, and it is the one agentic commerce actually runs on.

It sits at the transactable end of the readiness stack, downstream of JSON-LD and llms.txt. Where JSON-LD tells a crawler what your business IS in schema.org’s vocabulary, and llms.txt is a plain-text index for language models, agent.json goes further: it is API-shaped, meant to be fetched and acted on programmatically, listing not just facts but callable next steps with URLs and expected request bodies. If an MCP server is the live, conversational version of "here is what you can do with my business," agent.json is its static cousin: fetchable with a single GET request, no protocol handshake required, ideal for agents doing a first pass over many candidates before committing to a deeper connection.

What a good commerce agent.json actually contains

Strip away vendor-specific field names and the shape converges on the same handful of sections almost every implementation reaches for, because they map to what a buyer agent actually needs to decide and act:

• Identity: business name, URL, a plain-language description, and a link back to the manifest itself so an agent can always find the canonical source.
• Contact and channels: a preferred way to reach a human, explicitly ranked, so an agent never has to guess between an email address and a contact form.
• Offers: each product or service as a discrete entry with a stable key, name, description, price, currency, and current availability, never buried in prose.
• Actions: for each offer, the concrete next step. HTTP method, endpoint, content type, and the exact request body an agent should send, so a checkout or booking is executable, not just describable.
• Discovery links: pointers to the site’s other agent artifacts (llms.txt, an OpenAPI spec, an MCP server) so agent.json functions as a hub rather than a dead end.
• A plain-text fallback: a flattened, human-and-machine-readable summary of the same facts, which matters because not every consuming system parses nested JSON equally well, and a plain-text version is cheap insurance.

Here is a trimmed but real shape, representative of what a business-facing agent.json contains once you strip it to essentials:

{
  "schema_version": "agent-page.v1",
  "page": {
    "name": "Riverside Physio",
    "url": "https://riversidephysio.com",
    "agent_json_url": "https://riversidephysio.com/agent.json",
    "description": "Sports physiotherapy clinic in Austin, TX.",
    "currency": "usd",
    "contact": { "value": "book@riversidephysio.com", "channels": ["email", "phone"] },
    "llms_url": "https://riversidephysio.com/llms.txt",
    "openapi_url": "https://riversidephysio.com/openapi.json"
  },
  "offers": [
    {
      "key": "initial-assessment",
      "name": "Initial Physiotherapy Assessment",
      "price": "140.00",
      "currency": "usd",
      "availability": "available",
      "action": {
        "method": "POST",
        "endpoint": "https://riversidephysio.com/api/checkout",
        "content_type": "application/json",
        "body": { "offer": "initial-assessment" }
      }
    }
  ],
  "recommended_actions": [
    "Use an offer action for booking intent.",
    "Quote the source page URL when summarizing this offer for a buyer."
  ]
}

Notice what this is not: it is not marketing copy, and it is not a restatement of your homepage. Every field exists because an agent needs it to make or execute a decision. That discipline is the whole point, and it is why hand-writing one well takes real thought about what a buyer agent actually asks.

Should you build your own

You can, and for a single static offer list it is a reasonable afternoon project: pick a shape close to the example above, publish it at /agent.json, and keep it current by hand. The honest complication is the same one that applies to structured data generally: a manifest that quotes a price your checkout no longer honors is worse than no manifest, because an agent will act on it confidently and your customer, or your support inbox, absorbs the mismatch. The moment you have more than a handful of offers, or prices and availability that change, hand-maintenance becomes the actual risk, not the missing file.

The alternative is generating it from the same source of truth that runs your checkout and calendar, so the manifest can never say something your systems would not honor. That is the approach agent-commerce platforms take, Nexez included: agent.json (both a root manifest describing the platform and a per-business manifest at each published page) is generated automatically from live offer, pricing, and availability data, with negotiation and booking actions wired in only when the underlying plan and offer actually support them, never advertised speculatively.

What to watch next

The closest thing to convergence so far is Agentic Resource Discovery (ARD), the ai-catalog.json convention that Google and ten other companies shipped together in June 2026. It does not replace agent.json-style commerce manifests; it sits a level above them, as an index pointing to a site’s MCP server, A2A agent identity, and APIs in one place. If a genuine standard consolidates the naming mess described in this guide, ARD-style multi-party backing is the most likely shape it takes, because a spec with one author rarely becomes the default. Until then, the pragmatic move is the one that has been true of every emerging web convention: publish the artifact that solves your actual problem, keep it accurate and current, and treat the exact filename as far less important than whether the facts inside it are true.