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

本文暂无中文版，以下为英文原文。

Editor's note: this post was written in April 2026 and describes our site at that time. The MCP section has been updated since: AIsa now runs an MCP server.

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 an internal project. 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. When we wrote this, ours was permissive and advertised the rest:

User-agent: *
Allow: /
Sitemap: https://aisa.one/sitemap.xml

# LLM-readable documentation
# https://aisa.one/llms.txt
# https://aisa.one/llms-full.txt

/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. 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. When we wrote this, we set priority and changefreq honestly: the homepage at 1.0 and weekly, legal pages at 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. Our published card carries its own implementation version, separate from the AIsa product release, and we update it only when that machine-readable contract changes. Think of it as a business card and a menu, stapled together, both machine-readable.

/.well-known/mcp.json describes an MCP server. MCP, the Model Context Protocol, is how desktop agents like Claude Code and Cursor pick up new tools. When we wrote this, it was the file we were still catching up on. AIsa now runs an MCP server at https://mcp.aisa.one/mcp and publishes its manifest at this path, and the Connect page has the setup steps for each client. If you're building alongside us: don't leave agents to guess whether you have an MCP surface. Say so explicitly.

OpenAPI specs: when we wrote this, we published one per skill, and a root openapi.json that references them all was the next step. 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, when we wrote this, the path was:

1. robots.txt advertises what's available
2. llms.txt indexes skills and OpenAPI specs
3. /.well-known/agent-card.json handles capability negotiation
4. sitemap.xml gives the full URL map with priorities
5. Any skill's OpenAPI spec gives 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; "Browse the 5,000+ APIs in the catalog" 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. When we wrote this, it was our own largest open gap. Our site now carries Organization, WebSite, FAQPage and BlogPosting markup.

Publish a changelog feed. Returning agents can 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.

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. On AIsa, an unattended agent can pay per call with x402, with no account to open; the Pricing page has the details.

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 and well specified.

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). A2A is the lighter of the two to publish. If your primary users are desktop agents and chat clients, start with MCP: it's how agents connect to AIsa today.

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. Document your A2A and MCP spec versions so agents can capability-negotiate.
11. If you deploy agents, document their capabilities via a Foundry-style deployment surface.

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, /.well-known/agent-card.json and /.well-known/mcp.json.