# agents.txt

> An open specification for AI agent capability declarations, using two files (/agents.txt and /agents.json) at the site root to announce supported protocols, MCP servers, payments, and authorization to AI agents.

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.

## Features
- Plain-text /agents.txt capability declaration file
- Structured /agents.json companion with per-protocol detail
- Layer 4 of the agent-readiness stack (above robots.txt, sitemap.xml, llms.txt)
- Payment protocol declarations: x402, MPP, AP2
- Authorization protocol declarations: agent-auth, OAuth 2.0, auth.md
- MCP server endpoint discovery (Streamable HTTP)
- Agent skill package discovery (agentskills.io SKILL.md)
- A2A AgentCard URL declarations
- UCP profile URL declarations
- WebMCP in-browser tool page declarations
- x- prefix for experimental protocol advertising
- Forward-compatible: parsers ignore unknown fields
- Live audit tool at /audit for any URL
- MCP server with 6 tools: get_spec, parse_agents_txt, validate_agents_txt, validate_agents_json, audit_site, get_skill
- Hosted JSON Schema 2020-12 for agents.json validation and editor autocomplete
- herald generator (sibling npm package) for automated file generation
- Self-validating reference deployment
- CC0 spec license (public domain)
- Apache 2.0 reference code license

## Integrations
x402 (per-request crypto micropayments), MPP (session-based fiat/stablecoin payments), AP2 (mandate trust layer), agent-auth (Ed25519 JWT per-agent identity), OAuth 2.0 (client-credentials flow), auth.md, Model Context Protocol (MCP), A2A AgentCard (a2a-protocol.org), UCP (Universal Commerce Protocol, ucp.dev), WebMCP (navigator.modelContext), agentskills.io, Cloudflare Workers, Astro 6, robots.txt (RFC 9309), sitemap.xml (sitemaps.org), llms.txt (llmstxt.org), RFC 9727 API catalog, SEP-2127 MCP server card, RFC 9116 security.txt, OpenAPI 3.1 with Payment Discovery extensions

## Platforms
WEB, API, VSC_EXTENSION, JETBRAINS_PLUGIN, CLI

## Pricing
Open Source

## Version
1.0

## Links
- Website: https://agents-txt.com
- Documentation: https://agents-txt.com/spec
- Repository: https://github.com/agents-txt/agents-txt
- EveryDev.ai: https://www.everydev.ai/tools/agents-txt