@ai-sdk/openai 4.0.0-beta.2 → 4.0.0-beta.20

package/src/completion/map-openai-finish-reason.ts

@@ -1,8 +1,8 @@
-import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+import { LanguageModelV4FinishReason } from '@ai-sdk/provider';
 
 export function mapOpenAIFinishReason(
   finishReason: string | null | undefined,
-): LanguageModelV3FinishReason['unified'] {
+): LanguageModelV4FinishReason['unified'] {
   switch (finishReason) {
     case 'stop':
       return 'stop';

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

@@ -1,12 +1,12 @@
 import {
-  LanguageModelV3,
-  LanguageModelV3CallOptions,
-  LanguageModelV3FinishReason,
-  LanguageModelV3GenerateResult,
-  LanguageModelV3StreamPart,
-  LanguageModelV3StreamResult,
-  SharedV3ProviderMetadata,
-  SharedV3Warning,
+  LanguageModelV4,
+  LanguageModelV4CallOptions,
+  LanguageModelV4FinishReason,
+  LanguageModelV4GenerateResult,
+  LanguageModelV4StreamPart,
+  LanguageModelV4StreamResult,
+  SharedV4ProviderMetadata,
+  SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
@@ -42,8 +42,8 @@ type OpenAICompletionConfig = {
   fetch?: FetchFunction;
 };
 
-export class OpenAICompletionLanguageModel implements LanguageModelV3 {
-  readonly specificationVersion = 'v3';
+export class OpenAICompletionLanguageModel implements LanguageModelV4 {
+  readonly specificationVersion = 'v4';
 
   readonly modelId: OpenAICompletionModelId;
 
@@ -83,8 +83,8 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
     toolChoice,
     seed,
     providerOptions,
-  }: LanguageModelV3CallOptions) {
-    const warnings: SharedV3Warning[] = [];
+  }: LanguageModelV4CallOptions) {
+    const warnings: SharedV4Warning[] = [];
 
     // Parse provider options
     const openaiOptions = {
@@ -161,8 +161,8 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
   }
 
   async doGenerate(
-    options: LanguageModelV3CallOptions,
-  ): Promise<LanguageModelV3GenerateResult> {
+    options: LanguageModelV4CallOptions,
+  ): Promise<LanguageModelV4GenerateResult> {
     const { args, warnings } = await this.getArgs(options);
 
     const {
@@ -186,7 +186,7 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
 
     const choice = response.choices[0];
 
-    const providerMetadata: SharedV3ProviderMetadata = { openai: {} };
+    const providerMetadata: SharedV4ProviderMetadata = { openai: {} };
 
     if (choice.logprobs != null) {
       providerMetadata.openai.logprobs = choice.logprobs;
@@ -211,8 +211,8 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
   }
 
   async doStream(
-    options: LanguageModelV3CallOptions,
-  ): Promise<LanguageModelV3StreamResult> {
+    options: LanguageModelV4CallOptions,
+  ): Promise<LanguageModelV4StreamResult> {
     const { args, warnings } = await this.getArgs(options);
 
     const body = {
@@ -239,11 +239,11 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
       fetch: this.config.fetch,
     });
 
-    let finishReason: LanguageModelV3FinishReason = {
+    let finishReason: LanguageModelV4FinishReason = {
       unified: 'other',
       raw: undefined,
     };
-    const providerMetadata: SharedV3ProviderMetadata = { openai: {} };
+    const providerMetadata: SharedV4ProviderMetadata = { openai: {} };
     let usage: OpenAICompletionUsage | undefined = undefined;
     let isFirstChunk = true;
 
@@ -251,7 +251,7 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
       stream: response.pipeThrough(
         new TransformStream<
           ParseResult<OpenAICompletionChunk>,
-          LanguageModelV3StreamPart
+          LanguageModelV4StreamPart
         >({
           start(controller) {
             controller.enqueue({ type: 'stream-start', warnings });

package/src/embedding/openai-embedding-model.ts

@@ -1,5 +1,5 @@
 import {
-  EmbeddingModelV3,
+  EmbeddingModelV4,
   TooManyEmbeddingValuesForCallError,
 } from '@ai-sdk/provider';
 import {
@@ -16,8 +16,8 @@ import {
 } from './openai-embedding-options';
 import { openaiTextEmbeddingResponseSchema } from './openai-embedding-api';
 
-export class OpenAIEmbeddingModel implements EmbeddingModelV3 {
-  readonly specificationVersion = 'v3';
+export class OpenAIEmbeddingModel implements EmbeddingModelV4 {
+  readonly specificationVersion = 'v4';
   readonly modelId: OpenAIEmbeddingModelId;
   readonly maxEmbeddingsPerCall = 2048;
   readonly supportsParallelCalls = true;
@@ -38,8 +38,8 @@ export class OpenAIEmbeddingModel implements EmbeddingModelV3 {
     headers,
     abortSignal,
     providerOptions,
-  }: Parameters<EmbeddingModelV3['doEmbed']>[0]): Promise<
-    Awaited<ReturnType<EmbeddingModelV3['doEmbed']>>
+  }: Parameters<EmbeddingModelV4['doEmbed']>[0]): Promise<
+    Awaited<ReturnType<EmbeddingModelV4['doEmbed']>>
   > {
     if (values.length > this.maxEmbeddingsPerCall) {
       throw new TooManyEmbeddingValuesForCallError({

package/src/image/openai-image-model.ts

@@ -1,7 +1,7 @@
 import {
-  ImageModelV3,
-  ImageModelV3File,
-  SharedV3Warning,
+  ImageModelV4,
+  ImageModelV4File,
+  SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
@@ -27,8 +27,8 @@ interface OpenAIImageModelConfig extends OpenAIConfig {
   };
 }
 
-export class OpenAIImageModel implements ImageModelV3 {
-  readonly specificationVersion = 'v3';
+export class OpenAIImageModel implements ImageModelV4 {
+  readonly specificationVersion = 'v4';
 
   get maxImagesPerCall(): number {
     return modelMaxImagesPerCall[this.modelId] ?? 1;
@@ -54,10 +54,10 @@ export class OpenAIImageModel implements ImageModelV3 {
     providerOptions,
     headers,
     abortSignal,
-  }: Parameters<ImageModelV3['doGenerate']>[0]): Promise<
-    Awaited<ReturnType<ImageModelV3['doGenerate']>>
+  }: Parameters<ImageModelV4['doGenerate']>[0]): Promise<
+    Awaited<ReturnType<ImageModelV4['doGenerate']>>
   > {
-    const warnings: Array<SharedV3Warning> = [];
+    const warnings: Array<SharedV4Warning> = [];
 
     if (aspectRatio != null) {
       warnings.push({
@@ -332,7 +332,7 @@ type OpenAIImageEditInput = {
 };
 
 async function fileToBlob(
-  file: ImageModelV3File | undefined,
+  file: ImageModelV4File | undefined,
 ): Promise<Blob | undefined> {
   if (!file) return undefined;
 

package/src/index.ts

@@ -15,6 +15,7 @@ export type { OpenAIEmbeddingModelOptions } from './embedding/openai-embedding-o
 export type { OpenAISpeechModelOptions } from './speech/openai-speech-options';
 export type { OpenAITranscriptionModelOptions } from './transcription/openai-transcription-options';
 export type {
+  OpenaiResponsesCompactionProviderMetadata,
   OpenaiResponsesProviderMetadata,
   OpenaiResponsesReasoningProviderMetadata,
   OpenaiResponsesTextProviderMetadata,

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

@@ -20,10 +20,10 @@ export function getOpenAILanguageModelCapabilities(
 
   const supportsPriorityProcessing =
     modelId.startsWith('gpt-4') ||
-    modelId.startsWith('gpt-5-mini') ||
     (modelId.startsWith('gpt-5') &&
       !modelId.startsWith('gpt-5-nano') &&
-      !modelId.startsWith('gpt-5-chat')) ||
+      !modelId.startsWith('gpt-5-chat') &&
+      !modelId.startsWith('gpt-5.4-nano')) ||
     modelId.startsWith('o3') ||
     modelId.startsWith('o4-mini');
 
@@ -40,6 +40,7 @@ export function getOpenAILanguageModelCapabilities(
   const supportsNonReasoningParameters =
     modelId.startsWith('gpt-5.1') ||
     modelId.startsWith('gpt-5.2') ||
+    modelId.startsWith('gpt-5.3') ||
     modelId.startsWith('gpt-5.4');
 
   const systemMessageMode = isReasoningModel ? 'developer' : 'system';

package/src/openai-provider.ts

@@ -1,10 +1,10 @@
 import {
-  EmbeddingModelV3,
-  ImageModelV3,
-  LanguageModelV3,
-  ProviderV3,
-  SpeechModelV3,
-  TranscriptionModelV3,
+  EmbeddingModelV4,
+  ImageModelV4,
+  LanguageModelV4,
+  ProviderV4,
+  SpeechModelV4,
+  TranscriptionModelV4,
 } from '@ai-sdk/provider';
 import {
   FetchFunction,
@@ -30,68 +30,68 @@ import { OpenAITranscriptionModel } from './transcription/openai-transcription-m
 import { OpenAITranscriptionModelId } from './transcription/openai-transcription-options';
 import { VERSION } from './version';
 
-export interface OpenAIProvider extends ProviderV3 {
-  (modelId: OpenAIResponsesModelId): LanguageModelV3;
+export interface OpenAIProvider extends ProviderV4 {
+  (modelId: OpenAIResponsesModelId): LanguageModelV4;
 
   /**
    * Creates an OpenAI model for text generation.
    */
-  languageModel(modelId: OpenAIResponsesModelId): LanguageModelV3;
+  languageModel(modelId: OpenAIResponsesModelId): LanguageModelV4;
 
   /**
    * Creates an OpenAI chat model for text generation.
    */
-  chat(modelId: OpenAIChatModelId): LanguageModelV3;
+  chat(modelId: OpenAIChatModelId): LanguageModelV4;
 
   /**
    * Creates an OpenAI responses API model for text generation.
    */
-  responses(modelId: OpenAIResponsesModelId): LanguageModelV3;
+  responses(modelId: OpenAIResponsesModelId): LanguageModelV4;
 
   /**
    * Creates an OpenAI completion model for text generation.
    */
-  completion(modelId: OpenAICompletionModelId): LanguageModelV3;
+  completion(modelId: OpenAICompletionModelId): LanguageModelV4;
 
   /**
    * Creates a model for text embeddings.
    */
-  embedding(modelId: OpenAIEmbeddingModelId): EmbeddingModelV3;
+  embedding(modelId: OpenAIEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * Creates a model for text embeddings.
    */
-  embeddingModel(modelId: OpenAIEmbeddingModelId): EmbeddingModelV3;
+  embeddingModel(modelId: OpenAIEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * @deprecated Use `embedding` instead.
    */
-  textEmbedding(modelId: OpenAIEmbeddingModelId): EmbeddingModelV3;
+  textEmbedding(modelId: OpenAIEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * @deprecated Use `embeddingModel` instead.
    */
-  textEmbeddingModel(modelId: OpenAIEmbeddingModelId): EmbeddingModelV3;
+  textEmbeddingModel(modelId: OpenAIEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * Creates a model for image generation.
    */
-  image(modelId: OpenAIImageModelId): ImageModelV3;
+  image(modelId: OpenAIImageModelId): ImageModelV4;
 
   /**
    * Creates a model for image generation.
    */
-  imageModel(modelId: OpenAIImageModelId): ImageModelV3;
+  imageModel(modelId: OpenAIImageModelId): ImageModelV4;
 
   /**
    * Creates a model for transcription.
    */
-  transcription(modelId: OpenAITranscriptionModelId): TranscriptionModelV3;
+  transcription(modelId: OpenAITranscriptionModelId): TranscriptionModelV4;
 
   /**
    * Creates a model for speech generation.
    */
-  speech(modelId: OpenAISpeechModelId): SpeechModelV3;
+  speech(modelId: OpenAISpeechModelId): SpeechModelV4;
 
   /**
    * OpenAI-specific tools.
@@ -240,7 +240,7 @@ export function createOpenAI(
     return createLanguageModel(modelId);
   };
 
-  provider.specificationVersion = 'v3' as const;
+  provider.specificationVersion = 'v4' as const;
   provider.languageModel = createLanguageModel;
   provider.chat = createChatModel;
   provider.completion = createCompletionModel;

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';
@@ -24,7 +25,6 @@ export const openaiTools = {
    * Lark syntax). The model returns a `custom_tool_call` output item whose
    * `input` field is a string matching the specified grammar.
    *
-   * @param name - The name of the custom tool.
    * @param description - An optional description of the tool.
    * @param format - The output format constraint (grammar type, syntax, and definition).
    */
@@ -123,4 +123,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-openai-responses-usage.ts

@@ -1,4 +1,4 @@
-import { LanguageModelV3Usage } from '@ai-sdk/provider';
+import { LanguageModelV4Usage } from '@ai-sdk/provider';
 
 export type OpenAIResponsesUsage = {
   input_tokens: number;
@@ -13,7 +13,7 @@ export type OpenAIResponsesUsage = {
 
 export function convertOpenAIResponsesUsage(
   usage: OpenAIResponsesUsage | undefined | null,
-): LanguageModelV3Usage {
+): LanguageModelV4Usage {
   if (usage == null) {
     return {
       inputTokens: {

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

@@ -1,12 +1,13 @@
 import {
-  LanguageModelV3Prompt,
-  LanguageModelV3ToolApprovalResponsePart,
-  SharedV3Warning,
+  LanguageModelV4Prompt,
+  LanguageModelV4ToolApprovalResponsePart,
+  SharedV4Warning,
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
 import {
   convertToBase64,
   isNonNullable,
+  parseJSON,
   parseProviderOptions,
   ToolNameMapping,
   validateTypes,
@@ -22,11 +23,16 @@ import {
 } from '../tool/local-shell';
 import { shellInputSchema, shellOutputSchema } from '../tool/shell';
 import {
+  OpenAIResponsesCompactionItem,
   OpenAIResponsesCustomToolCallOutput,
   OpenAIResponsesFunctionCallOutput,
   OpenAIResponsesInput,
   OpenAIResponsesReasoning,
 } from './openai-responses-api';
+import {
+  toolSearchInputSchema,
+  toolSearchOutputSchema,
+} from '../tool/tool-search';
 
 /**
  * Check if a string is a file ID based on the given prefixes
@@ -50,7 +56,7 @@ export async function convertToOpenAIResponsesInput({
   hasApplyPatchTool = false,
   customProviderToolNames,
 }: {
-  prompt: LanguageModelV3Prompt;
+  prompt: LanguageModelV4Prompt;
   toolNameMapping: ToolNameMapping;
   systemMessageMode: 'system' | 'developer' | 'remove';
   providerOptionsName: string;
@@ -63,10 +69,10 @@ export async function convertToOpenAIResponsesInput({
   customProviderToolNames?: Set<string>;
 }): Promise<{
   input: OpenAIResponsesInput;
-  warnings: Array<SharedV3Warning>;
+  warnings: Array<SharedV4Warning>;
 }> {
-  const input: OpenAIResponsesInput = [];
-  const warnings: Array<SharedV3Warning> = [];
+  let input: OpenAIResponsesInput = [];
+  const warnings: Array<SharedV4Warning> = [];
   const processedApprovalIds = new Set<string>();
 
   for (const { role, content } of prompt) {
@@ -206,6 +212,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 +259,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 +365,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.
@@ -478,6 +544,36 @@ export async function convertToOpenAIResponsesInput({
               }
               break;
             }
+
+            case 'custom': {
+              if (part.kind === 'openai.compaction') {
+                const providerOpts =
+                  part.providerOptions?.[providerOptionsName];
+                const id = providerOpts?.itemId as string | undefined;
+
+                if (hasConversation && id != null) {
+                  break;
+                }
+
+                if (store && id != null) {
+                  input.push({ type: 'item_reference', id });
+                  break;
+                }
+
+                const encryptedContent = providerOpts?.encryptedContent as
+                  | string
+                  | undefined;
+
+                if (id != null) {
+                  input.push({
+                    type: 'compaction',
+                    id,
+                    encrypted_content: encryptedContent!,
+                  } satisfies OpenAIResponsesCompactionItem);
+                }
+              }
+              break;
+            }
           }
         }
 
@@ -488,7 +584,7 @@ export async function convertToOpenAIResponsesInput({
         for (const part of content) {
           if (part.type === 'tool-approval-response') {
             const approvalResponse =
-              part as LanguageModelV3ToolApprovalResponsePart;
+              part as LanguageModelV4ToolApprovalResponsePart;
 
             if (processedApprovalIds.has(approvalResponse.approvalId)) {
               continue;
@@ -527,6 +623,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' &&
@@ -628,6 +740,11 @@ export async function convertToOpenAIResponsesInput({
                           filename: item.filename ?? 'data',
                           file_data: `data:${item.mediaType};base64,${item.data}`,
                         };
+                      case 'file-url':
+                        return {
+                          type: 'input_file' as const,
+                          file_url: item.url,
+                        };
                       default:
                         warnings.push({
                           type: 'other',
@@ -692,6 +809,13 @@ export async function convertToOpenAIResponsesInput({
                       };
                     }
 
+                    case 'file-url': {
+                      return {
+                        type: 'input_file' as const,
+                        file_url: item.url,
+                      };
+                    }
+
                     default: {
                       warnings.push({
                         type: 'other',
@@ -722,6 +846,29 @@ export async function convertToOpenAIResponsesInput({
     }
   }
 
+  // when store is false, remove reasoning parts without encrypted content
+  if (
+    !store &&
+    input.some(
+      item =>
+        'type' in item &&
+        item.type === 'reasoning' &&
+        item.encrypted_content == null,
+    )
+  ) {
+    warnings.push({
+      type: 'other',
+      message:
+        'Reasoning parts without encrypted content are not supported when store is false. Skipping reasoning parts.',
+    });
+    input = input.filter(
+      item =>
+        !('type' in item) ||
+        item.type !== 'reasoning' ||
+        item.encrypted_content != null,
+    );
+  }
+
   return { input, warnings };
 }
 

package/src/responses/map-openai-responses-finish-reason.ts

@@ -1,4 +1,4 @@
-import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+import { LanguageModelV4FinishReason } from '@ai-sdk/provider';
 
 export function mapOpenAIResponseFinishReason({
   finishReason,
@@ -7,7 +7,7 @@ export function mapOpenAIResponseFinishReason({
   finishReason: string | null | undefined;
   // flag that checks if there have been client-side tool calls (not executed by openai)
   hasFunctionCall: boolean;
-}): LanguageModelV3FinishReason['unified'] {
+}): LanguageModelV4FinishReason['unified'] {
   switch (finishReason) {
     case undefined:
     case null: