mattzcarey · Oct 8, 2026 · Oct 4, 2026 · devin-ai-integration · Oct 4, 2026
diff --git a/.changeset/stable-lifecycle.md b/.changeset/stable-lifecycle.md
@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+`agents/lifecycle` is no longer experimental, and neither are the `Scheduler` (`agents/schedules`), `State` (`agents/state`), `WebSockets` (`agents/websockets`) and `MCPClientManager` (`agents/mcp/client`) capabilities. Their `@experimental` tags are removed. The Cap'n Web WebSocket transport, `Queue`, `Tasks`, `Streams`, `Sessions`, `RoutedAgents` and `Browser` stay experimental. See [Lifecycle](https://github.com/cloudflare/agents/blob/main/docs/agents/lifecycle.md).
diff --git a/docs/agents/index.md b/docs/agents/index.md
diff --git a/docs/agents/lifecycle.md b/docs/agents/lifecycle.md
@@ -1,8 +1,7 @@
 # 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` is stable. Most capabilities built on it are still
+experimental; each capability's page says which.
 
 `agents/lifecycle` lets reusable durable capabilities work in both `Agent` and a
 plain Cloudflare Durable Object. It uses composition: your class extends the

diff --git a/docs/agents/queue.md b/docs/agents/queue.md
@@ -7,9 +7,8 @@ survives the object leaving memory.
 
 ## Queue Lifecycle capability
 
-> **Experimental.** The `Queue` capability and the `agents/lifecycle` surface
-> it builds on may change between releases. Agent's established queue methods
-> (`this.queue()` and friends) are stable.
+> **Experimental.** The `Queue` capability may change between releases.
+> Agent's queue methods (`this.queue()` and friends) are stable.
 
 `Queue` is a reusable Lifecycle capability. A plain Lifecycle Object can
 install it without extending `Agent`:

