设计API给AI：默认值有害，错误是机会
Designing APIs for Agents
过去两年，我彻底转变了设计API的理念。以前我们为人类开发者设计API，追求极简和智能默认值，让用户50行代码就能跑起来。但现在，API的主要消费者是AI Agent。它们能瞬间读完所有文档，生成数千行代码。对人类友好的“智能默认值”和“容错机制”反而成了Agent的噩梦，导致幻觉和歧义。现在的设计原则是：默认值是坏的，必须显式；错误不是坏事，而是澄清误解的机会；拒绝模糊的字段名，用精确的事实代替感觉。Freestyle团队因此重构了SDK，去掉了所有抽象层，只提供最原始的事实和文档，让Agent能精准调用。
错误是Agent寻找正确路径的最佳途径，但前提是这些错误必须足够精确。
HN 评论区
48- 有评论者指出，在会话结束后利用缓存立即启动反思机制（reflections mechanism），能以极低成本自动捕获工具文档错误或设计缺陷，比依赖输入 token 的传统方式便宜 10 倍。
- 一位从业者提出 API 设计应优先支持文本接口并使其可 grep，通过缩短标识符长度、提供批量操作及包含额外上下文信息，显著减少 Agent 的交互轮次与 Token 消耗。
- 针对默认值有害的观点，有开发者反驳称将扩展程序的默认值显式写入设置文件（settings file），能让 Agent 直接感知完整配置表面，避免其盲目挖掘嵌套在代码或文档中的默认值。
- 有观点强调错误信息应包含指向文档的链接和具体修复提示，使 Agent 能自主排查问题，甚至利用旧 API 调用触发的错误消息反向通知人类升级技能（skill upgrader）。
- 关于向 LLM 询问反馈的有效性存在分歧，一方认为模型能基于会话轨迹进行模式匹配提供可操作建议，另一方则质疑模型无法知晓自身内部状态，其反馈可能只是看似合理的幻觉。