⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

Cloudflare AI Agents 构建指南：创建有状态、实时通信的智能体与聊天机器人

building-ai-agent-on-cloudflare by cloudflare/cloudflare-docs

45 周安装量

4,500 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/cloudflare/cloudflare-docs --skill building-ai-agent-on-cloudflare

AI/机器学习云服务开发运维

🇨🇳中文介绍

构建 Cloudflare Agents

使用 Cloudflare 的 Agents SDK 创建具有持久状态、实时通信和工具集成的 AI 驱动的智能体。

何时使用

用户想要构建一个 AI 智能体或聊天机器人
用户需要具有状态的、实时的 AI 交互
用户询问关于 Cloudflare Agents SDK 的信息
用户想要安排定时任务或后台 AI 工作
用户需要基于 WebSocket 的 AI 通信

先决条件

已启用 Workers 的 Cloudflare 账户
Node.js 18+ 和 npm/pnpm/yarn
Wrangler CLI (npm install -g wrangler)

快速开始

npm create cloudflare@latest -- my-agent --template=cloudflare/agents-starter
cd my-agent
npm start

Agent 运行在 http://localhost:8787

核心概念

什么是 Agent？

Agent 是一个有状态的、持久的 AI 服务，它：

跨请求和重连保持状态
通过 WebSockets 或 HTTP 进行通信
通过 Durable Objects 在 Cloudflare 边缘运行
可以安排任务和调用工具
水平扩展（每个用户/会话获得自己的实例）

Agent 生命周期

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

983,700 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

305,300 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

174,900 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

162,100 周安装

客户端连接 → Agent.onConnect() → Agent 处理消息
                                    → Agent.onMessage()
                                    → Agent.setState() (持久化 + 同步)
客户端断开连接 → 状态持久化 → 客户端重新连接 → 状态恢复

import { Agent, Connection } from "agents";

interface Env {
  AI: Ai;  // Workers AI binding
}

interface State {
  messages: Array<{ role: string; content: string }>;
  preferences: Record<string, string>;
}

export class MyAgent extends Agent<Env, State> {
  // 新实例的初始状态
  initialState: State = {
    messages: [],
    preferences: {},
  };

  // 当 agent 启动或恢复时调用
  async onStart() {
    console.log("Agent started with state:", this.state);
  }

  // 处理 WebSocket 连接
  async onConnect(connection: Connection) {
    connection.send(JSON.stringify({
      type: "welcome",
      history: this.state.messages,
    }));
  }

  // 处理传入消息
  async onMessage(connection: Connection, message: string) {
    const data = JSON.parse(message);

    if (data.type === "chat") {
      await this.handleChat(connection, data.content);
    }
  }

  // 处理断开连接
  async onClose(connection: Connection) {
    console.log("Client disconnected");
  }

  // 响应状态变化
  onStateUpdate(state: State, source: string) {
    console.log("State updated by:", source);
  }

  private async handleChat(connection: Connection, userMessage: string) {
    // 将用户消息添加到历史记录
    const messages = [
      ...this.state.messages,
      { role: "user", content: userMessage },
    ];

    // 调用 AI
    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
      messages,
    });

    // 更新状态（持久化并同步到所有客户端）
    this.setState({
      ...this.state,
      messages: [
        ...messages,
        { role: "assistant", content: response.response },
      ],
    });

    // 发送响应
    connection.send(JSON.stringify({
      type: "response",
      content: response.response,
    }));
  }
}

// src/index.ts
import { routeAgentRequest } from "agents";
import { MyAgent } from "./agent";

export default {
  async fetch(request: Request, env: Env) {
    // routeAgentRequest 处理路由到 /agents/:class/:name
    return (
      (await routeAgentRequest(request, env)) ||
      new Response("Not found", { status: 404 })
    );
  },
};

export { MyAgent };

客户端通过以下方式连接：wss://my-agent.workers.dev/agents/MyAgent/session-id

name = "my-agent"
main = "src/index.ts"
compatibility_date = "2024-12-01"

[ai]
binding = "AI"

[durable_objects]
bindings = [{ name = "AGENT", class_name = "MyAgent" }]

[[migrations]]
tag = "v1"
new_classes = ["MyAgent"]

// 当前状态始终可用
const currentMessages = this.state.messages;
const userPrefs = this.state.preferences;

