agents.json: Declaring What Your Site Can Do

A new emerging standard called agents.json allows websites to declare their capabilities to AI agents by publishing a manifest file that describes tasks and flows, bridging the gap between OpenAPI endpoint descriptions and agent goal discovery. Early adopters can gain native integration as agent frameworks add support, though the spec is still evolving and optional.

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.