ai 6.0.237 → 6.0.239

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.239" : "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.239" : "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/10-generating-structured-data.mdx

@@ -415,16 +415,22 @@ console.log(result.reasoningText);
 
 ## Error Handling
 
-When `generateText` with structured output cannot generate a valid object, it throws a [`AI_NoObjectGeneratedError`](/docs/reference/ai-sdk-errors/ai-no-object-generated-error).
+`generateText` can report structured output failures in two ways:
 
-This error occurs when the AI provider fails to generate a parsable object that conforms to the schema.
-It can arise due to the following reasons:
+- If the model response cannot be parsed or validated against the schema,
+  `generateText` rejects with an
+  [`AI_NoObjectGeneratedError`](/docs/reference/ai-sdk-errors/ai-no-object-generated-error).
+- If `generateText` returns a result without an output, accessing `result.output`
+  throws an
+  [`AI_NoOutputGeneratedError`](/docs/reference/ai-sdk-errors/ai-no-output-generated-error).
+  This can happen when the final step does not finish with a `stop` reason, for
+  example when it finishes with `tool-calls`.
 
-- The model failed to generate a response.
-- The model generated a response that could not be parsed.
-- The model generated a response that could not be validated against the schema.
+The `output` property is a getter, so destructuring it also triggers this
+access.
 
-The error preserves the following information to help you log the issue:
+`NoObjectGeneratedError` preserves the following information to help you log
+the issue:
 
 - `text`: The text that was generated by the model. This can be the raw text or the tool call text, depending on the object generation mode.
 - `response`: Metadata about the language model response, including response id, timestamp, and model.
@@ -432,14 +438,21 @@ The error preserves the following information to help you log the issue:
 - `cause`: The cause of the error (e.g. a JSON parsing error). You can use this for more detailed error handling.
 
 ```ts
-import { generateText, Output, NoObjectGeneratedError } from 'ai';
+import {
+  generateText,
+  NoObjectGeneratedError,
+  NoOutputGeneratedError,
+  Output,
+} from 'ai';
 
 try {
-  await generateText({
+  const result = await generateText({
     model,
     output: Output.object({ schema }),
     prompt,
   });
+
+  console.log(result.output);
 } catch (error) {
   if (NoObjectGeneratedError.isInstance(error)) {
     console.log('NoObjectGeneratedError');
@@ -447,6 +460,8 @@ try {
     console.log('Text:', error.text);
     console.log('Response:', error.response);
     console.log('Usage:', error.usage);
+  } else if (NoOutputGeneratedError.isInstance(error)) {
+    console.log('NoOutputGeneratedError');
   }
 }
 ```

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',
@@ -2339,9 +2396,9 @@ To see `generateText` in action, check out [these examples](#examples).
     },
     {
       name: 'output',
-      type: 'Output',
-      isOptional: true,
-      description: 'Experimental setting for generating structured outputs.',
+      type: 'InferCompleteOutput<OUTPUT>',
+      description:
+        'The generated output according to the `output` specification. Accessing this property throws `NoOutputGeneratedError` when no output is available, for example when the final step does not finish with a `stop` reason.',
     },
     {
       name: 'steps',
@@ -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/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx

@@ -120,6 +120,13 @@ It currently does not support accepting notifications from an MCP server, and cu
                 },
               ],
             },
+            {
+              name: 'initializationOptions',
+              type: 'RequestOptions',
+              isOptional: true,
+              description:
+                'Optional signal and timeout settings that bound transport startup and the initialize request. A timeout or abort closes the transport and rejects createMCPClient.',
+            },
             {
               name: 'clientName',
               type: 'string',

package/docs/07-reference/05-ai-sdk-errors/ai-no-output-generated-error.mdx

@@ -7,6 +7,11 @@ description: Learn how to fix AI_NoOutputGeneratedError
 
 This error is thrown when no LLM output was generated, e.g. because of errors.
 
+For `generateText`, accessing `result.output` throws this error when the result
+does not contain an output. This can happen when the final step does not finish
+with a `stop` reason, for example when it finishes with `tool-calls`. The
+`output` property is a getter, so destructuring it also triggers this access.
+
 ## Properties
 
 - `message`: The error message (optional, defaults to `'No output generated.'`)

package/docs/08-migration-guides/26-migration-guide-5-0.mdx

@@ -2069,11 +2069,48 @@ import { useAssistant } from '@ai-sdk/react';
 ```
 
 ```tsx filename="AI SDK 5.0"
-// useAssistant has been removed
-// Use useChat with appropriate configuration instead
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+
+function Chat() {
+  const { messages, sendMessage } = useChat({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+  });
+
+  // ...
+}
 ```
 
-For an implementation of the assistant functionality with AI SDK v5, see this [example repository](https://github.com/vercel-labs/ai-sdk-openai-assistants-api).
+The `useAssistant` hook was specific to the OpenAI Assistants API. OpenAI has
+deprecated that API in favor of the Responses API. Configure `useChat` for your
+route as shown above, then return a UI message stream from the route:
+
+```tsx filename="app/api/chat/route.ts"
+import { openai } from '@ai-sdk/openai';
+import { convertToModelMessages, streamText, type UIMessage } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const result = streamText({
+    model: openai.responses('gpt-4o-mini'),
+    prompt: convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+For persistent conversation state and built-in tools, see the
+[OpenAI Responses API guide](/cookbook/guides/openai-responses).
+
+If you need to connect `useChat` to another backend, see the
+[transport documentation](/docs/ai-sdk-ui/transport) and
+[stream protocol](/docs/ai-sdk-ui/stream-protocol). For migrating existing
+OpenAI Assistants data and API calls, see OpenAI's
+[Assistants migration guide](https://platform.openai.com/docs/assistants/migration).
 
 #### Attachments → File Parts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "6.0.237",
+  "version": "6.0.239",
   "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.161",
     "@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;
 
@@ -165,8 +167,10 @@ export interface GenerateTextResult<
   readonly experimental_output: InferCompleteOutput<OUTPUT>;
 
   /**
-   * The generated structured output. It uses the `output` specification.
+   * The generated output according to the `output` specification.
    *
+   * @throws {NoOutputGeneratedError} When no output is available, for example
+   * when the final step does not finish with a `stop` reason.
    */
   readonly output: InferCompleteOutput<OUTPUT>;
 }

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;