为AI智能体设计API的关键指南

背景

过去两年间，AI Agent（智能体）迅速崛起，代码生成与自动调用 API 的方式发生了根本变化。如今，绝大多数 API 的调用者已不再是手写代码的人类开发者，而是由 Agent 自动生成的代码。这一转变彻底颠覆了传统 API 设计的核心假设：过去我们设计 API 时默认使用者是人类，追求易用、简洁、低门槛；但在 Agent 时代，这些旧有的设计原则反而可能成为障碍。Hacker News 上这篇题为《Designing APIs for Agents》的文章，正是由一家提供高性能沙盒虚拟机（Freestyle）的团队撰写，基于他们自身从面向人类设计到面向 Agent 设计的实践反思。

核心内容

为人类设计好的 API 是什么样的

作者认为，为人类设计优秀 API 时，第一步是勾勒最简使用模式、新手上路流程和十大用例。然后构想出理想中的代码实现，再实际试用，找到卡住的地方，并添加合适的默认值和配置选项。目标是让使用者在 50 行内就能跑通功能，API 足够直观，以至于想要更多功能时能自然而然找到入口——理想情况下，只需用到 20 个字段中的 1 个的人，仅通过自动补全就能隐约感知到其他字段的存在，而无需通读文档。

作者举了两个优秀的例子：Stripe 和 Twilio 的 SDK。前者让他 14 岁时就能上手，无需了解 Stripe 的税务选项、ACH 是什么或其他五十多种功能；后者同样如此。这些 SDK 允许用户在几乎不了解底层细节的情况下取得大量进展。

为 Agent 设计 API 恰恰相反

AI Agent 可以一口气读完整套文档。Claude Code 平均每次提示使用 1 万以上的 token；首次交互时，Agent 就能读取你全部的 API 和所有相关文档。它们还能在几秒内生成数千行代码来达成目标。这彻底改变了设计逻辑。

为 Agent 设计好 API 的原则

1. 默认值是有害的（Defaults are bad）
   Agent 有能力阅读文档并理解合适的起始值，然后显式地填入所有参数。显式现在成本极低，明确指定预期行为可以减少 bug。过去人类因为不理解而略过的三十个字段，Agent 应该全部填充。这并不意味着次要字段不能加注释来区分，而是说填写大量看似不重要字段的代价已经消失，而理解代码行为的代价大幅上升。

2. 错误不是坏事（Errors are not bad）
   许多优秀 API 为了包容人类用户的“笨拙”，对大小写不敏感、接受多种输入形式（如 Postgres 接受 true、yes、on、1 作为布尔值）。这种模糊处理对 Agent 代码库极为有害——不同函数会使用不同值表示同一事物，给后续审查造成头痛。现代工具链（harnesses）可以在调试时读取文档，如果错误信息中直接告诉 Agent 如何修正则更好。不应进行“半正确”的合并，应让 Agent 在其侧自行显式合并值。对于人类，新手阶段的错误应尽量减少；对于 Agent，错误则是澄清含义的机会。当然，空泛无指引的内部错误会导致 Agent 陷入死循环，但那是坏错误的问题，不是错误本身的问题。

3. 分布明确，而非幻觉（In distribution, not in hallucination）
   当 API 含义模糊时，Agent 倾向于凭幻觉使用它，类似它见过的其他 API。因此作者偏好具体字段名而非通用名。例如 name 字段，某些 API 用作显示名，有些用作完整 ID，有些用作作用域内 ID。如果让 Agent 在十个不同场景中使用一个含 name 的 API，它很可能以五种不同方式使用——而只有一种正确。name 可以包含空格、斜杠、破折号、下划线、Emoji 吗？代码库越大，这个问题越严重。审阅者未来阅读这些代码时，也会对 name 产生五种不同解释。作者推荐使用 displayName、slug、externalId 等明确字段名，配合文档注释巩固正确含义。

4. 事实，而非感受（Facts, not feelings）
   在 Agent 时代，API 的价值在于提供 Agent 或其人类团队无法内部复制的事实——比如账单已付、消息已发送、虚拟机已配置（作者自荐 Freestyle VMs）。除此之外的工具类功能大多无关紧要，可以用文档和指南替代。作者对大多数 SDK 持怀疑态度，除了那些仅在语言层面暴露 API 规范（如将 API 错误转换为强类型的 TypeScript 错误）的 SDK。

实际案例：Freestyle 的转型

Freestyle 构建了沙盒领域最强大的虚拟机：支持 Docker-in-Docker、嵌套虚拟化、高级网络、8 倍以上内存（公开层）、全操作系统配置、私有 VPC/VPN、稳定且有效的完整内存快照，全部在 400ms 内完成。由于用户处理的是开放式的复杂问题，Freestyle 起初试图隐藏复杂性：构建了声明式函数式构建系统与 SDK 工具包，让用户通过“Bun 包”等抽象层直接使用，无需关心内部。但结果是“永远不够可配置，问题比答案多，Agent 完全无法理解并以各种方式错误使用”。最终，抽象层本身成了新手上路的最大阻碍。

几个月前，Freestyle 完全放弃了这种思路：移除所有复杂 SDK 包和间接层，改用指南（guide）。现在，当用户需要复杂功能时，直接让 Agent 读取指南，Agent 从中提取相关代码，适配到项目规范，自由定制行为。新体验既清洁又清晰，最终代码也更易理解。

其他 API/SDK 的实际案例

作者给出一个优秀例子：Flue Frame（标注为🏆 Excellent），属于 Agent 框架类，但原文未展开说明其具体设计。

关键要点

• 默认值有害：Agent 应显式填写所有参数，而非依赖隐式默认值。
• 错误是机会：明确的错误信息能帮助 Agent 纠正误解，应鼓励产生清晰错误，而非试图避免错误。
• 字段名要具体：避免通用名如 name，优先使用 displayName、slug、externalId 等，减少 Agent 的幻觉风险。
• API 应提供事实：核心价值在于返回不可内部复制的确定性结果（如支付确认、VM 创建），而非提供工具类抽象。
• 抽象层对 Agent 有害：隐藏复杂性的 SDK 包容易导致 Agent 误用，不如提供清晰指南让 Agent 自主编码。
• 人类与 Agent 的设计逻辑正好相反：过去追求最小化认知负荷，现在追求最大清晰度和显式性。

意义与影响

这篇文章标志着一个重要的设计范式转折：AI Agent 作为 API 的主流消费者，正在迫使开发者重新思考 API 的根本设计哲学。过去二十年的 API 设计最佳实践（如“合理默认值”、“宽容输入”、“简化新手体验”）在 Agent 面前可能成为 bug 的温床。相反，显式、冗长、具体、甚至“不友善”的 API（针对容易出错的输入直接报错）反而能提升 Agent 代码的可靠性与可维护性。

这一变化的影响将是深远的：

• SDK 开发生态可能转变——未来主流不再是提供“智慧型”抽象层，而是提供最小化、事实型、强类型接口，配合详尽指南。
• 错误消息的优先级大幅提升——清晰可读的错误信息将成为 Agent 调试的关键工具。
• 字段命名规范需要重新评估——企业级 API 设计将更倾向于长命名、无歧义标识符。
• AI Agent 框架（如 Claude Code、GPT 函数调用）的开发者，也需要据此调整提示策略。

最终，这篇文章提醒我们：当 AI 成为用户，我们为之设计的不是“人性化”，而是“机器可理解的可预测性”。