Designing Libraries for AI Agents: Lessons from Sury v11

说明与用途

德米特里解释了在 Sury v11 中，他如何将隐式方法替换为显式方法，删除模糊助手，并改进文档，使 API 对人类和 AI 代理都清晰可懂。

问题

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.

来源