为智能体设计API
内容提要
Webflow在构建MCP服务器时发现，面向开发者的API不适合智能体，需按意图设计任务级工具，减少调用次数和失败率。他们采用分层工具组织、文件系统抽象、会话状态管理和可观测性，并推出托管连接器，使会话增长6.7倍。核心是构建智能体可导航、可靠运行的完整操作环境，而非仅暴露API。
延伸解读
从端点到意图：API设计的范式转变
文章指出，面向开发者的API优化的是灵活性和可组合性，而智能体需要的是执行可靠性。传统API要求智能体自行组合多个端点、管理状态和处理失败，导致调用次数多、失败率高。Webflow的实践表明，将API按用户意图设计为任务级工具（如update_page_section）能显著减少调用次数和失败率。这提示开发者，为智能体设计API时，应优先考虑减少歧义和依赖调用，而非单纯暴露底层能力。
工具爆炸与分层架构的权衡
Webflow发现，纯粹的任务级工具设计会导致工具数量爆炸，增加智能体的导航负担。为此，他们采用分层工具组织，将相关能力分组到领域级工具中，并支持类型化组合操作。这种短期方案缓解了问题，但并未根本消除。长期来看，文件系统抽象和代码化项目表示（如将网站视为可编辑的代码文件）能进一步降低对显式工具发现的依赖，更契合LLM处理结构化文本和代码的优势。
可观测性：从基础设施到智能体行为
传统日志和追踪只能反映请求是否成功，无法揭示智能体的意图、探索过程和静默失败。Webflow通过集成MCPCat，捕获工具调用、缺失工具尝试和会话重放，发现了一些关键洞察：例如，27.7%的会话是第三方智能体直接在画布上设计，58.7%的会话集中在三个核心工作流，以及一个影响超过10%会话的静默错误。这表明，智能体系统的可观测性应关注模型如何推理、探索和恢复，而非仅关注请求状态。
托管连接器与技能层：降低采用门槛
Webflow推出托管MCP连接器后，用户无需手动配置MCP连接和认证，显著降低了采用摩擦，会话量在三个月内增长了6.7倍。文章强调，智能体不仅需要工具（能做什么），还需要技能（如何做好）。随着智能体从简单调用转向端到端站点工作，提供布局模式、CMS迁移手册、SEO工作流等技能变得至关重要。这提示，为智能体构建完整操作环境时，需同时考虑工具、技能和上下文丰富度。
Q&A
为什么面向开发者的API不适合智能体？
开发者API假设人类能阅读文档、研究、组合细粒度端点、管理状态并手动处理失败，而智能体缺乏这种隐式上下文，依赖API表面来指导规划和执行，直接暴露会导致工具过于底层、调用次数多、失败率高。
Webflow如何改进MCP工具设计以提高智能体执行可靠性？
Webflow将工具从端点级改为任务级，围绕用户意图设计，例如用update_page_section替代多个底层调用，减少依赖调用和状态保留，使平台内部处理编排，降低失败模式。
Webflow如何解决工具爆炸问题？
Webflow采用两种方法：短期是分层工具组织，将相关能力分组到领域级工具中；长期是文件系统抽象和代码表示，让智能体像操作代码一样操作项目，减少显式工具发现。
Webflow的MCP服务器如何管理会话状态？
Webflow使用Cloudflare Durable Objects，每个MCP会话拥有自己的服务器实例，管理用户上下文、可用工具和运行时协调，无需单独会话基础设施。
Webflow如何通过可观测性改进智能体体验？
Webflow集成MCPCat作为可观测层，捕获工具调用、资源读取、缺失工具尝试和响应模式，通过意图分析发现智能体期望但找不到的能力、降级工作流和静默错误，从而优化工具和流程。
Webflow推出托管MCP连接器后取得了什么效果？
托管连接器降低了用户配置MCP的摩擦，从手动配置变为托管集成，过去3个月会话增长了6.7倍。
Webflow认为智能体需要哪些技能层？
智能体需要布局模式、CMS迁移手册、SEO工作流、可访问性检查和品牌系统指导等技能，这些编码了如何做好任务，而不仅仅是API访问。
