← 返回目录

Cloudflare Agents

官方

框架 / SDK

基于 Cloudflare Durable Objects 构建持久化、有状态 AI 智能体的开源 SDK,MCP 服务器/客户端能力是其众多内置功能之一。

这是用于开发 MCP Server 或 Agent 的框架，不是可以直接连接到客户端的 Server。

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 开发工具第 176 / 438
Stars: ★ 5.9k 非常热门
传输方式: SSE · Streamable HTTP
运行环境: Node.js 24+
凭据: 无需凭据
许可证: MIT
最近提交: 今天

56FMRS · C

cloudflare/agents 是 Cloudflare 官方维护、功能全面且持续更新的智能体开发 SDK,MCP 服务器/客户端支持是其众多内置能力之一而非唯一定位;文档与示例丰富,但仓库当前不接受外部 PR,且没有独立于代码之外的现成 MCP 安装配置。

最强项 · 维护活跃度 15/20 最弱项 · 可靠性 7/20

可靠性

7/20

安全与权限

11/20

维护活跃度

15/20

文档质量

14/20

安装易用性

9/20

查看各项评分依据

可靠性 7/20: 该仓库实际上是一个通用的 Cloudflare Agent SDK（状态管理、调度、语音、工作流、支付等众多功能),MCP 只是其中一项能力,并非单一可运行的 MCP 服务器。未提供 server manifest,仓库根目录并非明确的可执行入口,README 中虽提到 examples/mcp-server、mcp-worker 等示例目录,但未展示实际的 MCP 初始化/工具列表握手过程或工具行为验证。README 提到使用 vitest 与 vitest-pool-workers 及 Playwright 测试,说明存在测试基础设施,但未见具体 CI workflow 文件或测试覆盖 MCP 关键路径的证据,故按静态评审规则不能给出高分。
安全与权限 11/20: 框架涉及多项具有较高风险的能力:x402 支付协议(可能导致真实付款)、邮件收发、沙箱代码执行、MCP 客户端/服务端连接等,但 README 中并未具体说明这些能力的权限范围、最小权限设计或用户凭证如何被处理。唯一体现风险控制意识的是「Workflows」功能提到具备 human-in-the-loop 审批机制,说明部分不可逆操作设有确认环节,但未覆盖到支付、邮件等其他风险点的默认行为说明。没有发现明文密钥或严重红线问题,但整体权限与数据边界披露不足。
维护活跃度 15/20: 项目采用 pnpm workspace + Nx 进行任务编排,具备 changeset 发布流程、lint/typecheck/test 检查脚本,说明工程化程度较高、维护活跃。MIT 许可证明确,star 数高、issue 数量也表明有一定用户基础和活跃反馈,仓库未被归档。但 README 未展示具体的发布版本历史、安全响应渠道或漏洞披露流程,且项目声明「暂不接受外部 PR」,可能影响社区贡献活跃度,故未给满分。
文档质量 14/20: README 结构清晰,列出功能表、包结构、大量示例目录(30+ demo)、guides 与 design 决策记录,并链接到官方文档站点 developers.cloudflare.com/agents,整体文档层次较丰富。但本次评审仅能看到 README 本身,对于 MCP 相关功能(如具体工具参数、认证方式、速率限制、成本、故障排查)没有直接呈现,需要进一步查阅 examples/mcp-server 等目录才能验证,存在文档深度未验证的隐性假设。
安装易用性 9/20: README 给出了两种安装方式(模板创建或 npm install)以及 wrangler.jsonc 配置示例,步骤总体清晰,但这是构建一个通用 Agent 应用的流程,而非直接连接 MCP 客户端的说明,还需要 Cloudflare 账户、Durable Objects 绑定、SQLite migration 等额外配置,属于中等复杂度的多步骤安装,且仅支持 Cloudflare Workers 平台,平台兼容性有限。由于未提供可验证的执行记录(如实际连接客户端截图或 CI 验证),静态评审规则下不能给出高分。

静态评测 · 未实际运行收录于 2026-08-06

查看 FMRS 评分方法 →

选型与风险

能访问什么执行命令或代码访问网络连接数据库

适合谁

在 Cloudflare Workers/Durable Objects 平台上开发有状态 AI 智能体的 TypeScript 开发者
希望把自研 Agent 能力以 MCP 服务器形式对外提供的团队
需要调度、WebSocket、语音或工作流等一体化能力的智能体应用开发者

不适合谁

只想要一个开箱即用、可直接填入 Claude Desktop 配置的固定工具 MCP 服务器的用户
不使用 Cloudflare Workers/Durable Objects 作为部署目标的团队
希望通过提交 PR 参与代码贡献的外部开发者(仓库当前不接受外部 PR)

