@ai-sdk/openai 4.0.95 → 4.0.97

package/docs/03-openai.mdx

@@ -720,6 +720,12 @@ the operation is idempotent, and set explicit step limits.
 
 The OpenAI responses API supports web search through the `openai.tools.webSearch` tool.
 
+<Note>
+  `openai.tools.webSearchPreview()` is deprecated. Use
+  `openai.tools.webSearch()` instead. The existing `searchContextSize` and
+  `userLocation` options are supported by both tools.
+</Note>
+
 ```ts
 const result = await generateText({
   model: openai('gpt-6-astra'),
@@ -1538,6 +1544,111 @@ In client mode, the flow spans two steps:
 
 For more details, see the [OpenAI Tool Search documentation](https://platform.openai.com/docs/guides/tools-tool-search).
 
+##### Load tools after an ordinary tool result
+
+When your own search function discovers tools, attach
+`providerOptions.openai.additionalTools` to its tool-result part. The Responses
+provider preserves the ordinary result and emits an `additional_tools` item
+immediately after it. Replaying the same messages preserves that insertion point.
+
+```ts
+import {
+  openai,
+  type OpenAIResponsesToolResultOptions,
+  type OpenAIToolOptions,
+} from '@ai-sdk/openai';
+import { generateText, tool, type ModelMessage } from 'ai';
+import { z } from 'zod/v4';
+
+const messages: ModelMessage[] = [
+  { role: 'user', content: 'Find Linear and list my issues.' },
+  {
+    role: 'assistant',
+    content: [
+      {
+        type: 'tool-call',
+        toolCallId: 'search-1',
+        toolName: 'search',
+        input: {},
+      },
+    ],
+  },
+  {
+    role: 'tool',
+    content: [
+      {
+        type: 'tool-result',
+        toolCallId: 'search-1',
+        toolName: 'search',
+        output: {
+          type: 'json',
+          value: { connection: 'linear', connected: true },
+        },
+        providerOptions: {
+          openai: {
+            additionalTools: [
+              {
+                type: 'function',
+                name: 'list_issues',
+                description: 'List Linear issues.',
+                parameters: {
+                  type: 'object',
+                  properties: {},
+                  additionalProperties: false,
+                },
+              },
+            ],
+          } satisfies OpenAIResponsesToolResultOptions,
+        },
+      },
+    ],
+  },
+];
+
+const tools = {
+  search: tool({ inputSchema: z.object({}) }),
+  list_issues: tool({
+    inputSchema: z.object({}),
+    execute: async () => ({ issues: ['Example issue'] }),
+    providerOptions: {
+      openai: { omitFromRequestTools: true } satisfies OpenAIToolOptions,
+    },
+  }),
+};
+
+const result = await generateText({
+  model: openai.responses('gpt-5.4'),
+  tools,
+  messages,
+  providerOptions: { openai: { store: false } },
+});
+
+// Keep the original messages, including the additionalTools option, on replay.
+messages.push(...result.responseMessages);
+messages.push({ role: 'user', content: 'List my issues again.' });
+await generateText({
+  model: openai.responses('gpt-5.4'),
+  tools,
+  messages,
+  providerOptions: { openai: { store: false } },
+});
+```
+
+`additionalTools` currently accepts function definitions with `type: 'function'`,
+`name`, `parameters`, and optional `description` and `strict`. An empty array emits
+no item. These are OpenAI-format definitions; keep their names and schemas aligned
+with the SDK tools used for local validation and execution.
+
+`omitFromRequestTools: true` omits only the function's top-level Responses tool
+definition. Keep the function in `tools` and, if you use `activeTools`, include it
+there too: inactive tools cannot be executed. Use automatic tool choice for these
+functions; OpenAI cannot force or allow-list a tool absent from the top-level list.
+
+Both `generateText` and `streamText` support this representation. For streaming,
+append `await result.responseMessages` when replaying the conversation. This
+support is for direct `@ai-sdk/openai` Responses requests; AI Gateway support is
+not guaranteed by this provider option.
+
 #### Custom Tool
 
 The OpenAI Responses API supports
@@ -1657,12 +1768,12 @@ canonical name — two MCP servers, for example — that name is ambiguous, so i
 name those tools as you declared them instead.
 
 <Note>
-  Three kinds of tools cannot be allow-listed, because OpenAI's `allowed_tools`
-  only sees the eagerly-loaded tool list: the [tool search tool](#tool-search),
-  tools marked with `deferLoading`, and tools grouped into a namespace. Naming
-  one of these in `allowedTools` removes it from the allow-list and emits a
-  warning; if that leaves no tools at all, the request fails with an error
-  instead of silently sending no restriction.
+  Some tools cannot be allow-listed, because OpenAI's `allowed_tools` only sees
+  the eagerly-loaded tool list: the [tool search tool](#tool-search), tools
+  marked with `deferLoading` or `omitFromRequestTools`, and tools grouped into a
+  namespace. Naming one of these in `allowedTools` removes it from the
+  allow-list and emits a warning; if that leaves no tools at all, the request
+  fails with an error instead of silently sending no restriction.
 </Note>
 
 <Note>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "4.0.95",
+  "version": "4.0.97",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,8 +35,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.28",
-    "@ai-sdk/provider-utils": "5.0.61"
+    "@ai-sdk/provider": "4.0.30",
+    "@ai-sdk/provider-utils": "5.0.63"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.4",

package/src/chat/openai-chat-language-model.ts

@@ -52,6 +52,8 @@ import { normalizeOpenAIJsonSchema } from '../normalize-openai-json-schema';
 
 type OpenAIChatConfig = {
   provider: string;
+  /** Model ID sent to the API. Defaults to the model's reported ID. */
+  requestModelId?: string;
   headers?: () => Record<string, string | undefined>;
   url: (options: { modelId: string; path: string }) => string;
   fetch?: FetchFunction;
@@ -182,7 +184,7 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
 
     const baseArgs = {
       // model id:
-      model: this.modelId,
+      model: this.config.requestModelId ?? this.modelId,
 
       // model specific settings:
       logit_bias: openaiOptions.logitBias,
@@ -404,7 +406,7 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
     } = await postJsonToApi({
       url: this.config.url({
         path: '/chat/completions',
-        modelId: this.modelId,
+        modelId: this.config.requestModelId ?? this.modelId,
       }),
       headers: combineHeaders(this.config.headers?.(), options.headers),
       body,
@@ -504,7 +506,7 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
 
     const url = this.config.url({
       path: '/chat/completions',
-      modelId: this.modelId,
+      modelId: this.config.requestModelId ?? this.modelId,
     });
 
     const { responseHeaders, value: response } = await postJsonToApi({

package/src/completion/openai-completion-language-model.ts

@@ -43,6 +43,8 @@ import {
 } from './openai-completion-language-model-options';
 type OpenAICompletionConfig = {
   provider: string;
+  /** Model ID sent to the API. Defaults to the model's reported ID. */
+  requestModelId?: string;
   headers?: () => Record<string, string | undefined>;
   url: (options: { modelId: string; path: string }) => string;
   fetch?: FetchFunction;
@@ -148,7 +150,7 @@ export class OpenAICompletionLanguageModel implements LanguageModelV4 {
     return {
       args: {
         // model id:
-        model: this.modelId,
+        model: this.config.requestModelId ?? this.modelId,
 
         // model specific settings:
         echo: openaiOptions.echo,
@@ -192,7 +194,7 @@ export class OpenAICompletionLanguageModel implements LanguageModelV4 {
     } = await postJsonToApi({
       url: this.config.url({
         path: '/completions',
-        modelId: this.modelId,
+        modelId: this.config.requestModelId ?? this.modelId,
       }),
       headers: combineHeaders(this.config.headers?.(), options.headers),
       body: args,
@@ -246,7 +248,7 @@ export class OpenAICompletionLanguageModel implements LanguageModelV4 {
 
     const url = this.config.url({
       path: '/completions',
-      modelId: this.modelId,
+      modelId: this.config.requestModelId ?? this.modelId,
     });
 
     const { responseHeaders, value: response } = await postJsonToApi({

package/src/index.ts

@@ -15,6 +15,7 @@ export type { OpenAIRealtimeModelConfig as Experimental_OpenAIRealtimeModelConfi
 export type {
   OpenAILanguageModelResponsesOptions,
   OpenAIResponsesSystemMessageOptions,
+  OpenAIResponsesToolResultOptions,
   /** @deprecated Use `OpenAILanguageModelResponsesOptions` instead. */
   OpenAILanguageModelResponsesOptions as OpenAIResponsesProviderOptions,
 } from './responses/openai-responses-language-model-options';

package/src/openai-config.ts

@@ -11,6 +11,8 @@ type SerializedOpenAIConfig = Omit<Partial<OpenAIConfig>, 'headers'> & {
 
 export type OpenAIConfig = {
   provider: string;
+  /** Model ID sent to the API. Defaults to the model's reported ID. */
+  requestModelId?: string;
   baseURL?: string;
   url: (options: { modelId: string; path: string }) => string;
   headers?: () => OpenAIHeaders;

package/src/openai-decision-model.ts

@@ -180,7 +180,10 @@ export class DecisionOpenAIModel implements DecisionModelV4 {
           },
         ],
         questions: Object.entries(questions).map(([name, question]) => {
-          const instructions = toText(question.instructions);
+          const instructions =
+            question.instructions == null
+              ? question.instructions
+              : toText(question.instructions);
           switch (question.type) {
             case 'boolean':
               return {
@@ -195,7 +198,7 @@ export class DecisionOpenAIModel implements DecisionModelV4 {
                     ? undefined
                     : `Criteria for false:\n${toText(question.criteria.false)}`,
                 ]
-                  .filter(part => part !== undefined)
+                  .filter(part => part != null)
                   .join('\n\n'),
               };
             case 'choice':

package/src/openai-tools.ts

@@ -107,6 +107,8 @@ export const openaiTools = {
    * Web search allows models to access up-to-date information from the internet
    * and provide answers with sourced citations.
    *
+   * @deprecated Use `webSearch` instead.
+   *
    * @param searchContextSize - The search context size to use for the web search.
    * @param userLocation - The user location to use for the web search.
    */

package/src/responses/convert-to-openai-responses-input.ts

@@ -20,7 +20,10 @@ import {
   type ToolNameMapping,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
-import { openaiResponsesSystemMessageOptionsSchema } from './openai-responses-language-model-options';
+import {
+  openaiResponsesSystemMessageOptionsSchema,
+  openaiResponsesToolResultOptionsSchema,
+} from './openai-responses-language-model-options';
 import {
   applyPatchInputSchema,
   applyPatchOutputSchema,
@@ -1794,6 +1797,19 @@ export async function convertToOpenAIResponsesInput({
             output: contentValue,
             ...(caller != null && { caller }),
           });
+
+          const options = await parseProviderOptions({
+            provider: providerOptionsName,
+            providerOptions: part.providerOptions,
+            schema: openaiResponsesToolResultOptionsSchema,
+          });
+          if (options?.additionalTools?.length) {
+            input.push({
+              type: 'additional_tools',
+              role: 'developer',
+              tools: options.additionalTools,
+            });
+          }
         }
 
         break;

package/src/responses/openai-responses-api.ts

@@ -6,6 +6,7 @@ import {
   type InferSchema,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
+import type { OpenAIResponsesToolResultOptions } from './openai-responses-language-model-options';
 
 const jsonValueSchema: z.ZodType<JSONValue> = z.lazy(() =>
   z.union([
@@ -162,6 +163,11 @@ export type OpenAIResponsesInputItem =
   | OpenAIResponsesAssistantMessage
   | OpenAIResponsesFunctionCall
   | OpenAIResponsesFunctionCallOutput
+  | {
+      type: 'additional_tools';
+      role: 'developer';
+      tools: NonNullable<OpenAIResponsesToolResultOptions['additionalTools']>;
+    }
   | OpenAIResponsesProgram
   | OpenAIResponsesProgramOutput
   | OpenAIResponsesCustomToolCall

package/src/responses/openai-responses-language-model-options.ts

@@ -457,3 +457,26 @@ export const openaiResponsesSystemMessageOptionsSchema = lazySchema(() =>
 export type OpenAIResponsesSystemMessageOptions = InferSchema<
   typeof openaiResponsesSystemMessageOptionsSchema
 >;
+
+export const openaiResponsesToolResultOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /** Function definitions to load immediately after this ordinary tool result. */
+      additionalTools: z
+        .array(
+          z.strictObject({
+            type: z.literal('function'),
+            name: z.string().min(1),
+            description: z.string().optional(),
+            parameters: z.record(z.string(), z.json()),
+            strict: z.boolean().optional(),
+          }),
+        )
+        .optional(),
+    }),
+  ),
+);
+
+export type OpenAIResponsesToolResultOptions = InferSchema<
+  typeof openaiResponsesToolResultOptionsSchema
+>;

package/src/responses/openai-responses-language-model.ts

@@ -598,7 +598,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
     }
 
     const baseArgs = {
-      model: modelId,
+      model: config.requestModelId ?? modelId,
       input,
       temperature,
       top_p: topP,
@@ -854,7 +854,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
     } = await this.getArgs(options);
     const url = this.config.url({
       path: '/responses',
-      modelId: this.modelId,
+      modelId: this.config.requestModelId ?? this.modelId,
     });
 
     const approvalRequestIdToDummyToolCallIdFromPrompt =
@@ -1547,7 +1547,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
 
     const url = this.config.url({
       path: '/responses',
-      modelId: this.modelId,
+      modelId: this.config.requestModelId ?? this.modelId,
     });
 
     const { responseHeaders, value: response } = await postJsonToApi({

package/src/responses/openai-responses-prepare-tools.ts

@@ -40,6 +40,12 @@ export type OpenAIToolOptions = {
    */
   async?: boolean;
   deferLoading?: boolean;
+  /**
+   * Omit this function from the Responses request's top-level tools array.
+   * Use for tools supplied in history through additionalTools. Keep the tool
+   * active in the SDK so its calls can still be validated and executed.
+   */
+  omitFromRequestTools?: boolean;
   outputSchema?: JSONObject;
   namespace?: {
     name: string;
@@ -145,6 +151,27 @@ export async function prepareResponsesTools({
         if (openaiOptions?.outputSchema != null) {
           outputSchemaToolNames?.add(tool.name);
         }
+        if (openaiOptions?.omitFromRequestTools === true) {
+          recordAllowedTool(
+            tool.name,
+            {
+              supported: false,
+              reason:
+                'tools omitted from the request tools array cannot be allow-listed',
+            },
+            undefined,
+          );
+          if (
+            allowedTools == null &&
+            toolChoice?.type === 'tool' &&
+            toolChoice.toolName === tool.name
+          ) {
+            throw new UnsupportedFunctionalityError({
+              functionality: `forcing tool "${tool.name}" omitted from the request tools array; use automatic tool choice for history-loaded tools`,
+            });
+          }
+          break;
+        }
         const openaiFunctionTool = prepareFunctionTool({
           tool,
           options: openaiOptions,