agents.txt

agents.txt is an open specification that defines Layer 4 of the agent-readiness stack — the capability discovery layer that sits above robots.txt, sitemap.xml, and llms.txt. A site publishes two files at its root: a plain-text /agents.txt declaring which protocols it supports, and a structured /agents.json companion carrying the per-protocol detail an agent needs to interact without crawling every page. The spec is CC0 (public domain) and the reference implementation is Apache 2.0.

What It Is

agents.txt fills the gap that the lower three layers of the web's agent-readiness stack leave open. robots.txt governs access, sitemap.xml inventories pages, and llms.txt briefs LLMs on content — but none of them tell an agent what it can do once it arrives. agents.txt is the answer: a single fetch at a canonical path gives an agent a complete capability map covering payment rails, authorization protocols, MCP server endpoints, agent skill packages, A2A AgentCards, UCP profiles, and WebMCP pages.

The format is deliberately minimal. /agents.txt is plain UTF-8 with seven directive types. /agents.json mirrors the same information in JSON with richer per-block detail (chain identifiers, default pricing, capability descriptions). Parsers ignore fields they do not recognize, making the format forward-compatible by design.

The Capability Block Architecture

The spec defines an open set of independent, optional capability blocks. A site emits only the blocks that apply to it:

• Payments (§8) — declares support for x402 (per-request crypto micropayments), MPP (session-based fiat/stablecoin), and AP2 (mandate trust layer)
• Authorization (§11) — declares agent-auth (per-agent Ed25519 keys) and OAuth 2.0 client-credentials flows
• MCP (§6) — advertises Model Context Protocol server endpoints (Streamable HTTP transport)
• Skills (§7) — points to agentskills.io-canonical SKILL.md packages
• A2A (§9) — lists A2A AgentCard URLs for multi-agent sites
• UCP (§10) — lists Universal Commerce Protocol profile URLs
• WebMCP (§6.6) — advertises pages that register in-browser tools via navigator.modelContext

New protocols can be advertised immediately using the x- prefix before formal registration, giving the ecosystem a runway to test protocols in the wild.

Reference Deployment and Tooling

The live site at agents-txt.com is itself a working agentic site and serves as the self-proof for the spec. It runs as three independent Cloudflare Workers: the main site worker (Astro 6 + Cloudflare Worker) serving static spec artifacts and synthetic payment demo routes, an MCP worker at mcp.agents-txt.com exposing six tools (get_spec, parse_agents_txt, validate_agents_txt, validate_agents_json, audit_site, get_skill), and an agent-auth worker handling Ed25519 JWT verification and OAuth 2.0 client-credentials flows.

The site self-validates through a closed loop: the audit_site MCP tool fetches the site's own /agents.txt, /agents.json, and /robots.txt, runs them through the same validators any third party would use, and checks §4.5 HTTP headers and cross-file consistency. A clean run is the production health check.

The companion generator herald (@agentstxtdev/herald on npm) emits agents.txt, agents.json, robots.txt, llms.txt, sitemap.xml, and four ecosystem discovery files from a single config file. It is a separate project and not required — the spec is implementation-agnostic and can be hand-written in five minutes.

Adoption Path

Three paths exist for site operators:

1. Hand-write — copy the relevant directives, save as /agents.txt, mirror in /agents.json. The $schema field in agents.json pointing at the hosted JSON Schema 2020-12 document enables inline validation and autocomplete in any JSON-aware editor.
2. Generate with herald — pnpm dlx @agentstxtdev/herald init then herald emit writes all files to the public directory.
3. Write a custom generator — the published JSON Schema at agents-txt.com/schema/agents-json/v1.0.json is the canonical validation target; the live audit tool at /audit or the audit_site MCP tool validates any URL.

Current Status: v1.0

The spec page states: "v1.0. Format and schema are stable." The GitHub repository was created in May 2026 and shows active development with the last push in late May 2026. Major capability blocks — Payments, Authorization, MCP, Skills, A2A, UCP, and WebMCP — are settled in v1.0. Structural changes require RFC-style PR review with two approvals; editorial fixes require one. The spec is governed by the agents-txt working group on GitHub under CC0, meaning anyone can implement, fork, or extend without licensing friction.