ai 7.0.126 → 7.0.128

package/docs/03-ai-sdk-core/65-lifecycle-callbacks.mdx

@@ -1,12 +1,12 @@
 ---
 title: Lifecycle Callbacks
-description: Observe AI SDK lifecycle events in generateText, streamText, embed, embedMany, rerank, and experimental_evaluate calls
+description: Observe AI SDK lifecycle events in generateText, streamText, embed, embedMany, rerank, and experimental_decide calls
 ---
 
 # Lifecycle Callbacks
 
 Event callbacks let you run your own code at important points in an AI SDK call.
-You can attach them directly to `generateText`, `streamText`, `embed`, `embedMany`, `rerank`, and `experimental_evaluate` calls to observe what happened, record usage, debug multi-step generations, and monitor tool execution.
+You can attach them directly to `generateText`, `streamText`, `embed`, `embedMany`, `rerank`, and `experimental_decide` calls to observe what happened, record usage, debug multi-step generations, and monitor tool execution.
 
 They are especially useful when you want application-specific logic close to the call site:
 
@@ -452,21 +452,20 @@ const result = await generateText({
   ]}
 />
 
-### `experimental_evaluate`
+### `experimental_decide`
 
 <PropertiesTable
   content={[
     {
       name: 'onStart',
-      type: '(event: Experimental_EvaluateStartEvent) => void | Promise<void>',
+      type: '(event: Experimental_DecideStartEvent) => void | Promise<void>',
       description:
-        'Called when the evaluation operation begins, before the evaluation model is called.',
+        'Called when the decision operation begins, before the decision model is called.',
     },
     {
       name: 'onEnd',
-      type: '(event: Experimental_EvaluateEndEvent) => void | Promise<void>',
-      description:
-        'Called when the evaluation operation completes successfully.',
+      type: '(event: Experimental_DecideEndEvent) => void | Promise<void>',
+      description: 'Called when the decision operation completes successfully.',
     },
   ]}
 />
@@ -1174,10 +1173,10 @@ For `embed`, `value` is a single string. For `embedMany`, `value` is an array of
   ]}
 />
 
-### Evaluation Events
+### Decision Events
 
-Evaluation callbacks are experimental. Their exported types are
-`Experimental_EvaluateStartEvent` and `Experimental_EvaluateEndEvent`.
+Decision callbacks are experimental. Their exported types are
+`Experimental_DecideStartEvent` and `Experimental_DecideEndEvent`.
 
 #### onStart
 
