Cloudflare Agents

Agents 是为代理型工作负载提供支持的持久化、有状态执行环境，由 Cloudflare 的 Durable Objects 提供技术支持。每个 Agent 都拥有独立的状态、存储和生命周期，并内置对实时通信、任务调度、AI 模型调用、MCP、工作流等功能的支持。

Agent 在空闲时会休眠，并在需要时唤醒。您可以运行数百万个 Agent——每个用户、每个会话或每个游戏房间对应一个——当它们处于非活动状态时，不会产生任何费用。

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

或者将它添加到现有项目中：

npm install agents

阅读文档 — 包括入门指南、API 参考、教程等。

快速示例

一个带有持久化状态、可调用方法并能与 React 前端实现实时同步的计数器 Agent：

// server.ts
import { Agent, routeAgentRequest, callable } from "agents";

export type CounterState = { count: number };

export class CounterAgent extends Agent<Env, CounterState> {
  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<CounterAgent, CounterState>({
    agent: "CounterAgent",
    onStateUpdate: (state) => setCount(state.count)
  });

  return (
    <div>
      <span>{count}</span>
      <button onClick={() => agent.stub.increment()}>+</button>
      <button onClick={() => agent.stub.decrement()}>-</button>
    </div>
  );
}

状态变化会自动同步到所有已连接的客户端。您可以像调用本地函数一样调用这些方法。

功能特性

功能	描述
持久化状态	自动同步到所有连接的客户端，重启后仍能保留状态
可调用方法	通过 @callable() 装饰器实现类型安全的 RPC
任务调度	支持一次性、周期性和基于 Cron 的任务
WebSockets	实时双向通信，并提供生命周期钩子
AI 聊天	消息持久化、可恢复的流式传输、服务器端/客户端工具执行
MCP	可作为 MCP 服务器运行，也可作为 MCP 客户端连接
工作流	支持人工介入审批的持久化多步骤任务
电子邮件	通过 Cloudflare 邮件路由接收和响应邮件
代码模式	LLMs 可生成可执行的 TypeScript 代码，而非单独的工具调用
SQL	通过 Durable Objects 直接执行 SQLite 查询
React 钩子	useAgent 和 useAgentChat 用于前端集成
Vanilla JS 客户端	AgentClient 适用于非 React 环境

即将推出： 实时语音 Agent、网页浏览（无头浏览器）、沙盒化代码执行以及多渠道通信（SMS、即时通讯应用）。

包列表

包	描述
agents	核心 SDK — Agent 类、路由、状态管理、任务调度、MCP、电子邮件、工作流
@cloudflare/ai-chat	高级 AI 聊天功能 — 持久化消息、可恢复流式传输、工具执行
hono-agents	Hono 中间件，用于将 Agents 集成到 Hono 应用程序中
@cloudflare/codemode	实验性功能 — LLMs 可编写可执行代码来编排工具

示例

在 examples/ 目录中，您会找到涵盖大多数 SDK 功能的自包含演示——包括 MCP 服务器/客户端、工作流、邮件 Agent、Webhook、井字棋、可恢复流式传输等。而 playground 则是一个集大成的展示，将所有功能整合在一个 UI 中。

此外，在 openai-sdk/ 目录下，还有使用 OpenAI Agents SDK 的示例。

您可以在本地运行任意示例：

cd examples/playground
npm run dev

文档

• 完整文档 位于 developers.cloudflare.com
• 本仓库中的 docs/ 目录（与上游同步）
• Anthropic 模式指南 — 顺序执行、路由、并行处理、编排者、评估者
• 人类介入指南 — 带有暂停/恢复功能的审批工作流

仓库结构

目录	描述
packages/agents/	核心 SDK
packages/ai-chat/	AI 聊天层
packages/hono-agents/	Hono 集成
packages/codemode/	代码模式（实验性）
examples/	自包含的演示应用
openai-sdk/	使用 OpenAI Agents SDK 的示例
guides/	深入的模式教程
docs/	与 developers.cloudflare.com 同步的 Markdown 文档
site/	部署的网站（agents.cloudflare.com、AI 实验室）
design/	架构和设计决策记录
scripts/	仓库范围内的工具链

开发

需要 Node 24+。使用 npm 工作区。

npm install          # 安装所有工作区
npm run build        # 构建所有包
npm run check        # 全面的 CI 检查（格式化、 lint、类型检查、导出）
CI=true npm test     # 运行测试（vitest + vitest-pool-workers）

对 packages/ 的更改需要创建变更集：

npx changeset

更多贡献者指南，请参阅 AGENTS.md。

贡献

目前我们不接受外部 Pull Request —— SDK 正在快速演进，我们希望保持 API 表面的可控性。不过，我们非常乐意听取您的意见：

• Bug 报告与功能请求 — 提交 Issue
• 问题与想法 — 发起讨论

许可证

MIT

Cloudflare Agents 快速上手指南

Cloudflare Agents 是基于 Durable Objects 构建的有状态、持久化执行环境，专为 AI 智能体（Agentic）工作负载设计。支持实时通信、定时任务、AI 模型调用及工作流编排，闲置时自动休眠以节省成本。

环境准备

• Node.js: 版本 24 或更高 (Node 24+)
• 包管理器: 推荐使用 npm (项目使用 npm workspaces)
• Cloudflare 账号: 需拥有 Cloudflare 账号以便部署和使用 Durable Objects

安装步骤

你可以选择创建一个全新的项目，或将 Agents 集成到现有项目中。

方案一：创建新项目（推荐）

使用官方模板快速初始化一个包含完整配置的项目：

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

方案二：集成到现有项目

在现有的 Cloudflare Workers 项目中安装核心 SDK：

npm install agents

提示：国内开发者若遇到 npm 下载缓慢，可临时切换至淘宝镜像源：

npm config set registry https://registry.npmmirror.com

基本使用

以下示例展示如何创建一个具有持久化状态的计数器 Agent，并通过 React 前端进行实时同步和调用。

1. 服务端代码 (server.ts)

定义 Agent 类，使用 @callable() 装饰器暴露可调用的方法，并管理内部状态。

// server.ts
import { Agent, routeAgentRequest, callable } from "agents";

export type CounterState = { count: number };

export class CounterAgent extends Agent<Env, CounterState> {
  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 })
    );
  }
};

2. 客户端代码 (client.tsx)

在 React 组件中使用 useAgent Hook 连接 Agent。状态变更会自动同步到所有连接的客户端，方法调用如同本地函数一样简单。

// 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<CounterAgent, CounterState>({
    agent: "CounterAgent",
    onStateUpdate: (state) => setCount(state.count)
  });

  return (
    <div>
      <span>{count}</span>
      <button onClick={() => agent.stub.increment()}>+</button>
      <button onClick={() => agent.stub.decrement()}>-</button>
    </div>
  );
}

3. 运行与测试

启动开发服务器即可体验实时状态同步：

npm run dev

此时，多个客户端连接同一 Agent 实例时，任意一方的计数操作都会实时反映在其他所有客户端上。