--- title: "Design APIs for agent consumers | Dhruv Doshi" description: "APIs were designed for human developers reading documentation. AI agents are becoming a significant consumer of the same interfaces, and they read APIs differently: they parse schemas…" canonical: https://doshidhruv.com/notes/design-apis-for-agent-consumers/ author: Dhruv Doshi --- [Skip to content](#main-content) [Dhruv Doshi](/) [Work](/projects)[Experience](/resume)[Notes](/notes)[Guides](/guides)[Research](/research)[Investing](/investing)[About](/about)[Contact](/contact)[Search /](/search)dark mode [All notes](/notes) [AI governance](/topics/ai-governance) # Design APIs for agent consumers 2026-10-01 · 4 minute read APIs were designed for human developers reading documentation. AI agents are becoming a significant consumer of the same interfaces, and they read APIs differently: they parse schemas literally, retry aggressively, hallucinate parameters when documentation is ambiguous, and cannot ask a colleague what an error means. Designing for agent consumers improves the API for everyone. ## Make the contract machine-complete Human developers tolerate ambiguity that agents cannot. Every endpoint needs a complete machine-readable contract: precise schemas with formats and constraints, enumerated values instead of free text where the set is closed, and explicit documentation of defaults. An agent faced with an undocumented optional field will invent a value; faced with a documented default, it will use it. Error responses deserve the same rigor. Return structured errors with stable machine-readable codes, human-readable messages, and — critically — guidance on what to do next. Distinguish retryable from permanent failures explicitly. An agent that cannot tell a rate limit from a validation error will retry the validation error until it is blocked. ## Design for the agent's failure modes Agents fail in predictable ways, and the API can defend against each. They call tools with slightly wrong arguments: validate strictly and return errors that name the expected shape. They repeat non-idempotent operations after timeouts: make mutations idempotent with client-supplied idempotency keys, so a retried request is safe. They paginate incorrectly: prefer cursor-based pagination with opaque cursors over offset pagination that drifts when data changes. They also chain calls in ways the designer did not anticipate. Keep related operations composable rather than chatty — an agent making forty sequential calls to assemble one view will be slow, expensive, and fragile. Where a workflow is common, offer a single higher-level operation alongside the primitives. ## Constrain the action space The most important design decision is what the API does not allow. Agents with broad write access and ambiguous tools cause the incidents people fear. Scope tokens narrowly, require explicit confirmation steps for destructive or irreversible actions, and rate-limit per principal so one misbehaving agent cannot exhaust shared capacity. Version tool definitions carefully. An agent's behavior depends on the exact schema it was given; changing a tool's parameters without versioning changes agent behavior without a code deploy. Treat tool schemas with the same change discipline as database migrations. ## Observe agent traffic separately Agents generate distinctive traffic patterns: high call volumes, unusual sequences, repeated retries, and exploration of endpoints humans rarely touch. Instrument agent consumers separately — by API key, user agent, or explicit identification — so you can see their success rates, error distributions, latency, and cost independently of human traffic. This telemetry is also a product input. The endpoints agents struggle with are usually the endpoints with the weakest contracts. Every agent failure caused by API ambiguity is a bug report for the API. ## Documentation as a runtime asset For agent consumers, documentation is not a website; it is context. Keep a machine-readable description of capabilities, constraints, and workflows that agents can retrieve at runtime. Keep it synchronized with the implementation — drift between documented and actual behavior is where agents fail most confusingly. The discipline is the same one good API design always required: precise contracts, explicit errors, safe retries, and least privilege. Agents simply punish violations faster and at greater scale than human developers did. Design for the strictest reader and every reader benefits. ## Test with real agents, not just unit tests Contract tests verify schemas. They do not verify that an agent can accomplish a task with your API. The difference matters because agent failures are behavioral: the agent calls endpoints in an unexpected order, misreads an ambiguous field, or gives up after an unhelpful error. None of this shows up in schema validation. Build task-based tests: give an agent a realistic goal — onboard a test customer, reconcile a report, migrate a configuration — and observe. Record where it hesitates, which errors confuse it, and how many calls it needs. The failures are a prioritized list of API improvements, ranked by actual agent pain rather than designer intuition. Run these tests against every significant API change. Tool schema modifications, new required fields, altered error formats, and changed pagination all shift agent behavior without breaking any contract test. A task-based regression suite is the only automated check that sees what agents see. Include adversarial tasks too. Ask the agent to do something it should not be able to do — access another tenant's data, perform a destructive action without confirmation, exceed its rate limit — and verify the API refuses cleanly. The security model of an agent-consumed API cannot rely on the consumer behaving well; it must hold against a consumer that is creative, persistent, and occasionally confused. The teams that get this right treat agent compatibility as a design requirement reviewed in every API design discussion, not a niche concern. The agents are coming either way; the only choice is whether your API is ready for them. ## Continue reading - ["AI red teaming: a practical playbook for enterprise teams"](/notes/ai-red-teaming-a-practical-playbook-for-enterprise-teams) · Note - ["Third-party AI vendor risk management"](/notes/third-party-ai-vendor-risk-management) · Note - ["Audit logging for AI systems: what to record and why"](/notes/audit-logging-for-ai-systems-what-to-record-and-why) · Note - [Data retention and deletion in AI systems](/notes/data-retention-and-deletion-in-ai-systems) · Note **Dhruv Doshi** · Toronto, Canada · [work@doshidhruv.com](mailto:work@doshidhruv.com) [Resume](/resume)[Notes](/notes)[Guides](/guides)[Topics](/topics)[Search](/search)[Research](/research)[Investing](/investing)[LinkedIn](https://www.linkedin.com/in/dhruvdoshi25071999)[GitHub](https://github.com/DhruvDoshi) [Sitemap](/sitemap.xml)[RSS](/feed.xml)[LLMs](/llms.txt) © 2026 Dhruv Doshi