Your API's Newest Users Are Agents: Designing for Non-Human Clients

Description and use

An agent‑friendly API requires structured errors, idempotency keys, and bounded responses to ensure predictable interaction and avoid duplicate actions.

Problem

Human‑facing APIs fail agents because they produce ambiguous errors, unbounded responses, and lack idempotency, leading to retries, hallucinations, and duplicate side effects.

Outcome

The example demonstrates how to refactor a human‑centric API into an agent‑friendly one, enabling reliable, deterministic interactions and preventing duplicate side effects.

Workflow

• Define structured error responses with stable code strings.
• Implement Idempotency‑Key header handling and store results keyed by the header.
• Limit response payloads to required fields and paginate lists with cursors.
• Publish a JSON schema for each tool endpoint that agents can load.
• Write an agent loop that plans, acts, and observes with a hard step limit and success predicate.
• Test the loop against the in‑memory ticket API to verify deterministic behavior.

Evidence

Ambiguous errors. A 400 with {"error": "bad request"} forces the agent to guess.

Source

Unbounded responses. Returning 50KB of nested JSON burns context window and increases the chance the agent truncates the useful part.

Source

No idempotency. Agents retry on timeouts. Without idempotency keys, you get duplicate side effects.

Source