diff --git a/docs/agents/scheduling.md b/docs/agents/scheduling.md
@@ -17,10 +17,6 @@ Under the hood, scheduling uses [Durable Object alarms](https://developers.cloud
 
 ## Scheduler Lifecycle primitive
 
-> **Experimental.** The `Scheduler` primitive and the `agents/lifecycle`
-> surface it builds on may change between releases. Agent's established
-> scheduling methods (`this.schedule()` and friends) are stable.
-
 `Scheduler` is a reusable Lifecycle capability. A plain Lifecycle Object can
 install it without extending `Agent`:
 
@@ -836,8 +832,8 @@ When using this schema with OpenAI models via the AI SDK, you must pass `provide
 
 ## API Reference
 
-Two surfaces share these semantics: the experimental `Scheduler` primitive
-(`agents/schedules`, methods on the scheduler instance) and the stable `Agent`
+Two surfaces share these semantics: the `Scheduler` capability
+(`agents/schedules`, methods on the scheduler instance) and the `Agent`
 methods (on the Agent class, delegating to `this.scheduler`).
 
 ### Scheduler primitive

diff --git a/packages/agents/src/index.ts b/packages/agents/src/index.ts
@@ -1111,8 +1111,6 @@ export class Agent<
 > extends DurableObject<Env> {
   /**
    * Runtime lifecycle and reusable durable capabilities for this Agent.
-   *
-   * @experimental The API surface may change before stabilizing.
    */
   readonly lifecycle = Lifecycle.install<Env, Props>(this, {
     maxAlarmMemoryLimitStrikes: this._resolvedOptions.maxAlarmMemoryLimitStrikes
@@ -1321,10 +1319,8 @@ export class Agent<
 
   /**
    * Durable scheduling capability installed into this Agent's Lifecycle.
-   *
-   * @experimental The API surface may change before stabilizing. Agent's
-   * schedule()/scheduleEvery()/getScheduleById()/listSchedules()/
-   * cancelSchedule() methods are the stable surface.
+   * Agent's schedule()/scheduleEvery()/getScheduleById()/listSchedules()/
+   * cancelSchedule() methods delegate to it.
    */
   readonly scheduler: Scheduler;
 

diff --git a/packages/agents/src/lifecycle/capability-runner.ts b/packages/agents/src/lifecycle/capability-runner.ts
@@ -101,8 +101,6 @@ export type MemoryLimitContext = {
  * - `onRoute` is addressed to one capability by its id; `onJob` is
  *   addressed by the due job's owning capability, with Lifecycle owning
  *   the queue and the one physical alarm.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export interface DurableObjectCapability<Props extends object = object> {
   /**

diff --git a/packages/agents/src/lifecycle/capability.ts b/packages/agents/src/lifecycle/capability.ts
@@ -69,8 +69,6 @@ export type LifecycleSockets = {
 
 /**
  * Standard services granted to every installed Lifecycle capability.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export type LifecycleServices = {
   /** The host's Durable Object name; see `Lifecycle.name`. */
@@ -130,8 +128,6 @@ const installedServices = new WeakMap<object, LifecycleServices>();
 
 /**
  * Base class for capabilities that consume standard Lifecycle services.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export abstract class LifecycleCapability<Props extends object = object> {
   readonly capabilityId: string;

diff --git a/packages/agents/src/lifecycle/current-agent.ts b/packages/agents/src/lifecycle/current-agent.ts
@@ -11,8 +11,6 @@ import type { LifecycleJobContext, LifecycleJobOutcome } from "./job-queue";
  *
  * Pass a more specific Lifecycle Object type to {@link getCurrentAgent} when
  * shared host code needs APIs implemented by a particular object.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export interface LifecycleObject<
   Env extends object = Cloudflare.Env,

diff --git a/packages/agents/src/lifecycle/durable-object-lifecycle.ts b/packages/agents/src/lifecycle/durable-object-lifecycle.ts
@@ -161,8 +161,6 @@ export type LifecycleOptions = {
  * Construct this as an instance field on a class that directly extends
  * `DurableObject`, then call {@link Lifecycle.installHandlers}
  * from that class's constructor.
- *
- * @experimental The API surface may change before stabilizing.
  */
 /** The dispatch hooks a catch-all can monopolize; uniqueness is per hook. */
 const CATCH_ALL_HOOKS = ["onRequest", "onWebSocketUpgrade"] as const;

diff --git a/packages/agents/src/lifecycle/index.ts b/packages/agents/src/lifecycle/index.ts
@@ -1,7 +1,5 @@
 /**
  * Durable Object lifecycle composition.
- *
- * @experimental Every export here may change before stabilizing.
  */
 export {
   LifecycleCapability,

diff --git a/packages/agents/src/mcp/client/index.ts b/packages/agents/src/mcp/client/index.ts
@@ -384,8 +384,7 @@ export type MCPServerFilter = {
 
 /**
  * A Durable Object capability that persists and aggregates MCP client
- * connections. Installing it directly on a Lifecycle (outside `agent.mcp`)
- * is experimental: that capability surface may change before stabilizing.
+ * connections. Install it on any Lifecycle, or use `agent.mcp` on an Agent.
  */
 export class MCPClientManager extends LifecycleCapability {
   public mcpConnections: Record<string, MCPClientConnection> = {};

diff --git a/packages/agents/src/schedules/index.ts b/packages/agents/src/schedules/index.ts
@@ -1,10 +1,8 @@
 /**
  * Persistent scheduling for Lifecycle Objects.
  *
- * @experimental The Scheduler surface (`Scheduler`, `SchedulerOptions`, and
- * the callback-map types) may change before stabilizing. `Schedule`,
- * `ScheduleCriteria`, and `ScheduleOptions` are shared with Agent's stable
- * scheduling methods.
+ * `Schedule`, `ScheduleCriteria`, and `ScheduleOptions` are shared with
+ * Agent's scheduling methods.
  */
 export { Scheduler } from "./scheduler";
 export type { SchedulerEventType, SchedulerOptions } from "./options";

diff --git a/packages/agents/src/schedules/options.ts b/packages/agents/src/schedules/options.ts
@@ -12,8 +12,6 @@ export type SchedulerEventType =
 
 /**
  * Optional callbacks and policy for a Scheduler capability.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export interface SchedulerOptions<
   Handlers extends SchedulerHandlers = SchedulerCallbacks

diff --git a/packages/agents/src/schedules/scheduler.ts b/packages/agents/src/schedules/scheduler.ts
@@ -160,8 +160,6 @@ function isSchedulerJobPayload(value: unknown): value is SchedulerJobPayload {
  * Lifecycle job queue; Lifecycle owns the physical alarm and the alarm
  * event loop, and Scheduler runs registered callbacks through Lifecycle's
  * host invocation boundary when its jobs come due.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export class Scheduler<
   Handlers extends SchedulerHandlers = SchedulerCallbacks

diff --git a/packages/agents/src/schedules/types.ts b/packages/agents/src/schedules/types.ts
@@ -50,8 +50,6 @@ export type Schedule<T = string> = {
 /**
  * Constraint for a Scheduler's registered callback map: named handlers
  * receiving the parsed payload and the schedule that fired.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export type SchedulerHandlers = Record<
   string,
@@ -67,8 +65,6 @@ export type SchedulerHandlers = Record<
  * must be registered or supplied by a composition-root resolver (the
  * aperture behind Agent's name-based scheduling API); a bare Scheduler
  * rejects it otherwise.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export type SchedulerCallbacks = Record<
   string,
@@ -77,8 +73,6 @@ export type SchedulerCallbacks = Record<
 
 /**
  * The payload type a registered scheduler callback accepts.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export type SchedulerPayload<Handler> = Handler extends (
   payload: infer Payload,

diff --git a/packages/agents/src/state/index.ts b/packages/agents/src/state/index.ts
@@ -12,8 +12,6 @@ export type StateChangeSource = Connection | "server";
  * Options for a {@link State} capability. Validation and the post-change hook
  * stay on the host, which passes them in; the capability owns storage and
  * change ordering.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export interface StateOptions<T = unknown> {
   /** Seeded on first access when nothing is stored. `undefined` seeds nothing. */
@@ -66,8 +64,6 @@ const DEFAULT_STATE = {} as unknown;
  * validated persistence. Install the instance with `Lifecycle.use()`. State
  * validation and the post-change notification hook stay on the host, which
  * injects both callbacks. This capability never touches connections.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export class State<T = unknown> extends LifecycleCapability {
   #state = DEFAULT_STATE as T;

diff --git a/packages/agents/src/websockets/index.ts b/packages/agents/src/websockets/index.ts
@@ -2,8 +2,6 @@
  * Opt-in WebSocket support for Lifecycle Objects: hibernating and Cap'n
  * Web connections plus the Agent identity and `rpc` frame protocol,
  * owned entirely by the capability.
- *
- * @experimental The WebSockets surface may change before stabilizing.
  */
 export { WebSockets } from "./websockets";
 export {

diff --git a/packages/agents/src/websockets/options.ts b/packages/agents/src/websockets/options.ts
@@ -20,8 +20,6 @@ export type WebSocketMessage = WSMessage;
  * Connection handlers for the WebSockets capability. Handlers run inside
  * the host invocation boundary with the live connection in ambient
  * context (`getCurrentAgent().connection`).
- *
- * @experimental The API surface may change before stabilizing.
  */
 export type WebSocketHandlers = {
   /** Handle a newly accepted hibernating WebSocket connection. */
@@ -51,8 +49,6 @@ export type WebSocketHandlers = {
 
 /**
  * Configuration for the WebSockets capability.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export interface WebSocketsOptions {
   /**

diff --git a/packages/agents/src/websockets/websockets.ts b/packages/agents/src/websockets/websockets.ts
@@ -142,8 +142,6 @@ function isRpcRequest(value: unknown): value is RpcRequest {
  * and client updates are validated and applied; the state owner
  * broadcasts changes with `broadcastState()`. Per-connection readonly
  * and no-protocol flags live here as well, for every host.
- *
- * @experimental The API surface may change before stabilizing.
  */
 export class WebSockets extends LifecycleCapability {
   /** Claims every upgrade, so Lifecycle dispatches it after all others. */