@ai-sdk/openai 4.0.59 → 4.0.61

package/docs/03-openai.mdx

@@ -192,9 +192,23 @@ The following provider options are available:
 
 <Note>
   Supported reasoning efforts vary by model. GPT-5.6 supports `'none'`, `'low'`,
-  `'medium'`, `'high'`, `'xhigh'`, and `'max'`.
+  `'medium'`, `'high'`, `'xhigh'`, and `'max'`. GPT-6 and later models support
+  `'low'`, `'medium'`, `'high'`, `'xhigh'`, and `'max'`.
 </Note>
 
+<Note type="warning">
+  GPT-6 and later models do not support `temperature`, `topP`, `logprobs`, or
+  the legacy `promptCacheRetention` option. The provider removes these settings
+  and returns a warning. Use the Responses API for GPT-6 tool calling.
+</Note>
+
+- **reasoningEffortUpdate** _'low' | 'medium' | 'high' | 'xhigh' | 'max'_
+  Updates the reasoning effort for GPT-6 and later models starting with the
+  current response without changing the request-level effort. Use this with
+  `previousResponseId` to preserve the original prompt prefix for caching.
+  Configuration updates require standard, single-agent mode and cannot be
+  combined with automatic compaction or automatic truncation.
+
 - **reasoningMode** _'standard' | 'pro'_
   Controls how much model work GPT-5.6 performs before returning a final answer. `'standard'` is the default. Use `'pro'` for difficult tasks where quality matters more than latency and token usage.
 
@@ -302,6 +316,57 @@ The following OpenAI-specific metadata may be returned:
 - **reasoningContext** _(optional)_
   Effective persisted-reasoning context returned by GPT-5.6 (`'current_turn'` or `'all_turns'`).
 
+#### Changing Reasoning Effort Mid-Conversation
+
+GPT-6 and later models can change reasoning effort between responses without
+changing the request-level `reasoning` setting. The provider sends
+`reasoningEffortUpdate` as an OpenAI `configuration_update` input item before
+the next user message. Keeping the request-level effort unchanged preserves the
+original prompt prefix for prompt caching.
+
+```ts highlight="8,26,32"
+import {
+  openai,
+  type OpenAILanguageModelResponsesOptions,
+  type OpenaiResponsesProviderMetadata,
+} from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+const first = await generateText({
+  model: openai.responses('gpt-6-astra'),
+  reasoning: 'low',
+  prompt: 'Draft a database migration plan.',
+});
+
+const metadata = first.finalStep.providerMetadata as
+  | OpenaiResponsesProviderMetadata
+  | undefined;
+const previousResponseId = metadata?.openai.responseId;
+
+if (!previousResponseId) {
+  throw new Error('OpenAI did not return a response ID.');
+}
+
+const second = await generateText({
+  model: openai.responses('gpt-6-astra'),
+  reasoning: 'low',
+  prompt: 'Analyze the failure modes and propose rollback steps.',
+  providerOptions: {
+    openai: {
+      previousResponseId,
+      reasoningEffortUpdate: 'high',
+    } satisfies OpenAILanguageModelResponsesOptions,
+  },
+});
+```
+
+The response metadata continues to report the request-level reasoning effort,
+not the effective effort selected by `reasoningEffortUpdate`. Configuration
+updates are not supported with `reasoningMode: 'pro'`,
+`contextManagement`, or `truncation: 'auto'`. Explicit compaction with
+`compactionTrigger` remains supported; send a new `reasoningEffortUpdate` after
+compaction when the effort should change again.
+
 #### Reasoning Output
 
 For reasoning models like `gpt-5`, you can enable reasoning summaries to see the model's thought process. Different models support different summarizers—for example, `o4-mini` supports detailed summaries. Set `reasoningSummary: "auto"` to automatically receive the richest level available. When `reasoningEffort` is set to a value other than `'none'`, the OpenAI Responses provider defaults `reasoningSummary` to `'detailed'`; set `reasoningSummary: null` to omit reasoning summaries.
@@ -463,6 +528,55 @@ metadata on tool-call parts. The SDK uses `providerMetadata.openai.namespace` or
 `providerOptions.openai.namespace` to round-trip the namespace back to OpenAI on
 subsequent requests.
 
