@ai-sdk/openai 3.0.97 → 3.0.98

package/docs/03-openai.mdx

@@ -1277,6 +1277,63 @@ The custom tool can be configured with:
   - **definition** _string_ - (grammar only) The grammar definition string (a regex pattern or Lark grammar).
 - **execute** _function_ (optional) - An async function that receives the raw string input and returns a string result. Enables multi-turn tool calling.
 
+#### Restricting Callable Tools
+
+The `allowedTools` provider option restricts which of the tools you declared the model is allowed to
+call, while still sending the full `tools` list to OpenAI. Because the tools list stays byte-identical
+across requests, the prompt cache is preserved — unlike `activeTools`, which removes tools from the
+request and invalidates the cache whenever the allow-list changes.
+
+`allowedTools` is only supported by the Responses API, and it overrides the request-level `toolChoice`.
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: openai.responses('gpt-5.5'),
+  tools: {
+    weather: weatherTool,
+    cityAttractions: cityAttractionsTool,
+    search: openai.tools.webSearch(),
+  },
+  providerOptions: {
+    openai: {
+      allowedTools: { toolNames: ['weather', 'search'], mode: 'auto' },
+    },
+  },
+  prompt: 'What is the weather in San Francisco?',
+});
+```
+
+- **toolNames** _string[]_ - The tools the model may call, named as you declared them in `tools`. For
+  provider-defined tools you may also use the canonical OpenAI name (for example `web_search`).
+- **mode** _'auto' | 'required'_ (optional) - `'auto'` (default) lets the model pick one of the allowed
+  tools or answer with a message; `'required'` forces it to call at least one of them.
+
+Both function tools and provider-defined tools can be allow-listed, including web search, file search,
+image generation, code interpreter, apply patch, shell, custom tools, and MCP servers.
+
+If a name matches both a tool you declared and the canonical OpenAI name of a different tool, the tool
+you declared under that name wins, and a warning reports the ambiguity. If several tools share the same
+canonical name — two MCP servers, for example — that name is ambiguous, so it is dropped with a warning;
+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.
+</Note>
+
+<Note>
+  An MCP server is allow-listed as a whole: the entry carries the server label,
+  so every tool on that server is callable. To restrict which tools on a server
+  the model may call, use the MCP tool's own `allowedTools` argument.
+</Note>
+
 #### Image Inputs
 
 The OpenAI Responses API supports Image inputs for appropriate models.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.97",
+  "version": "3.0.98",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

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

@@ -337,6 +337,21 @@ export type OpenAIResponsesFunctionTool = {
   defer_loading?: boolean;
 };
 
+/**
+ * Entry in `tool_choice.allowed_tools.tools`. OpenAI identifies most built-in
+ * tools by type alone; only `function`, `custom` and `mcp` carry an identifier.
+ */
+export type OpenAIResponsesAllowedTool =
+  | { type: 'function'; name: string }
+  | { type: 'custom'; name: string }
+  | { type: 'mcp'; server_label: string }
+  | {
+      type: Exclude<
+        OpenAIResponsesTool['type'],
+        'function' | 'custom' | 'mcp' | 'namespace' | 'tool_search'
+      >;
+    };
+
 export type OpenAIResponsesTool =
   | OpenAIResponsesFunctionTool
   | {

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

@@ -15,10 +15,15 @@ import { toolSearchArgsSchema } from '../tool/tool-search';
 import { webSearchArgsSchema } from '../tool/web-search';
 import { webSearchPreviewArgsSchema } from '../tool/web-search-preview';
 import type {
+  OpenAIResponsesAllowedTool,
   OpenAIResponsesFunctionTool,
   OpenAIResponsesTool,
 } from './openai-responses-api';
 
+type AllowedToolResolution =
+  | { supported: true; entry: OpenAIResponsesAllowedTool }
+  | { supported: false; reason: string };
+
 type OpenAIToolOptions = {
   deferLoading?: boolean;
   namespace?: {
@@ -60,7 +65,7 @@ export async function prepareResponsesTools({
     | {
         type: 'allowed_tools';
         mode: 'auto' | 'required';
-        tools: Array<{ type: 'function'; name: string }>;
+        tools: Array<OpenAIResponsesAllowedTool>;
       };
   toolWarnings: SharedV3Warning[];
 }> {
@@ -81,6 +86,35 @@ export async function prepareResponsesTools({
   const resolvedCustomProviderToolNames =
     customProviderToolNames ?? new Set<string>();
 
+  const allowedToolResolutions = new Map<string, AllowedToolResolution>();
+  const allowedToolAliases = new Map<
+    string,
+    AllowedToolResolution | 'ambiguous'
+  >();
+
+  const recordAllowedTool = (
+    toolName: string,
+    resolution: AllowedToolResolution,
+    canonicalName: string | undefined,
+  ) => {
+    allowedToolResolutions.set(toolName, resolution);
+
+    if (canonicalName == null || canonicalName === toolName) {
+      return;
+    }
+
+    const existingAlias = allowedToolAliases.get(canonicalName);
+
+    if (existingAlias == null) {
+      allowedToolAliases.set(canonicalName, resolution);
+    } else if (
+      existingAlias !== 'ambiguous' &&
+      !isSameAllowedTool(existingAlias, resolution)
+    ) {
+      allowedToolAliases.set(canonicalName, 'ambiguous');
+    }
+  };
+
   for (const tool of tools) {
     switch (tool.type) {
       case 'function': {
@@ -115,9 +149,32 @@ export async function prepareResponsesTools({
 
           namespaceTool.tools.push(openaiFunctionTool);
         }
+
+        recordAllowedTool(
+          tool.name,
+          namespace != null
+            ? {
+                supported: false,
+                reason:
+                  'tools inside an OpenAI tool namespace are not visible to tool_choice.allowed_tools',
+              }
+            : openaiOptions?.deferLoading === true
+              ? {
+                  supported: false,
+                  reason:
+                    'deferred tools are not visible to tool_choice.allowed_tools',
+                }
+              : {
+                  supported: true,
+                  entry: { type: 'function', name: tool.name },
+                },
+          undefined,
+        );
         break;
       }
       case 'provider': {
+        const openaiToolCountBefore = openaiTools.length;
+
         switch (tool.id) {
           case 'openai.file_search': {
             const args = await validateTypes({
@@ -321,6 +378,16 @@ export async function prepareResponsesTools({
             break;
           }
         }
+
+        if (openaiTools.length > openaiToolCountBefore) {
+          const openaiTool = openaiTools[openaiToolCountBefore];
+
+          recordAllowedTool(
+            tool.name,
+            toAllowedToolResolution(openaiTool),
+            toolNameMapping?.toProviderToolName(tool.name),
+          );
+        }
         break;
       }
       default:
@@ -333,15 +400,74 @@ export async function prepareResponsesTools({
   }
 
   if (allowedTools != null) {
+    const allowedToolEntries: Array<OpenAIResponsesAllowedTool> = [];
+    const droppedToolNames: string[] = [];
+
+    for (const name of allowedTools.toolNames) {
+      const directResolution = allowedToolResolutions.get(name);
+      const resolution = directResolution ?? allowedToolAliases.get(name);
+
+      if (directResolution != null && allowedToolAliases.has(name)) {
+        toolWarnings.push({
+          type: 'unsupported',
+          feature: `allowedTools entry "${name}"`,
+          details:
+            'this name is both a tool name and the provider tool name of another tool in this request; the tool with this name is allowed',
+        });
+      }
+
+      if (resolution === 'ambiguous') {
+        toolWarnings.push({
+          type: 'unsupported',
+          feature: `allowedTools entry "${name}"`,
+          details:
+            'several tools in this request share this provider tool name; use the tool name from the tools for this request instead',
+        });
+        droppedToolNames.push(name);
+        continue;
+      }
+
+      if (resolution == null) {
+        toolWarnings.push({
+          type: 'unsupported',
+          feature: `allowedTools entry "${name}"`,
+          details:
+            'the tool is not part of the tools for this request and is sent as a function tool',
+        });
+        allowedToolEntries.push({
+          type: 'function',
+          name: toolNameMapping?.toProviderToolName(name) ?? name,
+        });
+        continue;
+      }
+
+      if (!resolution.supported) {
+        toolWarnings.push({
+          type: 'unsupported',
+          feature: `allowedTools entry "${name}"`,
+          details: `${resolution.reason}; the tool is removed from the allowed tools`,
+        });
+        droppedToolNames.push(name);
+        continue;
+      }
+
+      allowedToolEntries.push(resolution.entry);
+    }
+
+    if (allowedToolEntries.length === 0) {
+      throw new UnsupportedFunctionalityError({
+        functionality: `allowedTools with only tools that cannot be allow-listed (${droppedToolNames.join(
+          ', ',
+        )})`,
+      });
+    }
+
     return {
       tools: openaiTools,
       toolChoice: {
         type: 'allowed_tools',
         mode: allowedTools.mode ?? 'auto',
-        tools: allowedTools.toolNames.map(name => ({
-          type: 'function',
-          name: toolNameMapping?.toProviderToolName(name) ?? name,
-        })),
+        tools: allowedToolEntries,
       },
       toolWarnings,
     };
@@ -389,6 +515,61 @@ export async function prepareResponsesTools({
   }
 }
 
+function allowedToolKey(entry: OpenAIResponsesAllowedTool): string {
+  switch (entry.type) {
+    case 'mcp':
+      return `mcp:${entry.server_label}`;
+    case 'function':
+    case 'custom':
+      return `${entry.type}:${entry.name}`;
+    default:
+      return entry.type;
+  }
+}
+
+function isSameAllowedTool(
+  a: AllowedToolResolution,
+  b: AllowedToolResolution,
+): boolean {
+  if (a.supported && b.supported) {
+    return allowedToolKey(a.entry) === allowedToolKey(b.entry);
+  }
+
+  if (!a.supported && !b.supported) {
+    return a.reason === b.reason;
+  }
+
+  return false;
+}
+
+function toAllowedToolResolution(
+  tool: OpenAIResponsesTool,
+): AllowedToolResolution {
+  switch (tool.type) {
+    case 'custom':
+      return { supported: true, entry: { type: 'custom', name: tool.name } };
+    case 'mcp':
+      return {
+        supported: true,
+        entry: { type: 'mcp', server_label: tool.server_label },
+      };
+    case 'file_search':
+    case 'web_search':
+    case 'web_search_preview':
+    case 'image_generation':
+    case 'code_interpreter':
+    case 'apply_patch':
+    case 'shell':
+    case 'local_shell':
+      return { supported: true, entry: { type: tool.type } };
+    default:
+      return {
+        supported: false,
+        reason: `OpenAI does not support ${tool.type} tools in tool_choice.allowed_tools`,
+      };
+  }
+}
+
 function prepareFunctionTool({
   tool,
   options,