Cloudflare Agents
在 Cloudflare 上构建可持久化、可实时通信的有状态 AI 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模型、语音及第三方服务费用。
这个 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 有哪些优点和局限？
- 每个 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？
新项目可执行：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 与同类方案有什么区别？
仓库内部提供不同抽象层：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 入口仍会重新导出，但已弃用。
常见问题
是否可以不使用 Cloudflare 部署？
MCP 是运行 Agent 的必要条件吗？
空闲 Agent 是否持续占用执行资源？
能否直接用于 React 之外的前端？
useAgent、useAgentChat 和 useVoiceAgent 外，仓库还提供面向非 React 环境的 AgentClient 和 VoiceClient。采用实验功能有什么风险？
experimental/ 明确用于开发中的实验且没有稳定性保证；生产系统应优先选择已发布的 packages，并单独评估升级风险。