Designing Libraries for AI Agents: Lessons from Sury v11

Description and use

Dmitry explains how in Sury v11 he replaced implicit methods with explicit ones, removed ambiguous helpers, and improved documentation to make the API clear for both humans and AI agents.

Problem

Library APIs often assume human readers of documentation, leading to implicit behaviors that confuse AI agents and humans alike.

Outcome

Sury v11’s explicit API design reduces runtime errors, improves developer experience, and aligns library behavior with AI agent expectations.

Workflow

• 1. Identify implicit API patterns that could mislead AI agents.
• 2. Split ambiguous methods into explicit variants (e.g., parseOrThrow, parseAsResult).
• 3. Rename or remove helpers that have dual meanings (e.g., is/validate).
• 4. Provide clear documentation and error messages that guide both humans and agents.
• 5. Test the API with AI agents to ensure predictable behavior.

Evidence

There's no parse in Sury. I didn't want to give a default that throws somewhere down the line, and nobody handles it.

Source

Now the choice is written down. The agent is more likely to take parseAsResult, and on review another agent can actually see that nobody handles the error.

Source