本页概述 Agents SDK。各功能的详细文档请参阅链接的参考页。
Agents SDK 提供两个主要 API：
| API | 描述 |
|---|---|
服务端 Agent 类 |
封装 Agent 逻辑：连接、状态、方法、AI 模型、错误处理 |
| 客户端 SDK | AgentClient、useAgent 与 useAgentChat，用于从浏览器连接 |
Agent 是扩展基类 Agent 的类：
import { Agent, routeAgentRequest } from "agents";
export class MyAgent extends Agent<Env, State> {
// Your agent logic
}
export default {
async fetch(request: Request, env: Env) {
return (
(await routeAgentRequest(request, env)) ||
new Response("Not found", { status: 404 })
);
},
} satisfies ExportedHandler<Env>;每个 Agent 可有数百万实例。每个实例是独立运行的单独微服务器，实现水平扩展。实例由唯一标识符（user ID、email、工单号等）寻址。
flowchart TD
A["onStart<br/>（实例唤醒）"] --> B["onRequest<br/>（HTTP）"]
A --> C["onConnect<br/>(WebSocket)"]
A --> D["onEmail"]
C --> E["onMessage ↔ send()<br/>onError（失败时）"]
E --> F["onClose"]
| 方法 | 触发时机 |
|---|---|
onStart(props?) |
实例启动或从休眠中唤醒时。接收通过 getAgentByName 或 routeAgentRequest 传递的可选初始化 props。 |
onRequest(request) |
每个发往实例的 HTTP 请求 |
onConnect(connection, ctx) |
建立 WebSocket 连接时 |
onMessage(connection, message) |
收到每个 WebSocket 消息时 |
onError(connection, error) |
发生 WebSocket 错误时 |
onClose(connection, code, reason, wasClean) |
WebSocket 连接关闭时 |
onEmail(email) |
邮件路由到实例时 |
onStateChanged(state, source) |
状态变化时（来自 server 或 client） |
| 属性 | 类型 | 描述 |
|---|---|---|
this.env |
Env |
环境变量与绑定 |
this.ctx |
ExecutionContext |
请求的执行上下文 |
this.state |
State |
当前持久化状态 |
this.sql |
函数 | 在嵌入式 SQLite 上执行 SQL 查询 |
| 功能 | 方法 | 文档 |
|---|---|---|
| 状态 | setState(), onStateChanged(), initialState |
存储并同步状态 |
| 可调用方法 | @callable() 装饰器 |
Callable 方法 |
| 调度 | schedule(), scheduleEvery(), getScheduleById(), listSchedules() |
计划任务 |
| Durable 执行 | runFiber(), startFiber(), stash(), onFiberRecovered(), keepAlive(), keepAliveWhile() |
持久执行 |
| 队列 | queue(), dequeue(), dequeueAll(), getQueue() |
队列任务 |
| WebSockets | onConnect(), onMessage(), onClose(), broadcast() |
WebSockets |
| HTTP/SSE | onRequest() |
HTTP 和 SSE |
| 邮件 | onEmail(), replyToEmail() |
电子邮件路由 |
| Workflows | runWorkflow(), waitForApproval() |
运行 Workflows |
| MCP 客户端 | addMcpServer(), removeMcpServer(), getMcpServers() |
MCP 客户端 API |
| AI 模型 | Workers AI、OpenAI、Anthropic 绑定 | 模型 |
| 协议消息 | shouldSendProtocolMessages(), isConnectionProtocolEnabled() |
协议消息 |
| 上下文 | getCurrentAgent() |
getCurrentAgent() |
| 追踪 | wrapAISDK() |
追踪 |
| 诊断通道 | subscribe()、诊断通道 |
诊断通道 |
| 子 Agent | subAgent(), abortSubAgent(), deleteSubAgent() |
子 Agent |
| Agent 作为工具 | runAgentTool(), clearAgentToolRuns(), hasAgentToolRun() |
将 Agent 用作工具 |
| Agent Skills | SKILL.md 解析器、Workspace、R2 和清单源、脚本运行程序 |
Agent Skills |
| 会话 | Sessions 功能模块：消息历史、分支、压缩和搜索 |
Sessions |
| Think | Think 基类、工作区工具、生命周期钩子、扩展 |
Think |
| Chat SDK | createChatSdkState(), ChatSdkStateAgent |
Chat SDK |
每个 Agent 实例有通过 this.sql 访问的嵌入式 SQLite 数据库：
// Create tables
this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;
// Insert data
this.sql`INSERT INTO users (id, name) VALUES (${id}, ${name})`;
// Query data
const users = this.sql<User>`SELECT * FROM users WHERE id = ${id}`;对于需要与客户端同步的状态，请改用 State API。
| 功能 | 方法 | 文档 |
|---|---|---|
| WebSocket 客户端 | AgentClient |
客户端 SDK |
| HTTP 客户端 | agentFetch() |
客户端 SDK |
| React hook | useAgent() |
客户端 SDK |
| Chat hook | useAgentChat() |
客户端 SDK |
| Agent 工具事件 | useAgentToolEvents() |
将 Agent 用作工具 |
模块级 helper export 包括 agents/agent-tools 的 agentTool()，将 Think 或 AIChatAgent 子类转为 AI SDK tool 定义。
import { useAgent } from "agents/react";
import type { MyAgent } from "./server";
function App() {
const agent = useAgent<MyAgent, State>({
agent: "my-agent",
name: "user-123",
});
// Call methods on the agent
agent.stub.someMethod();
// Update state (syncs to server and all clients)
agent.setState({ count: 1 });
}AI 聊天应用请扩展 AIChatAgent 而非 Agent：
import { AIChatAgent } from "@cloudflare/ai-chat";
class ChatAgent extends AIChatAgent {
async onChatMessage(onFinish) {
// this.messages contains the conversation history
// Return a streaming response
}
}功能包括：
- 内置消息持久化
- 自动可恢复流式传输（重连 mid-stream）
- 与
useAgentChatReact hook 配合
完整教程请参阅构建 chat agent。
Agent 通过 URL 模式访问：
https://your-worker.workers.dev/agents/:agent-name/:instance-name在 Worker 中使用 routeAgentRequest() 路由请求：
import { routeAgentRequest } from "agents";
export default {
async fetch(request: Request, env: Env) {
return (
routeAgentRequest(request, env) ||
new Response("Not found", { status: 404 })
);
},
} satisfies ExportedHandler<Env>;自定义路径、CORS 和实例命名模式请参阅路由。
构建你的第一个 Durable Agent
在 Durable Object 中运行 Pi harness，为其提供工作区，并通过 WebSocket 连接。
WebSockets
与 client 的实时双向通信。
构建 chat agent
使用 AIChatAgent 构建 AI 应用。