agent.json, AGENTS.md, llms.txt, agent-card.json: which files AI agents actually read

Published October 29, 2026 · Last reviewed October 29, 2026

Which files AI agents read depends on the agent. AGENTS.md is read by coding agents such as OpenAI Codex, Cursor and Claude Code, inside code repositories.¹² An A2A agent card at /.well-known/agent-card.json is fetched by software that speaks the A2A protocol; API Evangelist found one at 629 of 10,809 API providers it probed in October 2026.³⁴ llms.txt, proposed by Jeremy Howard in 2024, is a curated Markdown map of a site that coding tools read on documentation sites, but 97% of the files in Ahrefs’ May 2026 data got no requests at all, and Google Search does not use it.⁵⁶⁷ agent.json has no settled standard. agents.json is an OpenAPI-based spec from Wildcard that has not changed since August 2025. A guest contract such as Tobira’s guest-agent.json is read only by an assistant that follows a link to it.⁸⁹ None of these files gets a site cited on its own. Here is each one in turn: who defines it, who it is written for, its status and the evidence on who fetches it.

This piece covers each file as of October 29, 2026. It does not reopen whether llms.txt gets a site cited; our llms.txt verdict covers that. Agent cards get a section here and a full treatment in how A2A agent cards work.

We have a stake in the answer. The product page for Tobira Site Agent lists llms.txt, agent.json and AGENTS.md as the files the agent publishes for AI,¹⁰ so our own files appear next to everyone else’s, quoted as they read on the day we fetched them. The last section says what those files do for a site and what they leave to the live agent behind them.

Six files and who stands behind each: the short version

Three kinds of file sit in that table, and the difference matters more than any single row. llms.txt, AGENTS.md and most files called agent.json are descriptions: they tell a reader what exists and where to look. An A2A agent card is a description too, but a structured one that names a live endpoint and how to reach it, which is what lets other software discover an agent. A guest contract such as guest-agent.json goes further: it spells out what a visiting assistant may ask and do at that endpoint, and where the human has to say yes.

Descriptions make a site readable. Only a live endpoint makes it addressable, meaning an agent can ask a question and get an answer that did not exist on any page. When we defined the agentic website, readable, discoverable and addressable were three of its five layers: llms.txt and agent.json sit in the first, agent cards in the second, and only a contract with a live agent behind it reaches the third.

One caution on the last column: adoption and readership are different measurements. A file can sit on many thousands of domains and get almost no requests, so every count of sites below measures adoption.

llms.txt: a curated map with few confirmed readers

What it is. llms.txt is a Markdown file with a title, a one-paragraph summary and lists of links to the pages that matter, ideally with clean Markdown copies of those pages. It usually sits at the root of a site; version 2 of the proposal defines what a file at any other path covers: the pages under it. Jeremy Howard proposed it on September 3, 2024 and revised it on August 10, 2026, and it presents itself as a proposal for a file that helps agents use a website.⁵ It is not a ratified standard, and no standards body governs it.

How many sites publish it. That depends entirely on the sample, so always name the study. Ahrefs found the file on 28% of the 137,210 domains in its web analytics product, a sample that skews toward technical, SEO-aware sites, and treats that share as an upper bound.⁶ SEOmator found a real file on 8.6% of Cloudflare Radar’s top 100,000 domains on September 13, 2026, and calls that a level, not a trend.¹³ Both numbers are adoption. Neither says anything about readers.

Who reads it. On most sites, almost nobody. In the Ahrefs data, 97% of published llms.txt files received no requests at all in May 2026. Of the requests that did arrive, 96% came from bots, and named AI tools made up 19.5% of them, led by GPTBot, a training crawler, and Claude Code, a coding agent, ahead of every AI search or assistant bot.⁶ Google’s guide to generative AI features, last updated July 10, 2026, says Google Search does not use llms.txt and that creating one “will neither harm nor help” a site there.⁷ Google’s John Mueller had already called any benefit speculative, in Reddit comments that Search Engine Journal reported on June 2.¹⁴

Documentation sites are the exception. Mintlify, which hosts documentation for more than 20,000 companies, reports in its own data that /llms.txt was fetched about 10.8 million times across its sites in August 2026.¹⁵ The proposal’s author agrees, writing in his v2 notes that coding agents “use them reliably.”⁵ The readers exist; they are mostly coding tools reading documentation, not the assistant a buyer uses to compare vendors.

When it still earns its place. llms.txt costs an afternoon and gives an agent that is pointed at it a short, curated index instead of a crawl. That helps when something else sends the agent there: a link in another file, a developer’s instructions, or a site agent that tells visiting assistants where to look, as in our six-file knowledge pack example. Keep it short and in step with the live pages. It is not a lever for being found, cited or recommended by AI models.

