The Agent-Readable Web: What We've Learned Building AIsa

A few weeks ago I watched an autonomous agent try to use our own website.

Not our API — our website. It arrived cold, looking for the information a human visitor would have absorbed in half a glance: what we do, what we expose, how to authenticate, how to pay. It failed twice before I realized the failures were my fault. Our homepage was built for humans who already knew why they were there. The agent didn't.

That afternoon became the internal project that shipped as AIsa 1.4.0. Along the way we reread every spec, rebuilt our discovery surface from scratch, and arrived at a working theory of what "agent-friendly" actually means in 2026. This post is that theory, written for teams who are starting to notice the same thing we did: a non-trivial fraction of your traffic now has no eyes.

The four questions an agent asks

Humans arrive at your site with context. They remembered your brand, clicked an ad, saw a friend's tweet. Agents arrive cold, and they have to answer four questions in under a second:

1. What does this site do?
2. What can I do here programmatically?
3. How do I authenticate and pay?
4. Where do I get details if I need them?

Every practice in this post is ultimately a way to answer one of those questions without forcing the agent to parse a design-driven homepage. That's the whole game.

The discovery chain

We ended up thinking about agent-friendliness as a chain of hops. Each file should exist, and each should point to the next. If any link is missing, the agent either guesses or gives up.

/robots.txt is still the first file most crawlers request. We keep ours permissive and use it to advertise the rest:

/llms.txt is the llmstxt.org standard for giving language models a curated, markdown index of your most important content. We treat it as a press kit for agents: short summary, links to key docs, section headers an LLM can follow. Our current file is about 650 lines. We also publish /llms-full.txt — the expanded corpus for agents that want the full picture without crawling a hundred pages of navigation chrome.

/sitemap.xml still matters. We set priority and changefreq honestly — the homepage is 1.0 and weekly, individual model pages are 0.7 and monthly, legal pages are 0.3 and yearly. Agents use these to spend their crawl budget.

/.well-known/agent-card.json is the A2A standard, and the single file we've gotten the most feedback on. It's a versioned JSON document that tells another agent our name, API base, auth scheme, supported capabilities (streaming, push, state history), and the full list of skills we expose. Ours is at version 1.4.0 with a dated changelog going back to 1.0.0. Think of it as a business card and a menu, stapled together, both machine-readable.

/.well-known/mcp.json is where we're still catching up. MCP — the Model Context Protocol — has become the dominant way desktop agents like Claude Code and Cursor pick up new tools, and exposing a formal MCP manifest at the well-known path is the next step on our roadmap. If you're building alongside us: don't leave agents to guess whether you have an MCP surface. Say so explicitly.

OpenAPI specs — we publish one per skill (24 of them at the moment), and we're adding a root openapi.json that references them all. Don't make an agent assemble your API surface by crawling pages; hand it over.

The five-hop test

We use an internal benchmark we call the five-hop test: can an agent arriving at / with no prior context pull everything it needs to transact in five sequential requests?

On AIsa today the path is:

1. robots.txt — advertises what's available
2. llms.txt — indexes skills and OpenAPI specs
3. /.well-known/agent-card.json — capability negotiation
4. sitemap.xml — full URL map with priorities
5. Any skill's OpenAPI spec — full endpoint detail

Five hops, no JavaScript, no guessing. That's the bar we try to hold ourselves to, and I'd encourage any team reading this to run the same test. If it takes more than five hops, you've hidden something important behind rendering or navigation.

What happens after discovery

Discovery gets agents to your pages. Rendering decides whether they can actually read them. A few lessons we learned the expensive way:

Server-render your docs. A React shell that hydrates after three seconds is an empty page to most crawlers. We migrated our documentation off a client-side SPA early, and the retrieval quality improvement was immediate and obvious.

Use semantic HTML. <article>, <section>, <h1> through <h3>, and descriptive anchor text all do real work. "Click here" is useless; "Explore the 54 supported models" is a signal. This is free and we keep finding places we've skipped it.

Add JSON-LD. Even in 2026, schema.org markup in a <script type="application/ld+json"> block is one of the highest-leverage things you can ship. Organization, SoftwareApplication, APIReference, Product, FAQPage — pick the ones that fit and embed them in your <head>. Retrieval-augmented agents that don't speak A2A still read JSON-LD natively. This is our own largest open gap, and we're closing it next quarter.

Publish a changelog feed. We added an Atom changelog feed in 1.4.0. Returning agents can now diff against their last-seen version instead of re-crawling — versioned capability negotiation with no wasted bytes.

Agent commerce, briefly

If your product is something an agent might pay for on its user's behalf, the credit-card-in-a-human's-wallet model breaks. We've been betting on two protocols:

HTTP 402 / x402 — the revived "Payment Required" status code, now usable to signal paywalls in a way agents can resolve programmatically with stablecoin or micropayment rails.

Machine Payment Protocol (MPP) — an open standard for agents to negotiate and settle payments without a human approval loop per transaction.

Both are live in private beta on AIsa's Machine-to-Machine layer today and will be made publicly available soon. You don't need them to be agent-friendly, but if your unit economics depend on agents buying things autonomously, they matter more than almost anything else on this list.

The two protocols worth knowing

A2A (agent-to-agent) is how agents describe themselves to other agents. The agent-card.json file is the discovery artifact. It's light, well-specified, and almost every serious agent framework speaks it now.

MCP (Model Context Protocol) is how agents consume external tools. An MCP server exposes tools, resources, and prompts an agent can wire directly into its own toolbox.

A site that supports both is giving agents two ways in: "tell me what you can do" (A2A) and "let me plug your tools into my context" (MCP). We recommend starting with A2A — it's lighter — and adding MCP when your primary users are desktop agents.

The checklist we use internally

Work through these in order. Each one is cheap. Most teams can ship the first five in an afternoon.

1. Publish /robots.txt with sitemap, llms.txt, and llms-full.txt references.
2. Publish /llms.txt and /llms-full.txt following the llmstxt.org spec.
3. Publish /sitemap.xml with honest priorities and changefreq values.
4. Publish /.well-known/agent-card.json with version, API base, auth scheme, and capability flags.
5. If you have an MCP server, publish /.well-known/mcp.json.
6. Expose a root /openapi.json that references all per-skill specs.
7. Server-render your docs site.
8. Add JSON-LD (Organization, SoftwareApplication, APIReference) to every docs page's <head>.
9. Publish a versioned Atom changelog feed.
10. If you deploy agents, document their capabilities via a Foundry-style deployment surface.
11. Document your A2A and MCP spec versions so agents can capability-negotiate.

Why we're writing this

AIsa exists because we think the next decade of the web will be shaped by agents the same way the last two were shaped by mobile. If we're right, the sites that make themselves legible to agents now will compound, and the ones that don't will quietly fall out of the recommendation graph.

The good news: agent-friendliness and human-friendliness mostly agree. Clean semantics, honest metadata, server-rendered content, documented APIs — these help every reader. The work isn't building a second site for machines. It's finishing the job of making the first one legible.

If you're working on this at your own company and want to compare notes, we're easy to reach. The spec ecosystem is young enough that what any one team learns tends to be useful to everyone.

Further reading: llmstxt.org, the A2A specification, the Model Context Protocol, and the x402 / HTTP 402 revival. Our own discovery surface is live at /robots.txt, /llms.txt, and /.well-known/agent-card.json.