Cloudflare Agents

Agents（智能体）是专为 Agent 工作负载设计的持久化、有状态执行环境，由 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 接收并回复邮件
代码模式	LLM 生成可执行的 TypeScript 而非单个工具调用
SQL	通过 Durable Objects 进行直接 SQL 查询
React Hooks	提供 useAgent 和 useAgentChat 用于前端集成
原生 JS 客户端	为非 React 环境提供 AgentClient

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

软件包

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

示例

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