agents.json: Declaring What Your Site Can Do

Part of the Agent Readiness course. Measure any page with the Core Agent Vitals analyzer. This is an emerging standard — early, optional, and worth watching.

What it is

agents.json is a manifest — published at /agents.json or /.well-known/agents.json — that declares the capabilities your site exposes to agents: named flows ("search products", "create booking"), the API operations each flow uses, and the parameters an agent must supply. Where OpenAPI describes individual endpoints, agents.json describes tasks — the sequences that get something done.

Why agents need it

An agent reading your OpenAPI spec knows how to call each endpoint, but not which endpoints combine to accomplish a goal, or that a goal is even offered. agents.json closes that gap: it's a discovery layer that says "this site can do X, Y, Z, and here's the flow for each." That turns your site from a collection of endpoints into a set of advertised services an agent can plan against.

It's genuinely early — support is thin and the spec is evolving. But it's cheap to publish, and early adopters get native integration as agent frameworks add support. Treat it as a low-cost bet, not a requirement.

How to implement

Start minimal: declare one real flow that wraps operations you already have in OpenAPI.

{
  "agentsJson": "0.1.0",
  "info": { "title": "Acme", "version": "1.0.0" },
  "flows": [
    {
      "id": "search-products",
      "title": "Search products",
      "description": "Find products by keyword and return name, price, and availability.",
      "actions": [
        { "operationId": "searchProducts", "sourceUrl": "https://api.acme.com/openapi.json" }
      ]
    }
  ]
}

Reference your existing OpenAPI operations by operationId so there's one source of truth for the API mechanics and agents.json only adds the task layer.

Validate

curl -s https://your-site.com/agents.json | head

Confirm valid JSON with a populated flows array. The Core Agent Vitals analyzer checks /agents.json and /.well-known/agents.json and marks it present — it's scored as an emerging/optional signal, so its absence is informational, not a failure.

Common mistakes

• Declaring flows you don't actually support. An agent will try them. Only advertise capabilities that work end to end.
• Duplicating your OpenAPI instead of referencing it. Inline copies drift. Point actions at operationIds in your published spec.
• Publishing an empty manifest. A flows: [] file adds nothing. Ship it when you have at least one real flow.
• Treating it as mandatory. It isn't yet. Do the foundational lessons (robots, sitemap, JSON-LD, llms.txt, OpenAPI) first — they pay off today.

---

Next: WebMCP — letting agents call your actions directly.