AGENTS.md vs llms.txt vs ai-plugin.json vs agent-card.json

About the author: Brett Calloway is a Developer Advocate and AI Integration Specialist with 12 years of experience in API development. He writes on building context-rich AI agents using Model Context Protocol, drawing on a developer relations background that spans API integration patterns, AI agent architecture, and rapid prototyping with astrology, tarot, and numerology data.

API providers in 2026 face a confusing alphabet of agent-discovery files. AGENTS.md, llms.txt, ai-plugin.json, agent-card.json, plus MCP server URLs, plus OpenAPI, plus the standard sitemap.xml. Each file is a specification, each was authored by a different group, and each is consumed by a different class of automated reader. Treating them as redundant ships either too little context (your SDK is invisible to coding agents) or too much (your llms.txt becomes a 200K-byte dump nobody parses). This comparison breaks down what each file does, the actual byte size RoxyAPI ships at every well-known path, and the decision rule for which ones earn their weight in your stack.

Which agent-discovery file does which job

The four files target four different agent classes. AGENTS.md sits inside an SDK repository and is read by IDE-resident coding agents. llms.txt sits at the website root and is read by AI-search crawlers building citation indexes. ai-plugin.json sits at /.well-known/ai-plugin.json and was originally read by a 2023 plugin host that has since pivoted. agent-card.json sits at /.well-known/agent-card.json and is read by other autonomous agents performing capability discovery under the A2A protocol. None of them read each other. Confusing the four leads to writing instructions for one audience inside a file that reads to a different one.

Ready to see what these look like wired into a working API: the Astrology API ships all four files plus a remote MCP endpoint and is the easiest production reference. See pricing.

When AGENTS.md earns its weight

AGENTS.md belongs in your SDK repository, not at your website root. The format emerged in late 2024 as IDE-resident coding agents started reading repository markdown to bootstrap context. The file lives at AGENTS.md next to README.md, and a coding agent opened on the repo loads it automatically. RoxyAPI ships a 17,866-byte AGENTS.md in the TypeScript SDK repository covering install, the geocode-before-chart rule, namespace conventions, and POST body shape gotchas. The single most important section is the critical-rule callout that prevents the agent from inventing latitude and longitude values when the user asked for a city name. That one rule pays for the whole file because it stops a class of bug that would otherwise ship in every developer who pastes the agent output into production.

The other surfaces (llms.txt, ai-plugin.json, agent-card.json) live at your website domain. They cannot help an IDE agent that has never opened a browser tab against your site. AGENTS.md is the only file in this set that travels with your SDK package.

Why llms.txt is the AIO citation surface

llms.txt is a markdown manifest at your site root that mirrors what robots.txt does for search crawlers, except it targets AI search and citation indexes. The file at /llms.txt is a compact index. The companion at /llms-full.txt inlines the actual documentation pages so a crawler can read the full corpus in one fetch. RoxyAPI ships 53,071 bytes at /llms.txt and a much larger expanded surface at /llms-full.txt. Both are Redis-cached for one hour to keep the responses warm.

The file works because AI search systems do not crawl websites the way Google does. They sample, embed passages, and rank by passage-level relevance. A flat markdown file with link-rich sections is the highest-density format a crawler can index per request. Three rules govern a useful llms.txt: lead with the H1 plus a one-paragraph blockquote summary, keep the root file under 30 high-value links, and put the full prose in the companion file. A bloated root manifest performs worse than a minimal one because section noise dilutes the signal that helps crawlers decide which links are worth following.

Where ai-plugin.json still applies in 2026

ai-plugin.json is the OpenAI ChatGPT Plugin specification, version 1, originally introduced in 2023. The format describes a plugin to a host that wants to load it: name, description, auth scheme, OpenAPI URL, contact email, and (in the post-2024 extended form) a capabilities array. The host that originally consumed this file pivoted to a different action format in 2024, so the spec is technically dormant. Some 2026 agent runtimes still probe /.well-known/ai-plugin.json as a fallback discovery path, and a few 2023-era marketplaces continue to read it. The 10,854 bytes at the RoxyAPI well-known path covers all those probes for the cost of a single static JSON file with zero ongoing maintenance.

If you are deciding whether to ship ai-plugin.json on a new API in 2026, the answer is: only if your stack already generates it from your OpenAPI spec at deploy time. Hand-maintaining the file is wasted effort. Auto-generating it from your existing OpenAPI document is fine because the cost is zero and it covers the long tail of legacy probes.

How A2A agent-card.json fits the multi-agent stack

agent-card.json implements the A2A protocol v1.0, an agent-to-agent discovery standard registered with IANA in August 2025 and maintained jointly under the Linux Foundation. The file at /.well-known/agent-card.json describes what the agent is, what skills it offers, what authentication it requires, and which protocol bindings it speaks. RoxyAPI ships 11,974 bytes here, with one entry per product domain in the skills array, an apiKey security scheme declaring X-API-Key as the header, and per-domain HTTP+JSON protocol bindings.

