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

Описание и применение

API, ориентированный на агенты, требует структурированных ошибок, ключей идемпотентности и ограниченных ответов, чтобы обеспечить предсказуемое взаимодействие и избежать дублирования действий.

Задача

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

Результат

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

Рабочий процесс

• 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.

Доказательства

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

Источник

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

Источник

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

Источник