@ai-sdk/openai 3.0.97 → 3.0.99

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.99",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

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

@@ -1,6 +1,8 @@
 import {
   UnsupportedFunctionalityError,
   type LanguageModelV3Prompt,
+  type LanguageModelV3ToolResultOutput,
+  type LanguageModelV3ToolResultPart,
   type LanguageModelV3ToolApprovalResponsePart,
   type SharedV3ProviderOptions,
   type SharedV3Warning,
@@ -33,11 +35,206 @@ import type {
   OpenAIResponsesInput,
   OpenAIResponsesReasoning,
 } from './openai-responses-api';
+import {
+  getParallelToolCallMetadata,
+  type ParallelToolCallMetadata,
+} from './expand-parallel-tool-call';
 
 function serializeToolCallArguments(input: unknown): string {
   return JSON.stringify(input === undefined ? {} : input);
 }
 
+async function convertFunctionToolResultOutput({
+  output,
+  providerOptionsName,
+  warnings,
+}: {
+  output: LanguageModelV3ToolResultOutput;
+  providerOptionsName: string;
+  warnings: Array<SharedV3Warning>;
+}): Promise<OpenAIResponsesFunctionCallOutput['output']> {
+  switch (output.type) {
+    case 'text':
+    case 'error-text':
+      return output.value;
+    case 'execution-denied':
+      return output.reason ?? 'Tool call execution denied.';
+    case 'json':
+    case 'error-json':
+      return JSON.stringify(output.value);
+    case 'content':
+      return output.value
+        .map(item => {
+          const promptCacheBreakpoint = getPromptCacheBreakpoint(
+            item.providerOptions,
+            providerOptionsName,
+          );
+          switch (item.type) {
+            case 'text': {
+              return {
+                type: 'input_text' as const,
+                text: item.text,
+                ...(promptCacheBreakpoint != null && {
+                  prompt_cache_breakpoint: promptCacheBreakpoint,
+                }),
+              };
+            }
+
+            case 'image-data': {
+              return {
+                type: 'input_image' as const,
+                image_url: `data:${item.mediaType};base64,${item.data}`,
+                detail:
+                  item.providerOptions?.[providerOptionsName]?.imageDetail,
+                ...(promptCacheBreakpoint != null && {
+                  prompt_cache_breakpoint: promptCacheBreakpoint,
+                }),
+              };
+            }
+
+            case 'image-url': {
+              return {
+                type: 'input_image' as const,
+                image_url: item.url,
+                detail:
+                  item.providerOptions?.[providerOptionsName]?.imageDetail,
+                ...(promptCacheBreakpoint != null && {
+                  prompt_cache_breakpoint: promptCacheBreakpoint,
+                }),
+              };
+            }
+
+            case 'file-data': {
+              return {
+                type: 'input_file' as const,
+                filename: item.filename ?? 'data',
+                file_data: `data:${item.mediaType};base64,${item.data}`,
+                ...(promptCacheBreakpoint != null && {
+                  prompt_cache_breakpoint: promptCacheBreakpoint,
+                }),
+              };
+            }
+
+            case 'file-url': {
+              return {
+                type: 'input_file' as const,
+                file_url: item.url,
+                ...(promptCacheBreakpoint != null && {
+                  prompt_cache_breakpoint: promptCacheBreakpoint,
+                }),
+              };
+            }
+
+            default: {
+              warnings.push({
+                type: 'other',
+                message: `unsupported tool content part type: ${item.type}`,
+              });
+              return undefined;
+            }
+          }
+        })
+        .filter(isNonNullable);
+  }
+}
+
+type ParallelToolResultGroup = {
+  metadata: ParallelToolCallMetadata;
+  results: Array<LanguageModelV3ToolResultPart>;
+};
+
+function hasSameParallelToolCall(
+  first: ParallelToolCallMetadata,
+  second: ParallelToolCallMetadata,
+): boolean {
+  return (
+    first.itemId === second.itemId &&
+    first.toolCallId === second.toolCallId &&
+    first.toolName === second.toolName &&
+    first.input === second.input &&
+    first.count === second.count
+  );
+}
+
+function collectCompleteParallelToolResultGroups({
+  prompt,
+  providerOptionsName,
+}: {
+  prompt: LanguageModelV3Prompt;
+  providerOptionsName: string;
+}): Map<string, ParallelToolResultGroup> {
+  const pendingGroups = new Map<
+    string,
+    {
+      metadata: ParallelToolCallMetadata;
+      results: Map<number, LanguageModelV3ToolResultPart>;
+      invalid: boolean;
+    }
+  >();
+
+  for (const message of prompt) {
+    if (message.role !== 'tool') {
+      continue;
+    }
+
+    for (const part of message.content) {
+      if (part.type !== 'tool-result') {
+        continue;
+      }
+
+      const metadata = getParallelToolCallMetadata({
+        providerOptions: part.providerOptions,
+        providerOptionsName,
+      });
+
+      if (metadata == null) {
+        continue;
+      }
+
+      const existing = pendingGroups.get(metadata.toolCallId);
+      if (existing == null) {
+        pendingGroups.set(metadata.toolCallId, {
+          metadata,
+          results: new Map([[metadata.index, part]]),
+          invalid: false,
+        });
+        continue;
+      }
+
+      if (
+        !hasSameParallelToolCall(existing.metadata, metadata) ||
+        existing.results.has(metadata.index)
+      ) {
+        existing.invalid = true;
+        continue;
+      }
+
+      existing.results.set(metadata.index, part);
+    }
+  }
+
+  const completeGroups = new Map<string, ParallelToolResultGroup>();
+
+  for (const [toolCallId, group] of pendingGroups) {
+    if (group.invalid || group.results.size !== group.metadata.count) {
+      continue;
+    }
+
+    const results = Array.from({ length: group.metadata.count }, (_, index) =>
+      group.results.get(index),
+    );
+
+    if (results.every(isNonNullable)) {
+      completeGroups.set(toolCallId, {
+        metadata: group.metadata,
+        results,
+      });
+    }
+  }
+
+  return completeGroups;
+}
+
 type OpenAIPromptCacheBreakpoint = { mode: 'explicit' };
 
 function getPromptCacheBreakpoint(
@@ -93,6 +290,15 @@ export async function convertToOpenAIResponsesInput({
   let input: OpenAIResponsesInput = [];
   const warnings: Array<SharedV3Warning> = [];
   const processedApprovalIds = new Set<string>();
+  const parallelToolResultGroups =
+    hasConversation || hasPreviousResponseId
+      ? collectCompleteParallelToolResultGroups({
+          prompt,
+          providerOptionsName,
+        })
+      : new Map<string, ParallelToolResultGroup>();
+  const emittedParallelToolCalls = new Set<string>();
+  const emittedParallelToolResults = new Set<string>();
 
   for (const { role, content, providerOptions } of prompt) {
     switch (role) {
@@ -279,6 +485,49 @@ export async function convertToOpenAIResponsesInput({
               break;
             }
             case 'tool-call': {
+              const parallelToolCallMetadata = getParallelToolCallMetadata({
+                providerOptions: part.providerOptions,
+                providerOptionsName,
+              });
+              const parallelToolResultGroup =
+                parallelToolCallMetadata == null
+                  ? undefined
+                  : parallelToolResultGroups.get(
+                      parallelToolCallMetadata.toolCallId,
+                    );
+
+              if (
+                parallelToolCallMetadata != null &&
+                parallelToolResultGroup != null &&
+                hasSameParallelToolCall(
+                  parallelToolResultGroup.metadata,
+                  parallelToolCallMetadata,
+                )
+              ) {
+                if (
+                  !emittedParallelToolCalls.has(
+                    parallelToolResultGroup.metadata.toolCallId,
+                  )
+                ) {
+                  emittedParallelToolCalls.add(
+                    parallelToolResultGroup.metadata.toolCallId,
+                  );
+
+                  // Conversations already contain the original wrapper item.
+                  // previousResponseId chains require plain client function
+                  // calls to be reconstructed in full.
+                  if (!hasConversation) {
+                    input.push({
+                      type: 'function_call',
+                      call_id: parallelToolResultGroup.metadata.toolCallId,
+                      name: parallelToolResultGroup.metadata.toolName,
+                      arguments: parallelToolResultGroup.metadata.input,
+                    });
+                  }
+                }
+                break;
+              }
+
               const id = (part.providerOptions?.[providerOptionsName]?.itemId ??
                 (
                   part as {
@@ -709,6 +958,61 @@ export async function convertToOpenAIResponsesInput({
             continue;
           }
 
+          const parallelToolCallMetadata = getParallelToolCallMetadata({
+            providerOptions: part.providerOptions,
+            providerOptionsName,
+          });
+          const parallelToolResultGroup =
+            parallelToolCallMetadata == null
+              ? undefined
+              : parallelToolResultGroups.get(
+                  parallelToolCallMetadata.toolCallId,
+                );
+
+          if (
+            parallelToolCallMetadata != null &&
+            parallelToolResultGroup != null &&
+            hasSameParallelToolCall(
+              parallelToolResultGroup.metadata,
+              parallelToolCallMetadata,
+            )
+          ) {
+            if (
+              !emittedParallelToolResults.has(
+                parallelToolResultGroup.metadata.toolCallId,
+              )
+            ) {
+              emittedParallelToolResults.add(
+                parallelToolResultGroup.metadata.toolCallId,
+              );
+
+              const toolOutputs = await Promise.all(
+                parallelToolResultGroup.results.map(async result =>
+                  convertFunctionToolResultOutput({
+                    output: result.output,
+                    providerOptionsName,
+                    warnings,
+                  }),
+                ),
+              );
+
+              input.push({
+                type: 'function_call_output',
+                call_id: parallelToolResultGroup.metadata.toolCallId,
+                // The internal wrapper returns one output containing the child
+                // results in the same order as the original tool_uses array.
+                output: toolOutputs
+                  .map(output =>
+                    typeof output === 'string'
+                      ? output
+                      : JSON.stringify(output),
+                  )
+                  .join('\n'),
+              });
+            }
+            continue;
+          }
+
           const output = part.output;
 
           // Skip execution-denied with approvalId - already handled via tool-approval-response
@@ -897,96 +1201,11 @@ export async function convertToOpenAIResponsesInput({
             continue;
           }
 
-          let contentValue: OpenAIResponsesFunctionCallOutput['output'];
-          switch (output.type) {
-            case 'text':
-            case 'error-text':
-              contentValue = output.value;
-              break;
-            case 'execution-denied':
-              contentValue = output.reason ?? 'Tool call execution denied.';
-              break;
-            case 'json':
-            case 'error-json':
-              contentValue = JSON.stringify(output.value);
-              break;
-            case 'content':
-              contentValue = output.value
-                .map(item => {
-                  const promptCacheBreakpoint = getPromptCacheBreakpoint(
-                    item.providerOptions,
-                    providerOptionsName,
-                  );
-                  switch (item.type) {
-                    case 'text': {
-                      return {
-                        type: 'input_text' as const,
-                        text: item.text,
-                        ...(promptCacheBreakpoint != null && {
-                          prompt_cache_breakpoint: promptCacheBreakpoint,
-                        }),
-                      };
-                    }
-
-                    case 'image-data': {
-                      return {
-                        type: 'input_image' as const,
-                        image_url: `data:${item.mediaType};base64,${item.data}`,
-                        detail:
-                          item.providerOptions?.[providerOptionsName]
-                            ?.imageDetail,
-                        ...(promptCacheBreakpoint != null && {
-                          prompt_cache_breakpoint: promptCacheBreakpoint,
-                        }),
-                      };
-                    }
-
-                    case 'image-url': {
-                      return {
-                        type: 'input_image' as const,
-                        image_url: item.url,
-                        detail:
-                          item.providerOptions?.[providerOptionsName]
-                            ?.imageDetail,
-                        ...(promptCacheBreakpoint != null && {
-                          prompt_cache_breakpoint: promptCacheBreakpoint,
-                        }),
-                      };
-                    }
-
-                    case 'file-data': {
-                      return {
-                        type: 'input_file' as const,
-                        filename: item.filename ?? 'data',
-                        file_data: `data:${item.mediaType};base64,${item.data}`,
-                        ...(promptCacheBreakpoint != null && {
-                          prompt_cache_breakpoint: promptCacheBreakpoint,
-                        }),
-                      };
-                    }
-
-                    case 'file-url': {
-                      return {
-                        type: 'input_file' as const,
-                        file_url: item.url,
-                        ...(promptCacheBreakpoint != null && {
-                          prompt_cache_breakpoint: promptCacheBreakpoint,
-                        }),
-                      };
-                    }
-
-                    default: {
-                      warnings.push({
-                        type: 'other',
-                        message: `unsupported tool content part type: ${item.type}`,
-                      });
-                      return undefined;
-                    }
-                  }
-                })
-                .filter(isNonNullable);
-              break;
-          }
+          const contentValue = await convertFunctionToolResultOutput({
+            output,
+            providerOptionsName,
+            warnings,
+          });
 
           input.push({
             type: 'function_call_output',

package/src/responses/expand-parallel-tool-call.ts

@@ -0,0 +1,142 @@
+import {
+  isJSONObject,
+  type LanguageModelV3FunctionTool,
+  type LanguageModelV3ToolCall,
+  type SharedV3ProviderOptions,
+} from '@ai-sdk/provider';
+import { safeParseJSON } from '@ai-sdk/provider-utils';
+
+const parallelToolName = 'parallel';
+const recipientNamePrefix = 'functions.';
+
+/**
+ * Preserves the original wrapper identity so child results can be sent back as
+ * one function output when Responses API server-side state is used.
+ */
+export type ParallelToolCallMetadata = {
+  itemId: string;
+  toolCallId: string;
+  toolName: string;
+  input: string;
+  index: number;
+  count: number;
+};
+
+export function getParallelToolCallMetadata({
+  providerOptions,
+  providerOptionsName,
+}: {
+  providerOptions: SharedV3ProviderOptions | undefined;
+  providerOptionsName: string;
+}): ParallelToolCallMetadata | undefined {
+  const metadata = providerOptions?.[providerOptionsName]?.parallelToolCall;
+
+  if (
+    !isJSONObject(metadata) ||
+    typeof metadata.itemId !== 'string' ||
+    typeof metadata.toolCallId !== 'string' ||
+    typeof metadata.toolName !== 'string' ||
+    typeof metadata.input !== 'string' ||
+    typeof metadata.index !== 'number' ||
+    !Number.isInteger(metadata.index) ||
+    typeof metadata.count !== 'number' ||
+    !Number.isInteger(metadata.count) ||
+    metadata.index < 0 ||
+    metadata.count <= metadata.index
+  ) {
+    return undefined;
+  }
+
+  return metadata as ParallelToolCallMetadata;
+}
+
+export function isUndeclaredParallelToolCall({
+  toolName,
+  tools,
+}: {
+  toolName: string;
+  tools: Array<LanguageModelV3FunctionTool>;
+}): boolean {
+  return (
+    toolName === parallelToolName &&
+    !tools.some(tool => tool.name === parallelToolName)
+  );
+}
+
+/**
+ * Expands the internal parallel tool wrapper that OpenAI models can emit as a
+ * regular function call. The wrapper is only recognized when every nested
+ * recipient is a declared client-side function tool.
+ */
+export async function expandParallelToolCall({
+  toolCall,
+  tools,
+  providerOptionsName,
+  itemId,
+}: {
+  toolCall: Pick<LanguageModelV3ToolCall, 'toolCallId' | 'toolName' | 'input'>;
+  tools: Array<LanguageModelV3FunctionTool>;
+  providerOptionsName: string;
+  itemId: string;
+}): Promise<Array<LanguageModelV3ToolCall> | undefined> {
+  if (!isUndeclaredParallelToolCall({ toolName: toolCall.toolName, tools })) {
+    return undefined;
+  }
+
+  const parsedInput = await safeParseJSON({ text: toolCall.input });
+
+  if (!parsedInput.success || !isJSONObject(parsedInput.value)) {
+    return undefined;
+  }
+
+  const toolUses = parsedInput.value.tool_uses;
+  if (!Array.isArray(toolUses) || toolUses.length === 0) {
+    return undefined;
+  }
+
+  const availableToolNames = new Set(tools.map(tool => tool.name));
+  const expandedToolCalls: Array<LanguageModelV3ToolCall> = [];
+
+  for (const [index, toolUse] of toolUses.entries()) {
+    if (!isJSONObject(toolUse)) {
+      return undefined;
+    }
+
+    const recipientName = toolUse.recipient_name;
+    const parameters = toolUse.parameters;
+
+    if (
+      typeof recipientName !== 'string' ||
+      !recipientName.startsWith(recipientNamePrefix) ||
+      !isJSONObject(parameters)
+    ) {
+      return undefined;
+    }
+
+    const toolName = recipientName.slice(recipientNamePrefix.length);
+    if (toolName.length === 0 || !availableToolNames.has(toolName)) {
+      return undefined;
+    }
+
+    expandedToolCalls.push({
+      type: 'tool-call',
+      toolCallId: `${toolCall.toolCallId}_${index}`,
+      toolName,
+      input: JSON.stringify(parameters),
+      providerMetadata: {
+        [providerOptionsName]: {
+          parallelToolCall: {
+            itemId,
+            toolCallId: toolCall.toolCallId,
+            toolName: toolCall.toolName,
+            input: toolCall.input,
+            index,
+            count: toolUses.length,
+          } satisfies ParallelToolCallMetadata,
+        },
+      },
+    });
+  }
+
+  return expandedToolCalls;
+}

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