agents 0.26.0 → 0.28.0

package/docs/index.md

@@ -1,6 +1,25 @@
 # Agents Documentation
 
-Build stateful AI agents on Cloudflare Workers. Every agent is a Durable Object — an addressable, hibernatable actor with its own SQLite database, WebSockets, and scheduling — so you can afford one durable agent per user, account, task, or conversation, with near-zero cost while idle.
+Build stateful AI agents on Cloudflare Workers. An agent is a Durable Object: an addressable actor with its own SQLite database, alarms, and WebSockets. You can run one durable agent per user, account, task, or conversation, and pay close to nothing while it is idle.
+
+Every agent starts the same way. Extend `DurableObject`, install a [Lifecycle](./lifecycle.md), and add the capabilities you need:
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+import { Lifecycle } from "agents/lifecycle";
+import { MCPClientManager } from "agents/mcp/client";
+import { Scheduler } from "agents/schedules";
+
+export class Assistant extends DurableObject<Env> {
+  readonly mcp = new MCPClientManager("assistant", "1.0.0");
+  readonly scheduler = new Scheduler({ callbacks: {} });
+  readonly lifecycle = Lifecycle.install(this)
+    .use(this.mcp)
+    .use(this.scheduler);
+}
+```
+
+The Lifecycle runs startup, routes requests to capabilities, and owns the object's durable job queue and its single alarm. Capabilities are independent pieces that share it.
 
 ## Related package documentation
 
@@ -9,86 +28,95 @@ Build stateful AI agents on Cloudflare Workers. Every agent is a Durable Object
 
 ## Choose your path
 
-Pick the base class that matches what you are building. They share the same Durable Object foundation, so you can start small and move up without re-platforming.
+| You are building...                                     | Use                                                                                             |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| An agent that runs a model loop with tools and recovery | [Pi harness](./harnesses/pi.md) on a Durable Object                                             |
+| Your own agent loop                                     | [Sessions](./sessions.md), [Streams](./streams.md), and [Tasks](./tasks.md) on a Durable Object |
+| A chat or reasoning agent with every default built in   | [`Think`](https://github.com/cloudflare/agents/blob/main/docs/think/index.md)                   |
+| A chat UI that owns the loop and the stream             | [`AIChatAgent`](./chat-agents.md), built on the `Agent` class                                   |
+| Real-time state sync, `@callable` methods, email, voice | The [`Agent` class](./agent-class.md), which installs a preset of capabilities for you          |
+| Durable multi-step processes (not chat)                 | [Workflows](./workflows.md)                                                                     |
+
+## Getting started
 
-| You are building...                                            | Use                                                                           | Why                                                                                                                    |
-| -------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Stateful backend logic, real-time sync, custom protocols       | [`Agent`](./agent-class.md)                                                   | The core class: state, WebSockets, scheduling, SQL, and sub-agents. No opinions about chat or LLMs.                    |
-| A chat UI where you own the loop, the stream, and the response | [`AIChatAgent`](./chat-agents.md)                                             | A thin chat-protocol adapter for `useAgentChat`. Bring your own agentic loop and custom streaming.                     |
-| A durable, general-purpose reasoning agent                     | [`Think`](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) | Opinionated runtime: agentic loop, sessions, tools, memory, compaction, recovery, and multi-channel delivery built in. |
-| A voice agent (speech in, speech out)                          | [Voice mixins](./voice.md)                                                    | `withVoice` adds real-time STT/TTS, interruption and barge-in, and conversation persistence to an agent.               |
-| Durable multi-step processes (not chat)                        | [Workflows](./workflows.md)                                                   | Long-running, retryable step orchestration with Cloudflare Workflows.                                                  |
+- [Getting Started](./getting-started.md) - Quick start guide for new users
+- [Adding to an Existing Project](./adding-to-existing-project.md) - Integrate agents into your app
 
-Not sure? Start with [`Agent`](./agent-class.md) for raw building blocks, or [`Think`](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) if you want a chat or reasoning agent that already handles the hard parts.
+## Lifecycle
 
-## What makes these production-grade
+- [Durable Object Lifecycle](./lifecycle.md) - Install a Lifecycle on a Durable Object, write capabilities, and use the job queue
+- [getCurrentAgent()](./get-current-agent.md) - Accessing the current object, request, and connection across async calls
 
-The differentiator is not "we have durable state" — it is what happens when a turn is interrupted. Agents built on this SDK keep their promises across Durable Object eviction, deploys, client disconnects, and human waits:
+## Harnesses
 
-- **Turn recovery** — an in-flight LLM turn survives Durable Object eviction and resumes instead of silently dying. See [Chat & Fiber Recovery](./chat-agents.md#stream-recovery) and [Durable Execution](./durable-execution.md).
-- **Resumable streams** — a disconnected client rejoins the same stream rather than losing the response. See [Resumable Streaming](./resumable-streaming.md).
-- **Recovery-aware delivery** — Think snapshots channel delivery as `accepted`, `streaming`, or `completed`, so a restart replays a not-yet-streamed answer but posts a safe interruption notice rather than risking a duplicate partial reply. See [Messengers — Delivery and Recovery](https://github.com/cloudflare/agents/blob/main/docs/think/messengers.md#delivery-and-recovery).
-- **Durable submissions** — webhooks and RPC callers submit a turn with an idempotency key and check status later, instead of holding a request open. See [Programmatic Submissions](https://github.com/cloudflare/agents/blob/main/docs/think/programmatic-submissions.md).
-- **Human-in-the-loop without hangs** — a turn can pause for approval and resume later. A human wait is a first-class state, not a stuck request. See [Human in the Loop](./human-in-the-loop.md).
+- [Pi harness (Beta)](./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`.
 
