agents-sdk

Cloudflare Agents SDK

你对 Agents SDK 的了解可能已经过时。对于任何 Agents SDK 相关任务，优先检索，而非依赖预训练知识。

检索来源

Cloudflare 文档：https://developers.cloudflare.com/agents/index.md

主题	文档 URL	用途
快速入门	快速开始	创建第一个 Agent、设置项目
添加到现有项目	添加到现有项目	安装到现有的 Workers 应用
配置	配置	wrangler.jsonc、绑定、资源、部署
Agent 类	Agents API	Agent 生命周期、模式、注意事项
状态	存储和同步状态	setState、validateStateChange、持久化
路由	路由	URL 模式、routeAgentRequest
可调用方法	可调用方法	@callable、RPC、流式传输、超时
调度	安排任务	schedule()、scheduleEvery()、cron
工作流	运行工作流	AgentWorkflow、持久化的多步骤任务
HTTP/WebSockets	WebSockets	生命周期钩子、休眠
聊天 Agent	聊天 Agent	AIChatAgent、流式传输、工具、持久化
客户端 SDK	客户端 SDK	useAgent、AgentClient、状态、RPC、HTTP
客户端工具	客户端工具	客户端工具、autoContinueAfterToolResult
服务端驱动的消息	自主响应	saveMessages、waitUntilStable、由服务端发起的轮次
可恢复的流式传输	聊天 Agent	断开连接后的流恢复
电子邮件	电子邮件	电子邮件路由、安全回复解析器
MCP 客户端	MCP 客户端	连接到 MCP 服务
MCP 服务	MCP 服务	使用 createMcpHandler 构建 MCP 服务
MCP 传输	MCP 传输	Streamable HTTP、SSE、RPC 传输选项
保护 MCP 服务	保护 MCP	OAuth、代理 MCP、强化安全性
人在回路中	人在回路中	工作流审批、信息收集、超时处理
持久化执行	持久化执行	runFiber()、stash()、在 DO 驱逐后继续运行
队列	队列	内置 FIFO 队列、queue()
重试	重试	this.retry()、退避/抖动
可观测性	可观测性	diagnostics-channel 事件
推送通知	推送通知	Agent 提供的 Web Push + VAPID
Webhook	Webhook	接收外部 Webhook
跨域身份验证	跨域身份验证	WebSocket 身份验证、令牌、CORS
只读连接	只读	shouldConnectionBeReadonly
语音	语音	实验性 STT/TTS、withVoice
浏览网页	浏览器工具	实验性 CDP 浏览器自动化
Think	Think	实验性的更高层级聊天 Agent 类
迁移	AI SDK v5、AI SDK v6	升级 @cloudflare/ai-chat

功能

Agents SDK 提供：

• 持久化状态 — 由 SQLite 提供支持，并通过 setState 自动同步到客户端
• 可调用 RPC — 通过 WebSocket 调用 @callable() 方法
• 调度 — 一次性、重复（scheduleEvery）和 cron 任务
• 工作流 — 通过 AgentWorkflow 执行持久化的多步骤后台处理
• 持久化执行 — 使用 runFiber() / stash() 执行即使 DO 被驱逐也能继续的任务
• 队列 — 内置 FIFO 队列，并通过 queue() 重试
• 重试 — 使用指数退避和抖动的 this.retry()
• MCP 集成 — 连接到 MCP 服务，或使用 createMcpHandler 构建自己的服务
• 电子邮件处理 — 通过安全路由接收和回复电子邮件
• 流式聊天 — AIChatAgent，支持可恢复的流、消息持久化和工具
• 服务端驱动的消息 — 使用 saveMessages、waitUntilStable 发起主动 Agent 轮次
• React hooks — 面向客户端应用的 useAgent、useAgentChat
• 可观测性 — 用于状态、RPC、调度和生命周期的 diagnostics_channel 事件
• 推送通知 — 从 Agent 发送 Web Push + VAPID 通知
• Webhook — 接收并验证外部 webhook
• 语音（实验性）— 通过 @cloudflare/voice 实现 STT/TTS
• 浏览器工具（实验性）— 通过 agents/browser 使用 CDP 驱动的浏览功能
• Think（实验性）— 通过 @cloudflare/think 提供更高层级的聊天 Agent