AGENTS.md: a README for coding agents

AGENTS.md is the easiest file on this list to describe, because its own site calls it “a README for agents”: a plain Markdown file in a code repository that gives AI coding tools a project’s setup commands, test commands and conventions.¹ It has no required fields, and the AGENTS.md closest to the file being edited wins. More than 60,000 open-source projects use it; OpenAI Codex, Google’s Jules, Cursor and GitHub Copilot’s coding agent are among the tools that support it, and Claude Code reads it when a project has no CLAUDE.md. The Agentic AI Foundation stewards the format.¹² None of that makes it a convention for agents that browse websites. Nothing in the format tells a buyer’s assistant to look for it on your pricing page, and no specification pairs it with llms.txt.

Our own use is a different case. Tobira publishes an AGENTS.md at tobira.ai/@tobira-ai/AGENTS.md written for visiting AI assistants: it opens by telling them to use the guest JSON API rather than the web chat, then points to an overview, the guest contract and an OpenAPI document and sets out the trust boundary.¹⁶ That is a publisher choosing a familiar filename for a briefing; it does not change what the format is for. If you run a codebase, write an AGENTS.md for the coding agents that work in it; for a website, our checklist for making a site ready for AI agents covers what matters instead.

agent-card.json: the A2A discovery path

Of the files on this list, the agent card is the one with a working protocol behind it. In A2A, an agent publishes a JSON document describing itself: its name, its skills, the interfaces it serves, the protocol version and how to authenticate. The discovery guide gives the standard location as https://{agent-server-domain}/.well-known/agent-card.json, following RFC 8615, and IANA lists agent-card.json as a permanent well-known URI. A client that knows a domain sends one GET request to that path and gets the card back; curated registries and direct configuration are the other routes.³¹¹ A2A’s latest stable release is v1.0.1 (May 28, 2026), and the protocol has lived in the Agentic AI Foundation since August 17, 2026.³

Who reads it. Software that speaks A2A: agent frameworks, orchestrators and registries that need to find an agent and call it. We found no consumer assistant that documents fetching agent cards from the websites it browses, so a card is a way to be callable by other agents, not a way to be noticed by a chat product.

How many sites publish one, and how well. Kin Lane at API Evangelist probes the APIs.io catalog of API providers. In its October 17, 2026 snapshot, 629 of the 10,809 providers probed at their own domains served an A2A card, against 573 serving an llms.txt.⁴ His September analysis of 427 providers with cards found 60% passing every structural check, up from 15% in July, 8% still at the old /.well-known/agent.json path, and more than a third declaring no transport at all, which leaves a client knowing an agent exists but not how to reach it.¹² These are API providers, not the web at large. The lesson: serve the card at agent-card.json and fill in the interface, with its URL, protocol binding and version. A card with no reachable endpoint describes an agent nobody can call.

One card per domain, and what comes next. The well-known path holds one card per domain. A2A’s documentation for its next version, merged into the v1.1 development branch on October 21, 2026 and included in the v1.1.0-rc tag of October 29, but not in a stable release, names that limit and marks a catalog at /.well-known/ai-catalog.json as the preferred route for hosts with more than one agent.¹⁷ MCP’s Server Cards proposal, SEP-2127, is marked Final and leaves domain-level discovery to the same catalog; guides that put MCP cards under /.well-known/, such as /.well-known/mcp/server-card.json, follow a placement MCP considered and did not recommend.¹⁸ AI Catalog itself is still a draft, and the A2A and MCP steering committees are to vote on it once it is final.¹⁹

Tobira’s own card shows why this matters. The card for @tobira-ai declares a JSON-RPC interface at protocol version 1.0 and sits under the handle path, tobira.ai/@tobira-ai/agent-card.json, announced through a Link header with rel="service-desc" and through the agent’s agent.json; on October 29, 2026, tobira.ai/.well-known/agent-card.json still returned a 404.²⁰²¹ Tobira hosts many agents on one domain, so a client that only checks the well-known path would miss them, which is the case a domain-level catalog is designed for.

agent.json and agents.json: familiar names, no settled standard

“agent.json” is the name people reach for most, and it is the one with the least behind it. There is no settled web standard called agent.json. The name turns up in at least three unrelated places, and it helps to know which one you are looking at.

The old A2A path. Before A2A 0.3, agent cards were served at /.well-known/agent.json. The specification moved to agent-card.json, and 8% of the cards API Evangelist analysed in September 2026 were still on the old path.¹² A client written for current A2A looks for the new name, so a card left at the old one can be missed.