// setState 会持久化并同步到所有连接的客户端
this.setState({
  ...this.state,
  messages: [...this.state.messages, newMessage],
});

// 部分更新也有效
this.setState({
  preferences: { ...this.state.preferences, theme: "dark" },
});

对于复杂查询，使用嵌入式 SQLite 数据库：

// 创建表
await this.sql`
  CREATE TABLE IF NOT EXISTS documents (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    content TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`;

// 插入
await this.sql`
  INSERT INTO documents (title, content)
  VALUES (${title}, ${content})
`;

// 查询
const docs = await this.sql`
  SELECT * FROM documents WHERE title LIKE ${`%${search}%`}
`;

Agents 可以安排未来的工作：

async onMessage(connection: Connection, message: string) {
  const data = JSON.parse(message);

  if (data.type === "schedule_reminder") {
    // 安排从现在起 1 小时后的任务
    const { id } = await this.schedule(3600, "sendReminder", {
      message: data.reminderText,
      userId: data.userId,
    });

    connection.send(JSON.stringify({ type: "scheduled", taskId: id }));
  }
}

// 当定时任务触发时调用
async sendReminder(data: { message: string; userId: string }) {
  // 发送通知、邮件等
  console.log(`Reminder for ${data.userId}: ${data.message}`);

  // 也可以更新状态
  this.setState({
    ...this.state,
    lastReminder: new Date().toISOString(),
  });
}

// 延迟秒数
await this.schedule(60, "taskMethod", { data });

// 特定日期
await this.schedule(new Date("2025-01-01T00:00:00Z"), "taskMethod", { data });

// Cron 表达式（重复）
await this.schedule("0 9 * * *", "dailyTask", {});  // 每天上午 9 点
await this.schedule("*/5 * * * *", "everyFiveMinutes", {});  // 每 5 分钟

// 管理定时任务
const schedules = await this.getSchedules();
await this.cancelSchedule(taskId);

聊天 Agent（AI 驱动）

对于专注于聊天的 agents，请扩展 AIChatAgent：

import { AIChatAgent } from "agents/ai-chat-agent";

export class ChatBot extends AIChatAgent<Env> {
  // 为每条用户消息调用
  async onChatMessage(message: string) {
    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        ...this.messages,  // 自动历史记录管理
        { role: "user", content: message },
      ],
      stream: true,
    });

    // 将响应流式传输回客户端
    return response;
  }
}

自动消息历史记录
可恢复的流式传输（在断开连接后仍可继续）
内置 saveMessages() 用于持久化

import { useAgent } from "agents/react";

function Chat() {
  const { state, send, connected } = useAgent({
    agent: "my-agent",
    name: userId,  // Agent 实例 ID
  });

  const sendMessage = (text: string) => {
    send(JSON.stringify({ type: "chat", content: text }));
  };

  return (
    <div>
      {state.messages.map((msg, i) => (
        <div key={i}>{msg.role}: {msg.content}</div>
      ))}
      <input onKeyDown={(e) => e.key === "Enter" && sendMessage(e.target.value)} />
    </div>
  );
}

const ws = new WebSocket("wss://my-agent.workers.dev/agents/MyAgent/user123");

ws.onopen = () => {
  console.log("Connected to agent");
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Received:", data);
};

ws.send(JSON.stringify({ type: "chat", content: "Hello!" }));

请参阅 references/agent-patterns.md 了解：

工具调用和函数执行
多智能体编排
RAG（检索增强生成）
人工介入工作流

# 部署
npx wrangler deploy

# 查看日志
wrangler tail

# 测试端点
curl https://my-agent.workers.dev/agents/MyAgent/test-user

常见问题请参阅 references/troubleshooting.md。

references/examples.md — 官方模板和生产示例
references/agent-patterns.md — 高级模式
references/state-patterns.md — 状态管理策略
references/troubleshooting.md — 错误解决方案

🇺🇸English

Building Cloudflare Agents

Creates AI-powered agents using Cloudflare's Agents SDK with persistent state, real-time communication, and tool integration.

When to Use

User wants to build an AI agent or chatbot
User needs stateful, real-time AI interactions
User asks about the Cloudflare Agents SDK
User wants scheduled tasks or background AI work
User needs WebSocket-based AI communication

Prerequisites

