# Publish an agents.json Manifest

Published 2026-06-17 · Updated 2026-09-07 · Author: Özden Erdinc (https://erdinc.ai) · Editorial guidelines: /about#editorial-guidelines

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

## Sources

1. Wildcard AI: agents.json specification (schema 0.1.0), 2025. https://github.com/wild-card-ai/agents-json
2. IETF: RFC 8615 Well-Known Uniform Resource Identifiers (URIs), 2019. https://www.rfc-editor.org/rfc/rfc8615
3. IETF: RFC 9727 api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs, 2025. https://www.rfc-editor.org/rfc/rfc9727
4. IETF: RFC 8288 Web Linking, 2017. https://www.rfc-editor.org/rfc/rfc8288

Related: [the agents.json spec entry](/protocols/agents-json) · [the capabilities dimension](/agent-readiness/capabilities) · [capability and tooling protocols](/protocols/capability) · [audit your site](/services)