BridgeToAgentGet the kit — $49
All documentation
Specification

What is agents.json?

agents.json is a structured JSON file served at the root of your domain (https://yourdomain.com/agents.json) that describes the actions an agent can take on your site: search products, request a quote, book a demo, add to cart, subscribe to a newsletter.

If llms.txt is the reading list, agents.json is the control panel. One is for retrieval, the other is for execution.

Why it exists

LLMs are quickly evolving into agents — models that don't just read your page and answer a question, but click, fill forms, and complete transactions on the user's behalf. ChatGPT's Operator, Anthropic's Computer Use, Google's Project Mariner, and the new Chrome Lighthouse Agentic Browsing category are all in this lane.

An agent attempting to do something on your site has two options:

  1. Discover actions by trial and error. Click around, parse the DOM, submit forms, hope nothing breaks. Slow, expensive, fragile.
  2. Read a manifest. A file at a known URL that says "here are the five things you can do here, with the parameters you need." Fast, cheap, reliable.

agents.json is option 2. The first time an agent visits your site it fetches the manifest and caches it. Every subsequent interaction skips the discovery step.

The schema, at a glance

{
  "schema_version": "0.1",
  "name": "Acme Bicycles",
  "homepage": "https://acmebikes.com",
  "description": "Premium city bikes shipped from Stockholm.",
  "actions": [
    {
      "id": "search_products",
      "name": "Search products",
      "description": "Find bikes by keyword, frame size, or color.",
      "method": "GET",
      "endpoint": "https://acmebikes.com/search",
      "parameters": [
        { "name": "q", "type": "string", "required": true },
        { "name": "size", "type": "string", "required": false }
      ]
    },
    {
      "id": "request_quote",
      "name": "Request a custom quote",
      "description": "Submit a configuration request for a built-to-order bike.",
      "method": "POST",
      "endpoint": "https://acmebikes.com/api/quote",
      "parameters": [
        { "name": "email", "type": "string", "required": true },
        { "name": "frame_size", "type": "string", "required": true },
        { "name": "color", "type": "string", "required": true }
      ]
    }
  ],
  "_meta": {
    "generator_name": "BridgeToAgent",
    "version": "1.2",
    "standard": "agents.json + llms.txt + agent-instructions.md"
  }
}

The shape mirrors OpenAPI in spirit — actions, endpoints, typed parameters — but stays small enough that a non-technical site owner can read it and understand what their site is offering to agents.

What BridgeToAgent puts in your agents.json

We generate actions from your real site, not from prompts:

  • Search. Detected from your site's search endpoint. We probe for ?q=, ?s=, ?search=, and platform-specific patterns (/search?type=product&q=... on Shopify, /?s=... on WordPress, etc.).
  • Forms. Each public form on your site (contact, demo, newsletter, quote, booking) is mapped to an action with its fields typed.
  • Add-to-cart / book. When detected via Schema.org Product or Reservation, we surface the action with the proper endpoint.
  • Navigation shortcuts. The most-traversed internal paths show up as light-weight goto_* actions so an agent doesn't have to scrape the homepage to find the products page.

Every action carries a short human-readable description so an agent can pick the right one when the user's intent is ambiguous.

The _meta block

Every kit we generate includes a _meta block:

"_meta": {
  "generator_name": "BridgeToAgent",
  "homepage": "https://bridgetoagent.com",
  "made_with": "BridgeToAgent",
  "standard": "agents.json + llms.txt + agent-instructions.md",
  "version": "1.2"
}

This is not part of the action surface — it's metadata for downstream tooling. It lets us:

  • Detect format drift when the spec evolves (we can ship migrations keyed on version).
  • Identify legitimately-generated kits vs. handcrafted or LLM-hallucinated ones in third-party tooling.
  • Carry a backlink to the generator, which doubles as an attribution signal for site owners who want it.

The block is optional from a spec standpoint. Agents that don't recognize it ignore it.

Where to put it

Same rules as llms.txt:

  1. Served at /agents.json at the root of your domain.
  2. Content-Type: application/json.
  3. The body is parseable JSON. Not wrapped, not embedded in HTML.

On platforms like Shopify, Wix, or Squarespace that don't let you write arbitrary root paths, see the relevant install guide for the redirect-based workaround.

Common questions

How does this relate to WebMCP? WebMCP is Google's newer, more comprehensive proposal for declaring agent-actionable surfaces inside the page — annotated <button>s, <form>s, and Schema.org-extended elements. The two coexist: agents.json is the manifest an agent fetches first; WebMCP is the per-element annotation it sees once it's on the page. Until WebMCP adoption catches up, agents.json is the practical baseline. We'll ship WebMCP-annotated output as a kit add-on once the spec stabilizes.

Won't agents just scrape my forms anyway? Yes, but unreliably. Form scraping is the agent's fallback when no manifest is present. Sites with agents.json get higher agent task success rates because the agent skips the failure-prone discovery step.

Does this expose internal endpoints? Only the ones you list. The file is a curated surface, not an automatic introspection of your site. If you don't want an action exposed, don't put it in agents.json.

What about authentication? The current spec is read-mostly. Authenticated actions (place order, confirm booking, sign agreement) are part of the v0.2 working spec but not safe to expose yet — there's no settled identity-handoff model between agents and sites. The kit we ship covers public, unauthenticated actions. Authenticated flows arrive when the standard does.

Related