Cloudflare Agents

概要 – 一个 TypeScript/JavaScript SDK，可让您在 Cloudflare Durable Objects 上构建持久、有状态的“代理”。每个代理作为自己的 Durable Object 运行，拥有隔离的存储、生命周期钩子，并能在空闲时休眠。该平台增加了对实时同步、调度、AI 模型调用、工具执行、MCP（多通道协议）、语音、电子邮件、支付等的一流支持。

核心概念

概念	它为您提供什么
持久状态	代理在重启后保留数据，并自动同步到每个连接的客户端。
@callable() RPC	装饰类方法；它们成为类型安全的远程过程，您可以从浏览器像调用本地函数一样调用它们。
子代理	构建代理层级（父/子）以进行组合和路由。
调度	在代理内运行的一次性、重复或 cron 式作业。
WebSockets	具有生命周期事件的双向实时通道。
AI 聊天与工具	内置聊天层（`@cloudflare/ai-chat`），存储消息，支持可恢复流式传输，并可将其他代理作为工具运行。
MCP / WebMCP	用于 HTTP、SSE、RPC 或浏览器端工具桥接的通用多通道协议。
工作流	可暂停等待人工审批的多步骤持久任务。
语音与电子邮件	流式语音转文本/文本转语音管道，以及与 Cloudflare 电子邮件服务的集成。
支付（x402）	通过 x402 协议实现按调用付费的 API。
可观测性	内置跟踪、指标和结构化日志。
SQLite	直接查询每个代理的 SQLite 数据库。
React hooks 与 vanilla 客户端	用于 React 的 `useAgent`、`useAgentChat`、`useVoiceAgent`；用于纯 JavaScript 的 `AgentClient`。

典型用例

按用户或按会话状态 – 例如，一个个人助手，能在多次访问中记住用户的偏好。
实时协作应用 – 游戏房间、共享白板或仪表板，每个客户端都能立即看到相同的状态。
AI 驱动助手 – 调用 LLM、保留对话历史并调用工具代理（搜索、数据库等）的聊天代理。
定时后台工作 – 提醒、定期数据拉取或 cron 式作业，在用户数据附近运行。
语音机器人 – 端到端语音管道，可向代理流式传输音频或从代理接收音频。
工作流引擎 – 需要人工参与审批的多步骤流程。
按使用付费 API – 将函数作为 x402 定价的端点公开。

快速入门（快速步骤）

创建项目

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

将 SDK 添加到现有仓库
```
npm install agents
```
编写代理 – 扩展 Agent 并用 @callable() 标记方法（参见 README 计数器示例）。
在 wrangler.jsonc 中配置 Durable Objects（绑定名称、类名，以及如果需要的话 SQLite 迁移）。
部署 – 使用 wrangler publish（标准 Cloudflare Workers 工作流）。
从前端消费 – 使用 useAgent React hook 或 vanilla AgentClient 来调用方法并接收实时状态更新。

单仓库中的包

包	作用
`agents`	核心 SDK – 代理、路由、调度、MCP、工作流等。
`@cloudflare/ai-chat`	具有持久化和工具执行功能的高级聊天抽象。
`@cloudflare/think`	用于构建聊天助手的“代理循环”基础。
`@cloudflare/codemode`	让 LLM 生成可在沙箱 Worker 中运行的可执行 TypeScript。
`@cloudflare/worker-bundler`	在运行时打包 Workers 以支持动态代码加载。
`hono-agents`	将代理附加到 Hono Web 框架应用的中间件。
（已弃用）`@cloudflare/shell`、`@cloudflare/voice`	旧 API 的兼容包装器。

文档与学习资源

完整文档 – https://developers.cloudflare.com/agents/（入门、API 参考、指南）。
示例 – examples/ 下有 30 多个演示（playground、聊天助手、MCP、语音管道、工作流、支付、游戏等）。
指南 – Anthropic 模式、人工参与工作流、design/ 中的设计决策。
OpenAI SDK 示例 – openai-sdk/ 展示了如何将 OpenAI Agents JS SDK 与 Cloudflare Agents 结合使用。

谁在维护它？

由 Cloudflare 开发。该仓库使用 pnpm workspaces 和 Nx 进行构建和测试。目前贡献仅限于内部贡献者，但问题和讨论对社区开放。

许可证

MIT（见 LICENSE）。

cloudflare/agents