ai 7.0.41 → 7.0.42

package/docs/03-agents/02-building-agents.mdx

@@ -129,6 +129,10 @@ const result = await agent.generate({
 });
 ```
 
+Model call settings returned from `prepareStep`, such as `temperature`, apply
+only to the current step. Later steps use the agent's top-level setting unless
+they return another override.
+
 For the full model, including sensitive context filtering and where each context
 value is available, see [Runtime and Tool
 Context](/docs/ai-sdk-core/runtime-and-tool-context).

package/docs/03-agents/04-loop-control.mdx

@@ -180,6 +180,46 @@ const result = await agent.generate({
 });
 ```
 
+### Model Call Settings
+
+Override provider-agnostic model call settings for an individual step. This can
+be useful when tool-calling steps need more deterministic sampling than the
+final response:
+
+```ts
+import { ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  temperature: 0.7,
+  tools: {
+    // your tools
+  },
+  prepareStep: async ({ stepNumber }) => {
+    if (stepNumber === 0) {
+      return {
+        temperature: 0,
+        maxOutputTokens: 300,
+      };
+    }
+
+    return {};
+  },
+});
+
+const result = await agent.generate({
+  prompt: '...',
+});
+```
+
+`prepareStep` can override `maxOutputTokens`, `temperature`, `topP`, `topK`,
+`presencePenalty`, `frequencyPenalty`, `stopSequences`, `seed`, and
+`reasoning`. These overrides apply only to the current step. When a setting is
+omitted or `undefined`, the top-level value is used for that step. Defined
+falsy values such as `temperature: 0`, `seed: 0`, and an empty
+`stopSequences` array are preserved.
+
 ### Context Management
 
 Long-running agents can accumulate large tool results, reasoning parts, and assistant messages. Use `prepareStep` to mutate the message state that will be used by later steps. This is useful for compaction, and you decide when compaction should happen.

package/docs/03-ai-sdk-core/36-transcription.mdx

