使用 Agents SDK 构建的每个代理都运行在 Durable Object上。运行时负责协调启动、传入事件和计划任务。你的功能或 harness 会使用存储的状态,在中断后恢复:
- Lifecycle(
agents/lifecycle)负责启动、分发每个请求和 WebSocket 事件,并管理持久化作业队列和对象唯一的闹钟。 - 路由(
agents/routing)将 Worker 发出的请求发送到正确的命名对象。 - 功能 是通过
lifecycle.use()附加的特性,例如 WebSocket 客户端、共享状态、调度器和 MCP 连接。 - 可观测性 会跟踪模型调用,并发布 Lifecycle 及其功能发出的事件。
flowchart LR
Client["Client<br/>useAgent, AgentClient, HTTP"] -->|"HTTP or WebSocket"| Worker["Worker<br/>routeAgentRequest()"]
Worker --> L
subgraph DO["Durable Object, one per name"]
L["Lifecycle<br/>startup, dispatch, jobs, the one alarm"]
L --> WS["WebSockets"]
L --> SC["Scheduler"]
L --> H["Harness, such as PiHarness"]
L --> More["Other capabilities"]
WS --- DB[("SQLite storage")]
SC --- DB
H --- DB
More --- DB
end
DO -.->|"traces and events"| Obs["Observability"]
你无需自行组装所有这些部分。Harness会设置所需内容:
- Think 扩展了
Agent类,由它为你安装 Lifecycle 及其功能。 - Pi 本身是一项功能。你需要安装 Lifecycle 并通过
.use()添加 harness,Pi 会自行处理存储和恢复。
使用任一 harness 时,你通常会直接接触运行时的以下部分:
- 路由,用于将请求发送到正确的代理并检查调用者身份。
- WebSockets,用于将前端连接到代理。
- 可观测性,用于跟踪模型调用并调试代理执行的操作。
本节其余内容适用于构建自定义代理循环或添加自定义功能的场景。
你可以在普通的 DurableObject 上组合这些部分:
import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { routeAgentRequest } from "agents/routing";
import { Scheduler } from "agents/schedules";
import { WebSockets } from "agents/websockets";
export class MyAgent extends DurableObject {
scheduler = new Scheduler({ callbacks: {} });
webSockets = new WebSockets();
lifecycle = Lifecycle.install(this).use(this.scheduler).use(this.webSockets);
onRequest(request) {
return new Response(`Hello from ${this.lifecycle.name}`);
}
}
export default {
async fetch(request, env) {
return (
(await routeAgentRequest(request, env)) ??
new Response("Not found", { status: 404 })
);
},
};import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { routeAgentRequest } from "agents/routing";
import { Scheduler } from "agents/schedules";
import { WebSockets } from "agents/websockets";
export class MyAgent extends DurableObject<Env> {
readonly scheduler = new Scheduler({ callbacks: {} });
readonly webSockets = new WebSockets();
readonly lifecycle = Lifecycle.install(this)
.use(this.scheduler)
.use(this.webSockets);
onRequest(request: Request): Response {
return new Response(`Hello from ${this.lifecycle.name}`);
}
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
return (
(await routeAgentRequest(request, env)) ??
new Response("Not found", { status: 404 })
);
},
} satisfies ExportedHandler<Env>;Agent 类是同一运行时的预设版本:一个已安装 Lifecycle 和若干功能的 Durable Object。
- Lifecycle介绍 Lifecycle 提供的功能以及安装方法。
- 作业和闹钟介绍持久化作业队列。
getCurrentAgent()可从共享代码中读取当前对象、请求和连接。- Lifecycle API是
agents/lifecycle的完整参考。
- 路由介绍
routeAgentRequest()、URL 结构和代理命名。 - 路由选项介绍 CORS、位置选择、启动 props 和重试。
- 身份验证会在请求到达对象之前检查调用者。
- 自定义路由介绍如何使用自定义 URL 或通过 RPC 访问对象。
- HTTP 和 Server-Sent Events介绍如何在
onRequest()中处理请求并流式传输响应。
功能是可选特性。请从选择功能开始,了解你的 harness 已提供哪些功能,以及还需要自行添加哪些功能。
| 能力 | 导入 | 提供的功能 | 状态 |
|---|---|---|---|
WebSockets |
agents/websockets |
实时客户端连接 | 稳定 |
State |
agents/state |
与客户端同步的共享状态 | 稳定 |
Scheduler |
agents/schedules |
延迟、定时、Cron 和间隔回调 | 稳定 |
MCPClientManager |
agents/mcp/client |
与 MCP 服务器的连接 | 稳定 |
Streams |
agents/streams |
持久化的增量输出 | 实验性 |
Sessions |
agents/sessions |
持久化的对话历史记录 | 实验性 |
要编写自己的功能,请参阅构建功能。