@ai-sdk/openai 3.0.109 → 3.0.110

package/docs/03-openai.mdx

@@ -548,6 +548,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.
+
 #### Web Search Tool
 
 The OpenAI responses API supports web search through the `openai.tools.webSearch` tool.
@@ -736,6 +785,16 @@ for await (const part of result.fullStream) {
   setting `store: false`.
 </Note>
 
+To use `xhigh` or `max` quality, select `gpt-image-2.5-flare` or
+`gpt-image-2.5-sunburst` as the image generation tool's model:
+
+```ts
+openai.tools.imageGeneration({
+  model: 'gpt-image-2.5-flare',
+  quality: 'xhigh',
+});
+```
+
 For complete details on model availability, image quality controls, supported sizes, and tool-specific parameters,
 refer to the OpenAI documentation:
 
@@ -2665,6 +2724,19 @@ const { image, providerMetadata } = await generateImage({
 });
 ```
 
+The `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst` models also support
+`quality: 'xhigh'` and `quality: 'max'` for both image generation and editing:
+
+```ts
+const { image } = await generateImage({
+  model: openai.image('gpt-image-2.5-sunburst'),
+  prompt: 'A salamander at sunrise in a forest pond in the Seychelles.',
+  providerOptions: {
+    openai: { quality: 'max' } satisfies OpenAIImageModelGenerationOptions,
+  },
+});
+```
+
 For more on `generateImage()` see [Image Generation](/docs/ai-sdk-core/image-generation).
 
 OpenAI's image models return additional metadata in the response that can be
@@ -2678,7 +2750,7 @@ is available:
   - `revisedPrompt` _string_ - The revised prompt that was actually used to generate the image (OpenAI may modify your prompt for safety or clarity)
   - `created` _number_ - The Unix timestamp (in seconds) of when the image was created
   - `size` _string_ - The size of the generated image. One of `1024x1024`, `1024x1536`, or `1536x1024`
-  - `quality` _string_ - The quality of the generated image. One of `low`, `medium`, or `high`
+  - `quality` _string_ - The quality of the generated image. One of `low`, `medium`, `high`, `xhigh`, or `max`
   - `background` _string_ - The background parameter used for the image generation. Either `transparent` or `opaque`
   - `outputFormat` _string_ - The output format of the generated image. One of `png`, `webp`, or `jpeg`
 

package/package.json

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

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

@@ -45,10 +45,11 @@ const baseImageModelOptionsObject = z.object({
   /**
    * Quality of the generated image(s).
    *
-   * Valid values: `standard`, `hd`, `low`, `medium`, `high`, `auto`.
+   * Valid values: `standard`, `hd`, `low`, `medium`, `high`, `xhigh`, `max`, `auto`.
+   * `xhigh` and `max` are supported by GPT Image 2.5 models.
    */
   quality: z
-    .enum(['standard', 'hd', 'low', 'medium', 'high', 'auto'])
+    .enum(['standard', 'hd', 'low', 'medium', 'high', 'xhigh', 'max', 'auto'])
     .optional(),
 
   /**

package/src/index.ts

@@ -19,9 +19,11 @@ export type { OpenAILanguageModelCompletionOptions } from './completion/openai-c
 export type { OpenAIEmbeddingModelOptions } from './embedding/openai-embedding-options';
 export type { OpenAISpeechModelOptions } from './speech/openai-speech-options';
 export type { OpenAITranscriptionModelOptions } from './transcription/openai-transcription-options';
+export type { OpenAIToolOptions } from './responses/openai-responses-prepare-tools';
 export type {
   OpenaiResponsesProviderMetadata,
   OpenaiResponsesReasoningProviderMetadata,
+  OpenaiResponsesToolCallProviderMetadata,
   OpenaiResponsesTextProviderMetadata,
   OpenaiResponsesSourceDocumentProviderMetadata,
 } from './responses/openai-responses-provider-metadata';

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

@@ -4,6 +4,7 @@ export type OpenAILanguageModelCapabilities = {
   supportsFlexProcessing: boolean;
   supportsPriorityProcessing: boolean;
   supportsConfigurationUpdate: boolean;
+  supportsAsyncToolCalling: boolean;
   supportedReasoningEfforts: readonly string[] | undefined;
 
   /**
@@ -55,6 +56,7 @@ export function getOpenAILanguageModelCapabilities(
     supportsFlexProcessing,
     supportsPriorityProcessing,
     supportsConfigurationUpdate: isGpt6OrLaterModel,
+    supportsAsyncToolCalling: isGpt6OrLaterModel,
     supportedReasoningEfforts: isGpt6OrLaterModel
       ? ['low', 'medium', 'high', 'xhigh', 'max']
       : undefined,

package/src/openai-tools.ts

@@ -27,6 +27,7 @@ export const openaiTools = {
    *
    * @param name - The name of the custom tool.
    * @param description - An optional description of the tool.
+   * @param async - Whether the model can continue without waiting for the tool result.
    * @param format - The output format constraint (grammar type, syntax, and definition).
    */
   customTool,
@@ -65,7 +66,7 @@ export const openaiTools = {
    * @param outputCompression - Compression level for the output image (0-100).
    * @param outputFormat - The output format of the generated image. One of 'png', 'jpeg', or 'webp'.
    * @param partialImages - Number of partial images to generate in streaming mode (0-3).
-   * @param quality - The quality of the generated image. One of 'auto', 'low', 'medium', or 'high'.
+   * @param quality - The quality of the generated image. One of 'auto', 'low', 'medium', 'high', 'xhigh', or 'max'. 'xhigh' and 'max' require a GPT Image 2.5 model.
    * @param size - The size of the generated image. One of 'auto', '1024x1024', '1024x1536', or '1536x1024'.
    */
   imageGeneration,

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

@@ -589,6 +589,18 @@ export async function convertToOpenAIResponsesInput({
                 | string
                 | undefined;
 
+              const isAsync = (part.providerOptions?.[providerOptionsName]
+                ?.async ??
+                (
+                  part as {
+                    providerMetadata?: {
+                      [providerOptionsName]?: { async?: boolean };
+                    };
+                  }
+                ).providerMetadata?.[providerOptionsName]?.async) as
+                | boolean
+                | undefined;
+
               if (hasConversation && id != null) {
                 break;
               }
@@ -739,6 +751,7 @@ export async function convertToOpenAIResponsesInput({
                     typeof part.input === 'string'
                       ? part.input
                       : JSON.stringify(part.input),
+                  ...(isAsync != null && { async: isAsync }),
                   id,
                 });
                 break;
@@ -749,6 +762,7 @@ export async function convertToOpenAIResponsesInput({
                 call_id: part.toolCallId,
                 name: resolvedToolName,
                 arguments: serializeToolCallArguments(part.input),
+                ...(isAsync != null && { async: isAsync }),
                 ...(namespace != null && { namespace }),
               });
               break;

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

@@ -180,6 +180,7 @@ export type OpenAIResponsesFunctionCall = {
   call_id: string;
   name: string;
   arguments: string;
+  async?: boolean;
   id?: string;
   namespace?: string;
 };
@@ -220,6 +221,7 @@ export type OpenAIResponsesCustomToolCall = {
   call_id: string;
   name: string;
   input: string;
+  async?: boolean;
 };
 
 export type OpenAIResponsesCustomToolCallOutput = {
@@ -373,6 +375,7 @@ export type OpenAIResponsesFunctionTool = {
   name: string;
   description: string | undefined;
   parameters: JSONSchema7;
+  async?: boolean;
   strict?: boolean;
   defer_loading?: boolean;
 };
@@ -467,7 +470,7 @@ export type OpenAIResponsesTool =
       output_compression: number | undefined;
       output_format: 'png' | 'jpeg' | 'webp' | undefined;
       partial_images: number | undefined;
-      quality: 'auto' | 'low' | 'medium' | 'high' | undefined;
+      quality: 'auto' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | undefined;
       size: 'auto' | '1024x1024' | '1024x1536' | '1536x1024' | undefined;
     }
 
@@ -501,6 +504,7 @@ export type OpenAIResponsesTool =
       type: 'custom';
       name: string;
       description?: string;
+      async?: boolean;
       format?:
         | {
             type: 'grammar';
@@ -772,6 +776,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             call_id: z.string(),
             name: z.string(),
             arguments: z.string(),
+            async: z.boolean().nullish(),
             namespace: z.string().nullish(),
           }),
           z.object({
@@ -850,6 +855,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             call_id: z.string(),
             name: z.string(),
             input: z.string(),
+            async: z.boolean().nullish(),
           }),
           z.object({
             type: z.literal('shell_call'),
@@ -917,6 +923,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             call_id: z.string(),
             name: z.string(),
             arguments: z.string(),
+            async: z.boolean().nullish(),
             status: z.literal('completed'),
             namespace: z.string().nullish(),
           }),
@@ -926,6 +933,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             call_id: z.string(),
             name: z.string(),
             input: z.string(),
+            async: z.boolean().nullish(),
             status: z.literal('completed'),
           }),
           z.object({
@@ -1410,6 +1418,7 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
               name: z.string(),
               arguments: z.string(),
               id: z.string(),
+              async: z.boolean().nullish(),
               namespace: z.string().nullish(),
             }),
             z.object({
@@ -1418,6 +1427,7 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
               name: z.string(),
               input: z.string(),
               id: z.string(),
+              async: z.boolean().nullish(),
             }),
             z.object({
               type: z.literal('computer_call'),

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

@@ -80,6 +80,7 @@ import type {
   ResponsesReasoningProviderMetadata,
   ResponsesSourceDocumentProviderMetadata,
   ResponsesTextProviderMetadata,
+  ResponsesToolCallProviderMetadata,
 } from './openai-responses-provider-metadata';
 
 /**
@@ -242,6 +243,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
       allowedTools: openaiOptions?.allowedTools ?? undefined,
       toolNameMapping,
       customProviderToolNames,
+      supportsAsyncToolCalling: modelCapabilities.supportsAsyncToolCalling,
     });
 
     const { input, warnings: inputWarnings } =
@@ -910,8 +912,9 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
             providerMetadata: {
               [providerOptionsName]: {
                 itemId: part.id,
+                ...(part.async != null && { async: part.async }),
                 ...(part.namespace != null && { namespace: part.namespace }),
-              },
+              } satisfies ResponsesToolCallProviderMetadata,
             },
           });
           break;
@@ -929,7 +932,8 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
             providerMetadata: {
               [providerOptionsName]: {
                 itemId: part.id,
-              },
+                ...(part.async != null && { async: part.async }),
+              } satisfies ResponsesToolCallProviderMetadata,
             },
           });
           break;
@@ -1242,6 +1246,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
           toolSearchExecution?: 'server' | 'client';
           suppressInputStreaming?: boolean;
           bufferedInputDeltas?: string[];
+          async?: boolean | null;
         }
       | undefined
     > = {};
@@ -1321,6 +1326,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                   toolCallId: value.item.call_id,
                   suppressInputStreaming,
                   bufferedInputDeltas: suppressInputStreaming ? [] : undefined,
+                  async: value.item.async,
                 };
 
                 if (!suppressInputStreaming) {
@@ -1337,6 +1343,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                 ongoingToolCalls[value.output_index] = {
                   toolName,
                   toolCallId: value.item.call_id,
+                  async: value.item.async,
                 };
 
                 controller.enqueue({
@@ -1620,10 +1627,15 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                     providerMetadata: {
                       [providerOptionsName]: {
                         itemId: item.id,
+                        ...(item.async != null
+                          ? { async: item.async }
+                          : ongoingToolCall?.async != null
+                            ? { async: ongoingToolCall.async }
+                            : {}),
                         ...(item.namespace != null && {
                           namespace: item.namespace,
                         }),
-                      },
+                      } satisfies ResponsesToolCallProviderMetadata,
                     },
                   });
                 };
@@ -1667,6 +1679,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                   }
                 });
               } else if (value.item.type === 'custom_tool_call') {
+                const ongoingToolCall = ongoingToolCalls[value.output_index];
                 ongoingToolCalls[value.output_index] = undefined;
                 hasFunctionCall = true;
                 const toolName = toolNameMapping.toCustomToolName(
@@ -1686,7 +1699,12 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                   providerMetadata: {
                     [providerOptionsName]: {
                       itemId: value.item.id,
-                    },
+                      ...(value.item.async != null
+                        ? { async: value.item.async }
+                        : ongoingToolCall?.async != null
+                          ? { async: ongoingToolCall.async }
+                          : {}),
+                    } satisfies ResponsesToolCallProviderMetadata,
                   },
                 });
               } else if (value.item.type === 'web_search_call') {

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

@@ -24,7 +24,12 @@ type AllowedToolResolution =
   | { supported: true; entry: OpenAIResponsesAllowedTool }
   | { supported: false; reason: string };
 
-type OpenAIToolOptions = {
+export type OpenAIToolOptions = {
+  /**
+   * Whether the model can continue generating after calling this tool without
+   * waiting for its result.
+   */
+  async?: boolean;
   deferLoading?: boolean;
   namespace?: {
     name: string;
@@ -38,6 +43,7 @@ export async function prepareResponsesTools({
   allowedTools,
   toolNameMapping,
   customProviderToolNames,
+  supportsAsyncToolCalling = true,
 }: {
   tools: LanguageModelV3CallOptions['tools'];
   toolChoice: LanguageModelV3CallOptions['toolChoice'] | undefined;
@@ -47,6 +53,7 @@ export async function prepareResponsesTools({
   };
   toolNameMapping?: ToolNameMapping;
   customProviderToolNames?: Set<string>;
+  supportsAsyncToolCalling?: boolean;
 }): Promise<{
   tools?: Array<OpenAIResponsesTool>;
   toolChoice?:
@@ -124,6 +131,12 @@ export async function prepareResponsesTools({
         const openaiFunctionTool = prepareFunctionTool({
           tool,
           options: openaiOptions,
+          async: resolveAsyncToolOption({
+            value: openaiOptions?.async,
+            supportsAsyncToolCalling,
+            toolName: tool.name,
+            toolWarnings,
+          }),
         });
         const namespace = openaiOptions?.namespace;
 
@@ -355,6 +368,14 @@ export async function prepareResponsesTools({
               type: 'custom',
               name: args.name,
               description: args.description,
+              ...(resolveAsyncToolOption({
+                value: args.async,
+                supportsAsyncToolCalling,
+                toolName: args.name,
+                toolWarnings,
+              }) != null
+                ? { async: args.async }
+                : {}),
               format: args.format,
             });
             resolvedCustomProviderToolNames.add(args.name);
@@ -573,9 +594,11 @@ function toAllowedToolResolution(
 function prepareFunctionTool({
   tool,
   options,
+  async,
 }: {
   tool: LanguageModelV3FunctionTool;
   options: OpenAIToolOptions | undefined;
+  async: boolean | undefined;
 }): OpenAIResponsesFunctionTool {
   const deferLoading = options?.deferLoading;
 
@@ -584,11 +607,35 @@ function prepareFunctionTool({
     name: tool.name,
     description: tool.description,
     parameters: tool.inputSchema,
+    ...(async != null ? { async } : {}),
     ...(tool.strict != null ? { strict: tool.strict } : {}),
     ...(deferLoading != null ? { defer_loading: deferLoading } : {}),
   };
 }
 
+function resolveAsyncToolOption({
+  value,
+  supportsAsyncToolCalling,
+  toolName,
+  toolWarnings,
+}: {
+  value: boolean | undefined;
+  supportsAsyncToolCalling: boolean;
+  toolName: string;
+  toolWarnings: SharedV3Warning[];
+}): boolean | undefined {
+  if (value !== true || supportsAsyncToolCalling) {
+    return value;
+  }
+
+  toolWarnings.push({
+    type: 'unsupported',
+    feature: `async tool calling for "${toolName}"`,
+    details: 'Async tool calling is only supported by GPT-6 and later models.',
+  });
+  return undefined;
+}
+
 function mapShellEnvironment(environment: {
   type?: string;
   [key: string]: unknown;

package/src/responses/openai-responses-provider-metadata.ts

@@ -31,6 +31,16 @@ export type OpenaiResponsesProviderMetadata = {
   openai: ResponsesProviderMetadata;
 };
 
+export type ResponsesToolCallProviderMetadata = {
+  itemId: string;
+  async?: boolean;
+  namespace?: string;
+};
+
+export type OpenaiResponsesToolCallProviderMetadata = {
+  openai: ResponsesToolCallProviderMetadata;
+};
+
 export type ResponsesTextProviderMetadata = {
   itemId: string;
   phase?: 'commentary' | 'final_answer' | null;

package/src/tool/custom.ts

@@ -10,6 +10,7 @@ export const customArgsSchema = lazySchema(() =>
     z.object({
       name: z.string(),
       description: z.string().optional(),
+      async: z.boolean().optional(),
       format: z
         .union([
           z.object({
@@ -41,6 +42,12 @@ export const customToolFactory = createProviderToolFactory<
      */
     description?: string;
 
+    /**
+     * Whether the model can continue generating after calling this tool
+     * without waiting for its result.
+     */
+    async?: boolean;
+
     /**
      * The output format specification for the tool.
      * Omit for unconstrained text output.

package/src/tool/image-generation.ts

@@ -22,7 +22,9 @@ export const imageGenerationArgsSchema = lazySchema(() =>
         outputCompression: z.number().int().min(0).max(100).optional(),
         outputFormat: z.enum(['png', 'jpeg', 'webp']).optional(),
         partialImages: z.number().int().min(0).max(3).optional(),
-        quality: z.enum(['auto', 'low', 'medium', 'high']).optional(),
+        quality: z
+          .enum(['auto', 'low', 'medium', 'high', 'xhigh', 'max'])
+          .optional(),
         size: z
           .enum(['1024x1024', '1024x1536', '1536x1024', 'auto'])
           .optional(),
@@ -92,9 +94,10 @@ type ImageGenerationArgs = {
 
   /**
    * The quality of the generated image.
-   * One of low, medium, high, or auto. Default: auto.
+   * One of low, medium, high, xhigh, max, or auto. Default: auto.
+   * xhigh and max are supported by GPT Image 2.5 models.
    */
-  quality?: 'auto' | 'low' | 'medium' | 'high';
+  quality?: 'auto' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 
   /**
    * The size of the generated image.