agents 0.30.1 → 0.31.0

package/docs/harnesses/pi.md

@@ -1,10 +1,10 @@
 ---
-title: Pi harness (Beta)
+title: Pi harness
 pcx_content_type: get-started
-description: Host pi-durable sessions in a Durable Object with the beta PiHarness lifecycle capability. Connect a pi-ai model, add tools and skills, and keep sessions running across eviction.
+description: Host pi-durable sessions in a Durable Object with the PiHarness lifecycle capability. Connect a pi-ai model, add tools and skills, and keep sessions running across eviction.
 ---
 
-`PiHarness` hosts [pi-durable](https://github.com/earendil-works/pi/tree/main/packages/durable) in a Durable Object. It opens Pi over the object's SQLite database and connects Pi's sessions to the Agents SDK lifecycle, which wakes sessions with work after eviction. The API is in beta and may change.
+`PiHarness` hosts [pi-durable](https://github.com/earendil-works/pi/tree/main/packages/durable) in a Durable Object. It opens Pi over the object's SQLite database and connects Pi's sessions to the Agents SDK lifecycle, which wakes sessions with work after eviction.
 
 Pi owns everything about a run: the transcript, the inbox of steers and follow-ups, generation, tool calls, retries, and crash recovery. `PiHarness` supplies the storage and the wake. It does not provide a chat protocol or user interface. Your application chooses how clients reach sessions, such as WebSockets, HTTP, or RPC.
 
@@ -21,13 +21,14 @@ The three Pi packages are optional peer dependencies of `agents`, at `~1.4.0`. p
 `PiHarness` uses a factory function to construct Pi's `Harness` so it can be instantiated lazily:
 
 ```ts
+import { DurableObject } from "cloudflare:workers";
 import { createModels } from "@earendil-works/pi-ai/models";
 import { createRegistry, Harness } from "@earendil-works/pi-durable";
-import { Agent } from "agents";
 import { PiHarness } from "agents/harness/pi";
+import { Lifecycle } from "agents/lifecycle";
 import { createAI } from "agents/models/pi-ai";
 
-export class Assistant extends Agent<Env> {
+export class Assistant extends DurableObject<Env> {
   ai = createAI({ binding: this.env.AI });
   registry = createRegistry();
 
@@ -42,15 +43,12 @@ export class Assistant extends Agent<Env> {
       );
     },
     defaults: {
-      model: this.ai("@cf/zai-org/glm-4.7-flash"),
+      model: this.ai("@cf/zai-org/glm-5.3-flash"),
       thinkingLevel: "low"
     }
   });
 
-  constructor(ctx: DurableObjectState, env: Env) {
-    super(ctx, env);
-    this.lifecycle.use(this.harness);
-  }
+  lifecycle = Lifecycle.install(this).use(this.harness);
 
   async ask(prompt: string) {
     return (await this.harness.prompt(prompt)).text;
@@ -58,6 +56,8 @@ export class Assistant extends Agent<Env> {
 }
 ```
 
+`PiHarness` is a Lifecycle capability, so it runs on a plain Durable Object. `Lifecycle.install(this)` gives the object its startup, alarms and job queue, and `.use(this.harness)` installs the harness on it. The object needs a SQLite migration in your Wrangler configuration, like any Durable Object that uses SQLite storage. To use it from an `Agent`, which already has a lifecycle, call `this.lifecycle.use(this.harness)` in the constructor instead.
+
 | Option     | What it is                                                                                                                                                                                                                                                                                                                          |
 | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `harness`  | Required. Receives `{ storage, context, onWake }` and returns Pi's `Harness`, usually from `Harness.open`. Pass `onWake` to `Harness.open`, so the object can hibernate while Pi's tasks sleep (see [How recovery works](#how-recovery-works)). Models, the registry, `settings`, `env` and `onReport` are all yours to build here. |
@@ -149,7 +149,7 @@ harness: async ({ storage, context, onWake }) => {
   this.registry.install({
     name: "browser",
     tools: [
-      browserTool({ ctx: this.ctx, browser: this.browser, loader: this.env.LOADER })
+      browserTool({ browser: this.browser, loader: this.env.LOADER })
     ]
   });
   return Harness.open(
@@ -162,7 +162,7 @@ harness: async ({ storage, context, onWake }) => {
 readonly lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness);
 ```
 
-It needs a `browser` binding, a `LOADER` Worker Loader binding, and `export { CodemodeRuntime } from "@cloudflare/codemode"` from the Worker entry. Screenshots come back as images, and each conversation works in its own tab. Refer to [Persistent browser](../browse-the-web.md#persistent-browser) for how it behaves.
+It needs a `browser` binding, a `LOADER` Worker Loader binding, and `@cloudflare/codemode` installed (only until the deprecated codemode browser APIs are removed from `agents/browser`). Screenshots come back as images, and each conversation works in its own tab. Refer to [Persistent browser](../browse-the-web.md#persistent-browser) for how it behaves.
 
 ## Work with sessions
 
@@ -174,7 +174,7 @@ const { text } = await this.harness.prompt("What is 47 × 19?");
 
 // Another session, on a cheaper model.
 const session = await this.harness.sessions.create();
-await session.setModel(this.ai("@cf/zai-org/glm-4.7-flash"));
+await session.setModel(this.ai("@cf/zai-org/glm-5.3-flash"));
 
 // Durable once it returns; the same operation id twice is one submission.
 const receipt = await session.submit("Summarize the latest report", {
@@ -183,20 +183,20 @@ const receipt = await session.submit("Summarize the latest report", {
 const result = await session.wait(receipt.operationId);
 ```
 
-| Call                                              | What it does                                                                                                                                                                                                                                                                                                                         |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `prompt(input)`                                   | Submits and waits: the answer, and the transcript after it.                                                                                                                                                                                                                                                                          |
-| `submit(input, { operationId, whenBusy, entry })` | Hands the input to Pi and returns as soon as Pi has saved it, without waiting for the model. If the session is already working, the input waits until that work finishes. With `whenBusy: "steer"`, it joins the running work instead, after the current round of tool calls. `entry` records where the input came from (see below). |
-| `wait(operationId, signal?)`                      | The operation's result once Pi settles it. Aborting `signal` stops only the wait, not the work.                                                                                                                                                                                                                                      |
-| `steer(input)`                                    | `submit` with `whenBusy: "steer"`.                                                                                                                                                                                                                                                                                                   |
-| `abort(operationId?)`                             | Withdraws a queued operation, or with no id, stops everything running in the session.                                                                                                                                                                                                                                                |
-| `pending()`                                       | Operations Pi has not settled yet: queued, part of the running work, or `parked` (see [How recovery works](#how-recovery-works)).                                                                                                                                                                                                    |
-| `retry()`                                         | Runs again the tasks Pi's restart limit parked in the session's work. Resolves `false` when nothing was parked.                                                                                                                                                                                                                      |
-| `messages()`                                      | Pi's transcript entries since the newest reset.                                                                                                                                                                                                                                                                                      |
-| `events()`                                        | Pi's agent events: a `snapshot`, then one batch per commit.                                                                                                                                                                                                                                                                          |
-| `reset(handoff?)`                                 | Starts a new context, optionally from a handoff note.                                                                                                                                                                                                                                                                                |
-| `setModel(model)`                                 | Changes this session's model.                                                                                                                                                                                                                                                                                                        |
-| `busy()`                                          | Whether a run is going.                                                                                                                                                                                                                                                                                                              |
+| Call                                              | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prompt(input)`                                   | Submits and waits: the answer, and the transcript after it.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `submit(input, { operationId, whenBusy, entry })` | Hands the input to Pi and returns as soon as Pi has saved it, without waiting for the model. If the session is already working, the input waits until that work finishes. With `whenBusy: "steer"`, it joins the running work instead, after the current round of tool calls. With `whenBusy: "reject"`, it is not admitted: `submit` rejects with Pi's `ConversationBusy` and nothing is saved, so the same `operationId` can be submitted again later. `entry` records where the input came from (see below). |
+| `wait(operationId, signal?)`                      | The operation's result once Pi settles it. Aborting `signal` stops only the wait, not the work.                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `steer(input)`                                    | `submit` with `whenBusy: "steer"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `abort(operationId?)`                             | Withdraws a queued operation, or with no id, stops everything running in the session.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `pending()`                                       | Operations Pi has not settled yet: queued, part of the running work, or `parked` (see [How recovery works](#how-recovery-works)).                                                                                                                                                                                                                                                                                                                                                                               |
+| `retry()`                                         | Runs again the tasks Pi's restart limit parked in the session's work. Resolves `false` when nothing was parked.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `messages()`                                      | Pi's transcript entries since the newest reset.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `events()`                                        | Pi's agent events: a `snapshot`, then one batch per commit.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `reset(handoff?)`                                 | Starts a new context, optionally from a handoff note.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `setModel(model)`                                 | Changes this session's model.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `busy()`                                          | Whether a run is going.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 `harness.prompt()`, `submit()`, `wait()`, `abort()`, `retry()`, `messages()` and `pending()` act on the root session, or on `{ session }`. `harness.sessions` has `create()`, `fork(from)`, `get(id)` and `list()`, which includes sessions subagents created. `ROOT_SESSION` is the root's id.
 

package/docs/index.md

@@ -49,7 +49,7 @@ The Lifecycle runs startup, routes requests to capabilities, and owns the object
 
 ## Harnesses
 
-- [Pi harness (Beta)](./harnesses/pi.md) - Host pi-durable sessions in a Durable Object with durable storage and lifecycle wakeups
+- [Pi harness](./harnesses/pi.md) - Host pi-durable sessions in a Durable Object with durable storage and lifecycle wakeups
 - [Think harness (Experimental)](./harnesses/think.md) - Run Think's agent loop as a Lifecycle capability, with transcripts in Sessions, output in Streams, and turns that survive eviction
 - [Think (Experimental)](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) - Opinionated chat agent with built-in memory, tools, and streaming. Extends `Think`, which builds on `Agent`.
 
@@ -136,12 +136,12 @@ Building your own harness? Sessions stores the conversation, Streams holds durab
 - TODO: [AI SDK Integration](./ai-sdk.md) - Using Vercel AI SDK with agents
 - TODO: [TanStack Integration](./tanstack.md) - Using TanStack AI with agents
 - TODO: [Using AI Models](./using-ai-models.md) - OpenAI, Anthropic, Workers AI, and other providers
-- [Models (Experimental)](./models.md) - `createAI` — one AI SDK provider for Workers AI and third-party catalog models, same string space
-- [Models for pi-ai (Beta)](./models-pi-ai.md) - `createAI` for pi-ai: Workers AI ids and third-party models through AI Gateway, as a pi-ai provider
+- [Models](./models.md) - `createAI` — one AI SDK provider for Workers AI and third-party catalog models, same string space
+- [Models for pi-ai](./models-pi-ai.md) - `createAI` for pi-ai: Workers AI ids and third-party models through AI Gateway, as a pi-ai provider
 - [Context (Experimental)](./context.md) - System-prompt blocks, frozen prompts, writable/searchable/loadable providers, and their tools
 - [Workspace (Experimental)](https://github.com/cloudflare/agents/blob/main/docs/shell/index.md) - Durable virtual filesystem backed by SQLite + R2
 - [Codemode (Experimental)](./codemode.md) - LLM-generated executable code for tool orchestration
-- [Browse the Web (Experimental)](./browse-the-web.md) - Full CDP access for web inspection, scraping, and debugging
+- [Browse the Web](./browse-the-web.md) - Full CDP access for web inspection, scraping, and debugging
 - [Search the Web (Beta)](./search-the-web.md) - A `websearch` tool over Cloudflare's Web Search API for the pi harness, the AI SDK, and TanStack AI
 - [Fetch the Web (Beta)](./fetch-the-web.md) - A `web_fetch` tool that reads a URL as Markdown, JSON, or text, with a host-controlled URL policy, for the pi harness, the AI SDK, TanStack AI, and Think
 - TODO: [Cloudflare Sandboxes](./sandboxes.md) - Isolated environments for coding agents, ffmpeg, and heavy compute

package/docs/mcp-client.md

@@ -63,6 +63,8 @@ Install the exact MCP client peer used by this Agents release:
 pnpm add agents @modelcontextprotocol/client@2.3.1
 ```
 
+The MCP client does not need `@modelcontextprotocol/sdk` or `@modelcontextprotocol/server`. Those packages are optional peers used only by the MCP server APIs.
+
 ```typescript
 import { Agent } from "agents";
 

package/docs/mcp-servers.md

@@ -8,7 +8,9 @@ Build an MCP server on Workers with `createMcpHandler` from `agents/mcp/server`
 pnpm add agents @modelcontextprotocol/server@2.3.1 zod
 ```
 
-Use the exact `@modelcontextprotocol/server` version required by your installed Agents release.
+`@modelcontextprotocol/server` is an optional peer dependency of `agents`, so your package manager does not install it for you. Use the exact version required by your installed Agents release.
+
+Upgrading a server that uses `McpAgent`? See [Upgrading an existing `McpAgent` server](#upgrading-an-existing-mcpagent-server).
 
 ## Create a server
 
@@ -150,6 +152,7 @@ Wrap the handler with `OAuthProvider` from `@cloudflare/workers-oauth-provider`
 ```typescript
 import { OAuthProvider } from "@cloudflare/workers-oauth-provider";
 import { createMcpHandler, getMcpAuthContext } from "agents/mcp/server";
+import { env } from "cloudflare:workers";
 
 function createServer() {
   const server = new McpServer({ name: "Authenticated", version: "1.0.0" });
@@ -189,15 +192,17 @@ export default new OAuthProvider({
       return mcpHandler(request, env, ctx);
     }
   },
-  defaultHandler: AuthHandler // your consent and login flow
+  defaultHandler: AuthHandler, // your consent and login flow
+  // The URL MCP clients connect to. Every token is bound to it.
+  resourceMetadata: { resource: env.MCP_RESOURCE }
 });
 ```
 
 `OAuthProvider` needs an object with a `fetch` method, so wrap the handler as shown. Passing the handler function directly throws at startup.
 
-`getMcpAuthContext().props` returns the `props` you passed to `completeAuthorization()` in your auth flow. Tool callbacks also receive the standard SDK v2 `AuthInfo` at `context.http.authInfo`. Do not log or return `context.http.authInfo.token` or `authInfo.extra.props`.
+`getMcpAuthContext().props` returns the `props` you passed to `completeAuthorization()` in your auth flow. Tool callbacks also receive the standard SDK v2 `AuthInfo` at `context.http.authInfo`. `authInfo` is set only when the token has a client ID and `props` is a plain object. Tokens from `resolveExternalToken` have no client ID, so for those only `getMcpAuthContext().props` is available. Do not log or return `context.http.authInfo.token` or `authInfo.extra.props`.
 
-The OAuth flow needs a KV namespace bound as `OAUTH_KV`. For a complete server with a login page, see [`examples/mcp-worker-authenticated`](https://github.com/cloudflare/agents/tree/main/examples/mcp-worker-authenticated). For consent dialogs, CSRF, and proxying to a third-party identity provider, see [Securing MCP Servers](./securing-mcp-servers.md).
+Set `MCP_RESOURCE` in `wrangler.jsonc` to the URL clients connect to: Workers OAuth Provider 1.x binds every token to it. The OAuth flow also needs a KV namespace bound as `OAUTH_KV`. For a complete server with a login page, see [`examples/mcp-worker-authenticated`](https://github.com/cloudflare/agents/tree/main/examples/mcp-worker-authenticated). For the consent page and signing in through a third-party provider, see [Securing MCP Servers](./securing-mcp-servers.md).
 
 ## Elicitation
 
@@ -269,9 +274,23 @@ The handler does not serve the standalone SSE transport.
 
 If the handler lifecycle does not fit, use the SDK's `WebStandardStreamableHTTPServerTransport` from `@modelcontextprotocol/server` directly in your Worker.
 
-## Migrating from `McpAgent`
+## Upgrading an existing `McpAgent` server
+
+`McpAgent` is deprecated, but existing servers keep working. It is built on MCP SDK v1, which is an optional peer dependency of `agents`, so your package manager no longer installs it for you. Add the exact version your Agents release expects before you upgrade:
+
+```sh
+pnpm add agents @modelcontextprotocol/sdk@1.32.1 zod
+```
+
+Keep importing `McpServer` from `@modelcontextprotocol/sdk/server/mcp.js` in an `McpAgent`. An SDK v2 server from `@modelcontextprotocol/server` cannot run inside `McpAgent`. The same applies to `WorkerTransport` and `createLegacyMcpHandler` from `agents/mcp`.
+
+`agents/x402` also needs `@modelcontextprotocol/sdk`. It does not load the package at runtime, but its types refer to SDK v1 clients and tools.
+
+If your server imported `@modelcontextprotocol/sdk` without listing it in `package.json`, it only worked because `agents` installed the package. After you upgrade, the build fails with an unresolved `@modelcontextprotocol/sdk` import until you add it.
+
+Client code does not need the v1 SDK. If you import client helpers such as `RPCClientTransport` or `normalizeServerId` from `agents/mcp`, import them from `agents/mcp/client` instead.
 
-`McpAgent` is deprecated. To move an existing server to `createMcpHandler`, follow [Migrate to MCP SDK v2](https://developers.cloudflare.com/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2/).
+To move the server itself to `createMcpHandler`, follow [Migrate to MCP SDK v2](https://developers.cloudflare.com/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2/).
 
 ## Examples
 

package/docs/models-pi-ai.md

@@ -1,4 +1,4 @@
-# Models for pi-ai (Beta)
+# Models for pi-ai
 
 `agents/models/pi-ai` is the [pi-ai](https://github.com/earendil-works/pi/tree/main/packages/ai)
 twin of [`agents/models/ai-sdk`](./models.md): the same `createAI` factory, the same options,
@@ -21,7 +21,7 @@ import { getBuiltinModel } from "@earendil-works/pi-ai/providers/all";
 
 const ai = createAI({ binding: env.AI, id: "prod", cacheTtl: 60 });
 
-ai("@cf/zai-org/glm-4.7-flash"); // Workers AI: our catalog, our compat layer
+ai("@cf/zai-org/glm-5.3-flash"); // Workers AI: our catalog, our compat layer
 ai(getBuiltinModel("anthropic", "claude-opus-4-8")); // their model, our transport
 ```
 
@@ -47,7 +47,6 @@ design: a model this package cannot name exactly is yours to construct.
    `env.AI.run`, other model objects through the binding's `fetch` to AI Gateway's
    provider-native path. With [an account id and API token](#account-id-and-api-token) the
    same requests go over HTTP instead.
-5. Everything here is in beta and may change in a minor release.
 
 ## Quick start
 
@@ -66,7 +65,7 @@ import { createAI } from "agents/models/pi-ai";
 export default {
   async fetch(_request: Request, env: { AI: Ai }) {
     const ai = createAI({ binding: env.AI });
-    const reply = await ai.complete(ai("@cf/zai-org/glm-4.7-flash"), {
+    const reply = await ai.complete(ai("@cf/zai-org/glm-5.3-flash"), {
       messages: [{ role: "user", content: "Hello", timestamp: Date.now() }]
     });
     // `content` is an array of parts — text, thinking, tool calls.
@@ -103,7 +102,7 @@ Workers AI and catalog models go to AI Gateway's
 
 ```ts
 // 1. Workers AI — ours.
-ai("@cf/zai-org/glm-4.7-flash");
+ai("@cf/zai-org/glm-5.3-flash");
 
 // 2. pi-ai's Cloudflare AI Gateway catalog — a string, resolved by pi, not us.
 ai("anthropic/claude-opus-4.8");
@@ -181,7 +180,7 @@ import { createModels } from "@earendil-works/pi-ai/models";
 const models = createModels();
 models.setProvider(ai.provider); // provider id: "cloudflare"
 models.getModel("cloudflare", "anthropic/claude-opus-4.8");
-models.streamSimple(ai("@cf/zai-org/glm-4.7-flash"), context);
+models.streamSimple(ai("@cf/zai-org/glm-5.3-flash"), context);
 ```
 
 The provider's static list is every Workers AI id pi-ai knows plus every `<provider>/<id>` in
@@ -206,7 +205,7 @@ ai("anthropic/claude-opus-4.8", {
   requestTimeoutMs: 30_000,
   retries: { maxAttempts: 3, backoff: "exponential", retryDelayMs: 500 },
   byokAlias: "team-a", // which stored BYOK key, by alias
-  fallback: ["@cf/zai-org/glm-4.7-flash"], // ids or models, in any mix
+  fallback: ["@cf/zai-org/glm-5.3-flash"], // ids or models, in any mix
   headers: { "x-request-source": "docs" },
   sessionAffinity: "chat-42", // Workers AI prefix-cache routing
   reasoningEffort: "low", // "low" | "medium" | "high" | null
@@ -336,7 +335,7 @@ and are not resumed. The run id is on the `cloudflare` diagnostic as `runId`.
 ## Fallback
 
 ```ts
-ai(claude, { fallback: ["@cf/zai-org/glm-4.7-flash"] });
+ai(claude, { fallback: ["@cf/zai-org/glm-5.3-flash"] });
 ```
 
 Legs may be Workers AI ids or models, in any mix. They are tried in order: a leg is abandoned
@@ -368,11 +367,10 @@ Image generation is Workers AI only. The knobs a model takes are the model's:
 in a `cloudflare-compat` diagnostic on the result rather than sent and ignored.
 Every other model in the catalog takes the full set.
 
-## Beta
+## Requirements
 
 This subpath needs `@earendil-works/pi-ai@~1.4.0`, an optional peer of `agents`. `agents`
-takes no vendor package as a dependency, optional or otherwise. The surface is in beta
-and may change in a minor release. An unlisted `@cf/` id resolves with default metadata (a
+takes no vendor package as a dependency, optional or otherwise. An unlisted `@cf/` id resolves with default metadata (a
 128k context window, 8192 output tokens, zero cost); pass overrides when you know better.
 
 ## See also

package/docs/models.md

@@ -1,4 +1,4 @@
-# Models (Experimental)
+# Models
 
 `agents/models/ai-sdk` is Cloudflare's AI SDK provider. It takes two call
 forms, through the `AI` binding or
@@ -557,13 +557,6 @@ try {
 On a model object this covers the gateway's own failures; a vendor's own error
 is raised by that vendor's provider in its own error type.
 
-## Experimental
-
-This module is experimental. The surface may change in a minor release, and
-every exported symbol is tagged `@experimental`. It ships from `agents` first;
-the plan is for `cloudflare/ai` to re-export it and deprecate the older
-`workers-ai-provider` / `ai-gateway-provider` packages.
-
 ## See also
 
 - [Models for pi-ai](./models-pi-ai.md) — the same factory for pi-ai and pi-durable