跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

运行时

最后更新 查看 MarkdownAgent 设置

使用 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 时

你无需自行组装所有这些部分。Harness会设置所需内容:

  • Think 扩展了 Agent 类,由它为你安装 Lifecycle 及其功能。
  • Pi 本身是一项功能。你需要安装 Lifecycle 并通过 .use() 添加 harness,Pi 会自行处理存储和恢复。

使用任一 harness 时,你通常会直接接触运行时的以下部分:

  • 路由,用于将请求发送到正确的代理并检查调用者身份。
  • WebSockets,用于将前端连接到代理。
  • 可观测性,用于跟踪模型调用并调试代理执行的操作。

本节其余内容适用于构建自定义代理循环或添加自定义功能的场景。

自行组合运行时

你可以在普通的 DurableObject 上组合这些部分:

src/index.jsjs
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 })
		);
	},
};
src/index.tsts
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。

生命周期

路由

  • 路由介绍 routeAgentRequest()、URL 结构和代理命名。
  • 路由选项介绍 CORS、位置选择、启动 props 和重试。
  • 身份验证会在请求到达对象之前检查调用者。
  • 自定义路由介绍如何使用自定义 URL 或通过 RPC 访问对象。
  • HTTP 和 Server-Sent Events介绍如何在 onRequest() 中处理请求并流式传输响应。

功能 (Capabilities)

功能是可选特性。请从选择功能开始,了解你的 harness 已提供哪些功能,以及还需要自行添加哪些功能。

能力 导入 提供的功能 状态
WebSockets agents/websockets 实时客户端连接 稳定
State agents/state 与客户端同步的共享状态 稳定
Scheduler agents/schedules 延迟、定时、Cron 和间隔回调 稳定
MCPClientManager agents/mcp/client 与 MCP 服务器的连接 稳定
Streams agents/streams 持久化的增量输出 实验性
Sessions agents/sessions 持久化的对话历史记录 实验性

要编写自己的功能,请参阅构建功能。

可观测性

  • 跟踪会将模型调用、工具运行和审批记录为 Workers 跟踪信息。
  • 诊断渠道会发布 Lifecycle、其功能和 Agent 类发出的结构化事件。

这篇文档对您有帮助吗?