Cloudflare account with Workers enabled
Node.js 18+ and npm/pnpm/yarn
Wrangler CLI (npm install -g wrangler)

Quick Start

npm create cloudflare@latest -- my-agent --template=cloudflare/agents-starter
cd my-agent
npm start

Agent runs at http://localhost:8787

Core Concepts

What is an Agent?

An Agent is a stateful, persistent AI service that:

Maintains state across requests and reconnections
Communicates via WebSockets or HTTP
Runs on Cloudflare's edge via Durable Objects
Can schedule tasks and call tools
Scales horizontally (each user/session gets own instance)

Agent Lifecycle

Client connects → Agent.onConnect() → Agent processes messages
                                    → Agent.onMessage()
                                    → Agent.setState() (persists + syncs)
Client disconnects → State persists → Client reconnects → State restored

Basic Agent Structure

import { Agent, Connection } from "agents";

interface Env {
  AI: Ai;  // Workers AI binding
}

interface State {
  messages: Array<{ role: string; content: string }>;
  preferences: Record<string, string>;
}

export class MyAgent extends Agent<Env, State> {
  // Initial state for new instances
  initialState: State = {
    messages: [],
    preferences: {},
  };

  // Called when agent starts or resumes
  async onStart() {
    console.log("Agent started with state:", this.state);
  }

  // Handle WebSocket connections
  async onConnect(connection: Connection) {
    connection.send(JSON.stringify({
      type: "welcome",
      history: this.state.messages,
    }));
  }

  // Handle incoming messages
  async onMessage(connection: Connection, message: string) {
    const data = JSON.parse(message);

    if (data.type === "chat") {
      await this.handleChat(connection, data.content);
    }
  }

  // Handle disconnections
  async onClose(connection: Connection) {
    console.log("Client disconnected");
  }

  // React to state changes
  onStateUpdate(state: State, source: string) {
    console.log("State updated by:", source);
  }

  private async handleChat(connection: Connection, userMessage: string) {
    // Add user message to history
    const messages = [
      ...this.state.messages,
      { role: "user", content: userMessage },
    ];

    // Call AI
    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
      messages,
    });

    // Update state (persists and syncs to all clients)
    this.setState({
      ...this.state,
      messages: [
        ...messages,
        { role: "assistant", content: response.response },
      ],
    });

    // Send response
    connection.send(JSON.stringify({
      type: "response",
      content: response.response,
    }));
  }
}

Entry Point Configuration

// src/index.ts
import { routeAgentRequest } from "agents";
import { MyAgent } from "./agent";

export default {
  async fetch(request: Request, env: Env) {
    // routeAgentRequest handles routing to /agents/:class/:name
    return (
      (await routeAgentRequest(request, env)) ||
      new Response("Not found", { status: 404 })
    );
  },
};

export { MyAgent };

Clients connect via: wss://my-agent.workers.dev/agents/MyAgent/session-id

Wrangler Configuration

name = "my-agent"
main = "src/index.ts"
compatibility_date = "2024-12-01"

[ai]
binding = "AI"

[durable_objects]
bindings = [{ name = "AGENT", class_name = "MyAgent" }]

[[migrations]]
tag = "v1"
new_classes = ["MyAgent"]

State Management

Reading State

// Current state is always available
const currentMessages = this.state.messages;
const userPrefs = this.state.preferences;

Updating State

// setState persists AND syncs to all connected clients
this.setState({
  ...this.state,
  messages: [...this.state.messages, newMessage],
});

// Partial updates work too
this.setState({
  preferences: { ...this.state.preferences, theme: "dark" },
});

SQL Storage

For complex queries, use the embedded SQLite database:

// Create tables
await this.sql`
  CREATE TABLE IF NOT EXISTS documents (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    content TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`;

// Insert
await this.sql`
  INSERT INTO documents (title, content)
  VALUES (${title}, ${content})
`;

// Query
const docs = await this.sql`
  SELECT * FROM documents WHERE title LIKE ${`%${search}%`}
`;

Scheduled Tasks

Agents can schedule future work:

async onMessage(connection: Connection, message: string) {
  const data = JSON.parse(message);

  if (data.type === "schedule_reminder") {
    // Schedule task for 1 hour from now
    const { id } = await this.schedule(3600, "sendReminder", {
      message: data.reminderText,
      userId: data.userId,
    });

    connection.send(JSON.stringify({ type: "scheduled", taskId: id }));
  }
}