所需权限

Cloudflare 账户及已启用 SQLite 存储的 Durable Objects 权限
Workers 部署与绑定配置权限
按所用功能可能需要的 AI 模型调用凭据、邮件服务绑定等额外权限

风险与副作用

MCP 服务器/客户端能力由开发者自行实现,若未正确设计鉴权,可能暴露 Agent 状态或可调用方法
Code Mode 与沙箱化代码执行运行 LLM 生成的代码,隔离配置不当可能带来执行风险
Durable Object 绑定或 SQLite 迁移配置错误可能导致状态丢失或迁移失败
仓库不接受外部 PR,社区发现的问题只能通过 Issue 等待官方修复,响应速度不受贡献者控制

安装接入

准备工作

运行环境：Node.js 24+

在现有 Cloudflare Workers 项目中运行 npm install agents,或使用 npm create cloudflare@latest -- --template cloudflare/agents-starter 新建项目。将 Agent 类声明为 Durable Object,在 wrangler.jsonc 中配置对应的 durable_objects 绑定及 SQLite 迁移(new_sqlite_classes),并设置合适的 compatibility_date 与 nodejs_compat 标志。若要将某个 Agent 暴露为 MCP 服务器或作为 MCP 客户端连接其他服务,可参考仓库 examples/mcp* 目录中的示例代码自行实现,该功能没有独立的一键安装配置。

验证是否装好

这是用于构建 Agent 的 TypeScript SDK，不是可直接连接的 MCP 服务器。运行 npm install agents 后在代码中 import { Agent, routeAgentRequest } from "agents"，并按 wrangler.c 配置 Durable Object 绑定与 SQLite migration，本地启动后访问 Agent 路由返回状态即证明安装成功。

常见排障

确认 `wrangler.jsonc` 中的 `durable_objects` 绑定名称与迁移 `new_sqlite_classes` 中的类名完全一致
检查 `compatibility_date` 与 `nodejs_compat` 标志是否按 README 示例正确设置
构建仓库本身需要 Node 24+ 及 pnpm,可运行 `pnpm run check` 排查类型/格式/测试问题
参考 `examples/mcp*`、`examples/webmcp` 等目录中的示例代码定位 MCP 相关集成问题
查阅 `docs/` 与 `design/` 目录获取架构说明与设计决策记录

试试这样问

连接成功后，可以直接对 AI 助手这样说：

使用 cloudflare/agents-starter 模板创建一个新的 AI Agent 项目
帮我写一个继承 agents 包 Agent 类、带持久化计数状态的 TypeScript Agent
如何在 Cloudflare Agent 中把自己暴露为 MCP 服务器并连接 MCP 客户端？

使用场景

为每个用户/会话/房间创建独立的持久化、可休眠的智能体实例

将自定义 Agent 逻辑封装并对外暴露为 MCP 服务器

让 Agent 作为 MCP 客户端调用外部工具与其他 MCP 服务器

构建带状态同步、可调用方法的实时聊天或协作前端(React/原生 JS)

实现带人工审批环节的多步骤 durable 工作流

详细介绍

cloudflare/agents 是 Cloudflare 官方维护的 TypeScript SDK,用于在 Durable Objects 之上构建持久化、有状态的 AI 智能体(每个智能体拥有独立状态、存储与生命周期,空闲时休眠、按需唤醒)。它本身不是一个提供固定工具集的 MCP 服务器,而是一个应用框架:开发者可以用它把自己的 Agent 既作为 MCP 服务器对外暴露,也可以让 Agent 作为 MCP 客户端连接其他工具(支持 HTTP、SSE、RPC 与 elicitation)。除 MCP 外,SDK 还提供状态同步、可调用方法(RPC)、子智能体组合、任务调度、WebSocket 实时通信、AI 对话(含可续传流式响应)、WebMCP、durable 工作流(含人工审批)、邮件收发、语音管线、浏览器端智能体、Code Mode(LLM 生成可执行代码而非逐次工具调用)、沙箱化代码执行以及 x402 按次付费等能力。仓库以 pnpm workspace + Nx 管理多个包(核心 agents 包、ai-chat、think、codemode、shell、voice、worker-bundler、hono-agents),并提供 30 余个可独立运行的示例,其中包含多个 MCP 相关示例(mcp、mcp-client、mcp-server、mcp-worker、webmcp 等)。项目当前不接受外部 Pull Request,但欢迎通过 Issue 和 Discussion 反馈问题与需求。