能力

capability 会为 Agent 添加可复用功能，例如 WebSocket 连接、计划任务或 Agent harness。你可以将它作为字段在 Durable Object 上构造，再通过 lifecycle.use() 将其附加到 Lifecycle。只安装应用所需的功能即可。

Durable Object 会在重启后保留存储的数据。若要继续被中断的工作，功能还需要保存进度，并安排对象再次唤醒。Durable Object 只有一个用于安排唤醒的 alarm。

Lifecycle 负责协调启动、事件分发和持久化任务队列。Capabilities 共享这些服务，因此每项功能都无需各自管理对象的 alarm 或启动流程。capability 可以：

• 在表中存储数据。 例如，Scheduler 会将计划存储在 SQLite 中。Capabilities 在同一数据库中使用不同的表名。
• 将工作安排为任务。 任务会记录稍后要运行的工作。Lifecycle 将任务存储在 SQLite 中、设置 alarm，并在任务到期时调用 capability 的 onJob() 钩子。
• 处理匹配的请求。 例如，MCPClientManager 会在请求到达你的 onRequest() 之前处理其 OAuth 回调 URL。

每个 capability 只实现自己需要的钩子。

此示例在同一个对象中组合 Pi harness 和 scheduler：

flowchart TB
    accTitle: Capabilities 共享 Durable Object 的存储和 alarm
    accDescr: PiHarness 和 Scheduler 向 Lifecycle 提交作业；Lifecycle 将待处理作业存储在共享 SQLite 数据库中，并管理对象唯一的 alarm。
    subgraph DO["一个 Durable Object"]
        direction TB
        P["PiHarness<br/>Agent 循环与恢复"] -->|"唤醒作业"| L
        S["Scheduler<br/>计划回调"] -->|"计划作业"| L
        L["Lifecycle<br/>启动、分发与作业队列"] -->|"设置下次唤醒"| A["一个 alarm"]
        A -->|"调用"| L
        P -->|"Pi 数据"| DB[("共享 SQLite 数据库")]
        S -->|"计划"| DB
        L -->|"待处理作业"| DB
    end

两个 capability 都通过 Lifecycle 安排任务，不会覆盖彼此的 alarm。重启后，Lifecycle 会重新启动它们并分发到期任务。harness 或 capability 会读取已保存的状态，以决定如何继续。Lifecycle 不会自动保存任意 JavaScript 代码的执行进度。

Capabilities 会为 Agent 添加功能。安装前，请先检查 harness 或基类已经提供了什么。

如果起点未提供所需功能，请使用以下 capabilities：

如果你要编写自己的 Agent 循环，可考虑使用 Sessions 保存对话历史，并使用 Streams 保存可重放的输出。

有关对话存储的建议，请参阅选择会话存储。

此对象组合 MCP 连接、计划回调、共享设置和 WebSocket 客户端：

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { MCPClientManager } from "agents/mcp/client";
import { Scheduler } from "agents/schedules";
import { State } from "agents/state";
import { WebSockets } from "agents/websockets";

export class MyAgent extends DurableObject {
	mcp = new MCPClientManager("my-agent", "1.0.0");
	scheduler = new Scheduler({
		callbacks: {
			dailySummary: async () => {
				for (const connection of this.webSockets.getConnections()) {
					connection.send("Time for your daily summary");
				}
			},
		},
	});
	settings = new State({
		initialState: { model: "anthropic/claude-opus-5.5" },
		onChanged: (_state, source) => this.webSockets.broadcastState(source),
	});
	webSockets = new WebSockets({ state: this.settings });

	lifecycle = Lifecycle.install(this)
		.use(this.mcp)
		.use(this.scheduler)
		.use(this.settings)
		.use(this.webSockets);
}

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { MCPClientManager } from "agents/mcp/client";
import { Scheduler } from "agents/schedules";
import { State } from "agents/state";
import { WebSockets } from "agents/websockets";

type Settings = { model: string };

export class MyAgent extends DurableObject<Env> {
	readonly mcp = new MCPClientManager("my-agent", "1.0.0");
	readonly scheduler = new Scheduler({
		callbacks: {
			dailySummary: async () => {
				for (const connection of this.webSockets.getConnections()) {
					connection.send("Time for your daily summary");
				}
			},
		},
	});
	readonly settings: State<Settings> = new State<Settings>({
		initialState: { model: "anthropic/claude-opus-5.5" },
		onChanged: (_state, source) => this.webSockets.broadcastState(source),
	});
	readonly webSockets: WebSockets = new WebSockets({ state: this.settings });

	readonly lifecycle = Lifecycle.install(this)
		.use(this.mcp)
		.use(this.scheduler)
		.use(this.settings)
		.use(this.webSockets);
}

将 capability 所需的内容（例如回调或另一个 capability）传给其构造函数。在此示例中，WebSockets 接收 State capability，以便将设置同步给客户端。

以下 capabilities 随 agents 包提供，且已趋于稳定：

以下 capabilities 仍处于实验阶段，其 API 可能随版本变化：

例如 PiHarness 这样的 harness 是一种运行完整 Agent 循环的 capability。

如需编写自己的 capability，请参阅构建 capability。

• 在启动前安装。 在字段初始化器或构造函数中调用 use()。首次收到请求、alarm 或 WebSocket 消息时，Lifecycle 会启动；此后调用 use() 会抛出异常。
• 在 Lifecycle 之前声明字段。 类字段按顺序初始化。请在安装相应能力的 lifecycle 字段之前声明每个能力字段。
• 每项能力只安装一次。 每项能力都有稳定 ID，例如 "scheduler" 或 "mcp"。ID 用于区分其作业和事件；重复安装时，use() 会抛出异常。
• 启动顺序。 启动时，Lifecycle 按安装顺序运行每项能力的 onStart()，并将兜底能力放在最后。随后运行你自己的 onStart()。
• 请求顺序。 Lifecycle 会在调用你的 onRequest() 之前，按安装顺序将每个请求交给各项能力处理。WebSockets 会接受所有 WebSocket 升级请求，因此始终最后运行。更多信息，请参阅请求分发。
• 共享闹钟。 Scheduler 等需要稍后执行工作的能力，会将工作存储为 Lifecycle 作业，因此不会覆盖彼此的闹钟。
• 宿主上下文。 你注册的回调（例如 Scheduler 回调、WebSockets 处理程序和可调用函数）会在对象的上下文中运行；在此上下文中，getCurrentAgent() 会返回该对象。
• RPC。 原生 Durable Object RPC 会绕过 fetch()，因此不会启动 Lifecycle。对于使用能力的 RPC 方法，请在方法开头调用 await this.lifecycle.start()。

Agent 类是一个预设：它是已安装 Lifecycle 和多项能力的 Durable Object，包括 Scheduler、State、WebSockets 和 MCPClientManager。this.schedule()、this.setState() 和 this.addMcpServer() 等方法会调用这些能力。

如需为 Agent 添加其他能力，请在其构造函数中调用 this.lifecycle.use()。请勿重复安装 Agent 已有的能力，否则 use() 会因 ID 重复而抛出异常。