Publish an agents.json Manifest

Publish an agents.json manifest that declares the agent-facing actions your site exposes, so an agent can discover what it can do, not just read.

What is agents.json?

agents.json is a JSON manifest served at /.well-known/agents.json that declares what an agent may do on a site — endpoints, tools, policies and identity scheme — and where each lives. Two lineages share the name: Wildcard AI's open specification, which builds on OpenAPI and proposes the /.well-known/agents.json path (Wildcard AI, 2025), and the broader well-known-manifest pattern this site and its audit use. Both rest on RFC 8615, which reserves the /.well-known/ prefix for site-wide metadata (IETF, 2019). Where llms.txt declares your content, agents.json declares your capabilities: the discovery facet of the capability surface.

Why does agents.json matter for agents?

agents.json matters because reading a page tells an agent what you say, while a manifest tells it what it can do. Without a declared action surface an agent must infer interactions from forms and buttons, which is brittle and error-prone; a manifest gives it a typed list of operations — the prerequisite for moving from reading to acting, next to MCP and WebMCP in the capabilities dimension. The Agent-Readiness Audit reads the manifest for four checks worth 22 of 100 points: a valid manifest (7), an advertised JSON API (5), advertised WebMCP tools (5) and an identity block for Web Bot Auth (5).

How do you publish agents.json?

Publish agents.json by declaring each interface, pointing it at a live endpoint, and confirming the manifest resolves.

1. Enumerate the agent-facing interfaces — JSON endpoints, callable tools, markdown twins, policies — with method, path and parameters for each.
2. Encode them as JSON and serve the file at /.well-known/agents.json; follow Wildcard AI's schema (version 0.1.0) if you want OpenAPI-based workflows (Wildcard AI, 2025).
3. Verify: the file returns 200 and parses as JSON, and every declared endpoint answers.

The Audit's agents-manifest check (7 points) passes when /.well-known/agents.json returns 200 and parses as JSON; it does not validate against a schema. This site's manifest is live proof: it declares markdown, dataset, JSON-API, WebMCP and identity interfaces, is announced in the HTTP Link header as rel="service-desc" (RFC 8288; IETF, 2017), and is paired with an RFC 9727 API catalog at /.well-known/api-catalog (IETF, 2025).

agents.json — frequently asked questions

Where is agents.json served?

At /.well-known/agents.json — the path Wildcard AI's specification proposes (Wildcard AI, 2025) and the one the Agent-Readiness Audit fetches. RFC 8615 reserves the /.well-known/ prefix for exactly this kind of site metadata (IETF, 2019).

Is agents.json the same as llms.txt?

No. llms.txt curates content for an agent to read; agents.json declares interfaces for it to call — endpoints, tools, policies and identity. This site serves both files.

How does agents.json relate to the api-catalog well-known URI?

RFC 9727 defines /.well-known/api-catalog as a standard Linkset of a publisher's APIs (IETF, 2025); agents.json is the richer, agent-specific manifest. This site serves both and links them from its HTTP Link header.

Related: the agents.json spec entry · the capabilities dimension · capability and tooling protocols · audit your site

← Agent-Readiness · .md