// Called when scheduled task fires
async sendReminder(data: { message: string; userId: string }) {
  // Send notification, email, etc.
  console.log(`Reminder for ${data.userId}: ${data.message}`);

  // Can also update state
  this.setState({
    ...this.state,
    lastReminder: new Date().toISOString(),
  });
}

Schedule Options

// Delay in seconds
await this.schedule(60, "taskMethod", { data });

// Specific date
await this.schedule(new Date("2025-01-01T00:00:00Z"), "taskMethod", { data });

// Cron expression (recurring)
await this.schedule("0 9 * * *", "dailyTask", {});  // 9 AM daily
await this.schedule("*/5 * * * *", "everyFiveMinutes", {});  // Every 5 min

// Manage schedules
const schedules = await this.getSchedules();
await this.cancelSchedule(taskId);

Chat Agent (AI-Powered)

For chat-focused agents, extend AIChatAgent:

import { AIChatAgent } from "agents/ai-chat-agent";

export class ChatBot extends AIChatAgent<Env> {
  // Called for each user message
  async onChatMessage(message: string) {
    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        ...this.messages,  // Automatic history management
        { role: "user", content: message },
      ],
      stream: true,
    });

    // Stream response back to client
    return response;
  }
}

Features included:

Automatic message history
Resumable streaming (survives disconnects)
Built-in saveMessages() for persistence

Client Integration

React Hook

import { useAgent } from "agents/react";

function Chat() {
  const { state, send, connected } = useAgent({
    agent: "my-agent",
    name: userId,  // Agent instance ID
  });

  const sendMessage = (text: string) => {
    send(JSON.stringify({ type: "chat", content: text }));
  };

  return (
    <div>
      {state.messages.map((msg, i) => (
        <div key={i}>{msg.role}: {msg.content}</div>
      ))}
      <input onKeyDown={(e) => e.key === "Enter" && sendMessage(e.target.value)} />
    </div>
  );
}

Vanilla JavaScript

const ws = new WebSocket("wss://my-agent.workers.dev/agents/MyAgent/user123");

ws.onopen = () => {
  console.log("Connected to agent");
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Received:", data);
};

ws.send(JSON.stringify({ type: "chat", content: "Hello!" }));

Common Patterns

See references/agent-patterns.md for:

Tool calling and function execution
Multi-agent orchestration
RAG (Retrieval Augmented Generation)
Human-in-the-loop workflows

Deployment

# Deploy
npx wrangler deploy

# View logs
wrangler tail

# Test endpoint
curl https://my-agent.workers.dev/agents/MyAgent/test-user

Troubleshooting

See references/troubleshooting.md for common issues.

References

references/examples.md — Official templates and production examples
references/agent-patterns.md — Advanced patterns
references/state-patterns.md — State management strategies
references/troubleshooting.md — Error solutions

Weekly Installs

Repository

cloudflare/clou…are-docs

GitHub Stars

4.5K

First Seen

Feb 8, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

gemini-cli43

opencode43

codex43

kimi-cli42

github-copilot42

amp41

Azure Data Explorer (Kusto) 查询技能：KQL数据分析、日志遥测与时间序列处理

161,200 周安装

Cloudflare AI Agents 构建指南：创建有状态、实时通信的智能体与聊天机器人

🇨🇳中文介绍

构建 Cloudflare Agents

何时使用

先决条件

快速开始

核心概念

什么是 Agent？

Agent 生命周期

相关 Skills

基本 Agent 结构

入口点配置

Wrangler 配置

状态管理

读取状态

更新状态

SQL 存储

定时任务

定时选项

聊天 Agent（AI 驱动）

客户端集成

React Hook

原生 JavaScript

常见模式

部署

故障排除

参考资料

🇺🇸English

Building Cloudflare Agents

When to Use

Prerequisites

Quick Start

Core Concepts

What is an Agent?

Agent Lifecycle

Basic Agent Structure

Entry Point Configuration

Wrangler Configuration

State Management

Reading State

Updating State

SQL Storage

Scheduled Tasks

Schedule Options

Chat Agent (AI-Powered)

Client Integration

React Hook

Vanilla JavaScript

Common Patterns

Deployment

Troubleshooting

References

最新 Skills