为AI Agent设计可靠的API接口

我们很高兴你的到来。你可以期待在每周一至周五收到 TNS 的所有优质内容，帮助你及时掌握新闻动态，始终保持最佳状态。

请查看收件箱中的确认邮件，你可以在其中调整偏好设置，甚至加入更多群组。

在你喜爱的社交媒体平台上关注 TNS。

在 LinkedIn 上关注 TNS。

在等待第一期 TNS 新闻简报期间，不妨浏览最新的精选和热门文章。

2025 年初，在业界尚未形成明确的 AI 智能体就绪 API 实践指南之前，Webflow 就开始为 MCP 进行构建。2025 年 4 月，我们正式公开宣布推出 MCP 服务器；随后在 2025 年 5 月，我们与首批远程 MCP 服务器一同参加了 Cloudflare Demo Day。

我们最初的做法很直接：将现有 API 封装成 MCP 工具。但我们很快发现，为开发者设计的 API 并不适合 AI 智能体。开发者 API 假设人类能够阅读文档、开展调研或从各种外部来源获取答案、组合细粒度端点、管理状态并手动处理故障。AI 智能体拥有的隐含上下文要少得多，并且高度依赖 API 接口本身来指导规划与执行，以及判断应该重试、调整还是停止。因此，直接向 AI 智能体暴露开发者 API，导致我们早期的 MCP 工具层级过低且过于啰嗦：完成简单任务通常需要调用许多次工具，面对更复杂的工作流时却又力不从心。最终造成了难以察觉的故障、低效的运行过程，以及不可靠的任务完成结果。

“为开发者设计的 API 并不适合 AI 智能体。开发者 API 假设人类能够阅读文档、开展调研、组合细粒度端点、管理状态并手动处理故障。”

接下来的一年里，我们进行了大量迭代：围绕意图而非端点重新设计工具、简化模式、提高工具调用效率，并让响应更便于 AI 智能体推理。我们还持续深入投入底层基础能力——从代码层到文件系统抽象——以支持更加可靠、能力更强的 AI 智能体工作流。

其中许多决策如今都与业界逐渐形成的模式相似：面向任务的工具、AI 智能体可读的模式、可操作的错误指引，以及围绕意图而非实现细节设计的 API。本文将分享塑造 Webflow MCP 服务器的经验，以及为什么面向 AI 智能体的设计最终远不只是通过 MCP 暴露 API。它要求我们重新思考自主系统如何发现能力、协调执行、浏览产品功能界面，以及如何在运行时可靠地运作。

为什么开发者 API 不适合 AI 智能体

用户可能会要求 AI 智能体更新首页的首屏区域。在传统 API 中，这可能会变成一连串底层操作：

list pages
→ find homepage
→ fetch page content
→ inspect content tree
→ find hero section
→ update content

早期的 MCP 实现通常直接将现有开发者 API 暴露为 MCP 工具：

getPages()
getPageContent(pageId)
updateContent(contentId, payload)
publishPage(pageId)

问题并不在 MCP 本身。协议完全按照预期工作。LLM 只能看到工具描述、模式、之前的响应和当前的上下文窗口。它必须动态推断执行策略，同时在多次工具调用之间保留中间状态。故障模式正是从这里开始出现。每增加一次工具调用，都会增加延迟、Token 消耗、上下文压力和执行失败的概率。此时，AI 智能体必须：

正确保留中间标识符

从含义不明确的结果中选择正确的资源

理解冗杂或过于宽泛的响应

按顺序协调相互依赖的操作

判断故障是可以重试，还是必须终止

即使 API 在技术上支持该工作流，模型也会将过多的运行时预算用于探索 API，而不是完成用户的任务。

AI 智能体 API 需要具备什么

我们得到的教训是，通过 MCP 暴露 API 只是起点。AI 智能体能否可靠执行，更多取决于工具本身的形态和语义。开发者 API 通常针对灵活性与可组合性进行优化。AI 智能体 API 则需要针对执行可靠性进行优化：减少含义不明确的选择、减少相互依赖的调用、减少需要保留的状态，并在出现问题时提供更清晰的指引。

“开发者 API 通常针对灵活性与可组合性进行优化。AI 智能体 API 则需要针对执行可靠性进行优化：减少含义不明确的选择、减少相互依赖的调用、减少需要保留的状态，并在出现问题时提供更清晰的指引。”

对于更新首页首屏区域这一任务，更好的接口是一个直接匹配用户意图的任务级工具：

update_page_section({
  page: "home",
  section: "hero",
  changes: {
    heading: "Build faster with Webflow"
  }
})

声明式 API 将复杂的多步骤工作流转化为一次由意图驱动的调用。平台在内部负责协调，无需 AI 智能体发现内部结构、保留中间状态、协调相互依赖的操作，或从局部故障中恢复。这样可以减少故障模式，让 AI 智能体专注于用户目标，而不是执行细节。

