What is an agent-readable developer surface
An agent-readable surface is documentation and interfaces structured for how models consume them rather than how humans read them. Here is what changes and why it is engineering rather than writing.
The short answer
An agent-readable developer surface is documentation and interfaces built for how a model consumes them rather than how a human reads them. In practice that means four things. Typed interfaces over the real API, stable naming, exactly one canonical statement of each fact, and examples that actually run and are tested in CI.
The reason to care is that a growing share of integration questions about any protocol now get answered by a model before a developer opens the docs at all. The developer asks Claude or Cursor, gets an answer, and writes code against it. If that answer is wrong, the failure lands on your protocol.
Why prose fails a model in a way it does not fail a human
A human reading documentation tolerates a lot. Contradictions across two pages get resolved by picking the newer one. A stale example gets fixed by intuition. A missing type gets inferred from context. None of that recovery happens with a model. It reads what is there, weights it by how often the pattern appears, and produces the most plausible continuation.
So the same page that reads fine to a person can be actively harmful to a model. Two pages stating the same parameter differently teach it that both are valid. A tutorial written against a deprecated interface competes with the current one. Prose descriptions of a response shape, where a schema should be, get approximated into a shape that never existed.
The failure mode is quiet, which is what makes it expensive. Nobody files a bug that says the model hallucinated. They file a bug against your API, or they give up and pick a different protocol.
What actually changes
Typed interfaces first. A schema over the RPC surface, the contracts, and the SDK gives a model something to call rather than something to guess at. Tool interfaces exposed this way are the difference between an agent invoking your real API and an agent inventing a plausible one.
One canonical page per fact. Duplication is the enemy. If a parameter is documented in three places, at least two of them will drift, and the model has no way to know which survived. Consolidating to one authoritative statement and linking to it is a structural fix, not a stylistic one.
Runnable, tested examples. An example that is wired into CI breaks loudly the release it stops being true. An example in a markdown fence drifts silently for months, and every model that reads it inherits the drift.
An llms.txt at the root. A plain-language summary of what the project is and where the authoritative pages live, so a crawler does not have to reverse-engineer your information architecture from navigation markup.
How you know it worked
The part most teams skip is measurement, and without it this is all just a preference. Write a question set with the people who answer support. The questions developers actually ask, the integrations that actually go wrong. Then ask the models those questions against the surface and count the correct answers.
That number is the deliverable. It gives you a baseline before the work, a result after, and a regression test on every release. Correctness becomes a tested property instead of an assumption, which is the same standard the rest of your stack is already held to.
Why this is engineering
Everything above requires knowing what is true, which means reading the client source, and shipping into the repo, which means CI and review. It is not a writing exercise with a technical topic. The people who can do it are the people who can already read the implementation, which is why we treat the surface as part of the protocol rather than as marketing downstream of it.
Common questions
- What is an agent-readable developer surface?
- Documentation and interfaces structured for how models consume them. Typed schemas over the real API, stable naming, one canonical statement of each fact, and runnable examples tested in CI. A model reading an agent-readable surface answers correctly about the protocol instead of inventing an API.
- How is it different from good documentation?
- Good documentation optimises for a human who can resolve contradictions and infer missing detail. A model cannot do either. Agent-readable work removes duplication, replaces prose descriptions of shapes with schemas, and tests examples in CI, because a model inherits every inconsistency it reads.
- Do I need this if my docs are already good?
- Test it before deciding. Ask the models the ten questions your support channel gets most and count the correct answers. That number tells you whether your surface is agent-readable, and it is usually lower than teams expect.
- Is this the same as writing an llms.txt?
- No. An llms.txt is one useful piece, a plain summary at a known location. The structural work is the typed interfaces, the deduplication, and the tested examples. A summary pointing at documentation that contradicts itself does not help.
Working on something like this?
This is the layer we work in. If you have a hard problem underneath a product, tell us the hard part.