agents 0.20.1 → 0.22.0

package/docs/email.md

@@ -419,21 +419,10 @@ When your agent sends emails and expects replies, use secure reply routing to pr
 
 ### Setup
 
-1. Add a secret to your `wrangler.jsonc`:
-
-```jsonc
-// wrangler.jsonc
-{
-  "vars": {
-    "EMAIL_SECRET": "change-me-in-production"
-  }
-}
-```
-
-For production, use Wrangler secrets instead:
+1. Store the signing key as a Wrangler secret. Do not put it in `vars` or commit it to source control:
 
 ```bash
-wrangler secret put EMAIL_SECRET
+pnpm exec wrangler secret put EMAIL_SECRET
 ```
 
 2. Use the combined resolver pattern:

package/docs/http-websockets.md

@@ -408,17 +408,7 @@ export class MyAgent extends Agent {
 
 ## Hibernation
 
-Agents support hibernation - they can sleep when inactive and wake when needed. This saves resources while maintaining WebSocket connections.
-
-### Enabling Hibernation
-
-Hibernation is enabled by default. To disable:
-
-```typescript
-export class AlwaysOnAgent extends Agent {
-  static options = { hibernate: false };
-}
-```
+Agent WebSockets always use Cloudflare's Hibernation API. An idle Agent can leave memory while its WebSocket clients remain connected; there is no non-hibernating mode.
 
 ### How Hibernation Works
 

package/docs/human-in-the-loop.md

@@ -196,7 +196,7 @@ Define tools with `needsApproval` to require human confirmation:
 ```typescript
 import { AIChatAgent } from "@cloudflare/ai-chat";
 import { createWorkersAI } from "workers-ai-provider";
-import { streamText, tool, convertToModelMessages } from "ai";
+import { streamText, tool, convertToModelMessages, stepCountIs } from "ai";
 import { z } from "zod";
 
 export class MyAgent extends AIChatAgent {
@@ -238,7 +238,7 @@ export class MyAgent extends AIChatAgent {
           execute: async ({ city }) => fetchWeather(city)
         })
       },
-      maxSteps: 5
+      stopWhen: stepCountIs(5)
     });
 
     return result.toUIMessageStreamResponse();
@@ -246,6 +246,8 @@ export class MyAgent extends AIChatAgent {
 }
 ```
 
+The `inputSchema` accepts the AI SDK's flexible schema format, so you are not limited to Zod. You can also use Valibot, a Standard JSON Schema-compatible schema, or a raw JSON Schema wrapped with `jsonSchema()` from `ai`. See [Use Valibot or another schema library](./agent-tools.md#use-valibot-or-another-schema-library) for details.
+
 ### Client
 
 Handle approval requests with `addToolApprovalResponse`:
@@ -355,7 +357,7 @@ See the complete example: [guides/human-in-the-loop/](https://github.com/cloudfl
 
 ### Surviving restarts while waiting for a human
 
-A Durable Object can be evicted at any time (a deploy, an inactivity timeout, a resource limit), including while a turn is paused on an approval prompt or a client-side tool call. When [`chatRecovery`](./chat-agents.md#stream-recovery) is enabled (the default for `Think`), the SDK recognizes that such a turn is _waiting on the human_, not stuck, and does **not** seal it: the no-progress window, attempt cap, `maxRecoveryWork`, and `shouldKeepRecovering` are all suspended while the interaction is pending. Recovery parks the turn instead of failing it, and the user's eventual approval or `tool_result` resumes the conversation through the normal continuation path. A user who takes minutes to respond to a prompt that was interrupted by a deploy therefore does not see a spurious "session interrupted" error.
+A Durable Object can be evicted at any time (a deploy, an inactivity timeout, a resource limit), including while a turn is paused on an approval prompt or a client-side tool call. Durable [`chatRecovery`](./chat-agents.md#stream-recovery) is always enabled. The SDK recognizes that such a turn is _waiting on the human_, not stuck, and does **not** seal it: the no-progress window, attempt cap, `maxRecoveryWork`, and `shouldKeepRecovering` are all suspended while the interaction is pending. Recovery parks the turn instead of failing it, and the user's eventual approval or `tool_result` resumes the conversation through the normal continuation path. A user who takes minutes to respond to a prompt that was interrupted by a deploy therefore does not see a spurious "session interrupted" error.
 
 This protection applies to interactions only the client can resolve — `approval-requested` parts and `input-available` parts for client-side tools (those without a server `execute`). A server tool whose `execute()` was killed mid-flight is a genuine orphan and recovers through the normal transcript-repair path instead.
 
@@ -380,7 +382,7 @@ export class MyAgent extends AIChatAgent {
           inputSchema: z.object({})
         })
       },
-      maxSteps: 3
+      stopWhen: stepCountIs(3)
     });
 
     return result.toUIMessageStreamResponse();
