APIs Designed for Humans Break Under Agents

Most APIs were designed for a client that stops to think.

Imagine a scheduling assistant moving a customer meeting from Tuesday to Thursday. It must update the calendar event, replace the video link, check the attendee's travel policy, and notify six people. The first calendar request succeeds, but the response disappears during a network timeout.

A human developer sees uncertainty. They inspect the calendar, notice the meeting has already moved, and continue from the new state. They may read a warning in the documentation, search an issue, or ask support whether the endpoint is safe to retry.

An autonomous caller sees an incomplete step in a plan.

It retries. The endpoint creates a second invitation. The conferencing tool creates another room. A downstream notification says the meeting moved twice. Another agent, watching for calendar changes, starts rearranging travel around the duplicate.

Nothing in that sequence requires a spectacular model failure. Every call can be syntactically valid. Every service can behave as documented. The failure comes from an interface that left a critical question to human judgment: did this intent already take effect?

For decades, the person integrating an API supplied context, caution, and recovery logic that the contract did not express. Autonomous software removes that hidden subsidy. It can generate valid parameters, but it also repeats, composes, and acts before a person notices that something looks wrong.

This is the shift: an API can be excellent for developers and still be unsafe for agents. APIs designed around human interpretation become unsafe under autonomous repetition, composition, and delegated authority unless operational meaning becomes executable.

Key Ideas

• Most APIs depend on an interpretation subsidy: the undocumented judgment a human developer contributes while integrating them.
• Autonomous callers magnify small ambiguities through speed, call volume, composition depth, and delegated authority.
• Schemas make calls well formed. Agent-native contracts must also make effects, preconditions, recovery, cost, and authority machine-readable.
• REST remains a strong foundation. The assumptions surrounding its use need to evolve.

The best API documentation still contains a hidden human

Scripts, services, controllers, and integration platforms have consumed APIs for decades. The hidden assumption was subtler: a human designed and supervised the integration. That person read prose before writing the loop, noticed domain-specific meanings, learned which updates propagated slowly, and knew that deleting a Git branch and deleting a cloud account were not comparable just because both used DELETE.

This missing semantic work is an interpretation subsidy: the judgment a person quietly contributes to make an interface safe enough to use.

SDKs, examples, and support reduce that work. The subsidy remains whenever a client must infer business intent from naming, prose, convention, or experience. An autonomous caller may select a tool at runtime and combine it with tools its author never anticipated.

Autonomy turns documentation debt into runtime behavior.

The difference is not that agents are incapable of inference. They infer constantly. The difference is that an API contract should not require probabilistic inference to determine whether an action is authorized, reversible, complete, or safe to repeat.

Human Developer Experience versus Agent Experience

Interface concern	Human developer experience	Agent experience	What changes because the caller is autonomous
Discovery	Searches docs, reads guides, compares examples	Selects from schemas, tool descriptions, registries, or runtime capabilities	Capabilities, constraints, and effect classes must be discoverable without prose archaeology
Ambiguity	Pauses, experiments, asks a teammate, contacts support	Chooses a plausible interpretation and continues	Ambiguous fields need enumerated meanings, preconditions, and explicit unknown states
Validation	Recognizes suspicious output even when it is schema-valid	Treats valid structure as evidence that the call is usable	Validation must cover domain invariants and policy, not syntax alone
Errors	Reads a message and invents a recovery plan	Maps machine-readable state into retry, repair, escalate, or stop	Errors must carry recovery class, retry timing, failed scope, and stable identifiers
Retries	Usually writes bounded retry logic after studying semantics	May retry automatically as part of a general agent loop	Mutations need intent identity, deduplication, and explicit retry safety
Pagination	Notices duplicates, missing rows, or an endless cursor loop	Follows continuation tokens mechanically	Pages need snapshot semantics, termination state, stable ordering, and budget visibility
Rate limits	Adjusts a client after observing usage	Can fan out across tools, users, or subagents before throttling is visible	Limits need machine-readable reset, concurrency, cost, and tenant scope
Partial failure	Inspects which records changed	May classify the whole step as failed and replay it	Batch and composed operations need per-item receipts and reconciliation instructions
Authority	Understands the business context behind a credential	Optimizes within whatever permissions it receives	Permissions need least privilege, purpose boundaries, and high-risk confirmation gates
Long-running work	Watches a dashboard or waits for support	Needs to resume after restarts and distinguish pending from stuck	Operations need durable handles, progress, cancellation, and terminal outcomes
Deprecation	Reads notices and schedules migration	May keep selecting an old tool while it remains callable	Deprecation must be discoverable, dated, and paired with a machine-readable successor
Recovery	Uses judgment across several systems	Needs an explicit next safe action after ambiguous state	APIs must expose compensation, reconciliation, escalation, and stop conditions

Developer experience asks, “Can a person integrate this correctly?” Agent experience asks a harder question: Can software determine the next safe action from the contract and the observed state?

That changes the role of the API description.

A conversation can repair ambiguity. A contract has to prevent it

Human-facing API design often behaves like a conversation. Documentation explains the happy path. Examples supply context. An error message offers a hint. If the interaction remains unclear, the developer asks another person.

That model works because conversation has an escape hatch: the participants can renegotiate meaning. An autonomous execution path cannot depend on that escape hatch appearing at the right moment. Once a tool call sits inside a plan, the interface is part of an executable control system.

Consider an agent reserving inventory across three warehouses. The endpoint returns 409 conflict. A person may infer that stock changed after the quote. An agent needs the failed precondition, current inventory version, created reservations, expirations, and safe next operation.

This is the difference between the API as a conversation and the API as an executable contract.

A conversational interface can say, “Something changed. Try again.” An executable contract says, “The allocation plan was evaluated against inventory version 7812. Locations A and B were not modified. A temporary hold exists at location C until 14:05 UTC. Recompute from version 7821 using reconciliation token R, or release the hold.”

The second response converts recovery from interpretation into a state transition.

The most dangerous API response is not an error. It is an ambiguous success.

This is why structured errors matter. RFC 9457 gives HTTP APIs a standard problem-details shape, while gRPC status guidance distinguishes cases such as UNAVAILABLE, ABORTED, and FAILED_PRECONDITION by the level at which recovery should occur. The useful principle is not the choice of status vocabulary. It is that failure classification should lead to executable recovery.

Schemas solve syntax, not intent

OpenAPI 3.2 describes HTTP operations, schemas, security, and links. AsyncAPI 3.1 covers message-driven systems. GraphQL provides introspection and partial responses. gRPC combines service definitions with status semantics.

Function calling makes the relationship immediate. Google's Gemini documentation and the OpenAI API reference define tools with names, descriptions, and schemas. MCP adds discovery, invocation, lifecycle, and capability negotiation. Its November 2025 specification supports structured results and execution metadata.

Yet a perfectly valid schema can still describe a dangerous operation badly.

Consider cancel_order(order_id, reason). The input types may be exact. The schema still does not answer whether cancellation is reversible, whether fulfillment has started, whether duplicate calls are safe, or whether a human must approve orders above a threshold.

Anthropic's tool guidance makes this boundary explicit: names, descriptions, inputs, outputs, and returned context materially affect agent performance. MCP still warns that tool annotations are untrusted unless they come from a trusted server. Description is necessary. Trust and policy do not emerge from it.

Plain-language decode: A schema says what shape a call must have. A semantic contract says what the call means in the current state.

An agent evaluates an API through four questions. What can I do? Am I allowed to do it here? What state change should I expect? What should I do if the result is uncertain? Most API descriptions answer the first and leave the rest in prose.

So far, the problem is missing meaning. The next layer is what happens when execution amplifies that gap.

Autonomy changes the geometry of failure

Distributed systems already fail in ambiguous ways. A request can reach the server, commit a side effect, and lose the response. A read can observe stale state. A batch can partly succeed. A transaction can abort after another service has completed work. Autonomous callers do not invent these problems. They change their geometry.

Autonomy multiplies the consequences of ambiguity through four factors.

Factor	What autonomy changes
Loop speed	The caller can observe and act again before a person would finish reading the first response
Call volume	One interpretation can repeat across records, tenants, or environments
Composition depth	A local error becomes input to later tools and agents
Delegated authority	A guess can become a payment, deployment, message, or physical movement

The Knight Capital incident is a deterministic-automation analogy, not an LLM-agent incident. In 2012, a faulty router sent more than four million orders while trying to fill 212 customer orders during the first 45 minutes of trading. The SEC found that inadequate controls failed to contain the behavior; the resulting unwanted positions eventually produced a loss of more than $460 million. Machine speed scaled a weak boundary before people could catch up.

