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 {
  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.stub.increment()}>+
       agent.stub.decrement()}>-
    
  );
}

状态变更会自动同步至所有已连接的客户端。调用方法就像调用本地函数一样简单。

功能特性

功能特性	描述
持久化状态	同步至所有已连接客户端，且在重启后依然留存
可调用方法	通过 @callable() 装饰器实现的类型安全 RPC
任务调度	支持一次性、周期性及 cron 表达式任务
WebSockets	具备生命周期钩子的实时双向通信
AI 聊天	消息持久化、可恢复的流式传输、服务器/客户端工具执行
MCP	可作为 MCP 服务器，也可作为 MCP 客户端连接其他服务
工作流	支持包含人工介入审批的持久化多步骤任务
邮件	通过 Cloudflare Email Routing 接收和响应邮件
代码模式 (Code Mode)	让 LLM 生成可执行的 TypeScript 代码，而非单独的工具调用
SQL	通过 Durable Objects 进行直接 SQLite 查询
React Hooks	提供 useAgent 和 useAgentChat 用于前端集成
原生 JS 客户端	为非 React 环境提供 AgentClient

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

软件包

软件包	描述
agents	核心 SDK — Agent 类、路由、状态、调度、MCP、邮件、工作流
@cloudflare/ai-chat	高阶 AI 聊天 — 持久化消息、可恢复流式传输、工具执行
hono-agents	用于将 Agent 添加到 Hono 应用的中间件
@cloudflare/codemode	实验性功能 — 让 LLM 编写可执行代码来编排工具

示例

examples/ 目录包含了涵盖大部分 SDK 功能的独立演示程序，包括 MCP 服务器/客户端、工作流、邮件 Agent、Webhooks、井字棋游戏、可恢复流式传输等。playground 是一个集大成的展示项目，在一个界面中整合了所有功能。