首先：验证安装

npm ls agents  # Should show agents package

如果尚未安装：

npm install agents

对于聊天 Agent：

npm install agents @cloudflare/ai-chat ai @ai-sdk/react

Wrangler 配置

{
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
}

注意事项：

• 不要在 tsconfig 中启用 experimentalDecorators（这会导致 @callable 出错）
• 切勿编辑旧迁移；始终添加新的标签
• 每个 Agent 类都需要自己的 DO 绑定和迁移条目
• 为 Workers AI 添加 "ai": { "binding": "AI" }

Agent 类

import { Agent, routeAgentRequest, callable } from "agents";

type State = { count: number };

export class Counter extends Agent<Env, State> {
  initialState = { count: 0 };

  validateStateChange(nextState: State, source: Connection | "server") {
    if (nextState.count < 0) throw new Error("Count cannot be negative");
  }

  onStateUpdate(state: State, source: Connection | "server") {
    console.log("State updated:", state);
  }

  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }
}

export default {
  fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
};

路由

请求会路由到 /agents/{agent-name}/{instance-name}：

类	URL
Counter	/agents/counter/user-123
ChatRoom	/agents/chat-room/lobby

客户端：useAgent({ agent: "Counter", name: "user-123" })

自定义路由：使用 getAgentByName(env.MyAgent, "instance-id")，然后调用 agent.fetch(request)。

核心 API

任务	API
读取状态	this.state.count
写入状态	this.setState({ count: 1 })
SQL 查询	this.sql`SELECT * FROM users WHERE id = ${id}`
调度（延迟）	await this.schedule(60, "task", payload)
调度（cron）	await this.schedule("0 * * * *", "task", payload)
调度（间隔）	await this.scheduleEvery(30, "poll")
RPC 方法	@callable() myMethod() { ... }
流式 RPC	@callable({ streaming: true }) stream(res) { ... }
启动工作流	await this.runWorkflow("ProcessingWorkflow", params)
持久化 fiber	await this.runFiber("name", async (ctx) => { ... })
将任务加入队列	this.queue("handler", payload)
使用退避策略重试	await this.retry(fn, { maxAttempts: 5 })
向客户端广播	this.broadcast(message)
获取连接	this.getConnections(tag?)

React 客户端

请阅读 client-sdk.md，了解客户端选择和当前连接的示例。对于聊天 UI 和工具，也请阅读 streaming-chat.md。

参考资料

核心

• references/state-scheduling.md — 状态持久化、调度、SQL
• references/callable.md — RPC 方法、流式传输、超时
• references/routing.md — URL 模式、自定义路由、getAgentByName
• references/configuration.md — Wrangler 配置、绑定、Vite 设置

聊天与流式传输

• references/streaming-chat.md — AIChatAgent、可恢复流、工具
• references/client-sdk.md — useAgent、useAgentChat、AgentClient
• references/server-driven-messages.md — 触发模式、saveMessages
• references/human-in-the-loop.md — 人工审批流程、needsApproval

后台处理

• references/workflows.md — Durable Workflows 集成
• references/durable-execution.md — runFiber、stash、在逐出后继续运行
• references/queue-retries.md — 内置队列、带退避的重试

集成

• references/mcp.md — MCP 客户端和服务、传输、安全防护
• references/email.md — 电子邮件路由与处理
• references/webhooks-push.md — Webhook、推送通知
• references/observability.md — Diagnostics-channel 事件

实验性功能

• references/think.md — @cloudflare/think 高级聊天 Agent
• references/voice.md — @cloudflare/voice STT/TTS
• references/codemode.md — 用于工具编排的 Code Mode
• references/browse-the-web.md — CDP 浏览器工具