Designing Agent-Friendly APIs

This post introduces principles for designing agent-friendly APIs, focusing on how to make APIs more robust and understandable for AI agents. Key contributions include: 1. Error Guidance: Designing errors with clear explanations, concrete fixes, and doc links, using machine-readable error codes (RFC 9457). 2. Context Budgeting: Bounding responses, prioritizing high-signal fields, and ensuring verifiable success in-band. 3. Self-Description: Implementing describe/capabilities endpoints and providing detailed, example-rich OpenAPI specifications. 4. Safe Machine Tempo: Ensuring idempotency, paceable rate limits, predictability, and boundary guardrails (dry-run/preview). It also discusses metrics like Turns-to-First-Successful-Call (TTFSC) and unattended task success rate.