@@ -304,6 +304,7 @@ try {
 | [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#streaming-transcription-models) | `scribe_v2_realtime`     |
 | [Groq](/providers/ai-sdk-providers/groq#transcription-models)                       | `whisper-large-v3-turbo` |
 | [Groq](/providers/ai-sdk-providers/groq#transcription-models)                       | `whisper-large-v3`       |
+| [Mistral](/providers/ai-sdk-providers/mistral#transcription-models)                 | `voxtral-mini-latest`    |
 | [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `whisper-1`              |
 | [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `gpt-4o-transcribe`      |
 | [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `gpt-4o-mini-transcribe` |

package/docs/03-ai-sdk-core/65-devtools.mdx

@@ -105,10 +105,56 @@ the workspace.
 DevTools captures the following information from your AI SDK calls:
 
 - **Input parameters and prompts**: View the complete input sent to your LLM
-- **Output content and tool calls**: Inspect generated text and tool invocations
+- **Output content and tool calls**: Inspect generated text, tool invocations, and tool results
+- **Media previews**: View images, audio, and video included in prompts, tool inputs, and tool outputs
 - **Token usage and timing**: Monitor resource consumption and performance
 - **Raw provider data**: Access provider request and response payloads when body retention is enabled
 
+### Media previews
+
+DevTools recognizes current `file` content parts as well as the deprecated
+`image-*`, `file-*`, and `media` tool-result aliases. Inline image, audio, and
+video data is previewed directly, while the captured JSON shape and metadata
+remain available for inspection. The viewer displays at most 8 previews per
+value, traverses at most 12 nested levels, and embeds inline previews up to 5
+MiB. Longer JSON strings are truncated in the viewer to avoid duplicating large
+base64 payloads. Binary values in recognized media-bearing fields are persisted
+as base64 so they remain previewable; unrelated binary values retain their
+normal JSON representation.
+
+For example, a tool can return media through `toModelOutput`:
+
+```ts
+import { tool } from 'ai';
+import { z } from 'zod';
+
+const captureScreenshot = tool({
+  inputSchema: z.object({}),
+  execute: async () => ({
+    base64: await captureScreenshotAsBase64(),
+  }),
+  toModelOutput: ({ output }) => ({
+    type: 'content',
+    value: [
+      {
+        type: 'file',
+        filename: 'screenshot.png',
+        mediaType: 'image/png',
+        data: { type: 'data', data: output.base64 },
+      },
+    ],
+  }),
+});
+```
+
+Remote `http` and `https` media is not loaded automatically. Select **Load
+preview** in the viewer to fetch it with anonymous CORS and no referrer.
+Cross-origin browser credentials are omitted, but same-origin browser
+credentials may still be included by the browser. URLs containing embedded
+usernames or passwords are rejected. Unsupported media, provider references,
+malformed values, unsafe URL schemes, and inline values over the preview limit
+retain their JSON and metadata fallback without an embedded preview.
+
 Telemetry is enabled automatically, but AI SDK 7 excludes raw request and response bodies from step results by default. To make them available to DevTools for `generateText`, enable body retention on the call:
 
 ```ts highlight="4-7"

package/docs/06-advanced/11-secure-url-fetching.mdx

@@ -27,6 +27,10 @@ When the SDK fetches a URL taken from a provider response, it:
   are rejected too.
 - **Re-validates every redirect hop** — a URL that passes but then redirects to
   an internal address is blocked; the redirect is never followed blindly.
+- **Validates DNS at connection time on Node.js** — every resolved address is
+  checked, and the socket is pinned to the validated DNS result so DNS
+  rebinding cannot introduce a different address between validation and
+  connection.
 - **Strips risky request headers** — proxy-forwarding, cloud-metadata, and
   cookie headers are removed before the request.
 - **Drops credentials across origins** — caller headers (`Authorization`,
@@ -43,28 +47,17 @@ custom `baseURL` pointing at a self-hosted or `localhost` deployment) are
 exempt from these checks — they target exactly the host you told the SDK to
 talk to. Any redirect off that origin is still validated.
 
-## Limitation: DNS resolution and DNS rebinding
+## DNS validation across runtimes
 
-The built-in guard inspects the URL **as a string**. It deliberately does
-**not resolve DNS**, so two attacks remain out of scope at this layer:
+On Node.js, the default validated download fetch uses `node:dns` and an
+`undici` connector hook to validate every resolved address at connection time.
+The connector uses those exact results, closing both hostname-to-private-IP and
+DNS-rebinding bypasses.
 
-1. **Hostname that resolves to a private IP** — a literal host that looks public
-   but whose DNS record points at an internal address.
-2. **DNS rebinding** — a host that resolves to a public IP when validated and a
-   private IP a moment later when the socket actually connects (a
-   time-of-check/time-of-use window).
-
-### Why this isn't built in
-
-Closing these requires resolving DNS and pinning the resolved IP **at connect
-time** — Node-only capabilities (`node:dns`, a custom `undici` dispatcher). The
-SDK's provider utilities are **cross-runtime**: they run on the edge, in the
-browser, and on Bun/Deno, with no Node-only dependencies, so those APIs aren't
-available there. The threat is also specifically a **server-side** one — on the
-edge and in the browser, outbound `fetch` cannot reach a host's internal network
-or metadata endpoint in the first place. So connect-time IP pinning is only
-meaningful, and only available, on a Node server — which is exactly where you
-can add it yourself.
+If you inject or globally replace `fetch`, it is responsible for equivalent DNS
+validation and connection pinning. Other runtimes do not expose Node's
+DNS/socket hooks, so server deployments on those runtimes should restrict
+network egress to private, loopback, link-local, and cloud-metadata ranges.
 
 ## Hardening your deployment
 
@@ -77,9 +70,10 @@ Deny your server's network egress to `169.254.0.0/16`, RFC-1918 ranges, and
 loopback. This is the most robust control and is independent of application
 code.
 
-### 2. Inject a hardened `fetch`
+### 2. Harden an injected `fetch`
 
-Every provider accepts a custom `fetch`. On Node, back it with an `undici`
+The Node.js default is already pinned. If you inject or globally replace
+`fetch`, back it with an `undici`
 `Agent` whose `connect.lookup` validates the resolved IP and lets the socket
 connect only to a safe address — closing both the hostname-to-private and the
 DNS-rebinding windows:
@@ -113,5 +107,5 @@ import { createFal } from '@ai-sdk/fal';
 const fal = createFal({ fetch: safeFetch });
 ```
 
-The SDK's built-in validation and your connect-time pinning are complementary —
-keep both.
+The SDK's URL validation and your custom fetch's connect-time pinning are
+complementary — keep both.

package/docs/07-reference/01-ai-sdk-core/01-generate-text.mdx

@@ -597,7 +597,7 @@ To see `generateText` in action, check out [these examples](#examples).
       type: '(options: PrepareStepOptions) => PrepareStepResult<TOOLS> | Promise<PrepareStepResult<TOOLS>>',
       isOptional: true,
       description:
-        'Optional function that you can use to provide different settings for a step. You can modify the model, tool choices, active tools, instructions, input messages, and experimental sandbox for each step.',
+        'Optional function that you can use to provide different settings for a step. You can modify the model, model call settings, tool choices, active tools, instructions, input messages, and experimental sandbox for each step.',
       properties: [
         {
           type: 'PrepareStepFunction<TOOLS>',
@@ -682,6 +682,69 @@ To see `generateText` in action, check out [these examples](#examples).
               description:
                 'Optionally override which LanguageModel instance is used for this step.',
             },
+            {
+              name: 'maxOutputTokens',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Maximum number of tokens to generate for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'temperature',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Temperature for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'topP',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Nucleus sampling value for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'topK',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Top-K sampling value for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'presencePenalty',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Presence penalty for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'frequencyPenalty',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Frequency penalty for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'stopSequences',
+              type: 'string[]',
+              isOptional: true,
+              description:
+                'Stop sequences for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'seed',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Random sampling seed for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'reasoning',
+              type: 'LanguageModelV4CallOptions["reasoning"]',
+              isOptional: true,
+              description:
+                'Reasoning effort for this step. Uses the top-level value when omitted or undefined.',
+            },
             {
               name: 'toolChoice',
               type: 'ToolChoice<TOOLS>',
@@ -2362,7 +2425,8 @@ To see `generateText` in action, check out [these examples](#examples).
     {
       name: 'text',
       type: 'string',
-      description: 'The generated text by the model.',
+      description:
+        'The concatenation of all text parts generated in the final step. It is an empty string if the final step contains no text parts. Inspect `finalStep.content` to distinguish that case.',
     },
     {
       name: 'reasoning',
@@ -2795,7 +2859,8 @@ To see `generateText` in action, check out [these examples](#examples).
             {
               name: 'text',
               type: 'string',
-              description: 'The generated text.',
+              description:
+                'The concatenation of all text parts generated in this step. It is an empty string if the step contains no text parts.',
             },
             {
               name: 'reasoning',

package/docs/07-reference/01-ai-sdk-core/02-stream-text.mdx

@@ -641,7 +641,7 @@ To see `streamText` in action, check out [these examples](#examples).
       type: '(options: PrepareStepOptions) => PrepareStepResult<TOOLS> | Promise<PrepareStepResult<TOOLS>>',
       isOptional: true,
       description:
-        'Optional function that you can use to provide different settings for a step. You can modify the model, tool choices, active tools, instructions, input messages, and experimental sandbox for each step.',
+        'Optional function that you can use to provide different settings for a step. You can modify the model, model call settings, tool choices, active tools, instructions, input messages, and experimental sandbox for each step.',
       properties: [
         {
           type: 'PrepareStepFunction<TOOLS>',
@@ -726,6 +726,69 @@ To see `streamText` in action, check out [these examples](#examples).
               description:
                 'Optionally override which LanguageModel instance is used for this step.',
             },
+            {
+              name: 'maxOutputTokens',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Maximum number of tokens to generate for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'temperature',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Temperature for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'topP',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Nucleus sampling value for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'topK',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Top-K sampling value for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'presencePenalty',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Presence penalty for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'frequencyPenalty',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Frequency penalty for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'stopSequences',
+              type: 'string[]',
+              isOptional: true,
+              description:
+                'Stop sequences for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'seed',
+              type: 'number',
+              isOptional: true,
+              description:
+                'Random sampling seed for this step. Uses the top-level value when omitted or undefined.',
+            },
+            {
+              name: 'reasoning',
+              type: 'LanguageModelV4CallOptions["reasoning"]',
+              isOptional: true,
+              description:
+                'Reasoning effort for this step. Uses the top-level value when omitted or undefined.',
+            },
             {
               name: 'toolChoice',
               type: 'ToolChoice<TOOLS>',

package/docs/07-reference/01-ai-sdk-core/16-tool-loop-agent.mdx

@@ -123,7 +123,7 @@ To see `ToolLoopAgent` in action, check out [these examples](#examples).
       type: 'PrepareStepFunction',
       isOptional: true,
       description:
-        'Optional function to mutate step settings or inject state for each agent step.',
+        'Optional function to mutate step settings or inject state for each agent step, including per-step model call settings such as temperature, maxOutputTokens, sampling controls, penalties, stop sequences, seed, and reasoning. Model call setting overrides apply only to the current step.',
     },
     {
       name: 'include',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.41",
+  "version": "7.0.42",
   "type": "module",
   "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
   "license": "Apache-2.0",
@@ -42,9 +42,9 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.31",
+    "@ai-sdk/gateway": "4.0.32",
     "@ai-sdk/provider": "4.0.4",
-    "@ai-sdk/provider-utils": "5.0.14"
+    "@ai-sdk/provider-utils": "5.0.15"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",

package/src/generate-text/generate-text-result.ts

@@ -40,7 +40,9 @@ export interface GenerateTextResult<
   readonly content: Array<ContentPart<TOOLS>>;
 
   /**
-   * The text that was generated in the final step.
+   * The concatenation of all text parts generated in the final step.
+   * It is an empty string if the final step contains no text parts.
+   * Inspect `finalStep.content` to distinguish that case.
    */
   readonly text: string;
 

package/src/generate-text/generate-text.ts

@@ -84,6 +84,7 @@ import { text, type Output } from './output';
 import type { InferCompleteOutput } from './output-utils';
 import { parseToolCall } from './parse-tool-call';
 import type { PrepareStepFunction } from './prepare-step';
+import { prepareStepCallSettings } from './prepare-step-call-settings';
 import { convertToReasoningOutputs } from './reasoning-output';
 import { resolveToolApproval } from './resolve-tool-approval';
 import type { ResponseMessage } from './response-message';
@@ -888,6 +889,11 @@ export async function generateText<
                 prepareStepResult?.providerOptions,
               );
 
+              const stepCallSettings = prepareStepCallSettings({
+                callSettings,
+                stepSettings: prepareStepResult,
+              });
+
               await notify({
                 event: {
                   callId,
@@ -921,7 +927,7 @@ export async function generateText<
                 instructions: stepInstructions,
                 messages: stepMessages,
                 tools: stepTools,
-                ...callSettings,
+                ...stepCallSettings,
               };
               const languageModelCallStartEvent = {
                 callId,
@@ -951,7 +957,7 @@ export async function generateText<
                     ...languageModelCallStartEvent,
                     execute: async () =>
                       await stepModel.doGenerate({
-                        ...callSettings,
+                        ...stepCallSettings,
                         tools: stepTools,
                         toolChoice: stepToolChoice,
                         responseFormat: await output?.responseFormat,

package/src/generate-text/prepare-step-call-settings.ts

@@ -0,0 +1,31 @@
+import type { LanguageModelCallOptions } from '../prompt/language-model-call-options';
+import { prepareLanguageModelCallOptions } from '../prompt/prepare-language-model-call-options';
+
+/**
+ * Resolves model call settings for a single step.
+ *
+ * Undefined step settings intentionally fall back to the outer call settings,
+ * while defined falsy values such as `temperature: 0` and `seed: 0` are kept.
+ */
+export function prepareStepCallSettings({
+  callSettings,
+  stepSettings,
+}: {
+  callSettings: LanguageModelCallOptions;
+  stepSettings: LanguageModelCallOptions | undefined;
+}): LanguageModelCallOptions {
+  return prepareLanguageModelCallOptions({
+    maxOutputTokens:
+      stepSettings?.maxOutputTokens ?? callSettings.maxOutputTokens,
+    temperature: stepSettings?.temperature ?? callSettings.temperature,
+    topP: stepSettings?.topP ?? callSettings.topP,
+    topK: stepSettings?.topK ?? callSettings.topK,
+    presencePenalty:
+      stepSettings?.presencePenalty ?? callSettings.presencePenalty,
+    frequencyPenalty:
+      stepSettings?.frequencyPenalty ?? callSettings.frequencyPenalty,
+    stopSequences: stepSettings?.stopSequences ?? callSettings.stopSequences,
+    seed: stepSettings?.seed ?? callSettings.seed,
+    reasoning: stepSettings?.reasoning ?? callSettings.reasoning,
+  });
+}

package/src/generate-text/prepare-step.ts

@@ -7,6 +7,7 @@ import type {
   ToolSet,
 } from '@ai-sdk/provider-utils';
 import type { Instructions } from '../prompt';
+import type { LanguageModelCallOptions } from '../prompt/language-model-call-options';
 import type { LanguageModel, ToolChoice } from '../types/language-model';
 import type { ActiveTools } from './active-tools';
 import type { ResponseMessage } from './response-message';
@@ -95,13 +96,17 @@ export type PrepareStepFunction<
 
 /**
  * The result type returned by a {@link PrepareStepFunction},
- * allowing per-step overrides of model, tools, instructions, or messages.
+ * allowing per-step overrides of model call settings, model, tools,
+ * instructions, or messages.
+ *
+ * Model call setting overrides apply only to the current step. Undefined
+ * settings fall back to the outer call settings.
  */
 export type PrepareStepResult<
   TOOLS extends ToolSet,
   RUNTIME_CONTEXT extends Context = Context,
 > =
-  | {
+  | ({
       /**
        * Optionally override which LanguageModel instance is used for this step.
        */
@@ -175,5 +180,5 @@ export type PrepareStepResult<
        * container IDs for Anthropic's code execution.
        */
       providerOptions?: ProviderOptions;
-    }
+    } & LanguageModelCallOptions)
   | undefined;

package/src/generate-text/step-result.ts

@@ -176,7 +176,8 @@ export type StepResult<
   readonly content: Array<ContentPart<TOOLS>>;
 
   /**
-   * The generated text. Can be an empty string if the model has not generated any text.
+   * The concatenation of all text parts generated in this step.
+   * It is an empty string if the step contains no text parts.
    */
   readonly text: string;
 

package/src/generate-text/stream-text.ts

@@ -113,6 +113,7 @@ import type {
   InferPartialOutput,
 } from './output-utils';
 import type { PrepareStepFunction } from './prepare-step';
+import { prepareStepCallSettings } from './prepare-step-call-settings';
 import { convertToReasoningOutputs } from './reasoning-output';
 import type { ResponseMessage } from './response-message';
 import { createRestrictedTelemetryDispatcher } from './restricted-telemetry-dispatcher';
@@ -915,6 +916,11 @@ function createOutputTransformStream<
       textChunk += chunk.text;
       textProviderMetadata = chunk.providerMetadata ?? textProviderMetadata;
 
+      if (chunk.text.length === 0 && chunk.providerMetadata != null) {
+        controller.enqueue({ part: chunk, partialOutput: undefined });
+        return;
+      }
+
       // only publish if partial json can be parsed:
       const result = await output.parsePartialOutput({ text });
 
@@ -1963,6 +1969,11 @@ class DefaultStreamTextResult<
             prepareStepResult?.providerOptions,
           );
 
+          const stepCallSettings = prepareStepCallSettings({
+            callSettings,
+            stepSettings: prepareStepResult,
+          });
+
           const stepStartTimestampMs = now();
 
           const { retry } = prepareRetries({ maxRetries, abortSignal });
@@ -2035,7 +2046,7 @@ class DefaultStreamTextResult<
                 _internal: {
                   now,
                 },
-                ...callSettings,
+                ...stepCallSettings,
               }),
             ),
           );
@@ -2198,7 +2209,10 @@ class DefaultStreamTextResult<
                     }
 
                     case 'text-delta': {
-                      if (chunk.text.length > 0) {
+                      if (
+                        chunk.text.length > 0 ||
+                        chunk.providerMetadata != null
+                      ) {
                         controller.enqueue(chunk);
                       }
                       break;