@@ -1186,12 +1185,12 @@ Evaluation callbacks are experimental. Their exported types are
     {
       name: 'callId',
       type: 'string',
-      description: 'Unique identifier for this evaluation call.',
+      description: 'Unique identifier for this decision call.',
     },
     {
       name: 'operationId',
-      type: "'ai.evaluate'",
-      description: 'Evaluation operation identifier.',
+      type: "'ai.decide'",
+      description: 'Decision operation identifier.',
     },
     {
       name: 'runtimeContext',
@@ -1201,22 +1200,22 @@ Evaluation callbacks are experimental. Their exported types are
     {
       name: 'provider',
       type: 'string',
-      description: 'Provider identifier for the evaluation model.',
+      description: 'Provider identifier for the decision model.',
     },
     {
       name: 'modelId',
       type: 'string',
-      description: 'Evaluation model identifier.',
+      description: 'Decision model identifier.',
     },
     {
       name: 'state',
       type: 'string | object | array',
-      description: 'Shared state being evaluated.',
+      description: 'Shared state used to make decisions.',
     },
     {
       name: 'questions',
-      type: 'Readonly<Record<string, Experimental_EvaluationQuestion>>',
-      description: 'Questions being evaluated against the shared state.',
+      type: 'Readonly<Record<string, Experimental_DecisionQuestion>>',
+      description: 'Questions to decide against the shared state.',
     },
     {
       name: 'maxRetries',
@@ -1244,18 +1243,18 @@ Includes every `onStart` field plus:
   content={[
     {
       name: 'answers',
-      type: 'Record<string, Experimental_EvaluationAnswer>',
+      type: 'Record<string, Experimental_DecisionAnswer>',
       description: 'Exactly one typed answer per question ID.',
     },
     {
       name: 'usage',
       type: '{ inputTokens: number | undefined; outputTokens: number | undefined; totalTokens: number | undefined }',
-      description: 'Token usage for the evaluation operation.',
+      description: 'Token usage for the decision operation.',
     },
     {
       name: 'warnings',
       type: 'Array<Warning>',
-      description: 'Warnings from the evaluation model.',
+      description: 'Warnings from the decision model.',
     },
     {
       name: 'rounding',

package/docs/03-ai-sdk-harnesses/08-terminal-ui.mdx

@@ -6,8 +6,8 @@ description: Use @ai-sdk/tui with HarnessAgent.
 # Harnesses with Terminal UI
 
 `@ai-sdk/tui` can render harness streams, tool calls, reasoning sections, and
-approval prompts in a terminal. Because `HarnessAgent` requires a session on
-every call, wrap it with a small `AgentTUIAgent` adapter that injects one
+approval prompts in a terminal. Because `HarnessAgent` requires a session for
+`generate` and `stream` calls, wrap it with a small `AgentTUIAgent` adapter that injects one
 session for the lifetime of the terminal UI.
 
 ## Installation

package/docs/04-ai-sdk-ui/02-chatbot.mdx

@@ -323,7 +323,8 @@ When the user clicks the "Regenerate" button, the AI provider will regenerate th
 
 ### Throttling UI Updates
 
-By default, the `useChat` hook will trigger a render every time a new chunk is received.
+By default, `useChat` publishes message updates as each chunk is processed.
+React may batch multiple updates into a single render.
 React and Vue applications can throttle reactive message updates with the `throttle` option.
 Stream processing and event callbacks remain immediate, and the latest messages are published before the chat enters a terminal `ready` or `error` status.
 

package/docs/06-advanced/09-multistep-interfaces.mdx

@@ -84,7 +84,7 @@ Tool: bookFlight("BA123", "12th December", ["John Doe", "Jane Doe"])
 Model: Your flight has been booked!
 ```
 
-Before the last tool call, the passenger details needed by the `bookFlight` tool are not available in the application context. As a result, the model asks the user to provide the passenger details before proceeding with the booking.
+After `lookupFlight` returns, the passenger details needed by the `bookFlight` tool are not yet available in the application context. The model asks the user for those details; once the user supplies the names, the model can call `bookFlight`.
 
 Looking up passenger information could've been another tool that the model could've called before calling the `bookFlight` tool assuming that the user is logged into the application. This way, the model does not have to ask the user for the passenger details and can proceed with the booking.
 

package/docs/07-reference/01-ai-sdk-core/14-decide.mdx

@@ -0,0 +1,74 @@
+---
+title: experimental_decide
+description: Decide answers to typed questions against shared state with a decision model.
+---
+
+# `experimental_decide()`
+
+```ts
+import { experimental_decide } from 'ai';
+```
+
+Decides answers to a nonempty map of `choice`, `score`, and `boolean` questions against one
+state. See [Decisions](/docs/ai-sdk-core/decisions) for examples and semantics.
+
+## Parameters
+
+| Parameter         | Type                                             | Description                                                                                                                               |
+| ----------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `model`           | `Experimental_DecisionModel`                     | Required experimental v4 model instance or a string ID resolved by Gateway or an explicitly configured decision-capable default provider. |
+| `state`           | `string \| object \| array`                      | Required JSON-compatible shared state.                                                                                                    |
+| `questions`       | `Record<string, Experimental_DecisionQuestion>`  | Required nonempty question map.                                                                                                           |
+| `maxRetries`      | `number`                                         | Nonnegative integer; defaults to 2.                                                                                                       |
+| `abortSignal`     | `AbortSignal`                                    | Cancels the decisions request.                                                                                                            |
+| `headers`         | `Record<string, string>`                         | Additional HTTP headers.                                                                                                                  |
+| `providerOptions` | `ProviderOptions`                                | Provider-specific options.                                                                                                                |
+| `telemetry`       | `TelemetryOptions`                               | Telemetry configuration, including per-call integrations, input/output recording, and a function ID.                                      |
+| `runtimeContext`  | `Record<string, unknown>`                        | Context available to lifecycle callbacks and selectively included in telemetry with `telemetry.includeRuntimeContext`.                    |
+| `onStart`         | `(event: Experimental_DecideStartEvent) => void` | Called when the decision operation begins.                                                                                                |
+| `onEnd`           | `(event: Experimental_DecideEndEvent) => void`   | Called when the decision operation completes successfully.                                                                                |
+
+See [Lifecycle Callbacks](/docs/ai-sdk-core/lifecycle-callbacks#experimental_decide)
+for the complete `onStart` and `onEnd` event fields.
+
+## Result
+
+Returns `Promise<Experimental_DecisionResult<QUESTIONS>>`:
+
+- `answers`: One typed answer per question ID, with literal Choice option inference.
+- `usage`: `inputTokens`, `outputTokens`, and `totalTokens`, each possibly undefined.
+- `warnings`: Provider warnings, also passed to the SDK warning logger.
+- `rounding`: Optional provider-declared decimal precision for probabilities and scores.
+- `providerMetadata`: Optional provider-specific metadata.
+- `response`: Timestamp, model ID, and optional response ID, headers, and body.
+
+## Provider specification
+
+`Experimental_DecisionModelV4` is exported from `@ai-sdk/provider` and declares
+`specificationVersion: 'v4'`, `provider`, `modelId`, `supportedQuestionTypes`, and
+`doDecide(options)`. Decision models are isolated from stable `ProviderV4`.
+
+The public core types are `Experimental_DecisionModel`,
+`Experimental_DecisionQuestion`, `Experimental_DecisionAnswer`, and
+`Experimental_DecisionResult`. All decision-specific classes use the
+`Decision` prefix, with `Experimental_` aliases at package boundaries.
+
+## Errors
+
+Unsupported types throw `Experimental_DecisionUnsupportedQuestionTypeError`
+before provider I/O. Invalid inputs throw `InvalidArgumentError`; malformed
+answers throw `InvalidResponseDataError`. Invalid answers are not retried.
+Neither partial results nor missing probability synthesis are supported.
+
+## Model resolution
+
+Use `registry.decisionModel('provider:model')` or
+`customProvider({ decisionModels: { alias: model } }).decisionModel('alias')`
+to resolve models. Strings passed directly to `experimental_decide` use
+`globalThis.AI_SDK_DEFAULT_PROVIDER.decisionModel(id)` when a default provider is
+configured, or Gateway when no default provider is configured.
+
+Resolution errors use the existing `NoSuchModelError` and `NoSuchProviderError`
+classes with `modelType: 'decisionModel'`. Model instances and resolved models
+must implement v4; other versions throw `UnsupportedModelVersionError`.
+See [model resolution examples](/docs/ai-sdk-core/decisions#model-aliases-and-registries).

package/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx

@@ -368,11 +368,24 @@ Returns a Promise that resolves to an `MCPClient` with the following properties
                 'Tool definitions, typically returned by `listTools`.',
             },
             {
-              name: 'schemas',
-              type: 'TOOL_SCHEMAS',
+              name: 'options',
+              type: '{ schemas?: TOOL_SCHEMAS }',
               isOptional: true,
-              description:
-                'Optional schema definitions for compile-time type checking and typed outputs.',
+              description: 'Options for converting the tool definitions.',
+              properties: [
+                {
+                  type: 'options',
+                  parameters: [
+                    {
+                      name: 'schemas',
+                      type: 'TOOL_SCHEMAS',
+                      isOptional: true,
+                      description:
+                        'Optional schema definitions for compile-time type checking and typed outputs.',
+                    },
+                  ],
+                },
+              ],
             },
           ],
         },
@@ -641,6 +654,47 @@ The client throws `MCPClientError` for:
 - Missing server capabilities
 - Connection failures
 
+Import `MCPClientError` from `@ai-sdk/mcp` and use its `isInstance` method to
+safely narrow unknown errors:
+
+```typescript
+import { createMCPClient, MCPClientError } from '@ai-sdk/mcp';
+
+try {
+  await createMCPClient({
+    transport: {
+      type: 'http',
+      url: 'https://your-server.com/mcp',
+    },
+  });
+} catch (error) {
+  if (MCPClientError.isInstance(error)) {
+    if (error.statusCode === 401 || error.statusCode === 403) {
+      // Authentication or authorization must be fixed before retrying.
+      throw error;
+    }
+
+    // Inspect error.code and error.statusCode according to your application's policy.
+  }
+
+  throw error;
+}
+```
+
+The error exposes the optional `code`, `statusCode`, `url`, and `responseBody`
+properties. `code` is the JSON-RPC application error code. `statusCode`, `url`,
+and `responseBody` contain HTTP transport context when it is available. They
+are `undefined` for failures without an HTTP response, such as network errors,
+timeouts, aborted requests, and stdio transport failures.
+
+`MCPClientError` also represents configuration and protocol errors, so its
+type or a missing `statusCode` alone does not indicate a retryable failure.
+OAuth failures can instead throw the separately exported `UnauthorizedError`
+or `MCPClientOAuthError`.
+
+Avoid logging `url` or `responseBody` without redacting sensitive endpoint,
+query parameter, or server response data.
+
 For tool execution, errors are propagated as `CallToolError` errors.
 
 For unknown errors, the client exposes an `onUncaughtError` callback that can be used to manually log or handle errors that are not covered by known error types.

package/docs/07-reference/01-ai-sdk-core/23-tool-search.mdx

@@ -5,8 +5,8 @@ description: Search deferred tools and load their definitions on demand for dire
 
 # `toolSearch()`
 
-Creates a tool that searches the surrounding generation's deferred tools by name
-and description. The factory takes no arguments. Use it with `generateText`,
+Creates a tool that searches the surrounding generation's deferred tools, using
+keyword matching by default or a custom search callback. Use it with `generateText`,
 `streamText`, `ToolLoopAgent`, or `WorkflowAgent` from `@ai-sdk/workflow`.
 `WorkflowAgent` supports direct tool calling. The other APIs also support code
 mode configured with `toolDiscovery: 'conversation'`.
@@ -20,6 +20,60 @@ const search = toolSearch();
 See the [Tool Search guide](/docs/ai-sdk-core/tool-search) for direct-calling and
 code mode examples, including how code mode preserves the tool-definition cache.
 
+## Options
+
+Pass an optional configuration object to control the result limit:
+
+```ts
+const search = toolSearch({ maxResults: 10 });
+```
+
+`maxResults` is the maximum number of matching tools returned and discovered per
+search. It defaults to `5` and must be a positive safe integer. Invalid values
+throw `InvalidArgumentError` when creating the search tool. The model-facing
+description reflects the configured limit.
+
+The limit applies to both default keyword search and custom search callbacks,
+without changing their matching or ranking. Discovered tools accumulate across
+searches, so this is not a limit on the total number of tools loaded during a
+generation.
+
+Pass a `search` callback to select and rank tools using your application's search
+logic. The callback can return synchronously or asynchronously:
+
+```ts
+const search = toolSearch({
+  search: ({ query, tools }) => {
+    const preferred = /\bgmail\b/i.test(query)
+      ? ['gmail_list_messages', 'gmail_get_message']
+      : [];
+    return preferred.filter(name => tools.some(tool => tool.name === name));
+  },
+});
+```
+
+The callback has this signature:
+
+```ts
+search?: (options: {
+  query: string;
+  tools: Array<{ name: string; description?: string }>;
+}) => string[] | PromiseLike<string[]>;
+```
+
+`tools` contains all eligible deferred tools, before keyword matching or ranking.
+Eligibility respects `activeTools` and caller routing. Descriptions are resolved
+using the current tool context and sandbox; schemas are not included.
+
+Return tool names in ranked order. The SDK ignores unknown or ineligible names,
+removes duplicates while preserving order, and keeps the first `maxResults` valid
+names (five by default). Returned descriptions come from the SDK's candidate
+catalog. An empty array
+discovers no tools. Callback errors follow normal tool-execution error handling;
+the SDK does not fall back to keyword search.
+
+Without a callback, `toolSearch()` uses the default keyword search described below.
+
 ## Model Input
 
 The model supplies the following input to the search tool:
@@ -28,11 +82,12 @@ The model supplies the following input to the search tool:
 { "query": "weather forecast" }
 ```
 
-`query` is a required, nonempty string of search keywords. Search is local and
+`query` is a required, nonempty string. By default, search is local and
 case-insensitive, matching words in tool names and descriptions. Camel-case names
 are split into words. Name matches rank above description matches; equal scores
 preserve registration order. Function descriptions are resolved with the current
-tool context and sandbox. No embedding service or additional model call is used.
+tool context and sandbox. The default search uses no embedding service or
+additional model call. A custom callback can use either.
 
 ## Output
 
@@ -44,8 +99,9 @@ tool context and sandbox. No embedding service or additional model call is used.
 }
 ```
 
-Results contain at most five matching tools, with their names and optional
-descriptions. They do not include schemas. No matches returns `{ tools: [] }`.
+Results contain at most `maxResults` matching tools (five by default), with their
+names and optional descriptions. They do not include schemas. No matches returns
+`{ tools: [] }`.
 Every returned match is queued for discovery. Newly discovered tools can only be
 called on the next model step, after their definitions have been provided. A
 parallel call in the same response as the search cannot use a newly discovered

package/docs/07-reference/01-ai-sdk-core/40-provider-registry.mdx

@@ -299,20 +299,20 @@ The `createProviderRegistry` function returns a `Provider` instance. It has the
   ]}
 />
 
-## Experimental evaluation models
+## Experimental decision models
 
-The inferred return type also exposes `evaluationModel('providerId:modelId')`,
-returning `Experimental_EvaluationModelV4`. The provider must expose an
-`evaluationModel` factory. Custom separators and model ID
+The inferred return type also exposes `decisionModel('providerId:modelId')`,
+returning `Experimental_DecisionModelV4`. The provider must expose an
+`decisionModel` factory. Custom separators and model ID
 inference work as they do for video models. Language and image middleware do not
-wrap evaluation models. `ProviderRegistryProvider` remains a stable interface;
-use the inferred return type or `Experimental_EvaluationProviderRegistry` to
-retain experimental evaluation access.
+wrap decision models. `ProviderRegistryProvider` remains a stable interface;
+use the inferred return type or `Experimental_DecisionProviderRegistry` to
+retain experimental decision access.
 
-Unavailable evaluation capabilities or models throw `NoSuchModelError` with
-`modelType: 'evaluationModel'`; unknown registry providers throw
+Unavailable decision capabilities or models throw `NoSuchModelError` with
+`modelType: 'decisionModel'`; unknown registry providers throw
 `NoSuchProviderError`. These capabilities are structural extensions and are not
-added to the stable `ProviderV4` contract. Direct evaluation string IDs default
+added to the stable `ProviderV4` contract. Direct decision string IDs default
 to Gateway when no default provider is configured.
-See [Evaluation](/docs/ai-sdk-core/evaluation#model-aliases-and-registries)
+See [Decisions](/docs/ai-sdk-core/decisions#model-aliases-and-registries)
 for runnable usage patterns.

package/docs/07-reference/01-ai-sdk-core/42-custom-provider.mdx

@@ -202,20 +202,20 @@ The `customProvider` function returns a `Provider` instance. It has the followin
   ]}
 />
 
-## Experimental evaluation models
+## Experimental decision models
 
-Pass `evaluationModels: Record<string, Experimental_EvaluationModel>` to define
-aliases for evaluation model instances or string IDs. The returned provider adds
-`evaluationModel(alias): Experimental_EvaluationModelV4`. String aliases resolve
+Pass `decisionModels: Record<string, Experimental_DecisionModel>` to define
+aliases for decision model instances or string IDs. The returned provider adds
+`decisionModel(alias): Experimental_DecisionModelV4`. String aliases resolve
 through Gateway by default, or an explicitly configured default provider with
-an `evaluationModel` method. Unknown aliases use the fallback provider's evaluation
+a `decisionModel` method. Unknown aliases use the fallback provider's decision
 factory when available; model failures and unsupported questions do not trigger
 substitution.
 
-Unavailable evaluation capabilities or models throw `NoSuchModelError` with
-`modelType: 'evaluationModel'`; unknown registry providers throw
+Unavailable decision capabilities or models throw `NoSuchModelError` with
+`modelType: 'decisionModel'`; unknown registry providers throw
 `NoSuchProviderError`. These capabilities are structural extensions and are not
-added to the stable `ProviderV4` contract. Direct evaluation string IDs default
+added to the stable `ProviderV4` contract. Direct decision string IDs default
 to Gateway when no default provider is configured.
-See [Evaluation](/docs/ai-sdk-core/evaluation#model-aliases-and-registries)
+See [Decisions](/docs/ai-sdk-core/decisions#model-aliases-and-registries)
 for runnable usage patterns.

package/docs/07-reference/01-ai-sdk-core/66-extract-reasoning-middleware.mdx

@@ -1,11 +1,11 @@
 ---
 title: extractReasoningMiddleware
-description: Middleware that extracts XML-tagged reasoning sections from generated text
+description: Middleware that extracts reasoning sections from generated text using configurable delimiters
 ---
 
 # `extractReasoningMiddleware()`
 
-`extractReasoningMiddleware` is a middleware function that extracts XML-tagged reasoning sections from generated text and exposes them separately from the main text content. This is particularly useful when you want to separate an AI model's reasoning process from its final output.
+`extractReasoningMiddleware` is a middleware function that extracts delimited reasoning sections from generated text and exposes them separately from the main text content. This is particularly useful when you want to separate an AI model's reasoning process from its final output.
 
 ```ts
 import { extractReasoningMiddleware } from 'ai';
@@ -16,6 +16,22 @@ const middleware = extractReasoningMiddleware({
 });
 ```
 
+For models that emit non-XML delimiters, pass literal `opening` and `closing`
+strings. For example, Gemma 4's raw thought-channel output uses a newline in its
+opening delimiter:
+
+```ts
+const middleware = extractReasoningMiddleware({
+  tagName: { opening: '<|channel>thought\n', closing: '<channel|>' },
+});
+```
+
+Custom delimiters must be non-empty. They are matched literally, including
+characters such as `|`, and can span multiple streaming chunks. Empty reasoning
+blocks are removed from the answer text as well. Use this middleware when the
+server returns these markers in text; providers that already return reasoning
+separately do not need it.
+
 ## Import
 
 <Snippet
@@ -31,10 +47,10 @@ const middleware = extractReasoningMiddleware({
   content={[
     {
       name: 'tagName',
-      type: 'string',
+      type: 'string | { opening: string; closing: string }',
       isOptional: false,
       description:
-        'The name of the XML tag to extract reasoning from (without angle brackets)',
+        'An XML tag name without angle brackets (e.g. "think" for <think> / </think>), or an object containing non-empty literal opening and closing delimiters.',
     },
     {
       name: 'separator',
@@ -48,7 +64,7 @@ const middleware = extractReasoningMiddleware({
       type: 'boolean',
       isOptional: true,
       description:
-        'Starts with reasoning tokens. Set to true when the response always starts with reasoning and the initial tag is omitted. Defaults to false.',
+        'Starts with reasoning tokens. Set to true when the response always starts with reasoning and the opening delimiter is omitted. Defaults to false.',
     },
   ]}
 />
@@ -58,9 +74,9 @@ const middleware = extractReasoningMiddleware({
 Returns a middleware object that:
 
 - Processes both streaming and non-streaming responses
-- Extracts content between specified XML tags as reasoning
-- Removes the XML tags and reasoning from the main text
-- Adds a `reasoning` property to the result containing the extracted content
+- Extracts content between the specified delimiters as reasoning
+- Removes the delimiters and reasoning from the main text
+- Emits reasoning content parts separately from text content parts
 - Maintains proper separation between text sections using the specified separator
 
 ### Type Parameters

package/docs/07-reference/02-ai-sdk-ui/01-use-chat.mdx

@@ -486,6 +486,19 @@ Allows you to easily create a conversational user interface for your chatbot app
   ]}
 />
 
+## React rendering and shared Chat instances
+
+In React, `messages`, `status`, and `error` describe the snapshot for the current render.
+The underlying `Chat` updates as stream chunks are processed. React may batch updates,
+and `throttle` can delay message rendering without delaying stream processing or callbacks.
+Status and error updates include the latest messages, so a completed or failed response
+is rendered with its final message snapshot.
+
+Each `useChat({ chat })` call subscribes independently. Consumers sharing a `Chat`
+can display different message snapshots when they use different throttle intervals.
+A functional `setMessages` updater receives the Chat's latest messages, which may be
+newer than the messages in the current render.
+
 ## Learn more
 
 - [Chatbot](/docs/ai-sdk-ui/chatbot)

package/docs/07-reference/02-ai-sdk-ui/32-prune-messages.mdx

@@ -60,7 +60,7 @@ export async function POST(req: Request) {
     },
     {
       name: 'toolCalls',
-      type: `'all' | 'before-last-message' | 'before-last-\${number}-messages' | 'none' | Array<{ type: 'all' | 'before-last-message' | 'before-last-\${number}-messages'; tools?: string[] }>`,
+      type: `'all' | 'before-last-message' | \`before-last-\${number}-messages\` | 'none' | Array<{ type: 'all' | 'before-last-message' | \`before-last-\${number}-messages\`; tools?: string[] }>`,
       description:
         'How to prune tool call/results/approval content. Can specify a strategy string or an array for per-tool fine control. Default: [] (empty array, equivalent to "none").',
     },

package/docs/07-reference/03-ai-sdk-rsc/01-stream-ui.mdx

@@ -517,6 +517,7 @@ To see `streamUI` in action, check out [these examples](#examples).
             {
               name: 'response',
               type: 'Response',
+              isOptional: true,
               description: 'Optional response data.',
               properties: [
                 {

package/docs/07-reference/04-ai-sdk-workflow/01-workflow-agent.mdx

@@ -99,7 +99,7 @@ To see `WorkflowAgent` in action, check out [these examples](#examples).
       type: 'StopCondition | StopCondition[]',
       isOptional: true,
       description:
-        'Default stop condition for the agent loop. When omitted, WorkflowAgent has no maximum step count and continues until natural completion. Use `isStepCount()` to bound execution. Per-stream values override this default.',
+        'Default stop condition for the agent loop. When omitted, generate defaults to 20 steps, while stream has no maximum step count. Use `isStepCount()` to bound execution. Per-call values override this default.',
     },
     {
       name: 'activeTools',
@@ -478,6 +478,43 @@ To see `WorkflowAgent` in action, check out [these examples](#examples).
 
 ## Methods
 
+### `generate()`
+
+Runs the durable agent loop using the model's non-streaming `doGenerate()` method. Model calls and tool execution use the same orchestration as `stream()`.
+
+```ts
+const result = await agent.generate({ prompt: 'Summarize the findings.' });
+console.log(result.text);
+console.log(result.usage);
+```
+
+Accepts `WorkflowAgentGenerateOptions`, sharing prompt/messages, instructions, generation settings, tools and runtime context, preparation, stopping, output, and lifecycle options with `stream()`. It does not accept `writable`, `includeRawChunks`, `experimental_transform`, `sendFinish`, or `preventClose`. Without a configured stop condition, generation stops after at most 20 steps. `stream()` retains its existing unbounded default.
+
+The `include` option accepts `requestBody`, `responseBody`, and `requestMessages` booleans, all defaulting to `false`. Enable them only when the additional request/response data is needed. Response IDs, timestamps, model IDs, headers, and provider metadata are retained when supplied by the model.
+
+#### Returns
+
+Returns `Promise<WorkflowAgentGenerateResult>` with the core [`GenerateTextResult`](/docs/reference/ai-sdk-core/generate-text#returns) semantics:
+
+- `text`, `finishReason`, `rawFinishReason`, and `finalStep` describe the final step.
+- `content`, `files`, `sources`, `warnings`, tool calls, and tool results cover all steps.
+- `usage` and `totalUsage` sum all steps while retaining token details and unknown counts.
+- `responseMessages` includes generated messages, even when `prepareStep` replaces the input history.
+- `output` defaults to text, or follows the constructor/per-call output specification. Reading it throws `NoOutputGeneratedError` when output is unavailable, such as a final `tool-calls` response.
+
+Inside a workflow, `timeout` bounds model calls, including retries and dispatch after suspension. It does not cancel a hook that a tool is waiting on. Use the Workflow runtime’s `run.cancel()` to stop a suspended run. See [deadlines, cancellation, and replay](/docs/agents/workflow-agent#deadlines-cancellation-and-replay).
+
+Generation failures reject. The end callback runs before complete-output parsing; a parsing failure can therefore reject after `onEnd` has run. Existing Workflow callback shapes and preparation precedence apply; they are not all identical to core's callback APIs.
+
+<Note>
+  Use the result API inside workflow code and return selected serializable
+  fields (for example, `text` and `usage`) through `run.returnValue`. Returning
+  the whole result class is not supported. Performance data currently measures
+  the model response; complete tool/step timing is not yet reported.
+</Note>
+
+Approval requests appear in `content` and `responseMessages` without requiring a writable. To continue, append `responseMessages` to the original history and add a tool message containing the user's `tool-approval-response`. Preserve the request signature and tool-call input; use the same `experimental_toolApprovalSecret` environment-variable reference on continuation. Local approvals are validated before execution, and provider-executed approval responses are forwarded to the provider. See [approval round trips](/docs/agents/workflow-agent#approval-round-trips-without-streaming).
+
 ### `stream()`
 
 Runs the agent loop, streaming responses and executing tool calls as needed. Returns a promise resolving to a `WorkflowAgentStreamResult`.
@@ -549,7 +586,7 @@ const result = await agent.stream({
       name: 'timeout',
       type: 'number',
       isOptional: true,
-      description: 'Timeout in milliseconds. Creates an AbortSignal that aborts the operation after the given time.',
+      description: 'Model-call deadline in milliseconds. Inside a workflow, the absolute deadline is checked at dispatch and retry and remains in effect across suspension. It does not cancel a tool waiting on a Workflow hook; use run.cancel() to stop the suspended run.',
     },
     {
       name: 'sendFinish',