Designing Libraries for AI Agents: Lessons from Sury v11

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

Дмитрий описывает, как в версии 11 библиотеки Sury он заменил неявные методы на явные, убрал двусмысленные помощники и улучшил документацию, чтобы API был понятен как людям, так и ИИ‑агентам.

Задача

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

Результат

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

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

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

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

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

Источник

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.

Источник