@ai-sdk/openai 3.0.45 → 3.0.47

package/docs/03-openai.mdx

@@ -958,6 +958,145 @@ Your execute function must return:
 - **status** _'completed' | 'failed'_ - Whether the patch was applied successfully
 - **output** _string_ (optional) - Human-readable log text (e.g., results or error messages)
 
+#### Tool Search
+
+Tool search allows the model to dynamically search for and load tools into context as needed,
+rather than loading all tool definitions up front. This can reduce token usage, cost, and latency
+when you have many tools. Mark the tools you want to make searchable with `deferLoading: true`
+in their `providerOptions`.
+
+There are two execution modes:
+
+- **Server-executed (hosted):** OpenAI searches across the deferred tools declared in the request and returns the loaded subset in the same response. No extra round-trip is needed.
+- **Client-executed:** The model emits a `tool_search_call`, your application performs the lookup, and you return the matching tools via the `execute` callback.
+
+##### Server-Executed (Hosted) Tool Search
+
+Use hosted tool search when the candidate tools are already known at request time.
+Add `openai.tools.toolSearch()` with no arguments and mark your tools with `deferLoading: true`:
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { generateText, tool, stepCountIs } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: openai.responses('gpt-5.4'),
+  prompt: 'What is the weather in San Francisco?',
+  stopWhen: stepCountIs(10),
+  tools: {
+    toolSearch: openai.tools.toolSearch(),
+
+    get_weather: tool({
+      description: 'Get the current weather at a specific location',
+      inputSchema: z.object({
+        location: z.string(),
+        unit: z.enum(['celsius', 'fahrenheit']),
+      }),
+      execute: async ({ location, unit }) => ({
+        location,
+        temperature: unit === 'celsius' ? 18 : 64,
+      }),
+      providerOptions: {
+        openai: { deferLoading: true },
+      },
+    }),
+
+    search_files: tool({
+      description: 'Search through files in the workspace',
+      inputSchema: z.object({ query: z.string() }),
+      execute: async ({ query }) => ({
+        results: [`Found 3 files matching "${query}"`],
+      }),
+      providerOptions: {
+        openai: { deferLoading: true },
+      },
+    }),
+  },
+});
+```
+
+In hosted mode, the model internally searches the deferred tools, loads the relevant ones, and
+proceeds to call them — all within a single response. The `tool_search_call` and
+`tool_search_output` items appear in the response with `execution: 'server'` and `call_id: null`.
+
+##### Client-Executed Tool Search
+
+Use client-executed tool search when tool discovery depends on runtime state — for example,
+tools that vary per tenant, project, or external system. Pass `execution: 'client'` along with
+a `description`, `parameters` schema, and an `execute` callback:
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { generateText, tool, stepCountIs } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: openai.responses('gpt-5.4'),
+  prompt: 'What is the weather in San Francisco?',
+  stopWhen: stepCountIs(10),
+  tools: {
+    toolSearch: openai.tools.toolSearch({
+      execution: 'client',
+      description: 'Search for available tools based on what the user needs.',
+      parameters: {
+        type: 'object',
+        properties: {
+          goal: {
+            type: 'string',
+            description: 'What the user is trying to accomplish',
+          },
+        },
+        required: ['goal'],
+        additionalProperties: false,
+      },
+      execute: async ({ arguments: args }) => {
+        // Your custom tool discovery logic here.
+        // Return the tools that match the search goal.
+        return {
+          tools: [
+            {
+              type: 'function',
+              name: 'get_weather',
+              description: 'Get the current weather at a specific location',
+              deferLoading: true,
+              parameters: {
+                type: 'object',
+                properties: {
+                  location: { type: 'string' },
+                },
+                required: ['location'],
+                additionalProperties: false,
+              },
+            },
+          ],
+        };
+      },
+    }),
+
+    get_weather: tool({
+      description: 'Get the current weather at a specific location',
+      inputSchema: z.object({ location: z.string() }),
+      execute: async ({ location }) => ({
+        location,
+        temperature: 64,
+        condition: 'Partly cloudy',
+      }),
+      providerOptions: {
+        openai: { deferLoading: true },
+      },
+    }),
+  },
+});
+```
+
+In client mode, the flow spans two steps:
+
+1. **Step 1:** The model emits a `tool_search_call` with `execution: 'client'` and a non-null `call_id`. The SDK calls your `execute` callback with the search arguments. Your callback returns the discovered tools.
+2. **Step 2:** The SDK sends the `tool_search_output` (with the matching `call_id`) back to the model. The model can now call the loaded tools as normal function calls.
+
+For more details, see the [OpenAI Tool Search documentation](https://platform.openai.com/docs/guides/tools-tool-search).
+
 #### Custom Tool
 
 The OpenAI Responses API supports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.45",
+  "version": "3.0.47",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "3.0.8",
-    "@ai-sdk/provider-utils": "4.0.20"
+    "@ai-sdk/provider-utils": "4.0.21"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

package/src/openai-tools.ts

@@ -5,6 +5,7 @@ import { fileSearch } from './tool/file-search';
 import { imageGeneration } from './tool/image-generation';
 import { localShell } from './tool/local-shell';
 import { shell } from './tool/shell';
+import { toolSearch } from './tool/tool-search';
 import { webSearch } from './tool/web-search';
 import { webSearchPreview } from './tool/web-search-preview';
 import { mcp } from './tool/mcp';
@@ -123,4 +124,15 @@ export const openaiTools = {
    * @param serverUrl - URL for the MCP server.
    */
   mcp,
+
+  /**
+   * Tool search allows the model to dynamically search for and load deferred
+   * tools into the model's context as needed. This helps reduce overall token
+   * usage, cost, and latency by only loading tools when the model needs them.
+   *
+   * To use tool search, mark functions or namespaces with `defer_loading: true`
+   * in the tools array. The model will use tool search to load these tools
+   * when it determines they are needed.
+   */
+  toolSearch,
 };

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

@@ -7,6 +7,7 @@ import {
 import {
   convertToBase64,
   isNonNullable,
+  parseJSON,
   parseProviderOptions,
   ToolNameMapping,
   validateTypes,
@@ -21,6 +22,10 @@ import {
   localShellOutputSchema,
 } from '../tool/local-shell';
 import { shellInputSchema, shellOutputSchema } from '../tool/shell';
+import {
+  toolSearchInputSchema,
+  toolSearchOutputSchema,
+} from '../tool/tool-search';
 import {
   OpenAIResponsesCustomToolCallOutput,
   OpenAIResponsesFunctionCallOutput,
@@ -206,6 +211,41 @@ export async function convertToOpenAIResponsesInput({
                 break;
               }
 
+              const resolvedToolName = toolNameMapping.toProviderToolName(
+                part.toolName,
+              );
+
+              if (resolvedToolName === 'tool_search') {
+                if (store && id != null) {
+                  input.push({ type: 'item_reference', id });
+                  break;
+                }
+
+                const parsedInput =
+                  typeof part.input === 'string'
+                    ? await parseJSON({
+                        text: part.input,
+                        schema: toolSearchInputSchema,
+                      })
+                    : await validateTypes({
+                        value: part.input,
+                        schema: toolSearchInputSchema,
+                      });
+
+                const execution =
+                  parsedInput.call_id != null ? 'client' : 'server';
+
+                input.push({
+                  type: 'tool_search_call',
+                  id: id ?? part.toolCallId,
+                  execution,
+                  call_id: parsedInput.call_id ?? null,
+                  status: 'completed',
+                  arguments: parsedInput.arguments,
+                });
+                break;
+              }
+
               if (part.providerExecuted) {
                 if (store && id != null) {
                   input.push({ type: 'item_reference', id });
@@ -218,10 +258,6 @@ export async function convertToOpenAIResponsesInput({
                 break;
               }
 
-              const resolvedToolName = toolNameMapping.toProviderToolName(
-                part.toolName,
-              );
-
               if (hasLocalShellTool && resolvedToolName === 'local_shell') {
                 const parsedInput = await validateTypes({
                   value: part.input,
@@ -328,6 +364,35 @@ export async function convertToOpenAIResponsesInput({
                 part.toolName,
               );
 
+              if (resolvedResultToolName === 'tool_search') {
+                const itemId =
+                  (
+                    part.providerOptions?.[providerOptionsName] as
+                      | { itemId?: string }
+                      | undefined
+                  )?.itemId ?? part.toolCallId;
+
+                if (store) {
+                  input.push({ type: 'item_reference', id: itemId });
+                } else if (part.output.type === 'json') {
+                  const parsedOutput = await validateTypes({
+                    value: part.output.value,
+                    schema: toolSearchOutputSchema,
+                  });
+
+                  input.push({
+                    type: 'tool_search_output',
+                    id: itemId,
+                    execution: 'server',
+                    call_id: null,
+                    status: 'completed',
+                    tools: parsedOutput.tools,
+                  });
+                }
+
+                break;
+              }
+
               /*
                * Shell tool results are separate output items (shell_call_output)
                * with their own item IDs distinct from the shell_call's item ID.
@@ -527,6 +592,22 @@ export async function convertToOpenAIResponsesInput({
             part.toolName,
           );
 
+          if (resolvedToolName === 'tool_search' && output.type === 'json') {
+            const parsedOutput = await validateTypes({
+              value: output.value,
+              schema: toolSearchOutputSchema,
+            });
+
+            input.push({
+              type: 'tool_search_output',
+              execution: 'client',
+              call_id: part.toolCallId,
+              status: 'completed',
+              tools: parsedOutput.tools,
+            });
+            continue;
+          }
+
           if (
             hasLocalShellTool &&
             resolvedToolName === 'local_shell' &&

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

@@ -1,7 +1,18 @@
-import { JSONSchema7 } from '@ai-sdk/provider';
+import { JSONObject, JSONSchema7, JSONValue } from '@ai-sdk/provider';
 import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
+const jsonValueSchema: z.ZodType<JSONValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema.optional()),
+  ]),
+);
+
 export type OpenAIResponsesInput = Array<OpenAIResponsesInputItem>;
 
 export type OpenAIResponsesInputItem =
@@ -20,6 +31,8 @@ export type OpenAIResponsesInputItem =
   | OpenAIResponsesShellCallOutput
   | OpenAIResponsesApplyPatchCall
   | OpenAIResponsesApplyPatchCallOutput
+  | OpenAIResponsesToolSearchCall
+  | OpenAIResponsesToolSearchOutput
   | OpenAIResponsesReasoning
   | OpenAIResponsesItemReference;
 
@@ -199,6 +212,24 @@ export type OpenAIResponsesApplyPatchCallOutput = {
   output?: string;
 };
 
+export type OpenAIResponsesToolSearchCall = {
+  type: 'tool_search_call';
+  id: string;
+  execution: 'server' | 'client';
+  call_id: string | null;
+  status: 'in_progress' | 'completed' | 'incomplete';
+  arguments: unknown;
+};
+
+export type OpenAIResponsesToolSearchOutput = {
+  type: 'tool_search_output';
+  id?: string;
+  execution: 'server' | 'client';
+  call_id: string | null;
+  status: 'in_progress' | 'completed' | 'incomplete';
+  tools: Array<JSONObject>;
+};
+
 export type OpenAIResponsesItemReference = {
   type: 'item_reference';
   id: string;
@@ -249,6 +280,7 @@ export type OpenAIResponsesTool =
       description: string | undefined;
       parameters: JSONSchema7;
       strict?: boolean;
+      defer_loading?: boolean;
     }
   | {
       type: 'apply_patch';
@@ -407,6 +439,12 @@ export type OpenAIResponsesTool =
               path: string;
             }>;
           };
+    }
+  | {
+      type: 'tool_search';
+      execution?: 'server' | 'client';
+      description?: string;
+      parameters?: Record<string, unknown>;
     };
 
 export type OpenAIResponsesReasoning = {
@@ -592,6 +630,22 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
               }),
             ),
           }),
+          z.object({
+            type: z.literal('tool_search_call'),
+            id: z.string(),
+            execution: z.enum(['server', 'client']),
+            call_id: z.string().nullable(),
+            status: z.enum(['in_progress', 'completed', 'incomplete']),
+            arguments: z.unknown(),
+          }),
+          z.object({
+            type: z.literal('tool_search_output'),
+            id: z.string(),
+            execution: z.enum(['server', 'client']),
+            call_id: z.string().nullable(),
+            status: z.enum(['in_progress', 'completed', 'incomplete']),
+            tools: z.array(z.record(z.string(), jsonValueSchema.optional())),
+          }),
         ]),
       }),
       z.object({
@@ -815,6 +869,22 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
               }),
             ),
           }),
+          z.object({
+            type: z.literal('tool_search_call'),
+            id: z.string(),
+            execution: z.enum(['server', 'client']),
+            call_id: z.string().nullable(),
+            status: z.enum(['in_progress', 'completed', 'incomplete']),
+            arguments: z.unknown(),
+          }),
+          z.object({
+            type: z.literal('tool_search_output'),
+            id: z.string(),
+            execution: z.enum(['server', 'client']),
+            call_id: z.string().nullable(),
+            status: z.enum(['in_progress', 'completed', 'incomplete']),
+            tools: z.array(z.record(z.string(), jsonValueSchema.optional())),
+          }),
         ]),
       }),
       z.object({
@@ -1238,6 +1308,22 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
                 }),
               ),
             }),
+            z.object({
+              type: z.literal('tool_search_call'),
+              id: z.string(),
+              execution: z.enum(['server', 'client']),
+              call_id: z.string().nullable(),
+              status: z.enum(['in_progress', 'completed', 'incomplete']),
+              arguments: z.unknown(),
+            }),
+            z.object({
+              type: z.literal('tool_search_output'),
+              id: z.string(),
+              execution: z.enum(['server', 'client']),
+              call_id: z.string().nullable(),
+              status: z.enum(['in_progress', 'completed', 'incomplete']),
+              tools: z.array(z.record(z.string(), jsonValueSchema.optional())),
+            }),
           ]),
         )
         .optional(),

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

@@ -38,6 +38,10 @@ import { imageGenerationOutputSchema } from '../tool/image-generation';
 import { localShellInputSchema } from '../tool/local-shell';
 import { mcpOutputSchema } from '../tool/mcp';
 import { shellInputSchema, shellOutputSchema } from '../tool/shell';
+import {
+  toolSearchInputSchema,
+  toolSearchOutputSchema,
+} from '../tool/tool-search';
 import { webSearchOutputSchema } from '../tool/web-search';
 import {
   convertOpenAIResponsesUsage,
@@ -193,6 +197,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
         'openai.web_search_preview': 'web_search_preview',
         'openai.mcp': 'mcp',
         'openai.apply_patch': 'apply_patch',
+        'openai.tool_search': 'tool_search',
       },
       resolveProviderToolName: tool =>
         tool.id === 'openai.custom'
@@ -505,6 +510,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
 
     // flag that checks if there have been client-side tool calls (not executed by openai)
     let hasFunctionCall = false;
+    const hostedToolSearchCallIds: string[] = [];
 
     // map response content to content array (defined when there is no error)
     for (const part of response.output!) {
@@ -551,6 +557,54 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
           break;
         }
 
+        case 'tool_search_call': {
+          const toolCallId = part.call_id ?? part.id;
+          const isHosted = part.execution === 'server';
+
+          if (isHosted) {
+            hostedToolSearchCallIds.push(toolCallId);
+          }
+
+          content.push({
+            type: 'tool-call',
+            toolCallId,
+            toolName: toolNameMapping.toCustomToolName('tool_search'),
+            input: JSON.stringify({
+              arguments: part.arguments,
+              call_id: part.call_id,
+            } satisfies InferSchema<typeof toolSearchInputSchema>),
+            ...(isHosted ? { providerExecuted: true } : {}),
+            providerMetadata: {
+              [providerOptionsName]: {
+                itemId: part.id,
+              },
+            },
+          });
+
+          break;
+        }
+
+        case 'tool_search_output': {
+          const toolCallId =
+            part.call_id ?? hostedToolSearchCallIds.shift() ?? part.id;
+
+          content.push({
+            type: 'tool-result',
+            toolCallId,
+            toolName: toolNameMapping.toCustomToolName('tool_search'),
+            result: {
+              tools: part.tools,
+            } satisfies InferSchema<typeof toolSearchOutputSchema>,
+            providerMetadata: {
+              [providerOptionsName]: {
+                itemId: part.id,
+              },
+            },
+          });
+
+          break;
+        }
+
         case 'local_shell_call': {
           content.push({
             type: 'tool-call',
@@ -1026,6 +1080,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
             hasDiff: boolean;
             endEmitted: boolean;
           };
+          toolSearchExecution?: 'server' | 'client';
         }
       | undefined
     > = {};
@@ -1054,6 +1109,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
     > = {};
 
     let serviceTier: string | undefined;
+    const hostedToolSearchCallIds: string[] = [];
 
     return {
       stream: response.pipeThrough(
@@ -1188,6 +1244,28 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                   input: '{}',
                   providerExecuted: true,
                 });
+              } else if (value.item.type === 'tool_search_call') {
+                const toolCallId = value.item.id;
+                const toolName =
+                  toolNameMapping.toCustomToolName('tool_search');
+                const isHosted = value.item.execution === 'server';
+
+                ongoingToolCalls[value.output_index] = {
+                  toolName,
+                  toolCallId,
+                  toolSearchExecution: value.item.execution ?? 'server',
+                };
+
+                if (isHosted) {
+                  controller.enqueue({
+                    type: 'tool-input-start',
+                    id: toolCallId,
+                    toolName,
+                    providerExecuted: true,
+                  });
+                }
+              } else if (value.item.type === 'tool_search_output') {
+                // handled on output_item.done so we can pair it with the call
               } else if (
                 value.item.type === 'mcp_call' ||
                 value.item.type === 'mcp_list_tools' ||
@@ -1418,6 +1496,67 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                     result: value.item.result,
                   } satisfies InferSchema<typeof imageGenerationOutputSchema>,
                 });
+              } else if (value.item.type === 'tool_search_call') {
+                const toolCall = ongoingToolCalls[value.output_index];
+                const isHosted = value.item.execution === 'server';
+
+                if (toolCall != null) {
+                  const toolCallId = isHosted
+                    ? toolCall.toolCallId
+                    : (value.item.call_id ?? value.item.id);
+
+                  if (isHosted) {
+                    hostedToolSearchCallIds.push(toolCallId);
+                  } else {
+                    controller.enqueue({
+                      type: 'tool-input-start',
+                      id: toolCallId,
+                      toolName: toolCall.toolName,
+                    });
+                  }
+
+                  controller.enqueue({
+                    type: 'tool-input-end',
+                    id: toolCallId,
+                  });
+
+                  controller.enqueue({
+                    type: 'tool-call',
+                    toolCallId,
+                    toolName: toolCall.toolName,
+                    input: JSON.stringify({
+                      arguments: value.item.arguments,
+                      call_id: isHosted ? null : toolCallId,
+                    } satisfies InferSchema<typeof toolSearchInputSchema>),
+                    ...(isHosted ? { providerExecuted: true } : {}),
+                    providerMetadata: {
+                      [providerOptionsName]: {
+                        itemId: value.item.id,
+                      },
+                    },
+                  });
+                }
+
+                ongoingToolCalls[value.output_index] = undefined;
+              } else if (value.item.type === 'tool_search_output') {
+                const toolCallId =
+                  value.item.call_id ??
+                  hostedToolSearchCallIds.shift() ??
+                  value.item.id;
+
+                controller.enqueue({
+                  type: 'tool-result',
+                  toolCallId,
+                  toolName: toolNameMapping.toCustomToolName('tool_search'),
+                  result: {
+                    tools: value.item.tools,
+                  } satisfies InferSchema<typeof toolSearchOutputSchema>,
+                  providerMetadata: {
+                    [providerOptionsName]: {
+                      itemId: value.item.id,
+                    },
+                  },
+                });
               } else if (value.item.type === 'mcp_call') {
                 ongoingToolCalls[value.output_index] = undefined;