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 客户端	提供 AgentClient 用于非 React 环境

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

程序包

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

示例

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