从底层 API 转向任务级工具，方向是正确的，但在 Webflow 的规模下又引入了一个新问题：工具爆炸。Webflow 支持的有效工作流太多，无法将每一种工作流都建模为独立的 MCP 工具。纯粹面向任务的设计很快就会产生庞大且相互重叠的工具接口，使 AI 智能体难以高效浏览。要解决这个问题，基本有两种方法，我们将在后续章节中更深入地讨论这两种模式：

分层工具架构：我们没有暴露数百个独立工具，而是将相关能力归入更广泛的领域级工具，并在其中提供类型明确、可组合的操作。这既为 AI 智能体提供了结构更清晰、更易于浏览的产品功能地图，也使顶层工具空间保持在可管理的范围内。

引入以代码表示 Webflow 项目的文件系统抽象：AI 智能体可以使用熟悉的编程及 Shell 风格工作流，对结构化的项目表示执行操作。这使部分交互模型从 API 编排转向执行环境和代码驱动的操作。

发布并扩展我们的 MCP 服务器

我们得到的另一个教训是，为 AI 智能体设计 API 的范围远不止 API 接口本身。一旦 AI 智能体成为长时间运行工作流中的主动参与者，许多外围系统决策都会开始直接影响执行质量：会话架构、工具组织、运行时协调、可观测性，甚至分发方式。

在实践中，构建可靠的 AI 智能体系统成了一个全栈设计问题。这塑造了我们从以下四个方面构建 Webflow MCP 服务器的方式：

用于有状态执行和运行时协调的基础设施

便于清晰理解和高效发现能力的工具接口设计

用于理解 AI 智能体真实行为的可观测性系统

降低配置门槛并扩大采用规模的分发模式

事实证明，MCP 服务器的基础设施需求与传统 API 服务截然不同。虽然 MCP 本身并不要求服务器端状态，但现实中的 AI 智能体工作流高度依赖状态。AI 智能体可能只进行一次身份验证，然后检查站点上下文、跨不同产品功能界面调用多个工具，并在长时间运行的工作流中持续推理。如果将每次交互都视为完全无状态，模型就不得不反复重建上下文和执行状态，从而同时增加延迟和失败概率。

我们使用 Durable Objects 在 Cloudflare 上构建了 Webflow MCP 服务器，因为它们提供了一种自然的、面向会话的执行模型。每个 MCP 会话都拥有自己的服务器实例，用于管理用户上下文、可用工具和运行时协调，而不需要单独的会话基础设施。

我们还必须支持两种不同的执行环境。有些操作通过 Webflow API 以无头方式运行，而 Designer 操作——例如插入元素或更新样式——则依赖实时浏览器画布。对于这些工作流，MCP 服务器会与运行在用户当前 Webflow 会话中的 Designer Extension 保持 WebSocket 桥接。

该架构为 AI 智能体提供了统一的 MCP 接口，同时允许系统在幕后将操作路由到正确的运行时。与此同时，我们也一直在逐步将更多 Designer 能力迁移到无头 API 中。减少对实时浏览器执行的依赖，可以简化运行时架构、降低协调复杂度，并提升 AI 智能体工作流的整体稳定性与可靠性。

2. 设计工具接口

如前所述，我们发现有两种不同的方法有助于降低 AI 智能体的编排与发现开销：分层工具组织，以及使用 Webflow 项目的代码表示构建文件系统抽象。随着时间推移，我们开始将它们视为针对同一底层问题的短期和长期解决方案。

短期来看，随着 MCP 能力面的扩展，分层工具架构能够提供帮助，因为我们为 AI 智能体提供了一张更清晰的地图，而不是同时暴露所有工具。我们没有将每项任务都作为独立的 MCP 工具暴露出来，而是将相关能力归入领域级工具，并在其中提供类型化、可组合的操作。例如，CMS 操作被归入一个共享工具界面，涵盖集合、字段、条目、发布和更新；Designer 能力则围绕元素、样式、变量、资源和组件进行组织。

更具体地说，工具能力面逐渐演变为以下几个层次：

领域工具用于组织广泛的产品领域

操作在各个领域内提供可组合的类型化原语

工作流工具封装需要大量编排的任务

指南工具提供操作说明和产品上下文，以实现更安全的执行

虽然这种方法确实有助于缓解工具能力面和编排方面的问题，但它并没有从根本上消除这些问题。随着产品能力扩展，即使采用分层架构，有效工作流和操作的数量仍可能迅速增长。发展到某个阶段后，挑战就会从单纯组织工具，转变为降低系统对显式工具发现的依赖。即使工具层级结构组织良好，模型仍然需要搜索和选择能力、理解模式，并协调跨 API 的执行。

这正是文件系统式抽象和面向代码的环境变得越来越重要的原因。AI 智能体不必再通过显式调用 MCP 工具来完成所有交互，而是可以操作结构化的项目表示，使其更像一个可编程工作区。Anthropic 和 Cloudflare 最近在 AI 智能体基础设施方面的工作中，都探讨过类似方向。下面是一个在代码模式下更新主页的示例：

// agent edits your site as code
read src/pages/home.tsx
write src/components/Hero.tsx
write src/styles/theme.css