Our scheduling agent follows the same structural pattern at a smaller scale. The timeout is local. The duplicate invitation is a second-order effect. The travel and notification changes are third-order effects. By the time a person sees the calendar, the original uncertainty has propagated across several systems.

The remedy is not “never retry.” It is to make recovery part of the contract.

Retries need intent, not identical bytes

HTTP semantics define safe and idempotent methods and warn against automatically retrying non-idempotent requests without additional knowledge. That warning matters more when retry is produced by a general agent loop rather than endpoint-specific client code.

Stripe's idempotency keys identify one intended mutation across repeated POST requests; reuse with different parameters is rejected. AWS makes the same point in its guidance on safe retries: the contract should preserve semantic equivalence for the same client intent.

Plain-language decode: Idempotency means a retry represents the same intent, so repeating it does not accidentally perform the action twice. It is not a universal exactly-once guarantee.

For agents, an idempotency key should connect to a durable intent record: who initiated it, on whose behalf, under which policy, against which resource version, and with which result.

When the calendar response times out, the agent queries the receipt. If the move completed, it continues. If it never started, it retries with the same intent ID. If state is unknown, it reconciles or stops. A new key means a new intent.

Rate limits are control signals, not obstacles

Human-built integrations usually encode rate-limit behavior once. Autonomous systems may create dynamic concurrency through planning, parallel tool calls, or subagents. That makes “429, try later” dangerously incomplete.

GitHub's REST guidance tells clients to avoid concurrency, obey Retry-After, back off, and stop after bounded retries. Cloudflare exposes quota, policy windows, and retry timing. Stripe distinguishes rate and concurrency limits.

An agent-ready limit response should also expose scope and cost. Is the budget per user, tenant, workflow, or resource? Should parallel branches pause together? Without these answers, individually polite agents can still create a coordinated retry storm.

Pagination needs a stable world view

Pagination looks harmless until the caller can keep going indefinitely. Offset pagination can duplicate or skip items when records change between pages. GraphQL's cursor connection guidance pairs opaque cursors with hasNextPage and endCursor, making termination explicit. Kubernetes API concepts go further: list responses carry a resourceVersion, and watch clients can continue from that version or restart after a 410 Gone when history is no longer available.

For inventory reconciliation, “next page” is not enough. The contract should state whether pages share a snapshot, how long the cursor is valid, whether ordering is stable, and how much a full scan costs. Otherwise an agent can compare data that never existed in one consistent state.

Long-running work needs an operation, not a long wait

Provisioning, robotics jobs, CI pipelines, and migrations do not fit inside one request. Google's long-running operation pattern returns a durable handle with progress, result, and errors. Kubernetes deletion can return 202 Accepted while finalizers run. Temporal persists workflow progress across failures and long waits.

For an agent, 202 must not mean “probably done.” It needs an operation identity, state machine, bounded wait strategy, cancellation semantics, terminal evidence, and concurrency rules. The caller must resume after losing local memory.

Partial failure needs receipts

GraphQL responses can return data and errors together. Event systems can correlate requests and replies. Well-designed batch APIs can return per-item results. An agent may see one tool step where the service performed many effects.

If a CI agent promotes ten deployments and three fail, the response must identify completed and unchanged environments, rollback state, and the correct unit of retry. “Partial success” without a receipt invites guessing.

Transactions cannot solve every cross-system workflow. A payment can complete before inventory reservation fails. A robot can move a physical object that no database rollback can replace. A Git push can trigger an external build before the branch is reverted. Where atomicity ends, the contract needs compensation and reconciliation.

Compensation is a new domain action that offsets an earlier effect, not a rollback guarantee. Refunding a payment, restoring a calendar event, redeploying an artifact, and returning a robot arm to a safe pose carry different risks. An agent should not invent them from names.

At this point, the recurring failures point to one larger unit of meaning.

The Agent Contract Envelope

An Agent Contract Envelope is the machine-readable operational layer around an API operation. It does not replace OpenAPI, REST, GraphQL, gRPC, AsyncAPI, or MCP. It fills in the questions those interfaces cannot answer generically because the answers belong to the domain.

Contract dimension	Machine-readable question	Calendar example	Infrastructure example
Capability	What does this operation do, and under which protocol/version?	Move one meeting while preserving attendee identity	Replace a deployment image in one environment
Effect	Is it read-only, mutating, reversible, compensatable, or irreversible?	Mutates event and may notify attendees	Mutates running workloads and may restart pods
Authority	On whose behalf may this caller act, within which scope and budget?	Organizer may reschedule, delegate may only propose	Agent may deploy to staging, production requires approval
State	Which preconditions and resource versions make the operation valid?	Event version and current start time must match	Deployment generation and policy revision must match
Recovery	Can it be retried, reconciled, cancelled, or compensated?	Same intent ID deduplicates; restore action is available	Operation handle supports cancel; rollback uses prior revision
Evidence	What receipt proves what actually happened?	Event version, notification set, trace ID, operation status	Applied manifest digest, rollout state, audit principal
Escalation	When must execution stop or request human approval?	External attendee conflict or irreversible cancellation	Production blast radius, policy denial, repeated failure

The envelope applies bounded autonomy to the ambiguous calendar timeout, turning recovery from a guess into a state transition.

Before input: valid API, ambiguous operation

POST /v1/meetings/mtg_42/reschedule

{
  "starts_at": "2026-07-23T09:00:00+08:00",
  "notify": true
}

{
  "status": "accepted"
}

The request is easy to call. The response does not say whether the event changed, whether notifications were sent, whether a retry is safe, or how to inspect progress.

After input: operation semantics are part of the contract

operation: meeting.reschedule
intent_id: intent_7f31
actor:
  principal: agent:scheduling-assistant
  on_behalf_of: user:1842
authority:
  scope: calendar.events.reschedule
  approval: required_if_external_conflict
precondition:
  event_version: "19"
  starts_at: "2026-07-21T09:00:00+08:00"
effect:
  class: reversible_mutation
  notifications: proposed
execution:
  mode: preview_then_commit
  retry: same_intent_only
  timeout_outcome: inspect_operation
recovery:
  reconcile: /v1/operations/op_91
  compensate: meeting.restore_previous_version
evidence:
  required_receipt:
    operation_id: required
    terminal_status: required
    event_version: required
    notified_attendees: required
    conference_resource: required

After output: the service returns durable evidence

operation_id: op_91
intent_id: intent_7f31
status: succeeded
effect:
  event_id: mtg_42
  previous_version: "19"
  current_version: "20"
  starts_at: "2026-07-23T09:00:00+08:00"
  notified_attendees: 6
  conference_resource: room_583
evidence:
  trace_id: 4f8c...
  committed_at: "2026-07-21T10:42:18+08:00"

This envelope does not require YAML or these field names. It requires the request semantics and resulting evidence to exist somewhere stable and machine-readable: OpenAPI extensions, tool annotations, authorization policy, or the operation response.

The important design move is to stop treating them as tribal knowledge.

Authority has to travel with intent

Authentication answers who presented a credential. Authorization answers what that identity may do. Autonomous delegation adds two more questions: on whose behalf is it acting, and what purpose limits the action?

A calendar token with write access may permit deletion, but a scheduling agent should not delete a recurring meeting to resolve a conflict. A cloud role may permit database replacement, but a coding agent fixing a migration test should not exercise it. A voice agent may issue a refund, but a large refund after repeated misunderstanding needs review.

When an MCP implementation uses the specification's HTTP authorization flow, clients must request resource-specific tokens, servers must validate that tokens were issued for them, and servers must not pass client tokens through to upstream APIs. That is an important boundary, but least privilege still depends on operation design. Broad write scopes are easy for people to understand and dangerous for general-purpose agents to inherit.

Authority should be narrow across resource, action, amount, time, environment, and delegation depth. A subagent should not inherit every manager capability. Audit records should distinguish the user, orchestrator, specialist agent, and executing tool server.

High-risk actions need friction by design. OpenAI's agent guidance recommends rating tools by reversibility, permissions, and financial impact, then using human intervention for sensitive or repeatedly failing actions. NIST's AI Risk Management Framework likewise calls for defined roles and documented oversight.

Safety boundary: Human approval should be triggered by effect and risk, not by a vague confidence score alone.

