cloudflare/agents

Cloudflare Agents – 状态持久化、服务端 AI/工具代理

是什么 – 一个 TypeScript/JavaScript SDK，允许你在 Cloudflare Workers 上编写 Durable Objects，并将每个对象视为独立、长期运行的“代理”。代理拥有自己的持久化存储，可运行定时任务，保持 WebSocket 连接，调用 AI 模型，充当 MCP（多通道协议）服务器或客户端，并通过 @callable() 装饰器暴露类型安全的 RPC 方法。运行时会自动将空闲代理休眠，并在需要时唤醒，因此你可以以近乎零的空闲成本，启动数百万个用户或会话级代理。

核心概念

概念	提供的功能
持久状态	状态存储在 Cloudflare Durable Object 中，重启后仍保留；变更会自动同步到所有连接的客户端。
可调用方法	使用 `@callable()` 装饰类方法 – 它们会变成类型安全的 RPC 端点，可从浏览器或其他 Workers 调用。
子代理	代理可通过特性（facets）和嵌套路由组合其他代理（父/子），实现分层工作负载。
调度	可在代理内安排一次性、重复性或 cron 风格的任务。
WebSocket	内置实时双向通道，支持生命周期钩子。
AI 聊天与工具	内置聊天层（`@cloudflare/ai-chat`），支持消息持久化、可恢复流式传输，并可将子代理作为“工具”运行。
MCP / WebMCP	代理可暴露或消费多通道协议（HTTP、SSE、RPC 等），并桥接这些工具与浏览器。
工作流	支持暂停/恢复和审批步骤的多步骤、人机协作流程。
邮件与语音	直接集成 Cloudflare 邮件服务和语音管道（STT/TTS、VAD、SFU）。
代码模式	LLM 可生成调用你工具的 TypeScript 代码，生成的代码在沙箱 Worker（`@cloudflare/shell`）中运行。
支付（x402）	可通过 x402 协议对按调用计费的 API 进行计费。
可观测性	自动发出追踪、指标和结构化日志。
SQL	代理可直接在 Durable Object 内执行 SQLite 查询。
前端钩子	提供 React 钩子（`useAgent`、`useAgentChat`、`useVoiceAgent`）和原生 JS 客户端（`AgentClient`），便于集成。

单体仓库中的包

包	作用
`agents`	核心 SDK – 代理、路由、调度、MCP、工作流、语音、浏览器代理等
`@cloudflare/ai-chat`	高级聊天抽象，支持持久消息和工具执行
`@cloudflare/think`	带有“代理循环”和工作区工具的有观点聊天代理基类
`@cloudflare/codemode`	将 LLM 输出转换为可执行 TypeScript，调用你的工具
`@cloudflare/shell`	带虚拟文件系统的沙箱 JS 执行环境，用于安全的代码模式运行
`@cloudflare/voice`	语音 API 兼容包装器（已弃用，推荐使用核心 `agents/voice` 导出）
`@cloudflare/worker-bundler`	运行时打包 Workers，与 Worker-Loader 绑定一起使用
`hono-agents`	为 Hono Web 框架应用添加代理的中间件

典型用例

用户级助手 – 每个用户一个代理，存储对话历史、偏好，并运行定时提醒。
实时多人房间 – 每个游戏房间是一个代理，通过 WebSocket 同步状态给所有玩家。
工具调用 AI 助手 – LLM 调用子代理（如日历代理、搜索代理），并将结果流式返回给用户。
工作流自动化 – 复杂多步骤流程（如工单分类 → 人工审批 → 执行）可建模为持久工作流。
语音机器人 – 结合 STT/TTS 服务与代理，维护对话状态并调用其他工具。
按调用计费 API – 将函数暴露为 x402 计费端点；代理处理计费和限流。

快速开始（来自 README）

创建一个启动项目

npm create cloudflare@latest -- --template cloudflare/agents-starter

或向现有 Worker 添加 SDK
```
npm install agents
```
编写代理 – 继承 Agent 并使用 @callable() 标记方法（参见 README 中的计数器示例）。
在 wrangler.jsonc 中配置 Durable Objects（绑定名称、类名、SQLite 迁移标签）。
使用 Cloudflare Wrangler 部署，如同部署普通 Worker 一样。
从浏览器消费 – 使用 React 钩子 useAgent（或原生 AgentClient）调用方法并接收实时状态更新。

文档与学习资源

完整文档 – https://developers.cloudflare.com/agents/（入门指南、API 参考、教程）。
示例 – examples/ 目录下有 30+ 个自包含演示（游乐场、聊天助手、MCP 服务器/客户端、代码模式、语音管道、工作流等）。
设计文档 – design/ 包含架构决策记录和模式指南（Anthropic 模式、人机协作等）。
OpenAI SDK 示例 – openai-sdk/ 展示如何使用 OpenAI Agents JavaScript SDK 与 Cloudflare 代理集成。

开发工作流（贡献者）

Node 24+，pnpm 工作区，Nx 用于任务编排。
构建：pnpm run build（Nx 按依赖顺序构建包，缓存结果）。
检查：pnpm run check（lint + 类型检查）。
测试：pnpm run test（Vitest + Workers 运行时）和 pnpm run test:react（Playwright React 钩子测试）。
包变更需提交 changeset（pnpm exec changeset）。
外部 PR 目前不接受；团队更倾向于内部迭代，但欢迎提交 Issue 和讨论。

许可证

MIT – 宽松的开源许可证。

总结 – Cloudflare Agents 是一个生产级框架，用于构建可在 Cloudflare 边缘网络上大规模运行的状态持久化、服务端 AI 代理，原生支持实时同步、调度、工具调用、语音、邮件、支付等功能。