这种方式更自然地契合了当前 LLM 的优势。模型已经非常擅长对结构化文本进行推理、生成代码、编辑文件，以及在执行环境中工作。通过将交互模型从 API 编排转向结构化状态操作，系统能够降低发现开销、上下文消耗和多步骤协调负担。

“更深层次的经验是，扩展 AI 智能体系统并不只是增加更多工具，而是要为模型提供一个更易于导航、效率更高的操作环境。”

更深层次的经验是，扩展 AI 智能体系统并不只是增加更多工具，而是要为模型提供一个更易于导航、效率更高的操作环境。

当 AI 智能体开始在长时间运行的工作流中自主执行任务后，可观测性变得重要得多。

传统日志和追踪对于基础设施调试很有用——它们可以告诉我们哪些请求失败了、延迟呈现出怎样的模式，或者出现了哪些服务端异常。但它们并不适合用来理解 AI 智能体的行为。它们无法告诉我们 AI 智能体真正想完成什么、它预期存在哪些能力、工作流在哪个环节变得令人困惑，或者为什么一些看似“成功”的会话仍然产生了糟糕的结果。

为了弥合这一差距，我们集成了 MCPCat，将其作为围绕 MCP 服务器本身的可观测性层。通过在服务器初始化时对其进行封装，它可以捕获整个执行流程中的工具调用、资源读取、缺失工具调用尝试、会话元数据和响应模式。事实证明，最有价值的信号是意图。

缺失工具调用尝试揭示了 AI 智能体预期存在、但无法找到的能力或命名模式。会话回放则暴露出一些退化的工作流：模型不断探索、重试或改变方向，却始终没有产生明确错误。在许多情况下，从基础设施角度来看，系统似乎运行正常，但 AI 智能体体验实际上仍在悄无声息地失败。

我们最初预计，CMS 迁移和内容管理会占据主要使用场景。相反，Agent Goals 显示，通过第三方 AI 智能体直接在 Webflow 画布中进行设计的会话占比达到了 27.7%。我们还发现了一个影响超过 10% 会话的静默错误，并发现 58.7% 的会话集中在三个核心工作流上。

随着时间推移，我们意识到，AI 智能体系统的可观测性与 API 的可观测性有着根本区别。其目标不仅是了解请求是否成功，还要了解模型如何推理、如何探索能力、如何从歧义中恢复，以及如何在执行过程中失败。

4. 扩展分发

扩展 MCP 服务器的分发能力并不只是处理更多流量，还意味着降低采用门槛、扩大 AI 智能体使用 Webflow 的场景，并提升这些 AI 智能体所执行工作流的质量。

2026 年初，我们推出了托管式 MCP 连接器，并首先支持 Claude。此后，采用速度明显加快，因为它显著降低了用户的设置门槛。用户不再需要手动配置 MCP 连接和身份验证流程，而是可以通过托管式集成连接到 Webflow，大幅减少运维开销。我们观察到，过去 3 个月的会话数量增长了 6.7 倍。

采用规模的扩大也让一件事变得清晰：AI 智能体需要的不只是工具。工具暴露 AI 智能体能够做什么；技能则编码如何把事情做好。对于 Webflow 而言，许多成功结果都需要产品判断、可复用的工作流和领域惯例，而不只是 API 访问能力。随着 AI 智能体从简单的工具调用转向端到端的网站工作，将更多实用技能引入 Webflow MCP 体验变得至关重要，例如布局模式、CMS 迁移手册、SEO 工作流、无障碍检查和品牌系统指导。

随着采用规模扩大，挑战从协议机制转向了面向自主系统的产品体验：提供更丰富的网站上下文、扩展技能层，以及了解 AI 智能体的操作是否真正帮助用户取得了有意义的成果。

AI 智能体并不只是另一种 API 客户端。它们是一种不同类型的运行时参与者：能够基于上下文进行推理、动态探索能力、从界面结构中学习，并依赖系统让下一个正确操作既易于发现，又能可靠执行。

为这类用户进行设计，改变的远不止 API。它会影响我们如何组织工具、管理编排、暴露上下文、构建执行环境、观察工作流，甚至影响产品界面本身的建模方式。随着时间推移，我们发现自己设计的不只是 MCP 接口，而是面向自主系统的完整操作环境。

这促使我们转向分层工具架构、工作流抽象、文件系统式项目表示、更丰富的可观测性以及技能层。我们的目标从来都不是简单地向 AI 智能体暴露更多能力，而是帮助模型减少探索和编排负担，以更高的执行可靠性作出正确决策。

接下来的工作不只是让 Webflow 对 AI 智能体可编程，还要让 Webflow 对自主系统来说易于理解、易于导航，并在运行层面保持可靠，同时不损失使该平台对人类用户如此强大的灵活性。这既是一项深刻的产品挑战，也是一项系统挑战——而这正是我们在 Webflow 热衷于解决的问题。

本文最初于 2026 年 7 月 21 日发布在 webflow.com。