# 为什么把现有 API 包成 MCP 工具还不够？Webflow 的 Agent API 设计复盘

很多团队接入 MCP 时，第一反应都是：把现有 API 包装成工具，Agent 不就能调用了吗？

Webflow 的实践给出了一个更谨慎的答案：**协议接通只是起点，真正决定 Agent 能否稳定完成任务的，是工具的粒度、语义、状态管理和运行时反馈。**

这篇文章整理自 The New Stack 的《Designing APIs for agents》，重点不是介绍 MCP，而是讨论一个更基础的问题：当 API 的使用者从人类开发者变成 Agent，接口应该如何重新设计？

## 传统 API 为什么会拖累 Agent

开发者 API 通常追求灵活和可组合。它默认调用者可以阅读文档、理解产品结构、保存中间状态，并在失败后判断下一步怎么办。

人类开发者可以完成这样的调用链：

> 列出页面 → 找到首页 → 获取内容 → 检查内容树 → 定位 Hero 区域 → 更新内容 → 发布页面

但对 Agent 来说，每增加一步，都意味着更多 Token、延迟、上下文压力和出错机会。它还必须持续保存页面 ID、内容 ID 等中间信息，从模糊结果中选择正确对象，并判断错误究竟应该重试、修改参数还是立即停止。

因此，即使底层 API 在功能上支持某个任务，Agent 也可能把大量运行预算消耗在“理解和导航 API”上，而不是完成用户真正想做的事。

Webflow 早期直接把开发者 API 暴露为 MCP 工具，遇到的正是这种问题：工具过于底层、调用链太长，简单任务变得啰嗦，复杂任务则容易出现隐蔽失败。

## 从“调用端点”转向“表达意图”

Webflow 得出的核心结论是：Agent API 应该优先优化执行可靠性，而不是最大化底层能力的自由组合。

例如，用户想修改首页 Hero 区域时，与其让 Agent 自己发现页面结构并串联多个端点，不如提供一个任务级接口：

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

这个接口描述的是用户意图，而不是平台内部的实现步骤。页面查找、结构定位、状态保持和局部失败处理，都由平台在内部完成。

这种声明式设计不是简单地把多个 API 合并成一个“大工具”，而是重新划分责任：

- Agent 负责理解目标和提交意图；
- 平台负责确定执行路径、维护状态和处理内部编排；
- 工具响应负责明确说明结果、可重试错误和终止条件。

Agent 因而能把更多上下文用于理解用户，而不是记住一串内部标识符。

## 工具变少之后，还需要分层

意图工具也有一个明显风险：每个任务都建立专用工具，最终会造成工具爆炸。工具越多，描述越容易重叠，模型选择错误工具的概率也越高。

Webflow 的阶段性方案是把能力分成几层：

- **Domain**：按 CMS、页面、站点等业务领域组织能力；
- **Actions**：提供稳定、可复用的操作原语；
- **Workflow**：封装需要多步执行的任务；
- **Guide**：补充排版、SEO、品牌规范等使用知识。

这套结构试图在两个极端之间寻找平衡：既不把所有原子端点直接暴露给 Agent，也不为每一种表达方式创建一个新工具。

更长期的方向则是代码和文件系统抽象。与其要求模型在大量 API 中寻找正确组合，不如让它使用已经熟悉的 `read`、`write` 和结构化文件编辑模式。不过，原文也把这一方向描述为仍在演进中的探索，而不是已经被普遍验证的标准答案。

## MCP 协议之外，还有一整套可靠性工程

Webflow 的复盘也说明，Agent API 的可靠性并不只来自 Schema。

为了支持有状态会话，Webflow 使用 Cloudflare Durable Objects 管理会话级状态；涉及可视化 Designer 的操作时，再通过 WebSocket 连接浏览器中的扩展。与此同时，团队持续把关键能力下沉到 Headless API，减少对前端运行环境的依赖。

Skill 层则承担另一类职责：把排版、SEO 和品牌规范等知识放到 Agent 可读的指导层，而不是把所有规则硬塞进工具参数。

换句话说，一个可用的 Agent 接口至少包含四个部分：

1. 面向意图的工具表面；
2. 平台内部的状态与工作流编排；
3. Agent 可读的领域知识和操作指南；
4. 能观察真实用户意图与隐性失败的遥测系统。

只部署一个 MCP Server，并不会自动获得这些能力。

## 最值得关注的数据：成功响应不等于任务成功

Webflow 通过 MCPCat 分析真实会话后，发现实际使用方式与团队原先的预期并不一致：

- 27.7% 的会话直接在 Webflow 画布中进行设计；
- 超过 10% 的会话出现了没有明确报错、但执行结果已经偏离用户目标的失败；
- 58.7% 的会话集中在三个核心工作流；
- 托管 MCP Connector 上线后的三个月内，会话量增长到原来的 6.7 倍。

这些数字来自 Webflow 自身的生产场景，不能直接当作其他系统的通用基准，但它们揭示了一个重要问题：**HTTP 请求成功、工具没有抛错，并不等于 Agent 完成了任务。**

真正有用的 Agent 可观测性，需要记录用户意图、工具选择、调用链、重试行为、最终结果，以及 Agent 是否在没有错误码的情况下逐渐偏离目标。

## 对 Agent 系统设计的三个提醒

结合 Webflow 的实践，可以提炼出三条更通用的设计原则。

### 1. 优先减少决策分支，而不是增加工具数量

Agent 面对的工具越多、参数越模糊、调用依赖越复杂，执行可靠性越差。设计工具时，应优先减少歧义、依赖调用和必须跨步骤保存的状态。

### 2. 把可恢复性写进接口语义

错误响应不能只有“失败”。它还应该告诉 Agent：失败原因是什么、是否可以重试、需要修改哪个输入、是否必须重新读取状态，以及在什么条件下应该停止。

### 3. 用真实会话决定抽象边界

不要只凭架构想象决定哪些工具应该合并。先观察高频工作流、重复调用链和隐性偏离，再把最常见、最稳定的多步流程重构为任务级接口。

对于已有 Agent 系统，一个更稳妥的做法是先选择一个高频、低风险流程做对照试验，比较改造前后的任务完成率、工具调用数、Token、延迟和隐性偏离率。指标没有改善，就不应仅仅因为 MCP 或“Agent 原生 API”的概念而扩大迁移。

## 结语

MCP 解决的是 Agent 如何发现和调用工具，但它不会替你决定工具应该长什么样。

Webflow 的经验表明，Agent API 设计的真正转折点，是从“把现有端点交给模型”转向“让接口直接表达用户意图”，并由平台承担状态、编排、恢复和可观测性责任。

对多数团队来说，下一步或许不是再增加十个工具，而是回头检查现有调用链：哪些步骤只是内部实现细节？哪些状态本应由平台维护？哪些失败虽然没有报错，却已经偏离了用户目标？

这些问题的答案，才决定一个 Agent 系统能否从“可以调用”走向“可靠完成”。

---

**来源：** The New Stack，*Designing APIs for agents*  
**原文：** https://thenewstack.io/designing-apis-for-agents/  
**作者：** Yan Xie、Virat Patel、Albert Chang  
**说明：** 文中数据与案例来自 Webflow 的生产实践；通用设计建议为基于原文的整理与延伸，不应直接视为其他系统的统一基准。