Agents API

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

概览

Agents SDK 提供两套主要 API:

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

注意

Agents 依赖 Cloudflare Durable Objects。请参阅 Configuration 了解如何添加所需的 bindings。

Agent 类

Agent 是一个继承自 Agent 基类的类:

TypeScript


import { Agent } from "agents";


class MyAgent extends Agent<Env, State> {

  // Your agent logic

}


export default MyAgent;

每个 Agent 可以有数百万个实例。每个实例都是一个独立运行的微型服务器,支持横向扩展。实例通过唯一标识符寻址(用户 ID、电子邮件、工单号等)。

注意

Agent 的实例是全局唯一的:给定相同的名称(或 ID),你总会得到同一个 Agent 实例。

这让你无需在请求之间同步状态:如果某个 Agent 实例代表特定用户、团队、频道或其他实体,你可以直接用该 Agent 实例来存储那个实体的状态。无需搭建集中式的会话存储。

如果客户端断开连接,你始终可以将其路由回完全相同的 Agent,从中断处继续。

生命周期

flowchart TD A[“onStart
(instance wakes up)”] –> B[“onRequest
(HTTP)”] A –> C[“onConnect
(WebSocket)”] A –> D[“onEmail”] C –> E[“onMessage ↔ send()
onError (on failure)”] 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)	状态变化时触发(来自服务端或客户端)

核心属性

属性	类型	描述
this.env	Env	环境变量与 bindings
this.ctx	ExecutionContext	请求的执行上下文
this.state	State	当前持久化的状态
this.sql	Function	在嵌入式 SQLite 上执行 SQL 查询

服务端 API 参考

功能	方法	文档
State	setState()、onStateChanged()、initialState	Store and sync state
Callable methods	@callable() 装饰器	Callable methods
Scheduling	schedule()、scheduleEvery()、getSchedules()、cancelSchedule()	Schedule tasks
Durable execution	runFiber()、stash()、onFiberRecovered()、keepAlive()、keepAliveWhile()	Durable execution
Queue	queue()、dequeue()、dequeueAll()、getQueue()	Queue tasks
WebSockets	onConnect()、onMessage()、onClose()、broadcast()	WebSockets
HTTP/SSE	onRequest()	HTTP and SSE
Email	onEmail()、replyToEmail()	Email routing
Workflows	runWorkflow()、waitForApproval()	Run Workflows
MCP Client	addMcpServer()、removeMcpServer()、getMcpServers()	MCP Client API
AI Models	Workers AI、OpenAI、Anthropic bindings	Using AI models
Protocol messages	shouldSendProtocolMessages()、isConnectionProtocolEnabled()	Protocol messages
Context	getCurrentAgent()	getCurrentAgent()
Observability	subscribe()、diagnostics channels、Tail Workers	Observability
Sub-agents	subAgent()、abortSubAgent()、deleteSubAgent()	Sub-agents
Sessions	Session.create()、上下文块、压缩、搜索	Sessions
Think	Think 基类、工作区工具、生命周期钩子、扩展	Think

SQL API

每个 Agent 实例都内置一个 SQLite 数据库,通过 this.sql 访问:

TypeScript


// 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。

客户端 API 参考

功能	方法	文档
WebSocket client	AgentClient	Client SDK
HTTP client	agentFetch()	Client SDK
React hook	useAgent()	Client SDK
Chat hook	useAgentChat()	Client SDK

快速示例

TypeScript


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 });

}

Explain Code

聊天 Agent

对于 AI 聊天应用,改为继承 AIChatAgent 而非 Agent:

TypeScript


import { AIChatAgent } from "agents/ai-chat-agent";


class ChatAgent extends AIChatAgent {

  async onChatMessage(onFinish) {

    // this.messages contains the conversation history

    // Return a streaming response

  }

}

特性包括:

内置消息持久化
自动可恢复流式传输(可在流中途重连)
可与 useAgentChat React hook 协同工作

完整教程请参阅 Build a chat agent。

路由

Agents 通过 URL 模式访问:


https://your-worker.workers.dev/agents/:agent-name/:instance-name

在 Worker 中使用 routeAgentRequest() 来路由请求:

TypeScript


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>;

Explain Code

参阅 Routing 了解自定义路径、CORS 与实例命名模式。

后续步骤

Quick start 用约 10 分钟构建你的第一个 Agent。

Configuration 了解 wrangler.jsonc 配置与部署。

WebSockets 与客户端进行实时双向通信。

Build a chat agent 使用 AIChatAgent 构建 AI 应用。

Keyboard shortcuts

从零构建 Cloudflare Agent