llms.txt vs agents.md: what 32 API docs actually ship

Both files answer the same worry: an AI agent is reading your documentation and you cannot see what it does there. llms.txt is a Markdown map at your domain root that points a model at your real pages. agents.md (also shipped as AGENTS.md) is a briefing for a coding agent working in a repository: how to build, how to test, what not to touch.

They are not competitors, and choosing between them is the wrong question. One describes a website to a reader; the other describes a codebase to a contributor. Most teams that ship the second also ship the first.

So we stopped arguing about it and went and looked. We took the 34 developer documentation sites we had already sent agents into — API companies, SDK vendors, infrastructure and agent tooling — and requested six well-known paths at each docs origin.

The map has won. 28 of 32 sites publish llms.txt, and 25 go further and publish llms-full.txt — every page concatenated, which for the largest sites here is over 3 megabytes in a single response.

The repository briefing is rarer over HTTP, and that is expected: its home is a git root, not a web root. The 6 sites serving it at their docs origin are Novu, Turso, Steel, Hyperbrowser, Mem0, Chroma. Every one of them serves llms.txt as well — 6 of 6 — and not one site in the set ships agents.md instead of llms.txt. That answers the versus: in practice there is no trade-off being made.

We did not only fetch files. On each of these sites we ran an agent with one job: make a first successful API call using the documentation alone. Find the base URL, find the authentication scheme, find a request it can actually copy and send.

Of the 28 sites serving a valid llms.txt, that agent failed on 12. It had the map. It still could not place the call — because the pages the map pointed at described the SDK and never printed a request, or put the example behind JavaScript that a fetch does not run, or showed a request whose every value was a placeholder in angle brackets.

Shipping the file is not the same as being usable. A map that leads to a page with nothing copyable on it is a well-formatted dead end.

We are naming the companies that shipped the files, and we are not naming the 12, deliberately. An agent reads a bounded set of pages, the same way a real one does before it gives up — so the honest claim is “an agent following your own map did not get there”, not “your documentation contains no working request anywhere”. We have been wrong in that direction before, and one unfair accusation would cost more than this page is worth.