为智能体设计 API为智能体进行的良好设计与为人类进行的设计并不相同。如今大多数 API 的使用者是通过智能体编写的代码来调用 API 的而在两年前并非如此这一变化也改变了设计 API 的思路。创始人兼首席执行官本·斯韦德洛不再看好大多数为人类设计的系统对大多数软件包持怀疑态度反对过度使用工具函数现在反而支持使用非常长的名称这些观点是他在过去 24 个月内 180 度大转变的结果。适合人类的优秀 API为人类设计优秀 API 时第一步是勾勒出最小使用模式、入门流程以及前十大用例基于此设想理想情况下实现功能所需编写的代码然后尝试使用找出阻碍的边界情况必要时添加合理的默认值和配置选项。希望人们能用五十行代码实现实用功能之后 API 应容易上手让人轻松发现更多功能使用方式。理想情况下若有人只需二十个字段中的一个应仅通过自动补全功能了解其他十九个字段。优秀的 SDK 应足够直观粗略浏览文档就能使用。如 twilio.py 和 stripe.ts 示例就体现了这些理念。这与为智能体设计的方式恰恰相反AI 智能体可以一次性读完所有文档Claude Code 的提示平均使用 10000 多个令牌第一次提示就能读取整个 API 及相关文档还能在几秒内生成数千行代码实现目标这改变了设计思路。适合智能体的优秀 API智能体最需要清晰性代码要让人一目了然其功能。在 AI 智能体时代代码量增加使调试更困难解决办法是精确定义代码预期行为这意味着1. 默认值并非好事。可期望智能体阅读文档了解合适初始值并填写明确性成本不高明确预期行为可减少错误。智能体应填写每个字段虽不太重要与重要字段间可用注释分隔但填写大量看似不重要字段成本降低理解代码功能成本增加。2. 错误并非坏事。许多优秀 API 会弥补人类小失误但对智能体代码库有害会导致不同函数对同一事物使用不同值给审查人员带来困扰。调试时可期望现代工具读取文档错误信息中提示更好不应进行不完整转换应让智能体自行明确转换值。对于人类入门错误应减少对于智能体错误是明确事物含义的机会。但没有提示的空白内部错误会让智能体混乱好的错误能解决问题错误是智能体找到正确路径的最佳途径之一但必须精确根据数据智能体遇到的问题中有 27% 来自错误出色的错误设计与优秀文档同样重要。3. 注重明确性而非模糊性。API 不清晰时智能体往往会臆测使用所以更喜欢具体字段名。如 name 字段在不同 API 含义不同智能体使用会有多种方式未来审查人员也会有不同解读应尽量明确使用 displayName、slug、externalId 等无歧义的名称文档注释有助于巩固正确解释。4. 基于事实而非感觉。在智能体时代API 的价值在于提供智能体或其人类团队无法内部复制的事实如账单已支付、消息已发送或虚拟机已配置推荐 Freestyle VMs。除此之外的工具函数大多无关紧要可用文档和指南解释实现特定功能的方法对大多数只是暴露 API 规范的 SDK 持怀疑态度。付诸实践Freestyle 打造了沙箱领域中性能最强劲的虚拟机在虚拟化质量、扩展性、配置灵活性、稳定性以及全内存快照功能等方面表现出色且能在 400 毫秒内完成配置。用户面临复杂、开放性强、难调试且具挑战性的问题选择 Freestyle 是因为其他沙箱无法满足需求所以 Freestyle 尽力简洁一致地提供上述事实。过去Freestyle 试图隐藏复杂性构建声明式函数构建系统并结合 SDK 工具函数创建带依赖项的软件包但这些软件包可配置性不够问题多智能体无法理解并误用使用抽象层的复杂性成为用户使用产品的障碍。几个月前Freestyle 摒弃这些做法移除复杂的 SDK 软件包和间接层采用指南让智能体阅读指南提取代码、定制行为获得更清晰的入门体验和更简洁的代码。其他 API 和 SDK 的实践情况智能体框架1. 优秀 —— Flue 框架为智能体所需核心功能提供最小化语义一切是可插拔函数通过与智能体其他部分交互定义对功能描述清晰为构建工具提供共享语义。2. 良好 —— Vercel AI SDK围绕与智能体的连接提供共享 SDK 语义实用generateText 和 streamText 函数清晰能让智能体将与多种推理 API 的复杂交互视为既定事实。3. 中等 —— Mastra有出色的调度和工作流功能智能体大多由可自行实现的可插拔类型构建但在很多方面过于复杂且不够清晰如工作区、文件系统和沙箱语义对内部实现者有很强破坏性以智能体为中心的设计应减少契约用指南指导实现不同模式。4. 糟糕 —— Eve像把 Next.js 变成智能体框架适合 2016 年的技术水平技能系统完全是整体式、不可编程改变加载方式需放弃动态系统加载方式由 description 字符串决定无编程控制的钩子。沙箱 API1. 优秀 —— FreestyleAPI 功能简洁可实现对虚拟机的所有操作不添加过多工具函数建议智能体根据需要编写 gitClone 等函数。2. 良好 —— E2B有一定克制但工具函数存在问题如 sbx.runCode 函数以人类为中心设计对智能体不太友好并非所有沙箱支持所有语言但 SDK 保持较高一致性和可调试性。3. 中等 —— DaytonaSDK 内置多种功能但都不可配置部分功能在某些沙箱中不被支持Freestyle 支持这些功能但可自定义Daytona 的设计似乎针对人类理想情况下智能体应能很好理解 API。总结为智能体构建系统开始与为人类工程师构建系统分道扬镳许多核心原则仍适用但过去重要的因素现在不再重要代码行数、入门错误、阅读内容量、入门令牌数量等对评估 API 对智能体的适用性不太相关。这里提到的内容在 GPT - 4.5 时代可能不正确对 GPT - 6 可能也不相关期待看到未来的发展方向。随机想法1. 讨厌编写和编辑 Java 代码但不讨厌阅读Java 难以管理的继承关系对智能体可能不是问题。2. 认为当前“万物皆 CLI”的热潮不会持续太久CLI 是为难以阅读 OpenAPI 规范的人类和未跟上发展的认证原语提供的权宜之计预计随着 Auth.md 和智能体认证等系统更普遍CLI 将失宠智能体可直接读取文档、调用 APIOpenAPI 规范更易内省和全面理解对 MCP Apps 不持怀疑态度其为与智能体聊天提供新颖交互方式。3. 认为未来三年内用于封装 API 的 SDK 将完全过时如 2020 年 API 有无 SDK 对用 Swift 开发很重要如今已不是考虑因素预计智能体将主导简单集成SDK 在开发者体验方面的优势将不复存在。4. 文章灵感来源于与大卫·顾、雅各布·兹旺、本·沃纳和尼克·卡米的交流所有赞誉归功于他们不满冲作者来文中个人观点与他们无关。为 AI 智能体打造的强大虚拟机具备真正的根权限、嵌套虚拟化、即时启动、实时分叉以及暂停/恢复功能的全功能 Linux 虚拟机。可探索 Freestyle VMs。本页目录1. 为智能体设计 API2. 适合人类的优秀 API3. 这与为智能体设计的方式恰恰相反4. 适合智能体的优秀 API5. 付诸实践6. 其他 API 和 SDK 的实践情况7. 总结关键词智能体、API 设计、SDK产品Freestyle Git、Freestyle VMs文档Freestyle API 文档、Freestyle API 参考开源项目AdorableAI 应用构建器、Freestyle CLI、CloudstateJavaScript 数据库公司信息招聘信息、状态信息、博客、Discord 社区、隐私政策