agents 0.20.0 → 0.21.0

package/dist/ws-chat-transport-UNRIS2xl.d.ts

@@ -0,0 +1,184 @@
+import { ChatTransport, UIMessage, UIMessageChunk } from "ai";
+
+//#region src/chat/ws-chat-transport.d.ts
+/**
+ * Agent-like interface for sending/receiving WebSocket messages.
+ * Matches `AgentClient` from `agents/client` and the connection returned by
+ * `useAgent` from `agents/react`.
+ */
+interface AgentConnection {
+  send: (data: string) => void;
+  addEventListener: (
+    type: string,
+    listener: (event: MessageEvent) => void,
+    options?: {
+      signal?: AbortSignal;
+    }
+  ) => void;
+  removeEventListener: (
+    type: string,
+    listener: (event: MessageEvent) => void
+  ) => void;
+}
+type WebSocketChatTransportOptions<ChatMessage extends UIMessage = UIMessage> =
+  {
+    /** The framework-neutral AgentClient or useAgent connection. */ agent: AgentConnection;
+    /**
+     * Callback to add custom fields to the request body before sending.
+     */
+    prepareBody?: (options: {
+      messages: ChatMessage[];
+      trigger: "submit-message" | "regenerate-message";
+      messageId?: string;
+    }) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    /**
+     * Optional set to track active request IDs.
+     * IDs are added when a request starts and removed when it completes.
+     * Used by the onAgentMessage handler to skip messages already handled by the transport.
+     */
+    activeRequestIds?: Set<string>;
+    /**
+     * Whether generic client-side abort/cancel lifecycle should cancel the
+     * server turn. Explicit cancellation via cancelActiveServerTurn() always
+     * sends CF_AGENT_CHAT_REQUEST_CANCEL.
+     * @default false
+     */
+    cancelOnClientAbort?: boolean;
+  };
+/**
+ * ChatTransport that sends messages over WebSocket and returns a
+ * ReadableStream<UIMessageChunk> that the AI SDK's useChat consumes directly.
+ *
+ * This low-level transport handles new and regenerated request streams plus
+ * cancellation. Higher-level protocol coordination such as automatic reconnect
+ * resume, cross-tab transcript synchronization, and client-tool continuations
+ * is provided by integrations such as `useAgentChat`.
+ */
+declare class WebSocketChatTransport<
+  ChatMessage extends UIMessage = UIMessage
+> implements ChatTransport<ChatMessage> {
+  agent: AgentConnection;
+  private prepareBody?;
+  private activeRequestIds?;
+  private cancelOnClientAbort;
+  private _resumeResolver;
+  private _resumeNoneResolver;
+  private _onStreamPending;
+  private _retryResumeProbe;
+  private _expectToolContinuation;
+  private _abortToolContinuation;
+  private _activeServerTurnId;
+  private _cancelAttachedStream;
+  private _detachResumeStream;
+  constructor(options: WebSocketChatTransportOptions<ChatMessage>);
+  /**
+   * Point the singleton transport at a new Agent connection. A pending resolver
+   * belongs to the old Chat/socket generation and must settle before messages
+   * from the replacement connection can be consumed (#1914 review).
+   */
+  setAgent(agent: AgentConnection): void;
+  setCancelOnClientAbort(cancelOnClientAbort: boolean): void;
+  /**
+   * Explicitly cancel the active server turn, if any.
+   * This is separate from generic client-side abort/cancel lifecycle so
+   * clients can detach locally without stopping server work.
+   */
+  cancelActiveServerTurn(): boolean;
+  private sendCancelFrame;
+  private setActiveServerTurn;
+  private clearActiveServerTurn;
+  /**
+   * Mark that the next reconnectToStream() call should attach to a
+   * server-initiated tool continuation rather than a page-load resume.
+   */
+  expectToolContinuation(): void;
+  /**
+   * Abort the active client-side tool continuation stream, if one is attached
+   * to a server request id.
+   */
+  abortActiveToolContinuation(): boolean;
+  /**
+   * True when the transport is waiting for a resume handshake.
+   */
+  isAwaitingResume(): boolean;
+  /**
+   * Settle and detach the current handshake without interpreting it as a
+   * server-idle response. Used when the owning hook/agent generation changes.
+   */
+  cancelPendingResume(): boolean;
+  /**
+   * Invalidate all client-side resume state for an obsolete hook/agent
+   * generation without cancelling its durable server turn.
+   */
+  resetResumeState(): void;
+  /**
+   * Re-send the active handshake request on the latest socket generation. This
+   * preserves one AI SDK resume operation while recovering a request/reply lost
+   * with the previous WebSocket.
+   */
+  retryPendingResume(): boolean;
+  /**
+   * Called by onAgentMessage when it receives CF_AGENT_STREAM_RESUMING.
+   * If reconnectToStream is waiting, this handles the resume handshake
+   * (ACK + stream creation) and returns true. Otherwise returns false
+   * so the caller can use its own fallback path.
+   */
+  handleStreamResuming(data: { id: string }): boolean;
+  /**
+   * Called by onAgentMessage when it receives CF_AGENT_STREAM_RESUME_NONE.
+   * If reconnectToStream is waiting, resolves the promise with null
+   * immediately (no 5-second timeout). Returns true if handled.
+   */
+  handleStreamResumeNone(data?: { probeId?: string }): boolean;
+  /**
+   * Called by onAgentMessage when it receives CF_AGENT_STREAM_PENDING (#1784):
+   * the server accepted a turn but its stream has not started yet. If a resume
+   * path is awaiting, extend its probe timeout (so it keeps waiting for the
+   * eventual STREAM_RESUMING / STREAM_RESUME_NONE instead of resolving null
+   * after the short window). Returns true if a waiting path consumed it.
+   */
+  handleStreamPending(): boolean;
+  /**
+   * Called by the hook's shared message handler when a server turn finishes
+   * outside the currently attached transport stream, such as after local-only
+   * client cleanup.
+   */
+  handleServerTurnCompleted(requestId: string): void;
+  /**
+   * Register a server turn that is being rendered outside a transport-owned
+   * stream, such as the hook's fallback cross-tab/resume observer path.
+   */
+  observeServerTurn(requestId: string): void;
+  sendMessages(options: {
+    chatId: string;
+    messages: ChatMessage[];
+    abortSignal: AbortSignal | undefined;
+    trigger: "submit-message" | "regenerate-message";
+    messageId?: string;
+    body?: object;
+    headers?: Record<string, string> | Headers;
+    metadata?: unknown;
+  }): Promise<ReadableStream<UIMessageChunk>>;
+  reconnectToStream(_options: {
+    chatId: string;
+  }): Promise<ReadableStream<UIMessageChunk> | null>;
+  /**
+   * Creates a deferred ReadableStream for client-side tool continuations.
+   * The stream is returned immediately so AI SDK status becomes "submitted"
+   * right after addToolOutput()/addToolApprovalResponse(), then it waits for
+   * the server to announce the continuation via STREAM_RESUMING.
+   */
+  private _createToolContinuationStream;
+  /**
+   * Creates a ReadableStream that receives resumed stream chunks
+   * and forwards them to useChat as UIMessageChunk objects.
+   */
+  private _createResumeStream;
+}
+//#endregion
+export {
+  WebSocketChatTransport as n,
+  WebSocketChatTransportOptions as r,
+  AgentConnection as t
+};
+//# sourceMappingURL=ws-chat-transport-UNRIS2xl.d.ts.map

