# agents.json: Declaring What Your Site Can Do

> Source: <https://blog.r-lopes.com/posts/agent-readiness-agents-json>
> Published: 2026-07-02 14:00:00+00:00

*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](https://agentsjson.org) 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](https://agentvitals.dev/analyze) 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`operationId`

s 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.*