Cloudflare Agents SDK：把有状态 AI Agent 部署到边缘运行时
Cloudflare 面向 Workers 推出的 Agent 开发与运行框架，以 Durable Objects 承载身份、状态、实时连接和定时任务。
Cloudflare Agents SDK agent-framework ai-infrastructure serverless-compute open-source Cloudflare 面向 Workers 推出的 Agent 开发与运行框架，以 Durable Objects 承载身份、状态、实时连接和定时任务。
1. 项目定位
Cloudflare Agents SDK 是面向 Cloudflare Workers 的 JavaScript/TypeScript Agent 框架。官方在 2025 年 2 月首次发布 agents-sdk，目标是让开发者把能持续保存状态、接收事件并执行任务的 Agent 直接部署到 Cloudflare，而不必另建一套会话服务器。[S1]
2. 要解决的问题
普通无状态函数适合一次请求一次响应，但 Agent 往往要记住用户状态、维持实时连接、等待计划任务，并在多轮交互后继续工作。SDK 把这些运行时问题放到 Durable Objects 上处理，让每个 Agent 实例拥有独立身份、存储和生命周期。[S1][S2]
3. 核心抽象
开发者继承 Agent 类定义服务端逻辑，再通过请求路由把流量交给对应实例。状态变化可同步给客户端，方法可以像远程调用一样触发；官方仓库还提供聊天、调度、SQL、工作流和 MCP 等示例，便于从最小实例逐步扩展。[S2]
4. 状态与连接
SDK 依托 Durable Objects 保存状态，并支持 WebSocket 实时连接。实例空闲时可以休眠，需要时再被请求或事件唤醒。这个模型适合聊天会话、游戏角色、个人助理或需要长期上下文的自动化任务，但状态结构仍应由应用团队明确设计。[S1][S2]
5. 模型与工具边界
Agents SDK 负责运行、状态和通信，不替开发者决定模型、提示词或业务权限。团队可以接入 Workers AI 或其他模型服务，并为 Agent 配置工具；模型质量、工具返回值和第三方 API 可用性仍是独立风险，不能由运行时自动消除。
6. 开放与依赖边界
核心代码在 Cloudflare 官方 GitHub 仓库公开，便于审查实现与跟踪版本。[S2] 但实际托管路径深度依赖 Workers、Durable Objects 及其配置，迁移到其他云时不能只复制业务类，还要重做状态、路由、连接和调度层。
7. 适用场景
它适合每用户独立状态的对话助手、实时协作、定时跟进和带工具调用的内部 Agent。若任务只是一次性文本生成，直接调用模型 API 更简单；没有持久状态需求时，引入 Agent 实例会增加运维面。
8. 落地路径
先用官方 starter 建一个只有单一状态字段的测试 Agent，再接入真实模型与一项低风险工具。随后定义实例命名、状态迁移、超时和权限边界，最后才接入生产数据与长任务。
9. 验收建议
验收应覆盖断线重连后状态是否一致、并发更新是否丢失、实例休眠后能否恢复、计划任务是否只执行一次，以及越权工具调用是否被拒绝。还要记录每个任务的模型费用、执行时间和失败位置；只有恢复性与权限测试都通过，才适合扩大流量。
10. 来源与更新时间
本文截至 2026-08-12，依据 Cloudflare 首发说明与官方代码仓库整理。