A useful confirmation is specific. “Approve action?” is weak. “Approve cancellation of order 481, which stops unshipped items, issues a $2,840 refund, and cannot restore the allocation?” previews the effect. Approval should bind to the exact operation digest so the payload cannot change afterward.

Dry-run and policy-preview endpoints let agents ask what would change, which rule allows it, and what approval is required before crossing the mutation boundary. Google API guidance includes validate-only patterns, and Kubernetes-style systems separate desired state from reconciliation.

Observability must connect the goal to the side effect

Now we can bound authority. The next question is whether anyone can reconstruct why the agent acted.

Ordinary HTTP access logs can show that an endpoint received two requests, but usually do not record why the agent made the second one.

Agent observability needs a causal chain from human goal to plan, capability selection, tool call, service operation, downstream effects, observation, and recovery. OpenTelemetry context propagation provides the distributed tracing foundation. Its emerging GenAI semantic conventions include agent, workflow, and tool execution attributes, while warning that tool arguments and results may contain sensitive information.

Auditability does not mean logging every prompt or secret. It means recording the minimum evidence needed to reconstruct authority and effect: intent ID, actor lineage, policy decision, tool version, resource version, retry count, operation receipt, approval reference, and terminal state.

flowchart LR
    G[Human goal] --> P[Policy and plan]
    P --> C[Capability selection]
    C --> X{Effect risk}
    X -->|Low and bounded| E[Execute with intent ID]
    X -->|High or irreversible| H[Human approval]
    H -->|Approved digest| E
    H -->|Denied| S[Stop with evidence]
    E --> O[Observe operation receipt]
    O -->|Complete| R[Return verified result]
    O -->|Retryable| B[Bounded backoff]
    B --> E
    O -->|Ambiguous or partial| Q[Reconcile or escalate]
    Q --> S

Conceptual control model: an autonomous call remains bounded by policy, effect classification, durable intent, evidence, and stop conditions. It is not a measured reliability model.

For the calendar scenario, one trace should show that the second attempt reused the first intent ID and resolved to the existing operation. For CI/CD, it should connect code change, build, approval, artifact, deployment, health check, and rollback. For real-time collaboration, it should preserve who changed what and causal ordering across reconnects.

The unit of observability is no longer only the request. It is the delegated objective.

Composition turns local semantics into system policy

Tool composition is where otherwise good APIs become dangerous together.

A payment API may be idempotent, an inventory API may expose versions, and a messaging API may deduplicate sends. The workflow still fails if the agent invents a new intent at each step or loses the mapping between local receipts and the global objective.

Multi-agent orchestration adds another boundary. A manager delegates lookup, policy evaluation, and purchasing. If the purchase agent receives “approved item” without the budget, jurisdiction, or evidence freshness behind that decision, the handoff has stripped away policy.

Capability descriptions therefore need composition semantics: read-only or mutating, closed or open-world, parallel-safe or serial, expected cost, authoritative outputs, and context that must survive delegation.

Orchestration also needs exit conditions. Search stops at an evidence or call budget. Repair stops after bounded reconciliation. Robotics enters a safe state when observation diverges from the world model. “Keep trying until success” is an unbounded policy.

The human-factors literature on automation90046-8) has long shown that automation changes human work rather than simply removing it and can impose new coordination demands on operators. Escalation therefore needs a reviewable decision record, not a transcript dump.

Here is what this means: the agent has an incomplete representation of intent, while the service has an evolving representation of state. As in knowledge systems operating between uncertainties, the contract is the evidence boundary between them.

REST is not obsolete. Its surrounding assumptions are

It is tempting to turn this shift into a protocol obituary. That would be lazy.

REST's strongest ideas remain relevant: resource identity, stateless interaction, cacheability, uniform methods, and hypermedia exposing valid next actions. HTTP already distinguishes safe and idempotent methods, conditional requests, and asynchronous acceptance. Autonomous clients need those constraints.

Kubernetes API design shows how far resource-oriented HTTP can go. Stable identity and resourceVersion support concurrency. List and watch create resumable state. Finalizers expose deletion as a process. Declarative reconciliation separates desired outcome from convergence.

The problem is calling any JSON endpoint “REST” while leaving business semantics in client folklore.

REST becomes more valuable when its semantics are precise. Safe methods must not hide unsafe effects. Mutations should use preconditions. 202 Accepted should link to an operation. 409 or 412 should include a version and recovery path. Hypermedia can expose valid transitions. Problem details can distinguish repair from retry.

