ai 6.0.237 → 6.0.238

package/dist/internal/index.js

@@ -164,7 +164,7 @@ function detectMediaType({
 var import_provider_utils2 = require("@ai-sdk/provider-utils");
 
 // src/version.ts
-var VERSION = true ? "6.0.237" : "0.0.0-test";
+var VERSION = true ? "6.0.238" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/dist/internal/index.mjs

@@ -144,7 +144,7 @@ import {
 } from "@ai-sdk/provider-utils";
 
 // src/version.ts
-var VERSION = true ? "6.0.237" : "0.0.0-test";
+var VERSION = true ? "6.0.238" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

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

@@ -117,6 +117,10 @@ const agent = new ToolLoopAgent({
 
 Learn more about [loop control and stop conditions](/docs/agents/loop-control).
 
+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.
+
 ### Tool Choice
 
 Control how the agent uses tools:

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

@@ -178,6 +178,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`, and `seed`. 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
 
 Manage growing conversation history in long-running loops:

package/docs/03-ai-sdk-core/60-telemetry.mdx

@@ -197,7 +197,7 @@ The event types for each method are the same as the corresponding [event callbac
 
 `generateText` records 3 types of spans:
 
-- `ai.generateText` (span): the full length of the generateText call. It contains 1 or more `ai.generateText.doGenerate` spans.
+- `ai.generateText` (span): the full length of the generateText call. It is the direct parent of 1 or more `ai.generateText.doGenerate` spans and any `ai.toolCall` spans recorded for the call.
   It contains the [basic LLM span information](#basic-llm-span-information) and the following attributes:
 
   - `operation.name`: `ai.generateText` and the functionId that was set through `telemetry.functionId`
@@ -208,7 +208,7 @@ The event types for each method are the same as the corresponding [event callbac
   - `ai.response.finishReason`: the reason why the generation finished
   - `ai.settings.maxOutputTokens`: the maximum number of output tokens that were set
 
-- `ai.generateText.doGenerate` (span): a provider doGenerate call. It can contain `ai.toolCall` spans.
+- `ai.generateText.doGenerate` (span): a provider doGenerate call.
   It contains the [call LLM span information](#call-llm-span-information) and the following attributes:
 
   - `operation.name`: `ai.generateText.doGenerate` and the functionId that was set through `telemetry.functionId`
@@ -229,7 +229,7 @@ The event types for each method are the same as the corresponding [event callbac
 
 `streamText` records 3 types of spans and 2 types of events:
 
-- `ai.streamText` (span): the full length of the streamText call. It contains a `ai.streamText.doStream` span.
+- `ai.streamText` (span): the full length of the streamText call. It is the direct parent of 1 or more `ai.streamText.doStream` spans and any `ai.toolCall` spans recorded for the call.
   It contains the [basic LLM span information](#basic-llm-span-information) and the following attributes:
 
   - `operation.name`: `ai.streamText` and the functionId that was set through `telemetry.functionId`
@@ -241,7 +241,7 @@ The event types for each method are the same as the corresponding [event callbac
   - `ai.settings.maxOutputTokens`: the maximum number of output tokens that were set
 
 - `ai.streamText.doStream` (span): a provider doStream call.
-  This span contains an `ai.stream.firstChunk` event and `ai.toolCall` spans.
+  This span can contain `ai.stream.firstChunk` and `ai.stream.finish` events.
   It contains the [call LLM span information](#call-llm-span-information) and the following attributes:
 
   - `operation.name`: `ai.streamText.doStream` and the functionId that was set through `telemetry.functionId`

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

@@ -530,7 +530,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, system prompt, and input messages 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, system prompt, and input messages for each step.',
       properties: [
         {
           type: 'PrepareStepFunction<TOOLS>',
@@ -590,6 +590,62 @@ 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: 'toolChoice',
               type: 'ToolChoice<TOOLS>',
@@ -1977,7 +2033,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 `content` for a text part to distinguish that case.',
     },
     {
       name: 'reasoning',
@@ -2388,7 +2445,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

@@ -574,7 +574,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, system prompt, and input messages 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, system prompt, and input messages for each step.',
       properties: [
         {
           type: 'PrepareStepFunction<TOOLS>',
@@ -634,6 +634,62 @@ 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: 'toolChoice',
               type: 'ToolChoice<TOOLS>',

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

@@ -102,7 +102,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, and seed. Model call setting overrides apply only to the current step.',
     },
     {
       name: 'experimental_repairToolCall',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "6.0.237",
+  "version": "6.0.238",
   "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",
   "sideEffects": false,
@@ -45,9 +45,9 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@ai-sdk/gateway": "3.0.159",
+    "@ai-sdk/gateway": "3.0.160",
     "@ai-sdk/provider": "3.0.14",
-    "@ai-sdk/provider-utils": "4.0.40"
+    "@ai-sdk/provider-utils": "4.0.41"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",

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

@@ -36,7 +36,9 @@ export interface GenerateTextResult<
   readonly content: Array<ContentPart<TOOLS>>;
 
   /**
-   * The text that was generated in the last 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 `content` for a text part to distinguish that case.
    */
   readonly text: string;
 

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

@@ -77,6 +77,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 type { ResponseMessage } from './response-message';
 import { DefaultStepResult, type StepResult } from './step-result';
 import {
@@ -752,6 +753,11 @@ export async function generateText<
               prepareStepResult?.providerOptions,
             );
 
+            const stepCallSettings = prepareStepCallSettings({
+              callSettings,
+              stepSettings: prepareStepResult,
+            });
+
             await notify({
               event: {
                 stepNumber: steps.length,
@@ -816,20 +822,22 @@ export async function generateText<
                     'gen_ai.system': stepModel.provider,
                     'gen_ai.request.model': stepModel.modelId,
                     'gen_ai.request.frequency_penalty':
-                      settings.frequencyPenalty,
-                    'gen_ai.request.max_tokens': settings.maxOutputTokens,
-                    'gen_ai.request.presence_penalty': settings.presencePenalty,
-                    'gen_ai.request.stop_sequences': settings.stopSequences,
-                    'gen_ai.request.temperature':
-                      settings.temperature ?? undefined,
-                    'gen_ai.request.top_k': settings.topK,
-                    'gen_ai.request.top_p': settings.topP,
+                      stepCallSettings.frequencyPenalty,
+                    'gen_ai.request.max_tokens':
+                      stepCallSettings.maxOutputTokens,
+                    'gen_ai.request.presence_penalty':
+                      stepCallSettings.presencePenalty,
+                    'gen_ai.request.stop_sequences':
+                      stepCallSettings.stopSequences,
+                    'gen_ai.request.temperature': stepCallSettings.temperature,
+                    'gen_ai.request.top_k': stepCallSettings.topK,
+                    'gen_ai.request.top_p': stepCallSettings.topP,
                   },
                 }),
                 tracer,
                 fn: async span => {
                   const result = 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,30 @@
+import { prepareCallSettings } from '../prompt/prepare-call-settings';
+import type { PrepareStepCallSettings } from './prepare-step';
+
+/**
+ * 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: PrepareStepCallSettings;
+  stepSettings: PrepareStepCallSettings | undefined;
+}): PrepareStepCallSettings {
+  return prepareCallSettings({
+    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,
+  });
+}

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

@@ -4,9 +4,22 @@ import type {
   SystemModelMessage,
   Tool,
 } from '@ai-sdk/provider-utils';
+import type { CallSettings } from '../prompt/call-settings';
 import type { LanguageModel, ToolChoice } from '../types/language-model';
 import type { StepResult } from './step-result';
 
+export type PrepareStepCallSettings = Pick<
+  CallSettings,
+  | 'maxOutputTokens'
+  | 'temperature'
+  | 'topP'
+  | 'topK'
+  | 'presencePenalty'
+  | 'frequencyPenalty'
+  | 'stopSequences'
+  | 'seed'
+>;
+
 /**
  * Function that you can use to provide different settings for a step.
  *
@@ -51,12 +64,16 @@ export type PrepareStepFunction<
 
 /**
  * The result type returned by a {@link PrepareStepFunction},
- * allowing per-step overrides of model, tools, or messages.
+ * allowing per-step overrides of model call settings, model, tools, 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 Record<string, Tool> = Record<string, Tool>,
 > =
-  | {
+  | ({
       /**
        * Optionally override which LanguageModel instance is used for this step.
        */
@@ -99,5 +116,5 @@ export type PrepareStepResult<
        * container IDs for Anthropic's code execution.
        */
       providerOptions?: ProviderOptions;
-    }
+    } & PrepareStepCallSettings)
   | undefined;

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

@@ -65,7 +65,8 @@ export type StepResult<TOOLS extends ToolSet> = {
   readonly content: Array<ContentPart<TOOLS>>;
 
   /**
-   * The generated 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

@@ -103,6 +103,7 @@ import type {
   InferPartialOutput,
 } from './output-utils';
 import type { PrepareStepFunction } from './prepare-step';
+import { prepareStepCallSettings } from './prepare-step-call-settings';
 import type { ResponseMessage } from './response-message';
 import {
   runToolsTransformation,
@@ -714,6 +715,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 });
 
@@ -1670,6 +1676,11 @@ class DefaultStreamTextResult<
               prepareStepResult?.providerOptions,
             );
 
+            const stepCallSettings = prepareStepCallSettings({
+              callSettings,
+              stepSettings: prepareStepResult,
+            });
+
             await notify({
               event: {
                 stepNumber: recordedSteps.length,
@@ -1735,14 +1746,16 @@ class DefaultStreamTextResult<
                     'gen_ai.system': stepModel.provider,
                     'gen_ai.request.model': stepModel.modelId,
                     'gen_ai.request.frequency_penalty':
-                      callSettings.frequencyPenalty,
-                    'gen_ai.request.max_tokens': callSettings.maxOutputTokens,
+                      stepCallSettings.frequencyPenalty,
+                    'gen_ai.request.max_tokens':
+                      stepCallSettings.maxOutputTokens,
                     'gen_ai.request.presence_penalty':
-                      callSettings.presencePenalty,
-                    'gen_ai.request.stop_sequences': callSettings.stopSequences,
-                    'gen_ai.request.temperature': callSettings.temperature,
-                    'gen_ai.request.top_k': callSettings.topK,
-                    'gen_ai.request.top_p': callSettings.topP,
+                      stepCallSettings.presencePenalty,
+                    'gen_ai.request.stop_sequences':
+                      stepCallSettings.stopSequences,
+                    'gen_ai.request.temperature': stepCallSettings.temperature,
+                    'gen_ai.request.top_k': stepCallSettings.topK,
+                    'gen_ai.request.top_p': stepCallSettings.topP,
                   },
                 }),
                 tracer,
@@ -1751,7 +1764,7 @@ class DefaultStreamTextResult<
                   startTimestampMs: now(), // get before the call
                   doStreamSpan,
                   result: await stepModel.doStream({
-                    ...callSettings,
+                    ...stepCallSettings,
                     tools: stepTools,
                     toolChoice: stepToolChoice,
                     responseFormat: await output?.responseFormat,
@@ -1878,15 +1891,18 @@ class DefaultStreamTextResult<
                       }
 
                       case 'text-delta': {
-                        if (chunk.delta.length > 0) {
+                        if (
+                          chunk.delta.length > 0 ||
+                          chunk.providerMetadata != null
+                        ) {
                           controller.enqueue({
                             type: 'text-delta',
                             id: chunk.id,
                             text: chunk.delta,
                             providerMetadata: chunk.providerMetadata,
                           });
-                          activeText += chunk.delta;
                         }
+                        activeText += chunk.delta;
                         break;
                       }