agents-sdk

Cloudflare Agents SDK

停止。 关于 Agents SDK 的知识可能已过时。处理任何 Agents SDK 任务时，应优先检索，而非依赖预训练知识。

文档

开始实现前，请从 https://github.com/cloudflare/agents/tree/main/docs 获取最新文档。

主题	文档	用途
入门	docs/getting-started.md	第一个 Agent、项目设置
状态	docs/state.md	setState、validateStateChange、持久化
路由	docs/routing.md	URL 模式、routeAgentRequest、basePath
可调用方法	docs/callable-methods.md	@callable、RPC、流式传输、超时
调度	docs/scheduling.md	schedule()、scheduleEvery()、cron
工作流	docs/workflows.md	AgentWorkflow、持久化多步骤任务
HTTP/WebSockets	docs/http-websockets.md	生命周期钩子、休眠
电子邮件	docs/email.md	电子邮件路由、安全回复解析器
MCP 客户端	docs/mcp-client.md	连接到 MCP 服务
MCP 服务	docs/mcp-servers.md	使用 McpAgent 构建 MCP 服务
客户端 SDK	docs/client-sdk.md	useAgent、useAgentChat、React 钩子
人机协作	docs/human-in-the-loop.md	审批流程、暂停工作流
可恢复流式传输	docs/resumable-streaming.md	断开连接时恢复流

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

功能

Agents SDK 提供：

• 持久化状态 - 由 SQLite 支持，并自动同步到客户端
• 可调用 RPC - 通过 WebSocket 调用 @callable() 方法
• 调度 - 一次性、重复（scheduleEvery）和 cron 任务
• 工作流 - 通过 AgentWorkflow 执行持久化的多步骤后台处理
• MCP 集成 - 连接到 MCP 服务，或使用 McpAgent 构建自己的服务
• 电子邮件处理 - 通过安全路由接收和回复电子邮件
• 流式聊天 - 支持可恢复流的 AIChatAgent
• React 钩子 - 用于客户端应用的 useAgent、useAgentChat

首先：验证安装

npm ls agents  # Should show agents package

如果尚未安装：

npm install agents

Wrangler 配置

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

Agent 类

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

type State = { count: number };

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

  // Validation hook - runs before state persists (sync, throwing rejects the update)
  validateStateChange(nextState: State, source: Connection | "server") {
    if (nextState.count < 0) throw new Error("Count cannot be negative");
  }

  // Notification hook - runs after state persists (async, non-blocking)
  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" })

核心 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)

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/workflows.md - 持久化工作流集成
• references/callable.md - RPC 方法、流式传输、超时
• references/state-scheduling.md - 状态持久化、调度
• references/streaming-chat.md - AIChatAgent、可恢复流
• references/mcp.md - MCP 服务集成
• references/email.md - 电子邮件路由和处理
• references/codemode.md - Code Mode（实验性）