Cloudflare Agents
在 Cloudflare 上构建可持久化、可实时通信的有状态 AI Agent。
- Star 数
- ★ 5.8k
- 最近更新
- 2 天前
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 60/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 平台专用
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 需要为每位用户或每个会话保留独立状态的 SaaS 团队，可将每个 Agent 映射为一个 Durable Object，并在空闲时休眠。
- 不适合
- 需要把 Agent 部署在 Cloudflare 之外或自建运行时的团队
- 不愿维护 Durable Object 绑定与 SQLite 迁移配置的团队
- 希望提交外部 PR 参与共建的贡献者
- 源码审查
- 60/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
Cloudflare Agents 是一套基于 Durable Objects 的 TypeScript SDK，用于构建和部署具有独立状态、存储与生命周期的 Agent。核心 Agent 类提供持久状态、类型安全 RPC、定时任务、WebSocket、SQLite、MCP、工作流、邮件和可观测性等接口。仓库还包含 @cloudflare/ai-chat、@cloudflare/think、@cloudflare/codemode、@cloudflare/shell、@cloudflare/voice 等分层组件，以及 React 和原生 JavaScript 客户端。Agent 空闲时休眠、收到请求时唤醒，状态更新可自动同步到所有已连接客户端。它适合已经采用或愿意采用 Cloudflare Workers 与 Durable Objects 的团队；核心执行和部署边界明确依赖 Cloudflare 平台。
服务端通过继承 Agent<Env, State> 定义初始状态和生命周期，并用 @callable() 暴露可由客户端调用的类型安全方法；routeAgentRequest() 将传入的 Worker 请求路由到对应 Agent。Agent 可把状态保存到 Durable Object，并将变更实时同步给连接的 React 或原生 JavaScript 客户端。应用可通过 useAgent、useAgentChat、useVoiceAgent、AgentClient 或 VoiceClient 连接实例，还可运行一次性、周期性或 cron 任务。按需组合的模块支持持久聊天与可恢复流、服务端或客户端工具执行、MCP 客户端和服务器、带人工审批的持久工作流、语音管线、邮件、x402 支付及浏览器内 Agent。Code Mode 可让模型生成调用工具的 TypeScript，并由 @cloudflare/shell 在带虚拟文件系统的隔离 Worker 中执行。
- 需要为每位用户或每个会话保留独立状态的 SaaS 团队，可将每个 Agent 映射为一个 Durable Object，并在空闲时休眠。
- 构建实时多人房间、游戏房间或协作界面的前端团队，可使用 WebSocket 生命周期钩子和自动状态同步。
- 开发聊天助手的 TypeScript 团队，可用
@cloudflare/ai-chat保存消息、恢复流式响应，并协调服务端与客户端工具。 - 需要审批、暂停和恢复长任务的业务系统，可用 Workflows 实现持久化多步骤流程和 human-in-the-loop。
- 需要把 Agent 接入 MCP 工具生态的开发者，可将其作为 MCP 服务器，或通过 HTTP、SSE、RPC 与 elicitation 能力连接 MCP 服务。
- 构建语音助手或电话交互的团队，可采用
@cloudflare/voice的 STT、TTS、VAD、流式传输与中断处理能力。
如何安装或部署这个 Agent？
新项目可执行：npm create cloudflare@latest -- --template cloudflare/agents-starter。现有项目可执行：npm install agents。仓库开发要求 Node.js 24+，并使用 pnpm workspace；源码开发流程为 pnpm install、pnpm run build、pnpm run check 和 pnpm run test。来源未列出部署所需的 Cloudflare 凭据、登录命令或最终部署命令，因此这些步骤不能从给定材料中确定。
如何使用这个 Agent？
创建 class CounterAgent extends Agent<Env, CounterState>，设置 initialState = { count: 0 }，并用 @callable() 标记 increment()、decrement() 等远程方法。在 Worker 的 fetch 中调用 routeAgentRequest(request, env)。随后在 wrangler.jsonc 添加 Durable Object binding，例如名称和类名均为 CounterAgent，并在 migration 中用 new_sqlite_classes 注册该类；示例还使用 compatibility_date: "2026-06-11" 和 nodejs_compat。React 客户端通过 useAgent({ agent: "CounterAgent", onStateUpdate }) 连接，再调用 agent.stub.increment()。运行仓库示例可执行：cd examples/playground，然后执行 npm start。
这个 Agent 有哪些优点和局限？
- 每个 Agent 都有独立状态、存储和生命周期，状态可跨重启保留并实时同步到连接客户端。
- 在同一 SDK 体系内覆盖 RPC、调度、WebSocket、聊天、MCP、工作流、邮件、语音、支付、SQL 与可观测性，减少自行拼装基础设施的工作。
- 空闲实例可休眠并按需唤醒，适合按用户、会话或房间创建大量独立 Agent。
- 同时提供 React hooks 和原生 JavaScript 客户端，并通过 TypeScript 类型共享实现类型安全调用。
- 仓库包含 30 多个独立示例，以及架构设计记录和模式指南，覆盖多种具体集成场景。
- 核心状态与生命周期建立在 Cloudflare Durable Objects 上，迁移到其他运行时需要重新实现这些平台能力。
- 每个 Durable Object Agent 都需要 binding 和 SQLite migration，增加部署配置与迁移管理成本。
- 开发源码要求 Node.js 24+，并采用 pnpm 与 Nx，可能不符合使用其他 Node 版本或包管理器的团队标准。
- 旧的 AI chat 导入入口已弃用；现有项目需要迁移到
@cloudflare/ai-chat，新项目还需评估@cloudflare/think。 - 仓库当前不接受外部 pull request，外部团队只能通过 issue 或 discussion 提交反馈。
experimental/中的实验功能没有稳定性保证，不适合直接视为可靠的生产接口。
这个 Agent 与同类方案有什么区别？
仓库内部提供不同抽象层：agents 是底层核心 SDK；@cloudflare/ai-chat 聚焦持久消息、可恢复流和工具执行；@cloudflare/think 是更有约束的聊天 Agent 基类，并被推荐用于从零开始的新聊天项目。前端可在 React hooks 与非 React 的 AgentClient、VoiceClient 之间选择。旧的 agents/ai-chat-agent、agents/chat、agents/ai-react 和 agents/ai-types 入口仍会重新导出，但已弃用。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Cloudflare Agents 当前 | 60 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 5.8k | 2 天前 | TypeScript | — |
| Puppetmaster | 68 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 468 | 今天 | Python | Codex · Claude Code |
| Agently AI 应用运行时 | 63 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 1.7k | 5 天前 | Python | OpenAI API · Claude API |
| deepx-code | 63 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 393 | 27 天前 | Go | OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据展示了隔离执行、人工审批工作流、持久状态、外部邮件/支付/MCP能力以及通过环境秘密传入凭据；MIT文件和包作者字段也提供了来源线索。但没有系统说明最小权限、数据去向、秘密生命周期、外部操作逐项确认或可恢复回滚。Bonk工作流具有contents: write等较宽权限并引用浮动的@main动作，依赖安全材料也未展示审计、漏洞响应或供应链固定策略，因此多数信任项仅属薄弱覆盖。发布者身份仍按题设视为未知，未据此推断安全性。
README、包脚本、兼容性矩阵和少量测试对构建方式、AI SDK 6/7兼容及恢复状态顺序形成了较一致的静态证据，且Node、pnpm和主要依赖版本明确。扣分在于没有执行结果、可用性保证或广泛的错误信息示例；所给测试只覆盖超时传递和恢复状态，不能证明整体故障处理质量。
材料覆盖聊天、MCP、工作流、语音、浏览器、支付及多种客户端场景，并明确实验目录无稳定性保证、旧入口已弃用，同时给出完整的Workers、Durable Objects和本地开发配置。环境适配因此证据充分；但外部效果触发条件、路由授权边界以及不同能力何时应启用的精确定义不足，触发精度仅有基础示例支持。
README的信息架构、包/目录地图、安装命令、配置示例、30多个示例类别和开发命令都很完整，MIT许可由独立LICENSE文件确认。扣分来自快速演进和入口弃用所反映的命名稳定性风险、缺少集中FAQ和更全面的运行限制，以及仅见changeset流程和npm徽章而未见实际变更日志；维护渠道明确，但不接受外部PR且题设中的发布者身份未获企业注册验证。
快速示例可直接转化为服务端、客户端和wrangler配置，丰富示例与持久状态、实时同步、调度和工具集成显示出明显实用价值。广泛能力主要由README陈述，未由所给代码逐项支撑；成本方面仅有空闲时不收费的概括性主张，没有请求、存储、模型、语音或外部服务成本分析，故成本收益证据较弱。
核心定位可由README、package.json、工作流和测试相互对照，兼容范围、命令、许可证和部分恢复行为可追溯到具体文件。扣分在于大量功能和规模/成本陈述只有README摘要，所给代码覆盖面很窄，也没有独立来源；材料虽明确区分实验、弃用和正式路径，但未为全部营销性陈述标注证据或假设。
- 这是未执行代码或测试的静态审查；不能据此确认运行时安全、正确性、确定性或部署可用性。
- 部署前应核查Bonk工作流的写权限、浮动@main第三方动作及秘密暴露面，并尽可能固定动作版本和缩小权限。
- 邮件、支付、MCP、生成代码和沙箱功能会产生外部效果或处理敏感数据；应在应用层补充授权、确认、审计、数据保留和恢复策略。
- “空闲时不收费”不代表整体零成本；需另行评估Durable Objects、存储、AI模型、语音及第三方服务费用。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
Patch Changes - [#2571](https://github.com/cloudflare/agents/pull/2571) [1bd2bc5](https://github.com/cloudflare/agents/commit/1bd2bc5d5e90e963c4d7db52cb9ef1a95153b99e) Thanks [@mattzcarey](https://github.com/mattzcarey)! - createAI (agents/models/ai-sdk, agents/models/pi-ai) adds the zdr gateway option, and vendorKey: "request" for AI SDK models routed with your own vendor key. See [docs/agents/models.md](https://github.com/cloudflare/agents/blob/main/docs/agents/models.md#unified-billing-and-byok). …在 GitHub 查看 ↗ -
发布说明摘录
Patch Changes - [#2472](https://github.com/cloudflare/agents/pull/2472) [7945da9](https://github.com/cloudflare/agents/commit/7945da9c6e142119e296984fc9caadec41e182a5) Thanks [@mattzcarey](https://github.com/mattzcarey)! - ToolSetConnector now forwards each AI SDK tool's outputSchema into its connector descriptors, so durable codemode.describe() shows the output type instead of unknown, as McpConnector already does. Input and output schemas that convert asynchronously (jsonSchema(promise)) are now awaited instead of being dropped. …在 GitHub 查看 ↗ -
发布说明摘录
This release adds two new tools, browser via agents/browser/{pi,ai-sdk,tanstack-ai} allowing an agent to create and manipulate a persistent browser session and web_fetch via agents/webfetch/{pi,ai-sdk,tanstack-ai} that can retrieve most document formats converted into markdown. Minor Changes …在 GitHub 查看 ↗
常见问题
是否可以不使用 Cloudflare 部署？
MCP 是运行 Agent 的必要条件吗？
空闲 Agent 是否持续占用执行资源？
能否直接用于 React 之外的前端？
useAgent、useAgentChat 和 useVoiceAgent 外，仓库还提供面向非 React 环境的 AgentClient 和 VoiceClient。采用实验功能有什么风险？
experimental/ 明确用于开发中的实验且没有稳定性保证；生产系统应优先选择已发布的 packages，并单独评估升级风险。