@ai-sdk/openai 4.0.94 → 4.0.96

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.94",
+  "version": "4.0.96",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,8 +35,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.27",
-    "@ai-sdk/provider-utils": "5.0.60"
+    "@ai-sdk/provider": "4.0.29",
+    "@ai-sdk/provider-utils": "5.0.62"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.4",

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-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

@@ -1739,14 +1739,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
                   type: 'tool-input-start',
                   id: value.item.call_id,
                   toolName,
-                });
-
-                // Custom tool input is a string, so stream its JSON encoding
-                // consistently with the final tool call input.
-                controller.enqueue({
-                  type: 'tool-input-delta',
-                  id: value.item.call_id,
-                  delta: '"',
+                  inputEncoding: 'text',
                 });
               } else if (value.item.type === 'web_search_call') {
                 ongoingToolCalls[value.output_index] = {
@@ -2146,12 +2139,6 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
                   value.item.name,
                 );
 
-                controller.enqueue({
-                  type: 'tool-input-delta',
-                  id: value.item.call_id,
-                  delta: '"',
-                });
-
                 controller.enqueue({
                   type: 'tool-input-end',
                   id: value.item.call_id,
@@ -2649,7 +2636,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
                 controller.enqueue({
                   type: 'tool-input-delta',
                   id: toolCall.toolCallId,
-                  delta: escapeJSONDelta(value.delta),
+                  delta: value.delta,
                 });
               }
             } else if (isResponseApplyPatchCallOperationDiffDeltaChunk(value)) {

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,