Agents API 参考

本页概述 Agents SDK。各功能的详细文档请参阅链接的参考页。

概览

Agents SDK 提供两个主要 API：

API	描述
服务端 `Agent` 类	封装 Agent 逻辑：连接、状态、方法、AI 模型、错误处理
客户端 SDK	`AgentClient`、`useAgent` 与 `useAgentChat`，用于从浏览器连接

Agent 类

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`	Function	在嵌入式 SQLite 上执行 SQL 查询

服务端 API 参考

功能	方法	文档
状态	`setState()`、`onStateChanged()`、`initialState`	存储与同步状态
可调用方法	`@callable()` 装饰器	可调用方法
调度	`schedule()`、`scheduleEvery()`、`getScheduleById()`、`listSchedules()`	调度任务
Durable 执行	`runFiber()`、`startFiber()`、`stash()`、`onFiberRecovered()`、`keepAlive()`、`keepAliveWhile()`	Durable 执行
队列	`queue()`、`dequeue()`、`dequeueAll()`、`getQueue()`	队列任务
WebSockets	`onConnect()`、`onMessage()`、`onClose()`、`broadcast()`	WebSockets
HTTP/SSE	`onRequest()`	HTTP 与 SSE
邮件	`onEmail()`、`replyToEmail()`	邮件路由
Workflows	`runWorkflow()`、`waitForApproval()`	运行 Workflows
MCP Client	`addMcpServer()`、`removeMcpServer()`、`getMcpServers()`	MCP Client API
AI 模型	Workers AI、OpenAI、Anthropic 绑定	使用 AI 模型
协议消息	`shouldSendProtocolMessages()`、`isConnectionProtocolEnabled()`	协议消息
上下文	`getCurrentAgent()`	getCurrentAgent()
可观测性	`subscribe()`、diagnostics channel、Tail Workers	可观测性
Sub-agent	`subAgent()`、`abortSubAgent()`、`deleteSubAgent()`	Sub-agent
Agent 作为工具	`runAgentTool()`、`clearAgentToolRuns()`、`hasAgentToolRun()`	Agent 作为工具
Agent Skills	`skills` registry、bundled skill 源、script runner	Agent Skills
会话	`Session.create()`、context block、compaction、search	会话
Think	`Think` 基类、工作区工具、生命周期钩子、扩展	Think
Chat SDK	`createChatSdkState()`、`ChatSdkStateAgent`	Chat SDK

SQL API

每个 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}`;

需与客户端同步的状态请改用状态 API。

客户端 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 });
}

Chat Agent

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）
与 useAgentChat React 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>;

自定义 path、CORS 与实例命名模式请参阅路由。

下一步

快速入门

约 10 分钟构建第一个 Agent。

配置

了解 wrangler.jsonc 设置与部署。

WebSockets

与 client 的实时双向通信。

构建 chat agent

使用 AIChatAgent 构建 AI 应用。