A2A is complementary to MCP, not a replacement. MCP is the protocol an agent uses to call tools on a server it has already identified. A2A is the protocol two agents use to discover each other in the first place and decide whether collaboration is worth attempting. When a planning agent in a multi-agent system asks "is there an authoritative spiritual-data agent on the network", agent-card.json is the file that answers. The spec is still early in adoption, but it is the only one of the four with active standards-body governance, and it is the cheapest forward bet of the set.

When to choose each (decision tree)

Pick by the audience the file actually serves, not by which format is trendiest in 2026. The four files solve four different problems and overlap nowhere meaningfully.

Ship AGENTS.md when you publish an SDK and want IDE-resident coding agents to write correct integration code on the first prompt. Skip it if you do not ship an SDK package, because the file has no audience without one.

Ship llms.txt when your business depends on being cited in AI-search answers (Perplexity, ChatGPT, Google AIO). Skip it if your traffic is purely B2B sales-led with zero developer self-serve, because AI-search citations do not move that funnel.

Ship ai-plugin.json when your API stack already generates it from OpenAPI at deploy time. Skip the hand-maintained version, because the active host base has shrunk to a long tail of legacy probes and the maintenance cost is not worth the dwindling reach.

Ship agent-card.json when you operate in a domain where A2A peer discovery is plausible (data APIs, agent marketplaces, autonomous workflow systems). Skip it if your API is a one-shot consumer endpoint with no agent-to-agent collaboration story, because the audience has not formed yet for that traffic pattern.

The decision tree is not "pick one". It is "ship the ones whose audience exists". For a developer-first multi-domain API like RoxyAPI, all four audiences exist, and the combined cost is under 100KB plus one weekly review.

122,043 tokens

The combined byte budget is small, and the maintenance cost compounds slowly. Update AGENTS.md on every SDK release. Update llms.txt monthly or whenever a major surface changes. Touch ai-plugin.json once at deploy and forget it. Update agent-card.json when a new product domain is registered or when the auth model changes. Compared with the cost of writing a single FAQ page or maintaining a single blog post, the entire set is one of the cheapest distribution surfaces a developer-tools company can ship.

The deeper question is what each file says, not whether you ship it. A 53KB llms.txt that lists every endpoint with no opinionated commentary is dead bytes. A 53KB llms.txt that tells the crawler which 10 endpoints are most-called and what the common request-shape mistakes are turns into citable passages. Same for AGENTS.md: an autogenerated method dump teaches an agent nothing it cannot read from the OpenAPI spec. A hand-curated AGENTS.md with one critical-rule block (the geocode-before-chart pattern, the POST body field-name traps, the timezone format gotcha) saves the agent from shipping broken code on its first attempt. The format is the medium. The signal is what you write inside it.

FAQ

What is AGENTS.md?

AGENTS.md is a markdown file at the root of an SDK or application repository that teaches IDE-resident coding agents how to integrate with the package. It surfaced in late 2024 as Cursor, Claude Code, and similar agents began reading repository context automatically. The file is the only one of the four agent-discovery formats that travels with the SDK package itself, rather than at the website root.

What is llms.txt?

llms.txt is a plain-text or markdown manifest at a website root that lists the highest-value URLs for AI-search crawlers and citation indexes to fetch. The format mirrors what robots.txt does for search engines, except the audience is Perplexity, ChatGPT, Google AI Overviews, and similar systems. A companion file at /llms-full.txt inlines the documentation pages so the crawler can read the full corpus in one request.

Is ai-plugin.json deprecated?

The original host that consumed ai-plugin.json pivoted to a different action format in 2024, so the spec is dormant for its primary audience. Some 2026 agent runtimes still probe the well-known path as a fallback discovery surface, and a few 2023-era marketplaces continue to read it. Auto-generating the file from an existing OpenAPI spec is cheap and covers the long-tail probes; hand-maintaining it is not worth the effort.

Do I need to ship all four files?

No. Each file targets a different audience, and you only need the ones whose audience exists for your business. An SDK publisher needs AGENTS.md. A developer-tools company that depends on AI-search citations needs llms.txt. A data-API provider planning to participate in A2A peer discovery needs agent-card.json. ai-plugin.json is optional in 2026 and only earns its keep when auto-generated.

What is agent-card.json under the A2A protocol?

agent-card.json is a JSON file at /.well-known/agent-card.json that describes the identity, skills, authentication scheme, and protocol bindings of an agent under the A2A protocol v1.0. The format was registered with IANA in August 2025 and is maintained under the Linux Foundation. It complements MCP rather than replacing it: MCP describes how an agent calls tools on a known server, A2A describes how two agents discover each other in the first place.

Conclusion

Four agent-discovery files, four different consumers, four different signals. Each one is small enough to ship cheaply, durable enough to compound, and specific enough that confusing them ships nonsense to the wrong audience. For the RoxyAPI stack, every file plus the remote MCP endpoint plus the OpenAPI spec adds up to under 500KB on disk and under thirty minutes a month of maintenance. To see the full set in one production reference, explore the Astrology API and the API reference.