cloudflare/agents
GitHub: cloudflare/agents
Cloudflare 推出的基于 Durable Objects 的 AI 智能体框架，提供持久化状态、实时通信和多模态能力，帮助开发者低成本构建和部署有状态的 AI Agent。
Stars: 5191 | Forks: 608
# Cloudflare Agents
[](https://www.npmjs.com/package/agents)
[](https://www.npmjs.com/package/agents)
Agents 是由 Cloudflare [Durable Objects](https://developers.cloudflare.com/durable-objects/) 驱动的，专为智能体工作负载设计的持久化、有状态的执行环境。每个 agent 都拥有自己的状态、存储和生命周期——并内置了对实时通信、调度、AI 模型调用、MCP、工作流等的支持。
Agents 在空闲时会休眠，并按需唤醒。你可以运行数百万个 agent——每个用户、每个会话、每个游戏房间各一个——它们在不活动时没有任何成本。
```
npm create cloudflare@latest -- --template cloudflare/agents-starter
```
或者添加到现有项目中：
```
npm install agents
```
**[阅读文档](https://developers.cloudflare.com/agents/)** — 入门指南、API 参考、使用指南等。
## 快速示例
一个带有持久化状态、可调用方法，并能与 React 前端实时同步的计数器 agent：
```
// server.ts
import { Agent, routeAgentRequest, callable } from "agents";
export type CounterState = { count: number };
export class CounterAgent extends Agent {
initialState = { count: 0 };
@callable()
increment() {
this.setState({ count: this.state.count + 1 });
return this.state.count;
}
@callable()
decrement() {
this.setState({ count: this.state.count - 1 });
return this.state.count;
}
}
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
return (
(await routeAgentRequest(request, env)) ??
new Response("Not found", { status: 404 })
);
}
};
```
```
// client.tsx
import { useAgent } from "agents/react";
import { useState } from "react";
import type { CounterAgent, CounterState } from "./server";
function Counter() {
const [count, setCount] = useState(0);
const agent = useAgent({
agent: "CounterAgent",
onStateUpdate: (state) => setCount(state.count)
});
return (
{count}
);
}
```
状态更改会自动同步到所有已连接的客户端。可以像调用本地函数一样调用其方法。
该 agent 是一个 Durable Object，因此它需要在 `wrangler.jsonc` 中进行 binding 并设置一个 SQLite 迁移：
```
{
"name": "counter",
"main": "server.ts",
"compatibility_date": "2026-06-11",
"compatibility_flags": ["nodejs_compat"],
"durable_objects": {
"bindings": [{ "name": "CounterAgent", "class_name": "CounterAgent" }]
},
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["CounterAgent"] }]
}
```
## 功能
| 功能 | 描述 |
| ----------------------- | ------------------------------------------------------------------------------- |
| **持久化状态** | 同步至所有已连接的客户端，在重启后依然保留 |
| **可调用方法** | 通过 `@callable()` 装饰器实现类型安全的 RPC |
| **子 Agent** | 通过 facets、嵌套路由和类型化的父级查找实现父/子 DO 组合 |
| **Agent 工具** | 将具备聊天功能的子 agent 作为工具运行，并带有流式子时间线 |
| **调度** | 一次性、周期性和基于 cron 的任务 |
| **WebSockets** | 带有生命周期钩子的实时双向通信 |
| **AI 聊天** | 消息持久化、可恢复的流式传输、服务端/客户端工具执行 |
| **MCP** | 作为 MCP 服务端或作为 MCP 客户端连接（HTTP, SSE, RPC, elicitation） |
| **WebMCP** | 通过 WebSocket 将浏览器端工具暴露给 agents |
| **工作流** | 带有人工审核的持久化多步骤任务 |
| **电子邮件** | 通过 Cloudflare Email Service 发送、接收和回复 |
| **语音** | 连续的 STT、流式 TTS、VAD、中断、SFU 实用工具 |
| **浏览器 Agent** | 使用 `agents/browser` 在浏览器标签页中运行 agents |
| **代码模式** | LLM 生成可执行的 TypeScript，而不是单次的工具调用 |
| **沙盒执行** | 在带有虚拟文件系统的隔离 Worker 中运行生成的代码 |
| **x402 支付** | 通过 x402 协议实现按调用付费的 API 和工具 |
| **可观测性** | 内置的 tracing、指标和结构化日志 |
| **SQL** | 通过 Durable Objects 进行直接 SQLite 查询 |
| **React Hooks** | 用于前端集成的 `useAgent`, `useAgentChat`, `useVoiceAgent` |
| **原生 JS 客户端** | 用于非 React 环境的 `AgentClient` 和 `VoiceClient` |
## 包
| 包 | 描述 |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [`agents`](packages/agents) | 核心 SDK — `Agent` 类、路由、状态、调度、MCP、电子邮件、工作流、x402、浏览器 agent |
| [`@cloudflare/ai-chat`](packages/ai-chat) | 更高级的 AI 聊天 — 持久化消息、可恢复流式传输、工具执行 |
| [`@cloudflare/think`](packages/think) | 预设的聊天 agent 基础 — 智能体循环、流恢复、客户端工具、workspace 工具 |
| [`@cloudflare/codemode`](packages/codemode) | LLM 编写调用你工具的可执行代码，而不是一次仅进行一次工具调用 |
| [`@cloudflare/shell`](packages/shell) | 面向 agents 的沙盒化 JS 执行 + 虚拟文件系统（`Workspace`） |
| [`@cloudflare/voice`](packages/voice) | 语音管道 — STT, TTS, VAD, 流式传输, SFU 实用工具 |
| [`@cloudflare/worker-bundler`](packages/worker-bundler) | 在运行时构建并打包 Workers，以配合 Worker Loader binding 使用 |
| [`hono-agents`](packages/hono-agents) | 用于将 agents 添加到 Hono 应用的 Hono 中间件 |
## 示例
[`examples/`](examples) 目录包含 30 多个独立的演示。以下是不完全一览：
- **展示** — [`playground/`](examples/playground) 是一个大杂烩应用：状态、可调用方法、调度、聊天、工具、MCP、工作流、电子邮件、语音——全部集成在一个 UI 中
- **聊天与助手** — [`assistant/`](examples/assistant), [`agents-as-tools/`](examples/agents-as-tools), [`agent-skills/`](examples/agent-skills), [`workspace-chat/`](examples/workspace-chat), [`resumable-stream-chat/`](examples/resumable-stream-chat), [`structured-input/`](examples/structured-input), [`dynamic-tools/`](examples/dynamic-tools), [`multi-ai-chat/`](examples/multi-ai-chat), [`context-overflow-recovery/`](examples/context-overflow-recovery)
- **MCP** — [`mcp/`](examples/mcp), [`mcp-client/`](examples/mcp-client), [`mcp-server/`](examples/mcp-server), [`mcp-worker/`](examples/mcp-worker), [`mcp-worker-authenticated/`](examples/mcp-worker-authenticated), [`mcp-elicitation/`](examples/mcp-elicitation), [`mcp-rpc-transport/`](examples/mcp-rpc-transport), [`webmcp/`](examples/webmcp)
- **代码模式与沙盒** — [`codemode/`](examples/codemode), [`codemode-mcp/`](examples/codemode-mcp), [`codemode-mcp-openapi/`](examples/codemode-mcp-openapi), [`dynamic-workers/`](examples/dynamic-workers), [`dynamic-workers-playground/`](examples/dynamic-workers-playground), [`worker-bundler-playground/`](examples/worker-bundler-playground)
- **语音** — [`voice-agent/`](examples/voice-agent), [`voice-input/`](examples/voice-input), [`elevenlabs-starter/`](examples/elevenlabs-starter)
- **工作流与审批** — [`workflows/`](examples/workflows), [`a2a/`](examples/a2a)
- **认证、支付、通信** — [`auth-agent/`](examples/auth-agent), [`cross-domain/`](examples/cross-domain), [`x402/`](examples/x402), [`x402-mcp/`](examples/x402-mcp), [`email-agent/`](examples/email-agent), [`github-webhook/`](examples/github-webhook), [`push-notifications/`](examples/push-notifications)
- **游戏与其他** — [`tictactoe/`](examples/tictactoe), [`ai-chat/`](examples/ai-chat)
使用 [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/) 的示例位于 [`openai-sdk/`](openai-sdk) 中。正在进行中的实验性项目位于 [`experimental/`](experimental) 中（无稳定性保证）。
在本地运行任意示例：
```
cd examples/playground
npm start
```
## 文档
- developers.cloudflare.com 上的[完整文档](https://developers.cloudflare.com/agents/)
- 本仓库的 [`docs/`](docs) 目录（上游同步）
- [Anthropic 模式指南](guides/anthropic-patterns) — 顺序、路由、并行、编排器、评估器
- [人工介入指南](guides/human-in-the-loop) — 带有暂停/恢复功能的审批工作流
- [`design/`](design) — 架构与设计决策记录（聊天 API、子 agent、agent 工具、workspace、语音、浏览器工具、重试等）
## 仓库结构
| 目录 | 描述 |
| ----------------------------------------------------- | -------------------------------------------------------- |
| [`packages/agents/`](packages/agents) | 核心 SDK |
| [`packages/ai-chat/`](packages/ai-chat) | AI 聊天层 |
| [`packages/think/`](packages/think) | 预设的聊天 agent 基础 |
| [`packages/codemode/`](packages/codemode) | 代码模式 |
| [`packages/shell/`](packages/shell) | 沙盒化执行 + 文件系统 |
| [`packages/voice/`](packages/voice) | 语音管道 |
| [`packages/worker-bundler/`](packages/worker-bundler) | 运行时 Workers 打包器 |
| [`packages/hono-agents/`](packages/hono-agents) | Hono 集成 |
| [`examples/`](examples) | 独立演示应用 |
| [`experimental/`](experimental) | 正在进行中的实验性项目（未发布） |
| [`openai-sdk/`](openai-sdk) | 使用 OpenAI Agents SDK 的示例 |
| [`guides/`](guides) | 深度模式教程 |
| [`docs/`](docs) | 同步至 developers.cloudflare.com 的 Markdown 文档 |
| [`site/`](site) | 已部署的网站（agents.cloudflare.com，AI playground） |
| [`design/`](design) | 架构与设计决策记录 |
| [`scripts/`](scripts) | 仓库级工具 |
## 开发
需要 Node 24+。使用 pnpm workspaces 配合 [Nx](https://nx.dev) 进行任务编排、缓存和受影响检测。
```
pnpm install # install all workspaces
pnpm run build # build all packages (Nx, cached, dependency-ordered)
pnpm run check # sherif + export checks + oxfmt + oxlint + typecheck
pnpm run test # vitest + vitest-pool-workers (Workers runtime)
pnpm run test:react # Playwright-based React hook tests
pnpm exec nx affected -t build # build only what changed
pnpm exec nx affected -t test # test only what changed
```
对 `packages/` 的更改需要添加一个 changeset：
```
pnpm exec changeset
```
请参阅 [`AGENTS.md`](AGENTS.md) 获取更深入的贡献者指南。
## 贡献
我们目前不接受外部 pull request — 该 SDK 正在快速发展，我们希望保持可控的表面积。话虽如此，我们非常乐意倾听你的声音：
- **Bug 报告与功能请求** — [创建 issue](https://github.com/cloudflare/agents/issues)
- **问题与想法** — [发起讨论](https://github.com/cloudflare/agents/discussions)
## 许可证
[MIT](LICENSE)标签：AI智能体, Cloudflare, MITRE ATT&CK, 开发框架, 暗色界面, 状态管理, 程序员工具, 自动化攻击