Drafts that moved away from it. The ENS proposal for an agent card schema (ensdomains/ensips pull request #75) first named /.well-known/agent.json as its path and later changed it to /.well-known/agent-card.json to line up with A2A. It was filed as ENSIP-27 but dropped that self-assigned number in July 2026; ENSIP-27 now belongs to a different spec, Node Classification and Metadata, merged in August 2026. The proposal is still open and unmerged; our piece on the ENS agent card proposal covers it.²² A draft that renames its file to match a protocol with working clients shows which name those clients will look for.

Vendor files. Many products publish an agent.json with their own schema, Tobira included. Tobira’s file for @tobira-ai declares "object": "agent_ready_public_address" and "schema_version": "2026-05-27.stage1". It lists the agent’s other files and endpoints (the agent card, llms.txt, AGENTS.md, an OpenAPI document and the guest contract), tells visiting assistants to use the guest JSON API rather than the web chat, and carries a safety block: public data only, with "domain_verification_claimed": false.²¹ It is a useful index for an agent that already knows the format, which no other publisher shares; the schema is labelled stage 1, so field names may change.

agents.json, plural. A separate specification uses the plural name. Wildcard’s agents.json, version 0.1.0, is an open specification for “contracts for API and agent interactions”, built on OpenAPI, at the proposed path /.well-known/agents.json.⁸ Its use case is a language model calling a company’s API as tools, which is about APIs rather than a visiting assistant reading a marketing site. It also looks inactive: the repository has had no commits since August 21, 2025, and the registry its README links to returned a 404 on October 29, 2026.⁸ If your goal is to point agents at your API descriptions, an IETF standard already does that job: the /.well-known/api-catalog of RFC 9727, which 702 of the providers in Lane’s October snapshot served.²³⁴

The practical rule for any file with this name: say inside it which schema it follows, link to it from places agents do fetch (the page’s Link header, the agent card, llms.txt), and put anything an agent must act on behind an endpoint that a published contract describes.

guest-agent.json: the contract a visiting assistant can act on

The files so far describe a site or an agent. The last one on the list is a contract for doing something. Tobira publishes a guest contract for each site agent; the one for @tobira-ai, at tobira.ai/api/v1/agents/tobira-ai/guest-agent.json, is what a visiting assistant gets when it follows the links in the other files.⁹ It is Tobira’s own format, not a standard; it shows what a file has to contain before an agent can act rather than just read. Here is what it said on October 29, 2026.

How a conversation runs. A visiting assistant opens a guest session with one POST request, identifying itself as visitor_ai_agent on the json_guest_api transport, then sends messages and polls for replies, with a soft limit of 30 turns, 5 turns of grace and a hard cap of 50. When it asks for structured JSON, each reply carries the answer and a cannot_verify list of facts the agent could not confirm from approved public material, plus, when available, a confidence level, public source labels, a suggested next step and a booking offer.⁹ The cannot_verify field is the one to notice: it lets the visiting assistant tell its user what the site would not vouch for, instead of smoothing it over.

What it can do. Besides ask_question, the contract lists five actions: list_consultations, list_available_slots, prepare_booking, submit_authorized_contact and check_booking_status.⁹

Where the human stays in charge. prepare_booking and submit_authorized_contact both require authorized_by_user: true, and the consent text tells the assistant to get the user’s explicit authorization before it submits contact details or prepares a booking. Payment is a human action: a returned checkout URL is a handoff to the person, and “an AI visitor never completes payment.” And the visitor is a guest: the boundary block sets trusted_a2a, matchmaker_participant and network_participant to false, while a safety block lists what never leaves the agent, from internal owner notes and system prompts to API keys and support transcripts.⁹

Why a contract beats a file here. Assistants acting for a user will visit whether or not a site invites them. OpenAI’s documentation says ChatGPT-User visits pages when a user asks a question and that, for these user-initiated visits, “robots.txt rules may not apply.”²⁴ Such a visitor can scrape the page, or it can find a documented endpoint that answers its exact question, says what it cannot verify and hands the decision back to its user. One site-side interface a major assistant documents using is a contract too, not a file: OpenAI describes Site tools, in the ChatGPT desktop app’s built-in browser, as its implementation of the proposed WebMCP standard, for tools a page registers itself.²⁵ Microsoft’s NLWeb takes the same idea to a site-wide /ask endpoint.²⁶ See also WebMCP adoption and how AI agent conversation phases work.

Readable files, an addressable endpoint: what Tobira Site Agent publishes

Here is the claim on our own product page, and what sits behind it. Asked how AI agents find a site, the Site Agent FAQ answers: “Your agent publishes files for AI: llms.txt, agent.json and AGENTS.md.” It adds that agents visiting a site read those files and then talk to the agent directly, and it links to the domain-level tobira.ai/llms.txt as an example. The paid plans include a site ready for AI agents.¹⁰

Read against the sections above, that breaks into two parts.

The readable part. The files are descriptions: they make a site readable and tell an agent where to go next, and the agent card adds the discoverable layer. They do not, on their own, get a site cited or recommended by AI models; the llms.txt evidence above applies to ours too. The product page does not say whether a customer’s files sit on the customer’s domain or under a Tobira handle, and we did not check a customer install, so we make no claim either way.

The addressable part. Each of those files sends a visiting assistant to the guest contract, and the contract points at a live agent. That is the part a file cannot do: answer the question that is not on any page, from the owner’s approved public material; offer slots and prepare a booking with the user’s yes; send a checkout link that the human completes; pass contact details only with authorization. On the owner’s side, the page promises a short summary of each result rather than the transcript, and owners manage the agent from their own AI tools via MCP or API, through a bridge the guest contract marks as requiring the owner’s API key and closed to visiting assistants.¹⁰⁹

In one line: Site Agent publishes the machine-readable files AI agents look for and gives them a live endpoint to ask and act. That is the difference between a site agents can read and one they can ask, which our readable vs addressable explainer covers in full and the website for humans and their agents piece puts in context. The files are the smaller half of the job.

What to remember

• Sort the files by what they let an agent do. Most describe; an A2A agent card names a live endpoint; a guest contract says what a visitor may ask and do there.
• llms.txt is a map, not a magnet. 97% of the files in Ahrefs’ data got no requests, Google Search ignores it, and its steady readers are coding tools on documentation sites.
• AGENTS.md belongs in code repositories. Using the name for a website briefing is a publisher’s choice, not part of the format.
• Serve agent cards at /.well-known/agent-card.json, with a reachable interface, and watch the AI Catalog draft if one domain hosts several agents.
• agent.json has no settled standard, and Wildcard’s agents.json is an apparently inactive spec for API tool calls; RFC 9727’s api-catalog does that job as a standard.
• Only a live endpoint makes a site addressable. Anything an agent must act on needs a contract with the human’s consent written into it.

Before you add another agent file, open the ones your site already serves and read each one as a visiting assistant would: who defined it, who reads it, and where it sends that reader next.

FAQ

What is the difference between AGENTS.md and llms.txt?

They are written for different readers. AGENTS.md is a README for coding agents that sits in a code repository and tells tools such as Codex, Cursor or Claude Code how to build, test and follow a project’s conventions. llms.txt is a proposed Markdown index, usually at the root of a website, that points language models to the pages that matter. No specification pairs the two.

Is agent.json a web standard?

No settled web standard uses that name. /.well-known/agent.json was the A2A agent card path before version 0.3, and the protocol now uses /.well-known/agent-card.json. Other files called agent.json, Tobira’s included, follow each vendor’s own schema, so a generic agent cannot be expected to understand one without being told.

Where should an A2A agent card live?

At https://{your-domain}/.well-known/agent-card.json, the standard path in the A2A discovery guide and a permanent IANA registration. A client sends one GET request there and reads the card. Make sure the card declares a reachable interface with its URL, protocol binding and version; in API Evangelist’s September 2026 sample, more than a third of cards declared no transport. If you host several agents on one domain, A2A’s documentation for its next version prefers a catalog at /.well-known/ai-catalog.json, still a draft.

Do AI assistants read llms.txt?

Rarely, on most sites. Ahrefs found that 97% of published llms.txt files got no requests in May 2026, the AI tools that did fetch them were led by GPTBot and Claude Code rather than assistant or search bots, and Google says Google Search does not use the file. Documentation sites are the exception, where coding tools fetch it at scale. It still works as a curated map for an agent that is pointed to it.

What is agents.json?

agents.json, with an s, is Wildcard’s open specification for describing API contracts that language models can call as tools, built on OpenAPI and at version 0.1.0. It proposes the path /.well-known/agents.json, and its repository has not changed since August 2025. It is a different thing from agent.json and from A2A agent cards, and it targets API integrations rather than visitors to a marketing site.

Will publishing these files get my site recommended by ChatGPT?

There is no evidence that the files alone do that. They make a site easier to read for an agent that arrives, and an agent card or guest contract lets that agent call a live endpoint. Being cited or recommended depends on the assistant’s own retrieval and ranking, which none of these files controls.

Sources