Cloudflare Agents

Agent 是基于 Cloudflare Durable Objects 构建的持久化、有状态的执行环境，专为 Agent 工作负载而设计。每个 Agent 都拥有独立的状态、存储空间和生命周期，并内置了对实时通信、调度、AI 模型调用、MCP、工作流等功能的支持。

Agent 在空闲时会自动休眠，并在需要时唤醒。你可以运行数百万个 Agent——无论是按用户、按会话还是按游戏房间分配——且在不活跃时无需支付任何费用。

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

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

npm install agents

阅读文档 — 包含入门指南、API 参考、教程等更多内容。

快速示例

以下是一个计数器 Agent，具备持久化状态、可调用方法，并可与 React 前端实时同步：

// 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 (
    <div>
      {count}
      <button onClick={() => agent.stub.increment()}>+</button>
      <button onClick={() => agent.stub.decrement()}>-</button>
    </div>
  );
}

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

由于 Agent 是一个 Durable Object，因此它需要在 wrangler.jsonc 中进行绑定并进行 SQLite 迁移：

{
  "name": "counter",
  "main": "server.ts",
  "compatibility_date": "2026-01-28",
  "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 将浏览器端工具暴露给 Agent
工作流	具备人工干预（Human-in-the-loop）审批的持久化多步骤任务
电子邮件	通过 Cloudflare Email Service 发送、接收和回复邮件
语音	连续 STT（语音转文字）、流式 TTS（文字转语音）、VAD（语音活动检测）、打断及 SFU 工具
浏览器 Agent	使用 agents/browser 在浏览器标签页中运行 Agent
代码模式	LLM 生成可执行的 TypeScript 代码而非单个工具调用
沙箱执行	在具有虚拟文件系统的独立 Worker 中运行生成的代码
x402 支付	通过 x402 协议实现按调用付费的 API 和工具
可观测性	内置追踪、指标和结构化日志记录
SQL	通过 Durable Objects 进行直接的 SQLite 查询
React Hooks	使用 useAgent 实现 React 组件集成