在 Cloudflare 上构建 Agent

如今的大多数 AI 应用都是无状态的 — 处理一个请求、返回响应,然后忘记一切。真正的 agent 需要更多。它们需要记住对话、按时执行任务、调用工具、与其他 agent 协作,并与用户保持实时连接。Agents SDK 把这一切以一个 TypeScript 类的形式提供给你。

每个 agent 运行在一个 Durable Object 上 — 一个有状态的微服务器,自带 SQL 数据库、WebSocket 连接和调度能力。一次部署,Cloudflare 会在全球网络上运行你的 agent,可扩展至数千万实例。无需管理基础设施,无需重建会话,无需把状态外置。

入门

三条命令搞定一个运行中的 agent。无需 API key — starter 默认使用 Workers AI。

Terminal 窗口


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

cd agents-starter && npm install

npm run dev

starter 包含流式 AI 聊天、服务端和客户端工具、人工介入审批,以及任务调度 — 一个你可以在其上扩展或拆解的基础。你也可以接入 OpenAI、Anthropic、Google Gemini 或任何其他 provider。

构建聊天 agent 一步步走一遍 starter 并演示如何定制。

添加到现有项目把 agents 包装到 Workers 项目中并接好路由。

Agent 能做什么

记住一切 — 每个 agent 都有内置的 SQL 数据库和键值状态,实时同步到连接的客户端。状态挺过重启、部署和休眠。
构建 AI 聊天 — AIChatAgent 提供流式 AI 聊天,自动持久化消息、可恢复的流以及工具支持。配合 useAgentChat React hook,几分钟就能搭出聊天 UI。
用任意模型思考 — 调用任意 AI 模型 — Workers AI、OpenAI、Anthropic、Gemini — 并通过 WebSockets 或 Server-Sent Events 流式响应。需要数分钟响应的长时间推理模型也开箱即用。
使用并提供工具 — 定义服务端工具、运行在浏览器中的客户端工具,以及人工介入审批流程。通过 MCP 把 agent 的工具暴露给其他 agent 和 LLM。
自主行动 — 调度任务,按延迟、特定时间或 cron 触发。Agent 可以自己唤醒、做工作,然后再回到睡眠 — 不需要用户在场。
浏览网页 — 给你的 agent 配备由 Chrome DevTools Protocol 驱动的浏览器工具,抓取、截图、调试和与网页交互。
与用户对话 — 构建实时语音 agent,支持语音转文字、文字转语音和会话持久化 — 音频通过 WebSocket 流式传输。
协调工作 — 运行多步工作流,自动重试,或在多个 agent 之间协作。
响应事件 — 处理入站邮件、HTTP 请求、WebSocket 消息和状态变化 — 全部在同一个类中完成。

工作原理

agent 就是一个 TypeScript 类。用 @callable() 标记的方法变成类型化的 RPC,客户端可以直接通过 WebSocket 调用。

JavaScript
TypeScript

JavaScript


import { Agent, callable } from "agents";


export class CounterAgent extends Agent {

  initialState = { count: 0 };


  @callable()

  increment() {

    this.setState({ count: this.state.count + 1 });

    return this.state.count;

  }

}

Explain Code

TypeScript


import { Agent, callable } from "agents";


export class CounterAgent extends Agent<Env, { count: number }> {

  initialState = { count: 0 };


  @callable()

  increment() {

    this.setState({ count: this.state.count + 1 });

    return this.state.count;

  }

}

Explain Code


import { useAgent } from "agents/react";


function Counter() {

  const [count, setCount] = useState(0);

  const agent = useAgent({

    agent: "CounterAgent",

    onStateUpdate: (state) => setCount(state.count),

  });


  return <button onClick={() => agent.stub.increment()}>{count}</button>;

}

Explain Code

对于 AI 聊天,改为继承 AIChatAgent。消息会自动持久化,流在断开后可恢复,React hook 处理 UI。

JavaScript
TypeScript

JavaScript


import { AIChatAgent } from "@cloudflare/ai-chat";

import { createWorkersAI } from "workers-ai-provider";

import { streamText, convertToModelMessages } from "ai";


export class ChatAgent extends AIChatAgent {

  async onChatMessage() {

    const workersai = createWorkersAI({ binding: this.env.AI });

    const result = streamText({

      model: workersai("@cf/zai-org/glm-4.7-flash"),

      messages: await convertToModelMessages(this.messages),

    });

    return result.toUIMessageStreamResponse();

  }

}

Explain Code

TypeScript


import { AIChatAgent } from "@cloudflare/ai-chat";

import { createWorkersAI } from "workers-ai-provider";

import { streamText, convertToModelMessages } from "ai";


export class ChatAgent extends AIChatAgent {

  async onChatMessage() {

    const workersai = createWorkersAI({ binding: this.env.AI });

    const result = streamText({

      model: workersai("@cf/zai-org/glm-4.7-flash"),

      messages: await convertToModelMessages(this.messages),

    });

    return result.toUIMessageStreamResponse();

  }

}

Explain Code

完整流程参阅快速开始,完整聊天 API 参阅聊天 agent 指南,完整 SDK 参阅 Agents API 参考。