API strategy
Agent infrastructure
OpenAPI spec drift breaks agents before it breaks humans. The three kinds of drift, how to detect them in CI and runtime, and the governance model that holds.
OpenAPI spec drift is the gap between what your specification says and what your API actually does. It's the quiet failure mode behind broken SDKs, wrong client expectations, and — increasingly — agents that call tools with the wrong shape and get punished for it. The specification says one thing, the runtime returns another, and everything downstream trusts the wrong story.
Our view: drift isn't a documentation problem. It's a contract governance problem, and it becomes an operational problem the moment agents are the consumer. Humans read a spec, notice something looks off, and adjust. Agents don't. They serialise the spec into a tool schema, invoke it, and fail — usually silently until a customer complains.
This piece covers what OpenAPI drift actually is (three kinds, not one), why the agent era makes it more expensive, how to detect it in CI and at runtime, the governance model that keeps specs honest, and what agent-era API teams need to change about their contract discipline.
"Spec drift" gets used loosely. It's worth separating the three variants because they fail in different places and need different tooling.
Design-time drift is the divergence between two versions of the spec itself — v2.1 vs v2.2. This is the one CI usually catches, because tools like oasdiff can compare two OpenAPI documents and flag breaking changes. If you're versioning your spec in Git and running diff checks on pull requests, you're covering this case.
Implementation drift is the gap between the spec and the running service. The spec says status is one of active|paused|archived, the handler returns disabled, and nothing in the pipeline notices. This happens most often when the spec is hand-written alongside code that evolves independently, or when a code-generated spec loses fidelity because someone patched the handler without updating the annotation.
Consumer drift is the gap between what the spec advertises and what consumers actually depend on. A field the spec calls optional has been required-in-practice for three years because every client assumes it's present. Remove it "safely" per the spec and half your integrations break. This is the drift that shows up in postmortems, not linters.
Most teams treat drift as a linting problem and stop at the first variant. The second and third are where production breaks. And they're where agents get hit hardest, because agents infer behaviour from the schema alone — they don't have the folklore your longest-serving integration partner does.
APIs have always drifted. Docs go stale, SDKs lag, and integration partners work around gaps. What changes with agents is the failure mode.
A human developer reading a broken spec typically figures it out. They hit a 400, read the error, check the actual response shape, and correct their client. It's annoying, but it's self-healing. An agent doesn't self-heal in the same way. The foundation model reads the tool schema at plan time, decides which tool to call, constructs arguments, invokes, and either succeeds or hits an error path that the tool schema didn't warn it about. If the schema said the response would have customer_id and it actually has customerId, the downstream tool call breaks in a way the model has no context to fix.
Worse, drift often shows up as behavioural rather than structural. The endpoint accepts the request, returns 200, and quietly does something different than the spec implied. A field the agent thought was a filter is actually a sort key. A pagination parameter that the spec called page has silently become cursor on some endpoints. There's no error to catch — just wrong outcomes that surface as bad tool calls in an eval two weeks later.
This is one reason OpenAPI specifications need different treatment when SDK generators and agents are the consumer. The tolerance for drift is lower because the consumer is less forgiving. Every unmarked enum value, every stale example, every optional-but-actually-required field becomes a production incident waiting for the right prompt to trigger it.
The integration engineering tax on agent projects — the maintenance cost most teams don't budget for — is largely tax on this. Drift you don't detect becomes drift you pay for at runtime.
Drift detection is a two-layer problem. CI catches design-time drift. Runtime instrumentation catches implementation drift. Neither on its own is enough.
The baseline is straightforward. Store the OpenAPI document in the repo. On every pull request, run a diff against the last released version and classify changes as breaking, non-breaking, or unclassified. Tools that do this today:
Run oasdiff on every PR. Fail the build on unclassified changes — those are the ones humans need to look at, not just breaking ones. A field renamed from customer_id to customerId might not be flagged as breaking by every tool, but it's absolutely a breaking change for anyone consuming the API. Configure the rule set to your reality; the defaults are a starting point, not the answer.
CI diffing only covers what the spec says. It doesn't cover what the service actually does. For that you need runtime instrumentation:
The pattern to reach for: CI catches spec-to-spec drift, staging catches spec-to-service drift, and production traffic sampling catches drift that only shows up under real load or real payload shapes.
Every response your service emits should either match a schema in the spec or trigger an alert. That's the whole rule. If you can't get to that state, you're not detecting drift — you're hoping it doesn't happen. This is closer in spirit to monitoring third-party API integrations before the outage than to standard uptime checks.
There are two philosophies for keeping specs honest, and picking wrong is how most drift starts.
The OpenAPI document is the source of truth. Handlers, validators, and clients are generated from it or checked against it. Change the spec, regenerate, ship. This is what most "API design" advocacy assumes, and it's the model design platforms like Stoplight are built around; gateways like Kong support the model by ingesting OpenAPI (for example via deck's openapi2kong), though the relationship there is import-based rather than design-time.
Strengths: the spec cannot lie by construction. If a handler doesn't match the schema, the code doesn't compile or the tests fail before merge.
Weaknesses: it's expensive to retrofit. Most established SaaS teams don't have a spec-first codebase; they have a codebase that grew organically and had a spec bolted on later. Rewriting handlers to be spec-generated is a multi-quarter project, and the value curve doesn't always justify it.
The code is the source of truth. Annotations, decorators, or type inference generate the OpenAPI document. Frameworks like FastAPI, Fastify, and NestJS make this reasonably clean.
Strengths: fits how most teams already work. No rewrite required. The spec is a byproduct of the code, so it's always at least as fresh as the last deploy.
Weaknesses: the spec is only as good as the annotations. A field returned by the handler but not present in the response model? Silently omitted from the spec. An enum expanded in code but not in the type definition? Drift, immediately, and no tool will catch it unless you also do runtime validation.
Pick the model that fits your codebase and add the layer the other model gives you for free. Spec-first teams need runtime contract tests to catch handler drift the generator can't. Code-first teams need traffic-based validation to catch the annotation gaps the generator misses. This is the same principle as the API-first vs code-first debate — methodology alone doesn't solve the reachability problem, and it doesn't solve drift either. Discipline does.
A governance model that holds under agent traffic has three pieces: a source of truth (spec or code, pick one), automated diff on every change, and runtime validation on every deploy. Miss any of the three and you're back to hoping.
Drift is a solved problem in principle and an unsolved problem in practice, and the reason is usually the same: the spec was designed for humans who could work around its gaps. Agents can't.
Pontil is a Tools-as-a-Service platform — we make SaaS products accessible to AI agents by generating and running the tools agents invoke. Because we generate connectors from the codebase, not from a hand-maintained spec, the tool definitions agents call are grounded in what the service actually does. When the service changes, the tools update alongside it as part of the same pipeline, so implementation drift doesn't have a place to hide between deploys.
This is why we treat maintenance as a first-class concern, not a documentation afterthought. Agents will punish drift you don't catch. The economics of that punishment — cancelled projects, stalled rollouts, agents that pass eval and fail in production — are what most teams underestimate when they scope agent work.
The honest answer is: stricter than it used to be, and closer to the runtime than most teams currently keep it. When human developers were the only consumers, the spec could afford to be a lagging indicator — a document that got updated in the release notes cycle, verified by hand, and trusted because the API team said so. That model works when your readers can debug their way around gaps.
Agents can't debug their way around gaps. They serialise the spec into a tool schema, plan on the schema, and act on the plan. Drift becomes a production incident before it becomes a documentation ticket. Every unmarked enum, every stale example, every field that's optional-in-the-spec-but-required-in-reality is a landmine waiting for the right tool call.
The teams that will hold up under agent traffic are the ones treating their specs the way they already treat their tests: run on every commit, validated against reality on every deploy, and considered broken until proven otherwise. That's a governance shift, not a tooling shift — the tools already exist. What changes is whether contract discipline is a nice-to-have or a production requirement. In 2026, for anyone building agents on their own platform, it's the second one.
Stay up to date on the ever changing agentic landscape.
GET STARTED
Start with a 30-minute discovery call
contactus@pontil.com
