cloudflare-agents

用途

Cloudflare Agents SDK 用于在 Cloudflare Workers + Durable Objects 上构建 AI 驱动的自主智能体。它定位为基础设施层，负责连接、状态与调度，而非 AI 推理本身。

主要能力

通过 WebSocket 与 Server-Sent Events 进行实时通信
使用内置 SQLite 数据库持久化状态（每个智能体最高 1GB）
使用延迟、指定日期或 cron 表达式调度任务
通过触发异步 Cloudflare Workflows 运行工作流
使用 Browser Rendering API + Puppeteer 浏览网页
结合 Vectorize 向量数据库与 Workers AI embeddings 实现 RAG
构建实现 Model Context Protocol 的 MCP 服务器
支持 human-in-the-loop 的审核与批准模式
扩展到全球数百万个独立智能体实例

每个智能体实例是全局唯一、有状态的微服务器，可运行数秒、数分钟或数小时。

使用方式

快速开始

使用模板脚手架创建项目：

npm create cloudflare@latest my-agent -- \
  --template=cloudflare/agents-starter \
  --ts \
  --git \
  --deploy false

或在现有 Worker 中添加：

cd my-existing-worker
npm install agents

创建 Agent 类：

// src/index.ts
import { Agent, AgentNamespace } from "agents";

export class MyAgent extends Agent {
  async onRequest(request: Request): Promise<Response> {
    return new Response("Hello from Agent!");
  }
}

export default MyAgent;

配置 Durable Objects 绑定（wrangler.jsonc）：

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-agent",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-21",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [
      {
        "name": "MyAgent",
        "class_name": "MyAgent"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["MyAgent"]
    }
  ]
}

关键配置规则：name 与 class_name 必须一致；new_sqlite_classes 必须放在首个 migration 中（之后无法添加）；Agent 类必须导出；migration tag 不可重复使用。

部署：

npx wrangler@latest deploy

与 AI 推理层组合

推荐组合：Agents SDK + Vercel AI SDK。

import { AIChatAgent } from "agents/ai-chat-agent";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

export class ChatAgent extends AIChatAgent<Env> {
  async onChatMessage(onFinish) {
    return streamText({
      model: openai('gpt-4o-mini'),
      messages: this.messages,
      onFinish
    }).toTextStreamResponse();
  }
}

也可搭配 Workers AI（需手动解析 SSE）：

const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
  messages: [...],
  stream: true
});

可恢复流式传输（agents@0.2.24+）

AIChatAgent 支持可恢复流式传输，客户端可重新连接并继续接收流式响应而不丢失数据。流在页面刷新、连接中断后仍保留，并在打开的标签页与设备间同步。使用 AIChatAgent 且版本为 agents@0.2.24 或更高时自动生效，无需修改代码。

适用场景

需要以下任一能力时使用 Agents SDK：WebSocket 双向实时通信、Durable Objects 有状态实例、内置状态持久化、多智能体协调、定时任务或 cron、human-in-the-loop 工作流、长时间运行的智能体、有状态工具执行的 MCP 服务器。

若仅需基础聊天界面、SSE 单向流式、无持久状态、单用户单会话，则直接使用 Vercel AI SDK 更简单。

限制

Agents SDK 不提供 AI 推理、不处理流式响应解析、不包含模型提供商集成。它需要配置 Durable Objects、migrations 与 bindings，代码量与搭建复杂度高于仅用 AI SDK。

版本与依赖

最新版本：agents@0.3.3、@modelcontextprotocol/sdk@latest。推荐依赖 cloudflare-worker-base。状态为 Production Ready，最后更新于 2026-01-09。

近期更新：2026 年 1 月 Agents SDK v0.3.6 修复 callable methods、更新协议版本支持；2025 年 11 月 v0.2.24+ 引入可恢复流式传输、MCP 客户端改进与调度修复；2025 年 9 月兼容 AI SDK v5 并自动迁移消息；2025 年 8 月支持 MCP Elicitation、http-streamable 传输、任务队列与邮件集成；2025 年 4 月支持 MCP（MCPAgent 类）；2025 年 3 月包名由 agents-sdk 更名为 agents。