GraphQL offers typed discovery, but partial data and mutations still need policy. gRPC provides contracts, deadlines, and status codes, but cannot decide whether a refund is reversible. AsyncAPI models messages and correlation, but duplicate meaning remains domain-specific. MCP connects agents and tools, but cannot certify that a tool's claimed effect is true.

Better protocols reduce ambiguity. They do not eliminate the need to define intent, authority, and consequence.

Next, we need to test whether this is genuinely new or simply established engineering under a fresh label.

Common objections deserve serious answers

“This is just good API design with a new label”

Much of this is established distributed-systems design. The new part is the consumer model: agents may decide what to combine and where to stop at runtime, moving effect and escalation semantics closer to the API boundary.

“Models will get better at reading documentation”

They will interpret ambiguous prose more accurately. That does not make ambiguity a sound authorization or transaction mechanism. Reliability should improve with model capability, not depend on undocumented inference staying stable across versions.

“The agent framework or SDK can add this layer”

SDKs can normalize retries, tracing, and schemas. Frameworks can enforce budgets and confirmations. They cannot invent whether a payment settled, a robot completed motion, or an inventory hold exists. Protocol ergonomics matter because Python, TypeScript, hosted tools, MCP clients, and workflow engines all need the same operational truth.

“This will make every endpoint impossibly complex”

Not every endpoint needs the full envelope. Complexity should scale with effect risk. A weather lookup, Git branch delete, production migration, and robotic command should not share one control surface merely because each uses JSON.

Start with the operations that can hurt you

Organizations do not need an “agent-native API” rewrite. They need a risk-ordered contract audit.

1. Inventory effects, not endpoints. Classify operations as read-only, reversible mutation, compensatable mutation, or irreversible action. Record external side effects and blast radius.
2. Make ambiguous recovery observable. Add intent IDs, operation receipts, preconditions, partial-failure detail, and bounded retry guidance to the highest-risk mutations.
3. Bind authority to purpose. Narrow scopes by resource, action, amount, environment, duration, and delegation depth. Add preview and approval for high-risk effects.
4. Trace delegated objectives. Propagate intent and actor lineage through tools and services, then test whether an operator can reconstruct what happened without reading a model transcript.
5. Evaluate with agent behavior. Test tool selection, malformed and schema-valid-but-wrong calls, retry storms, stale pages, partial failures, version drift, prompt injection, and handoff loss.

That sequence is measurable. A platform team can count mutating operations without idempotent intent, long-running operations without durable state, errors without recovery classes, tools with broad credentials, and side effects without trace linkage. Those are better readiness metrics than the number of endpoints wrapped as tools.

Field note: In production, teams usually document the happy path more carefully than the recovery path. Human developers compensate with judgment. Agents make loops, composition, and recovery part of normal execution.

If one question changes your next API review, use this one:

Could an autonomous caller determine the next safe action after the response disappears?

If the answer depends on “a developer would know,” the contract is incomplete.

The contract becomes the product

The operational steps are concrete. Now we can make a bounded prediction.

Over the next five years, APIs will not become universally “AI APIs.” They will become more explicit about the conditions under which software may act.

Capability negotiation will expand beyond protocol versions into effect and policy negotiation. Tool discovery will include authority requirements, cost classes, concurrency limits, and reversibility. Long-running operations will expose richer state and evidence. Error responses will identify safe recovery programs. Documentation examples will become executable conformance tests. Observability will connect user intent to downstream effects across agents and services.

Some interfaces will adapt within stable rules. A cloud API may expose production mutations only when a client supports approval, intent identity, and trace propagation.

The scheduling agent will still face timeouts. Networks will still partition. Calendars will still change between reads. People will still give incomplete instructions. The difference is that the interface will no longer ask the agent to improvise policy from a missing response.

It will return an operation receipt. The retry will carry the same intent. The calendar version will reveal whether state changed. The notification effect will be explicit. A conflict with an external attendee will trigger a specific approval. The trace will show why each step occurred.

The API will not be self-driving. It will be self-describing enough to keep autonomy inside a boundary.

An API is not agent-ready because a model can call it. It is agent-ready when the contract makes guessing unnecessary where consequences begin.