What is agent.json, and which file does your business need?

Several projects use similar filenames for very different jobs. Before you publish an agent manifest, check who will read it, which format they expect and how you will keep it current.

Reviewed October 1, 2026 · 6 min read

There is no single, universally supported agent.json format. Some manifests describe a business and its offers. Others describe an AI agent, an API or a collection of services. The filename alone does not tell you which one you have.

A manifest is a machine-readable description that helps a compatible client discover information or capabilities. It is useful when the client understands its schema. Publishing one does not automatically enroll your business in an assistant or make every agent able to buy from you.

Similar names, different purposes#

Start with the specification your intended integration supports. The Wildcard agents.json project, A2A specification and Agentic Resource Discovery announcement describe different approaches:

These files are not interchangeable. An API description explains how to call a service. An agent card describes an agent. A business manifest may point to offers, policies and booking endpoints. Choose the format by the connection you need to make.

What a small business should publish#

Most businesses should begin with accurate public pages and a working purchase or booking flow. Add a manifest when a platform or integration can use it. You do not need to operate an AI agent yourself to make your services accessible through an API.

Keep the roles distinct. JSON-LD describes the facts on your pages. llms.txt can provide a short reading guide. A business manifest can describe supported actions, but only clients built to read that format will benefit from it.

Schema.org markup can identify a service and its price. An action manifest can add the endpoint, method and inputs needed to request a quote or start a booking. Neither replaces the checks your server must perform before accepting an order.

A manifest is usually a document a client fetches. An MCP server implements a protocol through which compatible applications can discover and call tools. A manifest may link to that server, but the link alone does not establish a working integration.

What a good commerce agent.json actually contains#

For a business manifest, useful information usually falls into six groups. Treat this as a planning checklist, then map it to the schema your client actually accepts.

• Identity: business name, canonical website, location and stable identifiers.
• Contact: supported channels and any limits on automated requests.
• Offers: stable offer IDs, descriptions, currency and the source of current price and availability.
• Actions: endpoint, HTTP method, required inputs, authentication and whether the action creates a commitment.
• Related resources: documented links to policies, API definitions, catalogs or MCP services.
• Fallback: a usable page or contact route when the automated action is unavailable.

This illustrative Nexez-style manifest shows how those pieces can fit together. It is not a universal standard or a complete checkout implementation. Replace the sample business and URLs, then follow your consumer's schema and authentication requirements:

{
  "schema_version": "agent-page.v1",
  "page": {
    "name": "Riverside Physio",
    "url": "https://physio.example",
    "agent_json_url": "https://physio.example/agent.json",
    "description": "Sports physiotherapy clinic in Austin, TX.",
    "currency": "usd",
    "contact": { "value": "book@physio.example", "channels": ["email", "phone"] },
    "llms_url": "https://physio.example/llms.txt",
    "openapi_url": "https://physio.example/openapi.json"
  },
  "offers": [
    {
      "key": "initial-assessment",
      "name": "Initial Physiotherapy Assessment",
      "price": "140.00",
      "currency": "usd",
      "availability": "available",
      "action": {
        "method": "POST",
        "endpoint": "https://physio.example/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."
  ]
}

The endpoint still needs to validate the offer, current price, availability and customer authorization. A manifest describes a possible action; it does not grant permission to perform it.

Should you build your own#

If a client already supports the format you need, a small static manifest can be straightforward to publish. Validate it against that client's schema and test a read-only request before connecting any action that books, charges or changes an account.

The harder part is keeping the description accurate. A stale offer or endpoint can produce a wrong quote or failed request. Recheck transactional details at the point of purchase, even when the manifest was generated recently.

Give the file an owner and a clear update path. Include it in the same release process as the API it describes, and test that its links still work after routing or authentication changes.

Generating a manifest from your business data reduces duplicate editing. Nexez uses listing data to publish its supported business resources. That reduces opportunities for drift, but live transactions still need current availability checks and server-side validation.

What to watch next#

Agentic Resource Discovery adds a catalog approach: one place to advertise resources such as APIs, MCP servers and A2A agents. Its usefulness for your business depends on whether your intended clients discover and consume that catalog.

Expect specifications and client support to change. Record the version you implement, link to its documentation and retest after upgrades. A familiar filename is less useful than a demonstrated connection between your published resource and a real client.

Choose one concrete workflow first, such as finding a service and requesting an available appointment. Publish the required information, connect the supported client and verify the result. Expand from that working integration.