+#### Async Tool Calling
+
+GPT-6 Astra and later Responses models support
+[async tool calling](https://developers.openai.com/api/docs/guides/async-tool-calling).
+An async tool lets the model continue generating independent output after issuing
+the call instead of waiting for its result. Your application still executes the
+tool and sends its result in a later request using the original tool call ID.
+
+Enable async calling on a function tool with `providerOptions.openai.async`:
+
+```ts
+import { openai, type OpenAIToolOptions } from '@ai-sdk/openai';
+import { generateText, tool } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: openai.responses('gpt-6-astra'),
+  tools: {
+    getWeather: tool({
+      description: 'Get the weather for a city.',
+      inputSchema: z.object({ city: z.string() }),
+      outputSchema: z.object({
+        city: z.string(),
+        temperatureC: z.number(),
+      }),
+      providerOptions: {
+        openai: { async: true } satisfies OpenAIToolOptions,
+      },
+    }),
+  },
+  prompt:
+    'Start the weather lookup for Paris, then list three general packing essentials without waiting.',
+});
+```
+
+The generated tool call exposes the provider marker as
+`providerMetadata.openai.async`. Use `providerMetadata.openai.responseId` as the
+next request's `previousResponseId`, and submit the result in a tool message with
+the original `toolCallId`.
+
+With `streamText`, OpenAI can continue streaming text after the completed
+`tool-call` part. Use the tool's `onInputAvailable` callback to start work as soon
+as that part arrives. If `execute` returns the same already-running promise, tool
+execution overlaps the rest of the model stream. Omit `execute` when the job
+should outlive the current generation and submit its result in a later request.
+
+Async calling applies to directly called function and custom tools. It does not
+apply to hosted tools and should not be combined with programmatic tool calling.
+
 #### Programmatic Tool Calling
 
 OpenAI Programmatic Tool Calling lets supported Responses models generate and run
@@ -1970,27 +2084,37 @@ import { openai } from '@ai-sdk/openai';
 import {
   experimental_getBatchResults as getBatchResults,
   experimental_getBatchStatus as getBatchStatus,
-  experimental_startTextBatch as startTextBatch,
+  experimental_startBatch as startBatch,
 } from 'ai';
 import { setTimeout } from 'node:timers/promises';
 
-const model = openai('gpt-4.1-nano');
+const model = 'gpt-4.1-nano';
 
-const batch = await startTextBatch({
-  model,
+const batch = await startBatch({
+  provider: openai,
   requests: [
-    { id: 'capital-france', prompt: 'What is the capital of France?' },
-    { id: 'capital-germany', prompt: 'What is the capital of Germany?' },
+    {
+      id: 'capital-france',
+      type: 'text',
+      model,
+      prompt: 'What is the capital of France?',
+    },
+    {
+      id: 'capital-germany',
+      type: 'text',
+      model,
+      prompt: 'What is the capital of Germany?',
+    },
   ],
 });
 
 let status = batch.status;
 while (status === 'pending') {
   await setTimeout(60_000);
-  ({ status } = await getBatchStatus({ model, batch }));
+  ({ status } = await getBatchStatus({ provider: openai, batch }));
 }
 
-for await (const item of getBatchResults({ model, batch })) {
+for await (const item of getBatchResults({ provider: openai, batch })) {
   if (item.status === 'succeeded') {
     console.log(item.id, item.text);
   } else {
@@ -1999,11 +2123,15 @@ for await (const item of getBatchResults({ model, batch })) {
 }
 ```
 
-`startTextBatch` returns a serializable batch reference. Persist this reference
+`startBatch` returns a serializable batch reference. Persist this reference
 to check the batch status or retrieve its results from another process. Results
 can arrive in a different order from the input requests, so match each result by
 its `id`.
 
+Each request specifies its `type` and `model`. OpenAI requires every text
+request in a batch to use the same model and throws before submission when the
+models differ.
+
 #### Webhooks
 
 <Note>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "4.0.59",
+  "version": "4.0.61",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,8 +35,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.10",
-    "@ai-sdk/provider-utils": "5.0.36"
+    "@ai-sdk/provider": "4.0.11",
+    "@ai-sdk/provider-utils": "5.0.37"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.1",

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

@@ -118,10 +118,25 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
     const modelCapabilities = getOpenAILanguageModelCapabilities(this.modelId);
 
     // AI SDK reasoning values map directly to the OpenAI reasoning values.
-    const resolvedReasoningEffort =
+    let resolvedReasoningEffort =
       openaiOptions.reasoningEffort ??
       (isCustomReasoning(reasoning) ? reasoning : undefined);
 
+    if (
+      resolvedReasoningEffort != null &&
+      modelCapabilities.supportedReasoningEfforts != null &&
+      !modelCapabilities.supportedReasoningEfforts.includes(
+        resolvedReasoningEffort,
+      )
+    ) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'reasoningEffort',
+        details: `${this.modelId} only supports the following reasoning efforts: ${modelCapabilities.supportedReasoningEfforts.join(', ')}`,
+      });
+      resolvedReasoningEffort = undefined;
+    }
+
     const isReasoningModel =
       openaiOptions.forceReasoning ?? modelCapabilities.isReasoningModel;
 
@@ -207,6 +222,19 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
       messages,
     };
 
+    if (
+      modelCapabilities.supportedReasoningEfforts != null &&
+      baseArgs.prompt_cache_retention != null
+    ) {
+      baseArgs.prompt_cache_retention = undefined;
+      warnings.push({
+        type: 'unsupported',
+        feature: 'promptCacheRetention',
+        details:
+          'promptCacheRetention is not supported by GPT-6 and later models; use promptCacheOptions instead',
+      });
+    }
+
     // remove unsupported settings for reasoning models
     // see https://platform.openai.com/docs/guides/reasoning#limitations
     if (isReasoningModel) {

package/src/index.ts

@@ -44,6 +44,7 @@ export type {
   OpenaiResponsesCompactionProviderMetadata,
   OpenaiResponsesProviderMetadata,
   OpenaiResponsesReasoningProviderMetadata,
+  OpenaiResponsesToolCallProviderMetadata,
   OpenaiResponsesTextProviderMetadata,
   OpenaiResponsesSourceDocumentProviderMetadata,
 } from './responses/openai-responses-provider-metadata';

package/src/{openai-responses-batch.ts → openai-batch.ts}

@@ -1,13 +1,15 @@
 import {
   InvalidArgumentError,
   InvalidResponseDataError,
-  type Experimental_BatchLanguageModelV4 as BatchLanguageModelV4,
-  type Experimental_BatchV4StartOptions as BatchV4StartOptions,
+  type Experimental_BatchV4 as BatchV4,
   type Experimental_BatchV4StartResult as BatchV4StartResult,
   type Experimental_BatchV4Error as BatchV4Error,
   type Experimental_BatchV4ItemResult as BatchV4ItemResult,
   type Experimental_BatchV4OperationOptions as BatchV4OperationOptions,
   type Experimental_BatchV4Status as BatchV4Status,
+  type Experimental_TextBatchV4ItemResult as TextBatchV4ItemResult,
+  type Experimental_BatchV4StartOptions as BatchV4StartOptions,
+  type Experimental_TextBatchV4Request as TextBatchV4Request,
   type LanguageModelV4GenerateResult,
   type SharedV4ProviderMetadata,
   type SharedV4Warning,
@@ -24,8 +26,6 @@ import {
   postJsonToApi,
   postToApi,
   safeValidateTypes,
-  WORKFLOW_DESERIALIZE,
-  WORKFLOW_SERIALIZE,
   zodSchema,
   type InferSchema,
 } from '@ai-sdk/provider-utils';
@@ -34,10 +34,7 @@ import {
   openaiErrorDataSchema,
   openaiFailedResponseHandler,
 } from './openai-error';
-import {
-  prepareOpenAIConfigForWorkflowDeserialize,
-  type OpenAIConfig,
-} from './openai-config';
+import type { OpenAIConfig } from './openai-config';
 import { openaiFilesResponseSchema } from './files/openai-files-api';
 import { convertOpenAIResponsesUsage } from './responses/convert-openai-responses-usage';
 import { mapOpenAIResponseFinishReason } from './responses/map-openai-responses-finish-reason';
@@ -48,6 +45,7 @@ import {
 import {
   mapWebSearchOutput,
   OpenAIResponsesLanguageModel,
+  openaiResponsesSupportedUrls,
 } from './responses/openai-responses-language-model';
 import type { OpenAIResponsesModelId } from './responses/openai-responses-language-model-options';
 import type { ResponsesReasoningProviderMetadata } from './responses/openai-responses-provider-metadata';
@@ -73,16 +71,18 @@ const openaiBatchProviderOptionsSchema = lazySchema(() =>
   ),
 );
 
-type OpenAIBatchRequest = Parameters<
-  BatchLanguageModelV4['experimental_doStartBatch']
->[0]['requests'][number];
+type OpenAIBatchModelIds = {
+  readonly text: OpenAIResponsesModelId;
+};
+
+type OpenAIBatchRequest = TextBatchV4Request<OpenAIResponsesModelId>;
 
 type OpenAIBatchPreparedRequest = {
   body: unknown;
   warnings: SharedV4Warning[];
 };
 
-type OpenAIBatchResponseConversion =
+type OpenAIBatchResultConversion =
   | { success: true; result: LanguageModelV4GenerateResult }
   | { success: false; error: BatchV4Error };
 
@@ -143,20 +143,25 @@ const openaiBatchResultLineSchema = lazySchema(() =>
 
 type OpenAIBatchResultLine = InferSchema<typeof openaiBatchResultLineSchema>;
 
-class OpenAIResponsesBatch {
+export class OpenAIBatch implements BatchV4<OpenAIBatchModelIds> {
+  readonly specificationVersion = 'v4' as const;
+  readonly provider: string;
+  readonly supportedUrls = openaiResponsesSupportedUrls;
+
   constructor(
     private readonly options: {
-      modelId: string;
+      provider: string;
       config: OpenAIConfig;
-      prepareRequest: (
-        request: OpenAIBatchRequest,
-      ) => PromiseLike<OpenAIBatchPreparedRequest>;
     },
-  ) {}
+  ) {
+    this.provider = options.provider;
+  }
 
-  async startBatch(
-    options: BatchV4StartOptions<OpenAIBatchRequest>,
+  async doStartBatch(
+    options: BatchV4StartOptions<OpenAIBatchModelIds>,
   ): Promise<BatchV4StartResult> {
+    validateSingleModel(options.requests);
+
     const fileParts: string[] = [];
     const warnings: BatchV4StartResult['warnings'] =
       options.webhookUrl == null
@@ -180,7 +185,7 @@ class OpenAIResponsesBatch {
       openaiBatchInputFileDefaultExpiresAfterSeconds;
 
     for (const request of options.requests) {
-      const preparedRequest = await this.options.prepareRequest(request);
+      const preparedRequest = await this.prepareRequest(request);
 
       fileParts.push(
         JSON.stringify({
@@ -285,7 +290,7 @@ class OpenAIResponsesBatch {
   }
 
   private async parseBatchProviderOptions(
-    providerOptions: BatchV4StartOptions<OpenAIBatchRequest>['providerOptions'],
+    providerOptions: BatchV4StartOptions<OpenAIBatchModelIds>['providerOptions'],
   ) {
     const providerOptionsName = this.options.config.provider.includes('azure')
       ? 'azure'
@@ -307,16 +312,16 @@ class OpenAIResponsesBatch {
     return batchOptions;
   }
 
-  async getBatchStatus(
+  async doGetBatchStatus(
     options: BatchV4OperationOptions,
   ): Promise<BatchV4Status> {
     const batch = await this.retrieveBatch(options);
     return convertOpenAIBatchStatus(batch);
   }
 
-  async getBatchResults(
+  async doGetBatchResults(
     options: BatchV4OperationOptions,
-  ): Promise<ReadableStream<BatchV4ItemResult<LanguageModelV4GenerateResult>>> {
+  ): Promise<ReadableStream<BatchV4ItemResult>> {
     const batch = await this.retrieveBatch(options);
 
     const batchStatus = convertOpenAIBatchStatus(batch);
@@ -368,7 +373,7 @@ class OpenAIResponsesBatch {
   }: {
     fileIds: string[];
     options: BatchV4OperationOptions;
-  }): AsyncGenerator<BatchV4ItemResult<LanguageModelV4GenerateResult>> {
+  }): AsyncGenerator<BatchV4ItemResult> {
     for (const fileId of fileIds) {
       const { value: lines } = await getFromApi({
         url: this.getUrl(`/files/${encodeURIComponent(fileId)}/content`),
@@ -393,7 +398,7 @@ class OpenAIResponsesBatch {
 
   private async convertResultLine(
     line: OpenAIBatchResultLine,
-  ): Promise<BatchV4ItemResult<LanguageModelV4GenerateResult>> {
+  ): Promise<TextBatchV4ItemResult> {
     if (line.error != null) {
       const error = {
         message: line.error.message,
@@ -401,18 +406,19 @@ class OpenAIResponsesBatch {
       };
 
       if (line.error.code === 'batch_cancelled') {
-        return { id: line.custom_id, status: 'cancelled', error };
+        return { type: 'text', id: line.custom_id, status: 'cancelled', error };
       }
 
       if (line.error.code === 'batch_expired') {
-        return { id: line.custom_id, status: 'expired', error };
+        return { type: 'text', id: line.custom_id, status: 'expired', error };
       }
 
-      return { id: line.custom_id, status: 'failed', error };
+      return { type: 'text', id: line.custom_id, status: 'failed', error };
     }
 
     if (line.response == null) {
       return {
+        type: 'text',
         id: line.custom_id,
         status: 'failed',
         error: {
@@ -425,6 +431,7 @@ class OpenAIResponsesBatch {
 
     if (line.response.status_code < 200 || line.response.status_code >= 300) {
       return {
+        type: 'text',
         id: line.custom_id,
         status: 'failed',
         error: await convertOpenAIErrorResponse({
@@ -434,11 +441,10 @@ class OpenAIResponsesBatch {
       };
     }
 
-    const conversion = await convertOpenAIResponsesBatchResponse(
-      line.response.body,
-    );
+    const conversion = await convertOpenAIBatchResult(line.response.body);
     if (!conversion.success) {
       return {
+        type: 'text',
         id: line.custom_id,
         status: 'failed',
         error: conversion.error,
@@ -446,17 +452,43 @@ class OpenAIResponsesBatch {
     }
 
     return {
+      type: 'text',
       id: line.custom_id,
       status: 'succeeded',
       result: conversion.result,
     };
   }
 
+  private async prepareRequest(
+    request: OpenAIBatchRequest,
+  ): Promise<OpenAIBatchPreparedRequest> {
+    const { args: body, warnings } =
+      await OpenAIResponsesLanguageModel.prepareRequest({
+        modelId: request.modelId,
+        config: this.options.config,
+        options: request.options,
+      });
+
+    return { body, warnings };
+  }
+
   private getUrl(path: string) {
-    return this.options.config.url({
-      modelId: this.options.modelId,
-      path,
-    });
+    return this.options.config.url({ path, modelId: '' });
+  }
+}
+
+function validateSingleModel(requests: ReadonlyArray<OpenAIBatchRequest>) {
+  const modelId = requests[0]?.modelId;
+
+  for (const request of requests) {
+    if (request.modelId !== modelId) {
+      throw new InvalidArgumentError({
+        argument: 'requests',
+        message:
+          'The OpenAI Batch API requires all requests in a batch to use the ' +
+          `same model. Found "${modelId}" and "${request.modelId}".`,
+      });
+    }
   }
 }
 
@@ -468,54 +500,6 @@ const openAIBatchConvertibleProviderToolIds = new Set([
   'openai.web_search_preview',
 ]);
 
-export class OpenAIResponsesBatchLanguageModel
-  extends OpenAIResponsesLanguageModel
-  implements BatchLanguageModelV4
-{
-  private readonly batch: OpenAIResponsesBatch;
-
-  static [WORKFLOW_SERIALIZE](model: OpenAIResponsesLanguageModel) {
-    return OpenAIResponsesLanguageModel[WORKFLOW_SERIALIZE](model);
-  }
-
-  static [WORKFLOW_DESERIALIZE](options: {
-    modelId: string;
-    config: Parameters<typeof prepareOpenAIConfigForWorkflowDeserialize>[0];
-  }) {
-    return new OpenAIResponsesBatchLanguageModel(
-      options.modelId as OpenAIResponsesModelId,
-      prepareOpenAIConfigForWorkflowDeserialize(options.config),
-    );
-  }
-
-  constructor(modelId: OpenAIResponsesModelId, config: OpenAIConfig) {
-    super(modelId, config);
-    this.batch = new OpenAIResponsesBatch({
-      modelId,
-      config,
-      prepareRequest: async request => {
-        const { args: body, warnings } = await this.getArgs(request.options);
-
-        return { body, warnings };
-      },
-    });
-  }
-
-  experimental_doStartBatch(
-    options: Parameters<BatchLanguageModelV4['experimental_doStartBatch']>[0],
-  ) {
-    return this.batch.startBatch(options);
-  }
-
-  experimental_doGetBatchStatus(options: BatchV4OperationOptions) {
-    return this.batch.getBatchStatus(options);
-  }
-
-  experimental_doGetBatchResults(options: BatchV4OperationOptions) {
-    return this.batch.getBatchResults(options);
-  }
-}
-
 function convertOpenAIBatchStatus(batch: OpenAIBatchResponse): BatchV4Status {
   const status = mapOpenAIBatchStatus(batch.status);
   const firstError = batch.errors?.data?.[0];
@@ -616,9 +600,9 @@ async function convertOpenAIErrorResponse({
   };
 }
 
-async function convertOpenAIResponsesBatchResponse(
+async function convertOpenAIBatchResult(
   body: unknown,
-): Promise<OpenAIBatchResponseConversion> {
+): Promise<OpenAIBatchResultConversion> {
   const validation = await safeValidateTypes({
     value: body,
     schema: openaiResponsesResponseSchema,

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

@@ -3,6 +3,9 @@ export type OpenAILanguageModelCapabilities = {
   systemMessageMode: 'remove' | 'system' | 'developer';
   supportsFlexProcessing: boolean;
   supportsPriorityProcessing: boolean;
+  supportsConfigurationUpdate: boolean;
+  supportsAsyncToolCalling: boolean;
+  supportedReasoningEfforts: readonly string[] | undefined;
 
   /**
    * Allow temperature, topP, logProbs when reasoningEffort is none.
@@ -19,6 +22,7 @@ export function getOpenAILanguageModelCapabilities(
     gptVersion?.minor == null &&
     (gptVersion?.variant?.startsWith('chat') ?? false);
   const isGptNanoModel = gptVersion?.variant?.startsWith('nano') ?? false;
+  const isGpt6OrLaterModel = gptVersion != null && gptVersion.major >= 6;
 
   const supportsFlexProcessing =
     (oSeriesVersion != null && oSeriesVersion >= 3) ||
@@ -41,6 +45,7 @@ export function getOpenAILanguageModelCapabilities(
   // https://platform.openai.com/docs/guides/latest-model#gpt-5-1-parameter-compatibility
   // GPT-5.1 and later model families support temperature, topP, logProbs when reasoningEffort is none.
   const supportsNonReasoningParameters =
+    !isGpt6OrLaterModel &&
     gptVersion != null &&
     (gptVersion.major > 5 ||
       (gptVersion.major === 5 && (gptVersion.minor ?? 0) >= 1));
@@ -50,6 +55,11 @@ export function getOpenAILanguageModelCapabilities(
   return {
     supportsFlexProcessing,
     supportsPriorityProcessing,
+    supportsConfigurationUpdate: isGpt6OrLaterModel,
+    supportsAsyncToolCalling: isGpt6OrLaterModel,
+    supportedReasoningEfforts: isGpt6OrLaterModel
+      ? ['low', 'medium', 'high', 'xhigh', 'max']
+      : undefined,
     isReasoningModel,
     systemMessageMode,
     supportsNonReasoningParameters,