package/docs/adding-to-existing-project.md

@@ -32,7 +32,7 @@ npm install agents hono-agents
 Create a new file for your agent (e.g., `src/agents/counter.ts`):
 
 ```typescript
-import { Agent } from "agents";
+import { Agent, callable } from "agents";
 
 type CounterState = {
   count: number;
@@ -41,11 +41,13 @@ type CounterState = {
 export class Counter extends Agent<Env, CounterState> {
   initialState: CounterState = { count: 0 };
 
+  @callable()
   increment() {
     this.setState({ count: this.state.count + 1 });
     return this.state.count;
   }
 
+  @callable()
   decrement() {
     this.setState({ count: this.state.count - 1 });
     return this.state.count;
@@ -371,7 +373,7 @@ By default, agents are routed at `/agents/{agent-name}/{instance-name}`. You can
 import { routeAgentRequest } from "agents";
 
 const agentResponse = await routeAgentRequest(request, env, {
-  prefix: "/api/agents" // Now routes at /api/agents/{agent-name}/{instance-name}
+  prefix: "api/agents" // Now routes at /api/agents/{agent-name}/{instance-name}
 });
 ```
 

package/docs/agent-class.md

@@ -250,7 +250,7 @@ class MyAgent extends Agent {
 
 ### RPC and Callable Methods
 
-`agents` take Durable Objects RPC one step forward by implementing RPC through WebSockets, so clients can also call methods on the Agent directly. To make a method callable through WS, developers can use the `@callable` decorator. Methods can return a serializable value or a stream (when using `@callable({ stream: true })`).
+`agents` take Durable Objects RPC one step forward by implementing RPC through WebSockets, so clients can also call methods on the Agent directly. To make a method callable through WS, developers can use the `@callable` decorator. Methods can return a serializable value or stream chunks (when using `@callable({ streaming: true })`).
 
 ```ts
 class MyAgent extends Agent {

package/docs/agent-tools.md

@@ -48,6 +48,35 @@ export class Assistant extends Think<Env> {
 }
 ```
 
+### Use Valibot or another schema library
+
+`agentTool()` accepts the AI SDK's flexible schema format. For Valibot, wrap the
+schema with `valibotSchema()` so the AI SDK receives both runtime validation and
+the JSON Schema required by the model. Use `@ai-sdk/valibot` v2 with AI SDK 6
+and v3 with AI SDK 7:
+
+```ts
+import { valibotSchema } from "@ai-sdk/valibot";
+import { agentTool } from "agents/agent-tools";
+import * as v from "valibot";
+
+const researchInput = valibotSchema(
+  v.object({
+    query: v.pipe(v.string(), v.minLength(3))
+  })
+);
+
+const research = agentTool(Researcher, {
+  description: "Research one topic in depth.",
+  inputSchema: researchInput
+});
+```
+
+You can also provide a Zod schema, a Standard JSON Schema-compatible schema, or
+a raw JSON Schema wrapped with `jsonSchema()` from `ai`. A validation-only
+Standard Schema is not sufficient for a tool input because it does not provide
+the JSON Schema sent to the model.
+
 The child can also be an `AIChatAgent`:
 
 ```ts

package/docs/browse-the-web.md

@@ -244,7 +244,7 @@ const md = await browserMarkdown(this.env.BROWSER, { url });
 const data = await browserExtract<{ price: number }>(this.env.BROWSER, {
   url,
   prompt: "the product price",
-  response_format: { type: "json_schema", schema: priceSchema }
+  response_format: { type: "json_schema", json_schema: priceSchema }
 });
 ```
 
@@ -279,6 +279,21 @@ class Researcher extends Think<Env> {
 
 Quick Actions require a Worker `compatibility_date` of `2026-03-24` or later and `remote: true` on the browser binding for local `wrangler dev`.
 
+## Using Kitesurf
+
+To use Kitesurf with the CDP-based `browser_execute` tool, select it in the session options:
+
+```ts
+const tools = createBrowserTools({
+  ctx: this.ctx,
+  browser: this.env.BROWSER,
+  loader: this.env.LOADER,
+  session: { browser: "kitesurf" }
+});
+```
+
+A Kitesurf browser is scoped to its CDP WebSocket. It therefore supports only one-shot execution. Session reuse, pause and resume, Live View, recording, `keepAliveMs`, protocol discovery, and Kitesurf-backed Quick Actions are not available.
+
 ## Live View and human-in-the-loop
 
 [Live View](https://developers.cloudflare.com/browser-run/features/live-view/) lets a human open a URL and watch — or take control of — a running browser session in real time. It is the building block for human-in-the-loop steps such as logging in, solving a CAPTCHA, completing MFA, or entering data you do not want to pass through an automation script.

package/docs/chat-agents.md

@@ -25,7 +25,7 @@ Built on the [AI SDK](https://ai-sdk.dev) and Cloudflare Durable Objects, you ge
 ### Install
 
 ```sh
-npm install @cloudflare/ai-chat agents ai workers-ai-provider
+npm install @cloudflare/ai-chat agents ai @ai-sdk/react workers-ai-provider
 ```
 
 ### Server
@@ -956,6 +956,8 @@ async onChatMessage() {
 }
 ```
 
+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-Side Tools
 
 Define a tool on the server without `execute`, then handle it on the client with `onToolCall`. Use this for tools that need browser APIs:

package/docs/client-sdk.md

@@ -264,17 +264,21 @@ const result = await agent.stub.processData({ input: "test" });
 
 ### Streaming Responses
 
-For methods that return `StreamingResponse`, handle chunks as they arrive:
+Mark a callable method as streaming. The framework passes a
+`StreamingResponse` as its first argument:
 
 ```typescript
-// Agent-side:
-@callable()
-async generateText(prompt: string) {
-  return new StreamingResponse(async (stream) => {
-    for await (const chunk of llm.stream(prompt)) {
-      await stream.write(chunk);
+// Agent-side
+import { Agent, callable, type StreamingResponse } from "agents";
+
+export class AIAgent extends Agent {
+  @callable({ streaming: true })
+  async generateText(stream: StreamingResponse, prompt: string) {
+    for (const chunk of ["Generated response for ", prompt]) {
+      stream.send(chunk);
     }
-  });
+    stream.end();
+  }
 }
 
 // Client-side:

package/docs/configuration.md

@@ -617,12 +617,18 @@ Define environments in wrangler.jsonc:
   "env": {
     "staging": {
       "name": "my-agent-staging",
+      "durable_objects": {
+        "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
+      },
       "vars": {
         "ENVIRONMENT": "staging"
       }
     },
     "production": {
       "name": "my-agent-production",
+      "durable_objects": {
+        "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
+      },
       "vars": {
         "ENVIRONMENT": "production"
       }
@@ -647,7 +653,7 @@ npx wrangler secret put OPENAI_API_KEY --env production
 
 ### Separate Durable Objects
 
-Each environment gets its own Durable Objects. Staging agents don't share state with production agents.
+Durable Object bindings are not inherited by named environments, so repeat them in every environment as shown above. Each environment gets its own Durable Objects. Staging agents do not share state with production agents.
 
 To explicitly separate:
 

package/docs/cross-domain-authentication.md

@@ -24,7 +24,7 @@ If the client and server share the origin, the browser will send cookies during
 
 ### Cross origin
 
-Cookies do not help across origins. Pass credentials in the URL query, then verify on the server.
+Cross-origin cookie behavior depends on the cookie's domain and `SameSite` attributes, whether the two origins are same-site, and browser third-party cookie policy. If you cannot rely on a cookie, pass a short-lived credential in the URL query and verify it on the server.
 
 ## Usage examples
 
@@ -79,50 +79,22 @@ function ChatComponent() {
 
 ### JWT refresh pattern
 
-Refresh the token when the connection fails due to authentication error.
+`useAgent` resolves an async query before connecting and reevaluates it when reconnecting. Return a fresh, short-lived application token each time:
 
 ```ts
 import { useAgent } from "agents/react";
-import { useCallback, useEffect } from "react";
-
-const validateToken = async (token: string) => {
-  // An example of how you might implement this
-  const res = await fetch(`${API_HOST}/api/users/me`, {
-    headers: {
-      Authorization: `Bearer ${token}`
-    }
-  });
-
-  return res.ok;
-};
+import { useCallback } from "react";
 
-const refreshToken = () => {
-  // Depends on implementation:
-  // - You could use a longer-lived token to refresh the expired token
-  // - De-auth the app and prompt the user to log in manually
-  // - ...
-};
+declare function getShortLivedAccessToken(): Promise<string>;
 
 function useJWTAgent(agentName: string) {
   const asyncQuery = useCallback(async () => {
-    let token = localStorage.getItem("jwt");
-
-    // If no token OR the token is no longer valid
-    // request a fresh token
-    if (!token && !(await validateToken(token))) {
-      token = await refreshToken();
-      localStorage.setItem("jwt", token);
-    }
-
-    return {
-      token
-    };
+    return { token: await getShortLivedAccessToken() };
   }, []);
 
-  const agent = useAgent({
+  return useAgent({
     agent: agentName,
-    query: asyncQuery,
-    queryDeps: [] // Run on mount
+    query: asyncQuery
   });
 }
 ```

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/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`:
@@ -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/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(
@@ -586,7 +586,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 +634,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

@@ -18,7 +18,7 @@ The MCP client capability lets your agent:
 Install the exact MCP client peer used by this Agents release:
 
 ```sh
-pnpm add agents @modelcontextprotocol/client@2.0.0-beta.5
+pnpm add agents @modelcontextprotocol/client@2.0.0
 ```
 
 ```typescript

package/docs/mcp-servers.md

@@ -14,12 +14,18 @@ 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:
 
 ```sh
-pnpm add agents @modelcontextprotocol/server@2.0.0-beta.5 zod
+pnpm add agents @modelcontextprotocol/server@2.0.0 zod
 ```
 
 ```typescript