Watching an AI agent work an unfamiliar API can be frustrating. It may read the OpenAPI spec just fine and form perfectly valid requests, and then wander into the same traps an impatient engineer might. Maybe it creates a resource, checks the list milliseconds later, doesn't see it, and creates it again. Maybe it hits a 429 and decides the answer is to call harder. It has no real way of knowing that /orders/place is a proposal, not a charge.
To be fair, none of that knowledge lives in the spec, and it was never supposed to. OpenAPI describes what an API is. How it behaves in production has almost no structured home there, only whatever prose someone tucked into a description field. That behavioral knowledge tends to live where it has always lived: in runbooks, in incident retros, in a Slack or Teams thread, and in the heads of the engineers who learned it the hard way.
Humans pick that knowledge up over days or weeks of onboarding. Agents mostly don't get it at all, so they end up re-deriving it the expensive way by making the mistakes themselves, at machine speed, against production endpoints.
What is api-agent.yaml? A field guide for AI agents using your API
api-agent.yaml, which I am calling The API Field Guide, is my proposal for where that knowledge should live. This is a YAML file the API owner publishes at /.well-known/api-agent.yaml, next to the OpenAPI spec. Think of it as the Ocean's Eleven briefing for your agent. Before anyone touched the vault, they knew the layout, the guards, the alarms, and the way out.
The file answers four questions, in four layers:
- What to know. The conceptual model, the insights no schema captures ("an order is not live until confirmed"), the scope gotchas a flat OAuth scope list doesn't explain, how long writes take to become visible in reads, how to paginate safely.
- What to do. Per-endpoint preconditions, idempotency requirements, side effects, reversibility and the exact call that compensates, latency expectations, and human-approval gates such as "orders above $50 stop and wait for a person."
- What changed. Structured deprecations, migration notes for breaking changes, and, when an API dies, a pointer to its successor's contract, published at a git-committed address that outlives the endpoint itself.
- What to say. A feedback channel, modeled on security.txt, where agents report undocumented errors and contract mismatches back to the owner.
The file usurps nothing. It points at OpenAPI, Arazzo, AsyncAPI, and auth.md through a refs block and adds only the layer none of them cover.
The feedback loop that makes AI agents better at using APIs
Each field is useful on its own, but the thing I keep coming back to is the closed loop they form.
An agent runs into behavior the contract didn't predict. It re-fetches the field guide and compares the version against the one in memory from the last visit. If the version changed, something about the API shifted, and the agent migrates using the breaking-change notes, or, if the API has reached end of life, the successor contract. If the version didn't change, the contract itself is wrong, and the agent files a structured stale_contract report. The owner folds those reports back into the file and republishes. Every agent that arrives afterward gets the corrected contract.
One agent's failure becomes every agent's knowledge. Agents stop being passive consumers of stale or outdated documentation and become the sensing layer that keeps the contract true.
Won't another file just burn more of the agent's context window?
Users of agents are trying to trim what they feed into context, not add to it, so a fair pushback here is: why ask agents to read one more file? And I think the math works out in a couple ways.
The file is small. A typical field guide should run you about 300 to 1,500 tokens, and every section is optional. I am going to estimate most people generate a YAML file about 25-50% filled out. Agents are told to read selectively and load only the sections a task requires, so this should be token efficient. Meanwhile, a single failed API call-and-retry cycle, plus whatever it takes to reason through the failure, tends to cost an agent more tokens than reading the whole file up front.
And the real comparison isn't field guide versus nothing. It's field guide versus what agents do today: scraping docs pages, guessing at retry policy, and learning by experiment. Against that baseline, this is the more efficient path.
Built skeptical: prompt injection and the trust model
A file that autonomous agents read and act on is an instruction channel, and instruction channels are attack surfaces. So the spec ships a trust model alongside the fields. The file is advisory, API-authored, and untrusted by default. Descriptive fields, such as error meanings and parameter gotchas, are safe to reason over because an agent can check them against observed behavior. Imperative fields, such as a test command to run or a successor contract to adopt, require human approval or out-of-band verification. Free text is treated as a prompt-injection surface, and field-guide text never outranks the human operating the agent.
This does NOT absolve engineers from safeguards on their APIs. Every limit that matters must be enforced server-side or at a gateway, as well. Declared limits protect cooperative agents from mistakes. Servers protect the API from everyone else.
Where it fits alongside MCP, Arazzo, agents.json, and AP2
This is deliberately one layer in a larger stack. MCP connects agents to tools, and a field guide is the enrichment source that makes a generated MCP server actually good. Arazzo and agents.json describe how to run a sequence of calls, while the field guide describes when to hold off and what to do when a call fails. AP2 proves that a human authorized a payment, and the field guide declares which operations need that proof. Your AI agent connected to Postman, or your in-house tooling can generate most of the file from the code, docs, collections, test runs, and monitors you already maintain.
The api-agent.yaml spec is a draft, and I want the argument
v0.3 is open for public comment. Read the full spec, a JSON Schema, three worked examples, and twelve open questions where I honestly don't know the right answer yet. A validator, a generator, and a reference implementation an agent can be pointed at are next on my list to build alongside this.
If you own an API, I'd love to know what you think of this! If you build and use agents and or AI tooling, tell me what's missing or needs adjustment. Issues and pull requests are welcome: github.com/tristandenyer/api-field-guide-spec.
