agents-sdk

Cloudflare Agents SDK

你对 Agents SDK 的了解可能已过时。对于任何 Agents SDK 任务，优先检索而非预训练。

检索来源

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

主题	文档 URL	用途
入门	快速开始	第一个智能体，项目设置
添加到现有项目	添加到现有项目	安装到现有 Workers 应用
配置	配置	wrangler.jsonc、绑定、资源、部署
Agent 类	Agents API	Agent 生命周期、模式、陷阱
状态	存储和同步状态	setState、validateStateChange、持久化
路由	路由	URL 模式、routeAgentRequest
可调用方法	可调用方法	@callable、RPC、流式、超时
调度	调度任务	schedule()、scheduleEvery()、cron
工作流	运行工作流	AgentWorkflow、持久化多步骤任务
HTTP/WebSocket	WebSocket	生命周期钩子、休眠
聊天智能体	聊天智能体	AIChatAgent、流式、工具、持久化
客户端 SDK	客户端 SDK	useAgent、useAgentChat、React 钩子
客户端工具	客户端工具	客户端工具、autoContinueAfterToolResult
服务器驱动消息	触发模式	saveMessages、waitUntilStable、服务器发起轮次
可恢复流式	可恢复流式	断连时的流恢复
邮件	邮件	邮件路由、安全回复解析器
MCP 客户端	MCP 客户端	连接到 MCP 服务器
MCP 服务器	MCP 服务器	使用 McpAgent 构建 MCP 服务器
MCP 传输	MCP 传输	Streamable HTTP、SSE、RPC 传输选项
保护 MCP 服务器	保护 MCP	OAuth、代理 MCP、加固
人机协同	人机协同	审批流程、needsApproval、工作流
持久化执行	持久化执行	runFiber()、stash()、在 DO 驱逐后存活
队列	队列	内置 FIFO 队列、queue()
重试	重试	this.retry()、退避/抖动
可观测性	可观测性	诊断通道事件
推送通知	推送通知	来自智能体的 Web Push + VAPID
Webhook	Webhook	接收外部 Webhook
跨域认证	跨域认证	WebSocket 认证、令牌、CORS
只读连接	只读	shouldConnectionBeReadonly
语音	语音	实验性 STT/TTS、withVoice
浏览网页	浏览器工具	实验性 CDP 浏览器自动化
思考	思考	实验性高级聊天智能体类
迁移	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 服务器或使用 McpAgent 构建自己的服务器
• 邮件处理 — 接收和回复邮件，支持安全路由
• 流式聊天 — AIChatAgent 支持可恢复流、消息持久化、工具
• 服务器驱动消息 — saveMessages、waitUntilStable 用于主动智能体轮次
• React 钩子 — useAgent、useAgentChat 用于客户端应用
• 可观测性 — diagnostics_channel 事件用于状态、RPC、调度、生命周期
• 推送通知 — 来自智能体的 Web Push + VAPID 投递
• Webhook — 接收和验证外部 Webhook
• 语音（实验性）— 通过 @cloudflare/voice 实现 STT/TTS
• 浏览器工具（实验性）— 通过 agents/browser 实现 CDP 驱动的浏览
• 思考（实验性）— 通过 @cloudflare/think 实现高级聊天智能体

首先：验证安装

npm ls agents  # 应显示 agents 包

如果未安装：

npm install agents

对于聊天智能体：

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）
• 永远不要编辑旧的迁移——始终添加新标签
• 每个智能体类需要自己的 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)
持久化纤程	await this.runFiber("name", async (ctx) => { ... })
入队工作	this.queue("handler", payload)
带退避重试	await this.retry(fn, { maxAttempts: 5 })
广播给客户端	this.broadcast(message)
获取连接	this.getConnections(tag?)

React 客户端

import { useAgent } from "agents/react";

function App() {
  const [state, setLocalState] = useState({ count: 0 });

  const agent = useAgent({
    agent: "Counter",
    name: "my-instance",
    onStateUpdate: (newState) => setLocalState(newState),
    onIdentity: (name, agentType) => console.log(`Connected to ${name}`)
  });

  return (
    <button onClick={() => agent.setState({ count: state.count + 1 })}>
      Count: {state.count}
    </button>
  );
}

参考资料

核心

• 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 — 持久化工作流集成
• 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 — 诊断通道事件

实验性

• references/think.md — @cloudflare/think 高级聊天智能体
• references/voice.md — @cloudflare/voice STT/TTS
• references/codemode.md — 用于工具编排的代码模式
• references/browse-the-web.md — CDP 浏览器工具