Agent Card vs llms.txt: a connection contract and a reading list

An Agent Card is for telling client agents how to connect to an A2A agent: its endpoints, skills, capabilities and required authentication, in a JSON document whose shape the A2A specification defines. llms.txt is for pointing language models at the most useful content on a website: a short Markdown overview with curated links, so a model does not have to scrape pages built for people.

One is a contract that software acts on. The other is a reading list for a model.

Status as of September 26, 2026. The Agent Card is part of the A2A specification, a Linux Foundation project at protocol version 1.0. llms.txt is a community proposal. Jeremy Howard published it at llmstxt.org on September 3, 2024, and the site now presents a revised v2, dated August 2026 on its changes page. No standards body has adopted it.

What llms.txt is for

The proposal starts from a practical problem. Web pages wrap their content in navigation, scripts and layout, and a whole site will not fit in a model’s context. A small, curated Markdown file at a predictable location lets an agent that is helping a user find the right material quickly. The proposal expects it to be used mostly at inference time, when an agent is looking something up.

The format, as v2 defines it:

• The file is named llms.txt and sits at /llms.txt or any subpath, such as /docs/llms.txt. It covers the pages under its path, and where several apply, the most specific wins.
• An H1 with the project or site name is the only required section.
• A blockquote gives a short summary, followed by optional detail in paragraphs or lists.
• H2 sections hold “file lists”: Markdown links with optional notes.
• A section titled “Optional” marks links an agent can skip when context is short.

v2 also proposes clean Markdown copies of pages, at the page URL with .md appended or with the extension replaced, and standard link relations (rel="alternate" with type="text/markdown", and rel="describedby" for the covering llms.txt) so agents can find both. The proposal explains why it did not use a /.well-known/ path: well-known URIs exist only at the origin root, and many authors control only a path on a shared host.

An illustrative file:

# Example Freight

> Example Freight quotes and books less-than-truckload shipments between Canada and the US.

## Docs

- [Shipping guide](https://example.com/docs/shipping.md): Pallet sizes, lanes and pickup windows
- [Agent Card](https://example.com/.well-known/agent-card.json): How other agents connect to our quoting agent

## Optional

- [Company history](https://example.com/about.md)

What an Agent Card is for

Every A2A server must publish an Agent Card. Clients usually fetch it from https://{domain}/.well-known/agent-card.json, a well-known URI in the sense of RFC 8615, before they send a first request. From the card, a client learns:

• where to connect, in supportedInterfaces (URL, protocol binding and protocol version);
• which optional features exist, in capabilities (streaming, push notifications, an extended card, extensions);
• what the agent can help with, in skills;
• how to authenticate, in securitySchemes and securityRequirements.

The card is structured data with required fields, defined by the AgentCard message in a2a.proto. Servers should send caching headers for it, and it can carry JWS signatures so clients can detect tampering. Agent Cards explained covers every field.

Side by side

	llms.txt	Agent Card
Purpose	Point language models to a site’s most useful content	Tell client agents how to connect to and use an A2A agent
Layer	Content guidance for model context	Discovery metadata for a protocol
Who reads it	A model or agent reading on a user’s behalf; people too	A2A client software and its developers; registries
Format	Markdown with a defined section order	JSON with a schema from a2a.proto
Location	/llms.txt or any subpath; link relations for discovery	/.well-known/agent-card.json; registries; direct configuration
Auth	None; public by design	Declares the authentication the agent requires; can be signed with JWS
State	None	None; the agent it describes manages tasks
What happens next	The model reads linked pages	The client sends A2A requests, such as SendMessage
Governance and status	Community proposal (llmstxt.org); v2, August 2026	Part of the A2A specification (Linux Foundation); version 1.0

Scope is the other structural difference. A well-known URI exists only at the root of an origin, so an Agent Card at /.well-known/agent-card.json speaks for one agent at that host. The llms.txt proposal chose path scoping on purpose: /docs/llms.txt covers everything under /docs/, so a project that controls only a directory on a shared host can still publish one. If one domain runs several A2A agents, each needs its own card, whether served from separate hosts, listed in a registry, or configured directly by clients.

When to use each

Publish llms.txt when you want models to answer questions about your product or documentation accurately. It costs little to produce and can be generated from your site’s content. It gives no one a way to act on your behalf.

Publish an Agent Card when you run an A2A agent that outside agents should be able to reach. Without it, A2A clients cannot find your endpoint or learn how to authenticate.

Using both

They answer different visitors, so a site with an agent often wants both. This site publishes both: emissar.ai/llms.txt is generated at build time from the published guides, comparisons and glossary, and it links to the Agent Card at /.well-known/agent-card.json for Emissar’s public A2A agent.

Practical rules:

• Link from llms.txt to the card and its documentation. A model reading your llms.txt then learns that an agent exists and where its card is.
• Keep facts consistent. Names, descriptions and status claims in llms.txt should match the card and the site. A model will repeat whatever the file says.
• Do not put connection details only in llms.txt. A2A clients read the card and ignore prose elsewhere. Endpoints, bindings and security requirements belong in the card.
• Neither file is a place for secrets. Both are public. Anything sensitive belongs behind authentication, for example in an extended Agent Card served only to authenticated clients.

Common misconceptions

“llms.txt is a standard like robots.txt.” It is a proposal. It borrows the idea of a fixed filename from /robots.txt and /sitemap.xml, but it has not been standardized, and the proposal itself says it serves a different purpose from robots.txt.

“llms.txt controls what AI systems may do with my content.” It is guidance for reading. It grants and restricts nothing.

“An Agent Card is the agent version of llms.txt.” A card is a structured contract that software acts on. It has required fields, defined semantics, and an optional signature. llms.txt is prose and links for a model to read.

“If I publish an Agent Card, models will know about my agent.” Only A2A clients look for the card. If you want a general-purpose model or search agent to learn that your agent exists, say so in your documentation, and in llms.txt if you publish one.