@@ -410,17 +412,18 @@ const { messages, sendMessage } = useAgentChat({
 });
 ```
 
-The server receives the tool output via `CF_AGENT_TOOL_RESULT` and can auto-continue the conversation (with `maxSteps > 1`), letting the LLM respond to the location data in the same turn.
+The server receives the tool output via `CF_AGENT_TOOL_RESULT` and can auto-continue the conversation when `stopWhen` allows another step, letting the LLM respond to the location data in the same turn.
 
 ### OpenAI Agents SDK Pattern
 
 When using the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/), use the `needsApproval` function for conditional approval:
 
 ```typescript
-import { Agent } from "agents";
-import { tool, run } from "@openai/agents";
+import { Agent as CloudflareAgent } from "agents";
+import { Agent as OpenAIAgent, tool, run } from "@openai/agents";
+import { z } from "zod";
 
-export class WeatherAgent extends Agent<Env, AgentState> {
+export class WeatherAgent extends CloudflareAgent<Env> {
   async processQuery(query: string) {
     const weatherTool = tool({
       name: "get_weather",
@@ -438,13 +441,13 @@ export class WeatherAgent extends Agent<Env, AgentState> {
       }
     });
 
-    const result = await run(this.openai, {
-      model: "gpt-4o",
-      tools: [weatherTool],
-      input: query
+    const openaiAgent = new OpenAIAgent({
+      name: "Weather assistant",
+      instructions: "Help the user check the weather.",
+      tools: [weatherTool]
     });
 
-    return result;
+    return run(openaiAgent, query);
   }
 }
 ```

package/docs/index.md

@@ -140,6 +140,7 @@ The differentiator is not "we have durable state" — it is what happens when a
 
 ## Reference
 
+- [Durable Object Lifecycle](./lifecycle.md) - Compose reusable durable components outside the Agent base class
 - TODO: [API Reference](./api-reference.md) - Complete API documentation
 - TODO: [FAQ / How is this different from Durable Objects?](./faq.md)
 - TODO: [Resources & Further Reading](./resources.md)

package/docs/lifecycle.md

@@ -0,0 +1,323 @@
+# Durable Object lifecycle
+
+> **Experimental.** Everything exported from `agents/lifecycle` — and the
+> capabilities built on it, including `Scheduler` — may change between
+> releases while the composition surface stabilizes.
+
+`agents/lifecycle` lets reusable durable capabilities work in both `Agent` and a
+plain Cloudflare Durable Object. It uses composition: your class extends the
+platform `DurableObject`, then constructs a lifecycle with `this`.
+
+## Plain Durable Object
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+import { Lifecycle } from "agents/lifecycle";
+
+export class MyObject extends DurableObject<Env> {
+  readonly lifecycle = Lifecycle.install(this);
+
+  onStart(): void {
+    // Runs once per in-memory object lifetime, before work is handled.
+  }
+
+  onRequest(request: Request): Response {
+    return new Response(`Hello from ${this.lifecycle.name}: ${request.url}`);
+  }
+
+  onAlarm(): void {
+    // Runs after lifecycle capabilities process the alarm.
+  }
+}
+```
+
+The side-effect-named static factory constructs the lifecycle and installs the
+runtime-facing `fetch`, `alarm`, `webSocketMessage`, `webSocketClose`, and
+`webSocketError` handlers. Do not define forwarding versions of those methods.
+Implement the semantic callbacks instead.
+
+The expanded equivalent is available when useful:
+
+```ts
+readonly lifecycle = new Lifecycle(this);
+
+constructor(ctx: DurableObjectState, env: Env) {
+  super(ctx, env);
+  this.lifecycle.installHandlers();
+}
+```
+
+Route named objects from the outer Worker when you want URL routing:
+
+```ts
+import { routeAgentRequest } from "agents";
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return (
+      (await routeAgentRequest(request, env)) ??
+      new Response("Not found", { status: 404 })
+    );
+  }
+};
+```
+
+The default URL shape is `/agents/:binding/:name`. Direct
+`env.MY_OBJECT.getByName(name).fetch(request)` calls work as well.
+
+`Agent` already constructs this lifecycle. Existing Agent classes continue to
+override `onStart`, `onRequest`, `onConnect`, `onMessage`, `onClose`, and
+`onError` normally.
+
+## Request call path
+
+```text
+routeAgentRequest(request)
+└─ named Durable Object stub.fetch(request)
+   └─ lifecycle-installed fetch
+      ├─ lifecycle startup capabilities
+      ├─ host onStart
+      ├─ lifecycle request capabilities
+      │  └─ first Response wins
+      └─ host onRequest
+```
+
+A warm object skips startup but still offers every request to its capabilities.
+
+## Reusable capabilities
+
+A capability implements only the phases it needs:
+
+```ts
+import type { DurableObjectCapability } from "agents/lifecycle";
+
+class AuditLog implements DurableObjectCapability {
+  constructor(private readonly storage: DurableObjectStorage) {}
+
+  onStart(): void {
+    this.storage.sql.exec(`
+      CREATE TABLE IF NOT EXISTS audit_log (
+        message TEXT NOT NULL
+      )
+    `);
+  }
+
+  onRequest({ request }: { request: Request }): Response | undefined {
+    if (new URL(request.url).pathname.endsWith("/health")) {
+      return new Response("ok");
+    }
+  }
+
+  onAlarm(): void {
+    this.storage.sql.exec("DELETE FROM audit_log");
+  }
+}
+```
+
+Install it before startup:
+
+```ts
+export class MyObject extends DurableObject<Env> {
+  private readonly audit = new AuditLog(this.ctx.storage);
+  readonly lifecycle = Lifecycle.install(this).use(this.audit);
+
+  onRequest(): Response {
+    return new Response("application response");
+  }
+}
+```
+
+Capabilities run in registration order. Startup and alarms run every hook
+sequentially. Request handling stops at the first returned `Response`. A phase
+failure propagates, and failed startup can be retried.
+
+Capabilities extending `LifecycleCapability` receive one standard service
+surface: storage, readiness, startup state, alarm coordination, a host
+invocation boundary, best-effort events, and capability routing.
+Host-specific bindings, authentication, and protocol adapters remain explicit
+constructor dependencies. Lifecycle never grants a capability the complete
+host implicitly.
+
+Capability hooks run outside host context, but user callbacks run through
+`this.lifecycle.runInHostContext(fn)` inside the host invocation context.
+Scheduler dispatches its registered callbacks through this boundary, and a
+future capability that calls user code should do the same.
+
+## Shared alarm ownership
+
+Lifecycle owns the Durable Object's single physical alarm. A capability that
+needs a future wake-up keeps its work in its own durable storage and implements
+`getNextAlarm()`:
+
+```ts
+import { LifecycleCapability, type AlarmContribution } from "agents/lifecycle";
+
+class Cleanup extends LifecycleCapability {
+  constructor() {
+    super("cleanup");
+  }
+
+  async getNextAlarm(): Promise<AlarmContribution> {
+    return (await this.lifecycle.storage.get<number>("cleanup:next")) ?? null;
+  }
+
+  async onAlarm(): Promise<void> {
+    const next = await this.lifecycle.storage.get<number>("cleanup:next");
+    if (next === undefined || next > Date.now()) return;
+    await this.lifecycle.storage.delete("cleanup:next");
+  }
+
+  async scheduleCleanup(time: number): Promise<void> {
+    await this.lifecycle.storage.put("cleanup:next", time);
+    await this.lifecycle.alarms.rearm();
+  }
+}
+```
+
+Lifecycle selects the earliest contribution from every capability and the
+host. It runs all capability `onAlarm()` hooks, then host `onAlarm()`, then
+recalculates the physical alarm. Capabilities do not depend on Scheduler or on
+each other merely to receive alarm wakes.
+A contribution can be `{ time, exclusive: true }` when its wake time must
+replace ordinary wake candidates, such as a pending teardown. This changes only
+which physical alarm is armed; when that alarm fires, normal capability and host
+hook order still applies. Hosts can implement `getNextAlarm()` for alarm work
+that has not yet been extracted into a capability.
+
+## Capability events
+
+Capabilities publish best-effort telemetry through their standard service
+surface. Lifecycle assigns the capability source from the stable ID passed to
+`super()`:
+
+```ts
+class Cleanup extends LifecycleCapability {
+  constructor() {
+    super("cleanup");
+  }
+
+  reportRemoval(key: string): void {
+    this.lifecycle.events.emit("cleanup:remove", { key });
+  }
+}
+```
+
+Lifecycle publishes events from a plain Lifecycle Object to the existing
+`agents:*` diagnostics channels according to the event type. Delivery is
+best-effort, runs outside ambient host context, and does not fail the emitting
+capability when a telemetry sink throws. Persist an outbox in the capability
+when delivery is part of the durable business operation.
+
+## Capability routing
+
+Every `LifecycleCapability` also receives `lifecycle.routes`. `toRoot()` routes
+a message to the matching capability ID on the root Lifecycle; `to(address, …)`
+routes to another addressed Lifecycle. Lifecycle owns the generic envelope and
+dispatch. A host with child objects supplies the transport internally.
+
+Agent uses this for facet schedules: Scheduler sends owner-scoped CRUD to the
+root Scheduler and routes due callbacks back to the matching facet Scheduler.
+Existing rows remain in the root `cf_agents_schedules` table. Scheduler does not
+implement facet traversal, and Agent exposes only one internal generic Lifecycle
+route aperture.
+
+## Explicit disposal
+
+`lifecycle.dispose()` calls each capability's optional `dispose()` method in
+reverse installation order. This phase releases live resources such as MCP
+transports and listeners. It does not delete capability tables. An explicit
+Lifecycle Object destruction disposes live resources once, then calls
+`storage.deleteAll()` once for all shared durable state. Eviction calls neither.
+
+## Lifecycle Object context
+
+`agents/lifecycle` exports the `LifecycleObject` interface for a
+`DurableObject` with an installed `Lifecycle` and the semantic hooks Lifecycle
+dispatches. This is a host type, not the batteries-included `Agent` class
+exported from `agents`.
+
+Lifecycle establishes the `getCurrentAgent()` context only while it invokes
+host hooks. Capability hooks run outside that ambient context and use their own
+`this`, hook arguments, and explicitly supplied dependencies.
+
+```ts
+import { getCurrentAgent } from "agents/lifecycle";
+
+function currentRequestOrigin(): string | undefined {
+  const { request } = getCurrentAgent();
+  return request ? new URL(request.url).origin : undefined;
+}
+
+export class MyObject extends DurableObject<Env> {
+  readonly lifecycle = Lifecycle.install(this);
+
+  onRequest(): Response {
+    return Response.json({ origin: currentRequestOrigin() });
+  }
+}
+```
+
+Pass the concrete host class when shared host code needs its additional APIs:
+
+```ts
+const { agent: object } = getCurrentAgent<MyObject>();
+```
+
+Host context values follow the invocation:
+
+- `onStart` and `onAlarm`: object;
+- `onRequest`: object and request;
+- `onConnect`: object, connection, and upgrade request;
+- `onMessage`, `onClose`, and `onError`: object and connection.
+
+`getConnectionTags(connection, { request })` remains argument-driven because it
+already receives both values explicitly. The root `agents` package continues
+to export `getCurrentAgent()` for the `Agent` class as a compatibility alias.
+
+## WebSockets always hibernate
+
+The lifecycle always uses Cloudflare's WebSocket Hibernation API. Idle clients
+remain connected while the Durable Object can leave memory. When a message
+wakes the object, its constructor and lifecycle startup run again before
+`onMessage`.
+
+State needed after a wake must be stored durably or through connection state:
+
+```ts
+onConnect(connection: Connection): void {
+  connection.setState({ authenticated: true });
+}
+
+onMessage(connection: Connection<{ authenticated: boolean }>): void {
+  console.log(connection.state?.authenticated);
+}
+```
+
+There is no non-hibernating mode.
+
+## Native RPC
+
+Native Durable Object RPC does not pass through `fetch`. An RPC method that
+requires initialized capabilities starts the lifecycle explicitly:
+
+```ts
+async runTask(): Promise<void> {
+  await this.lifecycle.start();
+  // initialized work
+}
+```
+
+Agent's internal RPC entry points already enforce this boundary.
+
+## Object names
+
+Use `idFromName()` or `getByName()`. The lifecycle reads the authoritative name
+from `ctx.id.name` and exposes it as `lifecycle.name`.
+
+For migration only, the lifecycle can read an existing `__ps_name` record
+written by an older PartyServer release. It never writes that key. Deprecated
+name headers and bootstrap methods are not supported.
+
+If a name cannot be resolved, the error covers named addressing, updating local
+Wrangler/workerd and the compatibility date, unsupported raw IDs and oversized
+names, and rescheduling alarms created before 2026-03-15.

package/docs/long-running-agents.md

@@ -86,7 +86,7 @@ type Task = {
   externalJobId?: string;
 };
 
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   initialState: ProjectState = {
     name: "",
     status: "planning",
@@ -115,7 +115,7 @@ The pattern extends naturally to any event source that can reach a Worker — an
 The agent does not need to be "started" or "deployed" separately for each wake source — they all route to the same Durable Object instance. The agent's identity (its name) is the routing key.
 
 ```typescript
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   async onStart() {
     // Daily deadline check at 9am UTC — idempotent, safe across restarts
     await this.schedule(
@@ -163,7 +163,7 @@ Sometimes an agent needs to do work that takes longer than the idle eviction win
 `keepAlive()` prevents this by creating a heartbeat that resets the inactivity timer:
 
 ```typescript
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   async generateProjectPlan(goal: string) {
     const result = await this.keepAliveWhile(async () => {
       const plan = await this.callLLM(`Create a project plan for: ${goal}`);
@@ -223,7 +223,7 @@ side effects. If recovery succeeds, return a recovery result from
 aborted, failed, or intentionally left interrupted.
 
 ```typescript
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   async executeTask(task: Task) {
     await this.runFiber(`task:${task.id}`, async (ctx) => {
       const resources = await this.gatherResources(task);
@@ -268,7 +268,7 @@ The project manager frequently kicks off work that takes far longer than any sin
 The project manager starts a CI pipeline for a task. The pipeline takes 20 minutes. Rather than holding a connection open, the agent registers its own URL as the callback and goes to sleep:
 
 ```typescript
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   async startCIPipeline(task: Task) {
     const response = await fetch("https://ci.example.com/api/pipelines", {
       method: "POST",
@@ -307,7 +307,7 @@ export class ProjectManager extends Agent<ProjectState> {
 Not every external service supports callbacks. When the project manager submits a video asset for generation, it needs to check back periodically until the job completes:
 
 ```typescript
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   async startVideoGeneration(task: Task) {
     const response = await fetch("https://video-api.example.com/generate", {
       method: "POST",
@@ -354,7 +354,7 @@ export class ProjectManager extends Agent<ProjectState> {
 A production deployment involves multiple steps that must each retry independently — build, test, stage, promote. The project manager should not manage these steps internally; it delegates to a [Workflow](./workflows.md) that handles retries and step sequencing:
 
 ```typescript
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   async startDeployment(task: Task) {
     const instanceId = await this.runWorkflow("DEPLOY_WORKFLOW", {
       taskId: task.id,
@@ -422,7 +422,7 @@ type PlanStep = {
   result?: unknown;
 };
 
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   async createPlan(goal: string) {
     const steps = await this.keepAliveWhile(async () => {
       return this.callLLM(`
@@ -508,7 +508,7 @@ This pattern has several advantages for long-running agents:
 A project manager does not do everything itself. It delegates specialized work to sub-agents — child Durable Objects (facets) spawned under the parent. Each facet has its own isolated SQLite state and runs in parallel, but stays colocated on the same machine as the parent.
 
 ```typescript
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   async delegateTask(task: Task) {
     // Get a stub to a specialized agent (same DO namespace, unique name)
     const researcher = await this.subAgent(
@@ -537,7 +537,7 @@ For chat-oriented sub-agents, [Think](https://github.com/cloudflare/agents/blob/
 
 The patterns above handle the project manager's coordination work — scheduling, delegating, polling. But the project manager also uses an LLM directly: generating plans, summarizing progress, drafting status emails. Those LLM calls stream tokens over a connection that cannot be resumed if the agent is evicted mid-response.
 
-For chat-oriented agents built on `AIChatAgent`, this is an even sharper problem — the user is watching the response stream in real time and sees it stop mid-sentence. `chatRecovery` wraps each chat turn in a `runFiber`, providing automatic `keepAlive` during streaming and a recovery hook when the agent restarts:
+For chat-oriented agents built on `AIChatAgent` or `Think`, this is an even sharper problem — the user is watching the response stream in real time and sees it stop mid-sentence. Durable recovery wraps every chat turn in a `runFiber`, providing automatic `keepAlive` during streaming and a recovery hook when the agent restarts:
 
 ```typescript
 import { AIChatAgent } from "@cloudflare/ai-chat";
@@ -547,8 +547,6 @@ import type {
 } from "@cloudflare/ai-chat";
 
 class ProjectChat extends AIChatAgent<Env> {
-  override chatRecovery = true;
-
   override async onChatRecovery(
     ctx: ChatRecoveryContext
   ): Promise<ChatRecoveryOptions> {
@@ -573,7 +571,7 @@ The right recovery strategy depends on the LLM provider:
 
 For a complete multi-provider implementation with full code for each strategy, see the [`forever-chat` example](https://github.com/cloudflare/agents/tree/main/experimental/forever-chat) and the [`forever.md` design doc](https://github.com/cloudflare/agents/tree/main/experimental/forever.md).
 
-[Think](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) enables `chatRecovery` by default. The default path persists partial output and auto-continues or retries the turn when safe, so many apps do not need a custom hook. Override `onChatRecovery` when a provider has a better recovery strategy, or configure `chatRecovery = { maxAttempts, terminalMessage, onExhausted }` to tune the terminal user experience.
+`AIChatAgent` and [Think](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) always enable durable recovery. The default path persists partial output and auto-continues or retries the turn when safe, so many apps do not need a custom hook. Override `onChatRecovery` when a provider has a better recovery strategy, or configure `chatRecovery = { maxAttempts, terminalMessage, onExhausted }` to tune the terminal user experience.
 
 If the agent is interrupted before any assistant stream chunks are written, there is no partial assistant message to continue. When the latest persisted message is still the unanswered user message from that turn, chat recovery retries the turn automatically unless `onChatRecovery` returns `{ continue: false }`.
 
@@ -586,7 +584,7 @@ An agent that runs for months accumulates data: conversation history, timeline e
 Schedule periodic cleanup to prune old data and archive completed work:
 
 ```typescript
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   async onStart() {
     await this.schedule("0 0 * * *", "housekeeping", {}, { idempotent: true });
   }
@@ -634,7 +632,7 @@ For simpler cases: keep only the last N messages in the active context (sliding
 A long-running agent eventually completes its purpose. The project ships, the investigation concludes, the monitoring window closes. Clean up explicitly:
 
 ```typescript
-export class ProjectManager extends Agent<ProjectState> {
+export class ProjectManager extends Agent<Env, ProjectState> {
   async completeProject() {
     // Cancel remaining schedules
     const schedules = await this.listSchedules();

package/docs/mcp-client.md

@@ -13,6 +13,61 @@ The MCP client capability lets your agent:
 
 > **Note:** This page covers connecting to MCP servers as a client. To create your own MCP server, see [Creating MCP Servers](./mcp-servers.md).
 
+## Compose the MCP client with a Durable Object
+
+`MCPClientManager` is a lifecycle capability. A class can extend the platform
+`DurableObject` directly and install the manager without extending `Agent`:
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+import { Lifecycle } from "agents/lifecycle";
+import { MCPClientManager } from "agents/mcp/client";
+
+export class MyObject extends DurableObject<Env> {
+  readonly mcp = new MCPClientManager("my-object", "1.0.0");
+
+  readonly lifecycle = Lifecycle.install(this).use(this.mcp);
+
+  onRequest() {
+    return Response.json({ tools: this.mcp.listTools() });
+  }
+}
+```
+
+The lifecycle calls the manager automatically:
+
+- `onStart()` initializes its schema and restores persisted connections before
+  the host handles work.
+- `onRequest()` intercepts registered OAuth callback URLs before the host's
+  request handler.
+
+Do not call these hooks manually. For a native Durable Object RPC method,
+which bypasses `fetch`, call `await this.lifecycle.start()` before using the
+manager. Explicit cleanup remains available through `mcp.dispose()`; Durable
+Objects do not provide an eviction callback.
+
+The manager does not require a particular OAuth callback route. Pass the exact
+callback URL to `registerServer()` and route that request to the same named
+Durable Object. The manager persists the URL and only intercepts a callback
+whose origin and pathname match it.
+
+An HTTP-only manager does not need `env`. Pass the Durable Object environment
+when the catalog can contain RPC servers so persisted binding names can be
+resolved after a wake:
+
+```ts
+readonly mcp = new MCPClientManager("my-object", "1.0.0", {
+  env: this.env
+});
+```
+
+If an RPC row exists without `env`, startup logs a warning identifying the
+server and does not recreate that connection.
+
+`Agent` installs this same capability object directly. Existing `this.mcp`,
+`addMcpServer()`, `removeMcpServer()`, and `getMcpServers()` APIs remain
+available.
+
 ## Quick Start
 
 Install the exact MCP client peer used by this Agents release:

package/docs/mcp-servers.md

@@ -14,6 +14,12 @@ This guide covers the different ways to create MCP servers with the Agents SDK a
 - **`McpAgent`** is a retained, feature-frozen SDK v1 path for existing stateful deployments. New servers should use `createMcpHandler()`.
 - **Raw transport** gives you low-level control if the standard handler lifecycle is not suitable.
 
+`McpAgent` and the other retained SDK v1 registration APIs use the upstream
+Zod-based schema contract. Define their tool input and output schemas as Zod
+shapes; AI SDK flexible-schema adapters are not accepted. For a new MCP server
+that needs Standard Schema support, use `@modelcontextprotocol/server` v2 with
+`createMcpHandler()`.
+
 ## Stateless MCP Server with `createMcpHandler()`
 
 The simplest way to create an MCP server. Install the exact SDK v2 server peer, then use the isolated server entry point so legacy Agents transports and MCP clients stay out of your Worker bundle: