{"slug": "agents-json-declaring-what-your-site-can-do", "title": "agents.json: Declaring What Your Site Can Do", "summary": "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.", "body_md": "*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.*\n\n## What it is\n\n[agents.json](https://agentsjson.org) is a manifest — published at `/agents.json`\n\nor `/.well-known/agents.json`\n\n— 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.\n\n## Why agents need it\n\nAn 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.\n\nIt'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.\n\n## How to implement\n\nStart minimal: declare one real flow that wraps operations you already have in OpenAPI.\n\n```\n{\n  \"agentsJson\": \"0.1.0\",\n  \"info\": { \"title\": \"Acme\", \"version\": \"1.0.0\" },\n  \"flows\": [\n    {\n      \"id\": \"search-products\",\n      \"title\": \"Search products\",\n      \"description\": \"Find products by keyword and return name, price, and availability.\",\n      \"actions\": [\n        { \"operationId\": \"searchProducts\", \"sourceUrl\": \"https://api.acme.com/openapi.json\" }\n      ]\n    }\n  ]\n}\n```\n\nReference your existing OpenAPI operations by `operationId`\n\nso there's one source of truth for the API mechanics and agents.json only adds the task layer.\n\n## Validate\n\n```\ncurl -s https://your-site.com/agents.json | head\n```\n\nConfirm valid JSON with a populated `flows`\n\narray. The [Core Agent Vitals analyzer](https://agentvitals.dev/analyze) checks `/agents.json`\n\nand `/.well-known/agents.json`\n\nand marks it present — it's scored as an emerging/optional signal, so its absence is informational, not a failure.\n\n## Common mistakes\n\n**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`\n\nat`operationId`\n\ns in your published spec.**Publishing an empty manifest.** A`flows: []`\n\nfile 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.\n\n*Next: WebMCP — letting agents call your actions directly.*", "url": "https://wpnews.pro/news/agents-json-declaring-what-your-site-can-do", "canonical_source": "https://blog.r-lopes.com/posts/agent-readiness-agents-json", "published_at": "2026-07-02 14:00:00+00:00", "updated_at": "2026-07-03 21:15:06.080189+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["agents.json", "OpenAPI", "Core Agent Vitals", "Acme"], "alternates": {"html": "https://wpnews.pro/news/agents-json-declaring-what-your-site-can-do", "markdown": "https://wpnews.pro/news/agents-json-declaring-what-your-site-can-do.md", "text": "https://wpnews.pro/news/agents-json-declaring-what-your-site-can-do.txt", "jsonld": "https://wpnews.pro/news/agents-json-declaring-what-your-site-can-do.jsonld"}}