-## Getting Started
+## Capabilities
 
-- [Getting Started](./getting-started.md) - Quick start guide for new users
-- [Adding to an Existing Project](./adding-to-existing-project.md) - Integrate agents into your app
-- [Understanding the Agent Class](./agent-class.md) - Deep dive into the Agent class architecture
+Install each capability with `lifecycle.use()`. Capabilities marked experimental may change between releases.
 
-## Core Concepts
+| Capability         | Import              | Status       | Docs                                                            |
+| ------------------ | ------------------- | ------------ | --------------------------------------------------------------- |
+| `PiHarness`        | `agents/harness/pi` | Beta         | [Pi harness](./harnesses/pi.md)                                 |
+| `MCPClientManager` | `agents/mcp/client` | Stable       | [MCP client](./mcp-client.md)                                   |
+| `Scheduler`        | `agents/schedules`  | Stable       | [Scheduling](./scheduling.md)                                   |
+| `State`            | `agents/state`      | Stable       | [Lifecycle](./lifecycle.md#websockets-are-an-opt-in-capability) |
+| `WebSockets`       | `agents/websockets` | Stable       | [Lifecycle](./lifecycle.md#websockets-are-an-opt-in-capability) |
+| `Queue`            | `agents/queue`      | Experimental | [Queue](./queue.md)                                             |
+| `RoutedAgents`     | `agents/routing`    | Experimental | [Routing](./routing.md)                                         |
+| `Browser`          | `agents/browser`    | Experimental | [Browse the Web](./browse-the-web.md)                           |
+| `Sessions`         | `agents/sessions`   | Experimental | [Sessions](./sessions.md)                                       |
+| `Streams`          | `agents/streams`    | Experimental | [Streams](./streams.md)                                         |
+| `Tasks`            | `agents/tasks`      | Experimental | [Tasks](./tasks.md)                                             |
 
-- [State Management](./state.md) - Managing agent state with `setState()`, `initialState`, and `onStateChanged()`
+Building your own harness? Sessions stores the conversation, Streams holds durable incremental output, and Tasks runs replayable background work. [Models](./models.md) and [Models for pi-ai](./models-pi-ai.md) give you one provider for Workers AI and third-party models. [Context](./context.md) and [Workspace](https://github.com/cloudflare/agents/blob/main/docs/shell/index.md) are also available.
+
+## Agent class
+
+`Agent` extends `DurableObject`, installs a Lifecycle, and adds `Scheduler`, `Queue`, `MCPClientManager`, `State`, `WebSockets`, `Tasks`, and dynamic agents for you. Its methods (`this.schedule()`, `this.queue()`, `this.setState()`) delegate to those capabilities. Features below are documented for `Agent` and its subclasses.
+
+### Core
+
+- [Understanding the Agent Class](./agent-class.md) - How the Agent class is built on the Lifecycle
+- [State Management](./state.md) - `setState()`, `initialState`, and `onStateChanged()`
 - [Routing](./routing.md) - How `routeAgentRequest()` and agent naming works, plus `RoutedAgents` for a hub that routes to many independent Agents
 - [Dynamic agents](./sub-agents.md) - Facet-backed child agents for code the parent supervises (dynamic/generated code, per-run tool agents, sandboxes) — not the recommended primitive for many independent peers like chats
 - [HTTP & WebSockets](./http-websockets.md) - Request handling and real-time connections
 - [Callable Methods](./callable-methods.md) - The `@callable` decorator and client-server method calls
 - [Readonly Connections](./readonly-connections.md) - Restricting which connections can modify state
-- [getCurrentAgent()](./get-current-agent.md) - Accessing agent context across async calls
+- [Client SDK](./client-sdk.md) - Connecting from React (`useAgent`) and vanilla JS (`AgentClient`), state sync, and RPC calls
 
-## Client SDK
+### Background processing
 
-- [Client SDK](./client-sdk.md) - Connecting from React (`useAgent`) and vanilla JS (`AgentClient`), state sync, and RPC calls
+- [Queue](./queue.md) - Durable background task execution
+- [Scheduling](./scheduling.md) - Delayed, scheduled, and cron-based tasks
+- [Retries](./retries.md) - Automatic retries with exponential backoff and jitter
+- [Durable Execution](./durable-execution.md) - `runFiber()`, `startFiber()`, `stash()`, and crash recovery for long tasks
+- [Workflows](./workflows.md) - Durable multi-step processing with Cloudflare Workflows
+- [Human in the Loop](./human-in-the-loop.md) - Approval flows and manual intervention
 
-## Communication Channels
+### Communication channels
 
 - [Email Service](./email.md) - Sending, receiving, and replying to emails
 - [Webhooks](./webhooks.md) - Receiving and sending webhook events
 - [Push Notifications](./push-notifications.md) - Browser push notifications via Web Push API and scheduled delivery
 - TODO: [SMS](./sms.md) - Text message integration (Twilio, etc.)
 - [Voice Agents](./voice.md) - Build voice agents with real-time speech-to-text, text-to-speech, and conversation persistence
-- [Channels](./channels.md) - Send and receive messages through Slack, Telegram, email, browser voice, or custom adapters
 - [Chat SDK State](./chat-sdk.md) - Store Chat SDK subscriptions, locks, queues, and history in Agents sub-agents
 
-## Background Processing
-
-- [Queue](./queue.md) - Durable background task execution
-- [Scheduling](./scheduling.md) - Delayed, scheduled, and cron-based tasks
-- [Retries](./retries.md) - Automatic retries with exponential backoff and jitter
-- [Durable Execution](./durable-execution.md) - `runFiber()`, `startFiber()`, `stash()`, and crash recovery for long tasks
-- [Workflows](./workflows.md) - Durable multi-step processing with Cloudflare Workflows
-- [Human in the Loop](./human-in-the-loop.md) - Approval flows and manual intervention
-
-## AI Integration
+### Chat and AI
 
-- TODO: [AI SDK Integration](./ai-sdk.md) - Using Vercel AI SDK with agents
-- TODO: [TanStack Integration](./tanstack.md) - Using TanStack AI with agents
 - [Chat Agents](./chat-agents.md) - `AIChatAgent` class and `useAgentChat` React hook
 - [Chat & Fiber Recovery](./chat-agents.md#stream-recovery) - Recover LLM turns after Durable Object eviction
 - [Agent Tools](./agent-tools.md) - Run chat-capable sub-agents as tools with streaming child timelines
 - [Server-Driven Messages](./server-driven-messages.md) - Autonomous agent workflows: scheduled follow-ups, queue processing, webhooks, chained reasoning
-- 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
-- [Pi harness (Beta)](./harnesses/pi.md) - Host pi-durable sessions in a Durable Object with durable storage and lifecycle wakeups
-- TODO: [RAG (Retrieval Augmented Generation)](./rag.md) - Vector search with Vectorize
-- [Sessions (Experimental)](./sessions.md) - Durable message trees, streamed history, compaction, search, and lossless attachment offload
-- [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)](https://github.com/cloudflare/agents/blob/main/docs/agents/codemode.md) - LLM-generated executable code for tool orchestration
 - [Client Tools Continuation](./client-tools-continuation.md) - Handling tool calls across client/server
 - [Resumable Streaming](./resumable-streaming.md) - Automatic stream resumption on client disconnect
+- [Long-Running Agents](./long-running-agents.md) - Building agents that persist for weeks or months: lifecycle, recovery, async operations, and planning
+- TODO: [SQL API](./sql.md) - Using `this.sql` for direct database queries
+- TODO: [Memory & Persistence](./memory.md) - Long-term storage patterns
 
 ## Think (Experimental)
 
@@ -103,50 +131,46 @@ The differentiator is not "we have durable state" — it is what happens when a
 - [Sub-agents and Programmatic Turns](https://github.com/cloudflare/agents/blob/main/docs/think/sub-agents.md) - RPC streaming, `saveMessages`, recovery
 - [Programmatic Submissions](https://github.com/cloudflare/agents/blob/main/docs/think/programmatic-submissions.md) - Durable Think turn admission for webhooks and RPC callers
 
+## Models and tools
+
+- 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
+- [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
+- [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
+- TODO: [RAG (Retrieval Augmented Generation)](./rag.md) - Vector search with Vectorize
+
 ## MCP (Model Context Protocol)
 
 - [Creating MCP Servers](./mcp-servers.md) - Build MCP servers with `McpAgent`
 - [Securing MCP Servers](./securing-mcp-servers.md) - OAuth and authentication for MCP
-- [Connecting to MCP Servers](./mcp-client.md) - `addMcpServer()` and consuming external MCP tools
+- [Connecting to MCP Servers](./mcp-client.md) - `MCPClientManager` on a Durable Object, or `addMcpServer()` on an Agent
 - [MCP Transports](./mcp-transports.md) - Transport options: Streamable HTTP, SSE, and RPC
 
-## Authentication & Security
-
-- TODO: [Securing your Agents](./securing-agents.md) - Authentication, authorization, and access control
-- [Cross-Domain Authentication](./cross-domain-authentication.md) - Auth across different domains
-
-## Observability & Debugging
+## Operations
 
+- [Configuration](./configuration.md) - wrangler.jsonc setup, types, secrets, and deployment
 - [Observability](./observability.md) - Monitoring and tracing agent activity
+- [Cross-Domain Authentication](./cross-domain-authentication.md) - Auth across different domains
+- TODO: [Securing your Agents](./securing-agents.md) - Authentication, authorization, and access control
 - TODO: [Testing](./testing.md) - Unit tests, integration tests, mocking agents
 - TODO: [Evals](./evals.md) - Evaluating AI agent quality and behavior
-
-## Agent Studio
-
 - TODO: [Agent Studio](./agent-studio.md) - Local dev tool for inspecting and interacting with agent instances
 
-## Compute Environments
-
-- [Browse the Web (Experimental)](./browse-the-web.md) - Full CDP access for web inspection, scraping, and debugging
-- TODO: [Cloudflare Sandboxes](./sandboxes.md) - Isolated environments for coding agents, ffmpeg, and heavy compute
-
-## Advanced Topics
-
-- [Long-Running Agents](./long-running-agents.md) - Building agents that persist for weeks or months: lifecycle, recovery, async operations, and planning
-- TODO: [SQL API](./sql.md) - Using `this.sql` for direct database queries
-- TODO: [Memory & Persistence](./memory.md) - Long-term storage patterns
-- [Configuration](./configuration.md) - wrangler.jsonc setup, types, secrets, and deployment
-
-## Migration Guides
+## Migration guides
 
 - [Migration to AI SDK v5](./migration-to-ai-sdk-v5.md)
 - [Migration to AI SDK v6](./migration-to-ai-sdk-v6.md)
 
 ## Reference
 
-- [Durable Object Lifecycle](./lifecycle.md) - Compose reusable durable components outside the Agent base class
-- [Tasks](./tasks.md) - Durable, replayable background work with journaled steps and durable sleeps (experimental)
-- [Streams](./streams.md) - Durable incremental output: chunk log, cursor, replay-then-tail reads (experimental)
 - 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

@@ -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
@@ -156,6 +155,46 @@ Host-specific bindings, authentication, and protocol adapters remain explicit
 constructor dependencies. Lifecycle never grants a capability the complete
 host implicitly.
 
+A capability's public operations can run before startup, because
+[native RPC](#native-rpc) bypasses the automatic startup on fetch, alarm and
+WebSocket events. If an operation starts work that `onStart` also awaits, such
+as lazily opening a store, it must call `await this.lifecycle.ready()` first:
+
+```ts
+class Store extends LifecycleCapability {
+  #opening: Promise<Database> | undefined;
+
+  constructor() {
+    super("store");
+  }
+
+  async onStart(): Promise<void> {
+    await this.#open();
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    const db = await this.#open();
+    return db.get(key);
+  }
+
+  async #open(): Promise<Database> {
+    // Without this, an RPC that calls get() before startup begins the open
+    // outside startup, and onStart then waits on it behind a closed gate.
+    await this.lifecycle.ready();
+    this.#opening ??= openDatabase(this.lifecycle.storage);
+    return this.#opening;
+  }
+}
+```
+
+Startup holds the input gate (`blockConcurrencyWhile`) while `onStart` runs, so
+work begun outside startup has its timers and I/O held back and never finishes.
+`onStart` waits on it until startup times out after 30 seconds and the object
+is reset. Whether it happens depends on whether the RPC arrives first, so it
+shows up as an intermittent timeout. `ready()` resolves immediately inside
+startup, so `onStart` can call the same guarded method. `Tasks`, `Streams`,
+`Scheduler`, `Queue` and `PiHarness` guard their operations this way.
+
 Capability hooks run outside host context, but user callbacks run through
 `this.lifecycle.runInHostContext(fn)` inside the host invocation context.
 Scheduler and Queue dispatch their registered callbacks through this

package/docs/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`:

package/docs/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

package/docs/search-the-web.md

@@ -0,0 +1,135 @@
+# Search the Web (Beta)
+
+`agents/websearch` gives a model a `web_search` tool over Cloudflare's [Web Search API](https://developers.cloudflare.com/web-search/), called through the `AI` binding and billed by the account's AI Gateway. The same tool is available for the pi harness, the AI SDK, and TanStack AI.
+
+This page covers what the SDK adds on top of the API. For the binding, the providers, pricing, payment, and the error codes, see the [Web Search API docs](https://developers.cloudflare.com/web-search/).
+
+> **Beta** — this feature may have breaking changes in future releases.
+
+## Quick Start
+
+You need:
+
+- An `AI` binding: `"ai": { "binding": "AI" }` in `wrangler.jsonc`.
+- workerd 1.20260924.1 or later, which is where `env.AI.websearch()` arrived. It ships with wrangler 4.141.0 and `@cloudflare/vite-plugin` 1.60.2.
+- AI Gateway credits or a provider key on the gateway, in the account the Worker runs in. That account pays for every search. The `AI` binding always calls Cloudflare, so under `wrangler dev` searches run against, and bill, the account you are logged in to.
+
+Then add the tool to your harness. Every adapter takes the same options; the TanStack AI adapter also takes `name`, because TanStack AI tools carry their name in the definition.
+
+Pi harness:
+
+```ts
+import { webSearchTool } from "agents/websearch/pi";
+
+this.registry.install({
+  name: "tools",
+  tools: [webSearchTool({ binding: this.env.AI, provider: "exa" })]
+});
+```
+
+AI SDK:
+
+```ts
+import { webSearchTool } from "agents/websearch/ai-sdk";
+
+const result = streamText({
+  model,
+  tools: { web_search: webSearchTool({ binding: this.env.AI }) },
+  messages
+});
+```
+
+If you convert UI messages yourself, pass the same tools to `convertToModelMessages(messages, { tools })`. Without them, the AI SDK sends earlier search results back to the model as the full JSON response instead of the trimmed text. `AiSdkHarness` does this for you.
+
+TanStack AI:
+
+```ts
+import { webSearchTool } from "agents/websearch/tanstack-ai";
+
+const tools = [webSearchTool({ binding: this.env.AI })];
+```
+
+## Options
+
+The model's input is `{ query, limit? }` and nothing else. The host fixes everything that affects cost or data handling. An invalid `limit`, `maxDescriptionChars`, `timeoutMs`, or `byokAlias` throws a `RangeError` when the tool is created:
+
+| Option                | Default              | Notes                                                                                                                                                     |
+| --------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `binding`             | —                    | The `AI` binding. Or pass `source` instead (see [Other sources](#other-sources)).                                                                         |
+| `gateway`             | `"default"`          | AI Gateway id.                                                                                                                                            |
+| `provider`            | platform default     | `"ceramic"`, `"exa"`, or `"linkup"`. The model cannot choose or change it.                                                                                |
+| `byokAlias`           | —                    | Bill a provider key stored on the gateway. Passed through as the API defines it.                                                                          |
+| `limit`               | `5`                  | Results per search when the model does not ask for a count, and the most it gets when it asks for more. The tool description tells the model this number. |
+| `maxDescriptionChars` | `600`                | Per-result description length in the model's view. `Infinity` passes descriptions through whole.                                                          |
+| `description`         | built-in description | Replaces the tool description the model sees.                                                                                                             |
+| `timeoutMs`           | `30000`              | Give up on a search after this long, as a retryable `web_search_timeout` failure.                                                                         |
+
+## Model Interface
+
+The model gets text: a numbered list of title, URL, and description, with descriptions trimmed to `maxDescriptionChars`. Some providers return descriptions of several thousand characters per result, so the default keeps a five-result search to a few kilobytes of context.
+
+```
+3 results for "cloudflare web search api":
+
+1. Introducing the Web Search API
+https://blog.cloudflare.com/introducing-web-search-api/
+Today we are launching the Web Search API in open beta…
+
+2. …
+```
+
+The host gets the full API response, without trimming, as `WebSearchToolOutput`: `items` with their whole descriptions and every documented field, `metadata` with `requestId` and `latencyMs`, plus `provider`. Items without a URL are dropped, a missing title falls back to the URL, and fields the API does not document are left out:
+
+- **Pi**: in the tool result's `details`, as `{ ok: true, output }`. The tool is `replay: "safe"`: if a search is interrupted mid-call, for example by an eviction, pi runs it again when the session recovers, and that is a second billed search. Completed results are stored and not searched again.
+- **AI SDK**: as the return value of `execute`, so `onFinish`, UI message parts, and logs see the full response. `toModelOutput` renders the text for the model.
+- **TanStack AI**: the server tool returns the rendered text, so the host gets the same text the model does.
+
+`renderWebSearchResults(output, { maxDescriptionChars })` from `agents/websearch` is the renderer, if you want the same text elsewhere.
+
+The API has no pagination. The tool description tells the model to search again with a rephrased query when it wants more or different results.
+
+Results are for discovery. To let the model read the pages it finds, add the [`web_fetch` tool](./fetch-the-web.md) beside `web_search`; the `web_search` description tells the model to fetch result URLs with `web_fetch` when it is available.
+
+## Failures
+
+A failed search becomes a `WebSearchError` with `status`, `code`, `retryable`, and `requestId` (AI Gateway's id for the request, for the gateway log). Every error has a `code`: the API's own when it sends one, for example `web_search_payment_required`, otherwise one derived from the HTTP status, such as `web_search_rate_limited` or `web_search_unavailable`. On a runtime older than the one above, the binding has no `websearch()` and the search fails with code `web_search_unsupported_runtime`.
+
+The error's `message` is written for you, and can say to top up credits or configure a key. The model gets different text that tells it what to do next: fix the query, retry once, or carry on without search.
+
+- **Pi**: the tool returns an error result with the model's text, and `details` is `{ ok: false, message, status, code, retryable, requestId }`.
+- **AI SDK** and **TanStack AI**: the tool throws a `WebSearchError`, which is how those frameworks report tool errors. Its `message` is the model's text, and its `cause` is the original error with the API's detail.
+
+Every adapter entry point re-exports `WebSearchError`, so `instanceof` checks do not need a second import.
+
+If the harness cancels the call, the search is aborted and the abort propagates instead of becoming a failed result.
+
+## Other sources
+
+`createAIWebSearch` and `createHTTPWebSearch` from `agents/websearch` return a `WebSearchSource`: an object whose `search({ query, limit? }, { signal? })` returns the API response (`limit` defaults to 5), with no model involved. Use them from scheduled jobs, or outside Workers:
+
+```ts
+import { createHTTPWebSearch } from "agents/websearch";
+
+const search = createHTTPWebSearch({
+  accountId: env.CF_ACCOUNT_ID,
+  apiToken: env.CF_API_TOKEN,
+  provider: "linkup"
+});
+const { items } = await search.search({
+  query: "cloudflare agents sdk",
+  limit: 3
+});
+```
+
+Any `WebSearchSource` can be passed to a tool as `source` instead of `binding`. That is how tests substitute a fake, and how you wrap a source with caching or logging. Spread the source you wrap so its `provider` is kept:
+
+```ts
+webSearchTool({
+  source: {
+    search: async ({ query }) => ({
+      items: [{ url: "https://example.com", title: query }],
+      metadata: { query, requestId: "test", latencyMs: 0 }
+    })
+  }
+});
+```