@ai-sdk/openai 3.0.36 → 3.0.38

package/docs/03-openai.mdx

@@ -958,6 +958,84 @@ Your execute function must return:
 - **status** _'completed' | 'failed'_ - Whether the patch was applied successfully
 - **output** _string_ (optional) - Human-readable log text (e.g., results or error messages)
 
+#### Custom Tool
+
+The OpenAI Responses API supports
+[custom tools](https://developers.openai.com/api/docs/guides/function-calling/#custom-tools)
+through the `openai.tools.customTool` tool.
+Custom tools return a raw string instead of JSON, optionally constrained to a grammar
+(regex or Lark syntax). This makes them useful for generating structured text like
+SQL queries, code snippets, or any output that must match a specific pattern.
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { generateText, stepCountIs } from 'ai';
+
+const result = await generateText({
+  model: openai.responses('gpt-5.2-codex'),
+  tools: {
+    write_sql: openai.tools.customTool({
+      name: 'write_sql',
+      description: 'Write a SQL SELECT query to answer the user question.',
+      format: {
+        type: 'grammar',
+        syntax: 'regex',
+        definition: 'SELECT .+',
+      },
+      execute: async input => {
+        // input is a raw string matching the grammar, e.g. "SELECT * FROM users WHERE age > 25"
+        const rows = await db.query(input);
+        return JSON.stringify(rows);
+      },
+    }),
+  },
+  toolChoice: 'required',
+  prompt: 'Write a SQL query to get all users older than 25.',
+  stopWhen: stepCountIs(3),
+});
+```
+
+Custom tools also work with `streamText`:
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { streamText } from 'ai';
+
+const result = streamText({
+  model: openai.responses('gpt-5.2-codex'),
+  tools: {
+    write_sql: openai.tools.customTool({
+      name: 'write_sql',
+      description: 'Write a SQL SELECT query to answer the user question.',
+      format: {
+        type: 'grammar',
+        syntax: 'regex',
+        definition: 'SELECT .+',
+      },
+    }),
+  },
+  toolChoice: 'required',
+  prompt: 'Write a SQL query to get all users older than 25.',
+});
+
+for await (const chunk of result.fullStream) {
+  if (chunk.type === 'tool-call') {
+    console.log(`Tool: ${chunk.toolName}`);
+    console.log(`Input: ${chunk.input}`);
+  }
+}
+```
+
+The custom tool can be configured with:
+
+- **name** _string_ (required) - The name of the custom tool. Used to identify the tool in tool calls.
+- **description** _string_ (optional) - A description of what the tool does, to help the model understand when to use it.
+- **format** _object_ (optional) - The output format constraint. Omit for unconstrained text output.
+  - **type** _'grammar' | 'text'_ - The format type. Use `'grammar'` for constrained output or `'text'` for explicit unconstrained text.
+  - **syntax** _'regex' | 'lark'_ - (grammar only) The grammar syntax. Use `'regex'` for regular expression patterns or `'lark'` for [Lark parser grammar](https://lark-parser.readthedocs.io/).
+  - **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.
+
 #### Image Inputs
 
 The OpenAI Responses API supports Image inputs for appropriate models.
@@ -1429,7 +1507,7 @@ The following optional provider options are available for OpenAI chat models:
 
 OpenAI has introduced the `o1`,`o3`, and `o4` series of [reasoning models](https://platform.openai.com/docs/guides/reasoning).
 Currently, `o4-mini`, `o3`, `o3-mini`, and `o1` are available via both the chat and responses APIs. The
-models `codex-mini-latest` and `computer-use-preview` are available only via the [responses API](#responses-models).
+model `gpt-5.1-codex-mini` is available only via the [responses API](#responses-models).
 
 Reasoning models currently only generate text, have several limitations, and are only supported using `generateText` and `streamText`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.36",
+  "version": "3.0.38",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "3.0.8",
-    "@ai-sdk/provider-utils": "4.0.15"
+    "@ai-sdk/provider-utils": "4.0.16"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

package/src/chat/openai-chat-options.ts

@@ -32,15 +32,10 @@ export type OpenAIChatModelId =
   | 'gpt-4o-search-preview-2025-03-11'
   | 'gpt-4o-mini-search-preview'
   | 'gpt-4o-mini-search-preview-2025-03-11'
-  | 'gpt-4-turbo'
-  | 'gpt-4-turbo-2024-04-09'
-  | 'gpt-4'
-  | 'gpt-4-0613'
   | 'gpt-3.5-turbo-0125'
   | 'gpt-3.5-turbo'
   | 'gpt-3.5-turbo-1106'
   | 'gpt-3.5-turbo-16k'
-  | 'chatgpt-4o-latest'
   | 'gpt-5'
   | 'gpt-5-2025-08-07'
   | 'gpt-5-mini'

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

@@ -33,8 +33,6 @@ export function getOpenAILanguageModelCapabilities(
     modelId.startsWith('o1') ||
     modelId.startsWith('o3') ||
     modelId.startsWith('o4-mini') ||
-    modelId.startsWith('codex-mini') ||
-    modelId.startsWith('computer-use-preview') ||
     (modelId.startsWith('gpt-5') && !modelId.startsWith('gpt-5-chat'));
 
   // https://platform.openai.com/docs/guides/latest-model#gpt-5-1-parameter-compatibility

package/src/openai-tools.ts

@@ -1,5 +1,6 @@
 import { applyPatch } from './tool/apply-patch';
 import { codeInterpreter } from './tool/code-interpreter';
+import { customTool } from './tool/custom';
 import { fileSearch } from './tool/file-search';
 import { imageGeneration } from './tool/image-generation';
 import { localShell } from './tool/local-shell';
@@ -18,6 +19,17 @@ export const openaiTools = {
    */
   applyPatch,
 
+  /**
+   * Custom tools let callers constrain model output to a grammar (regex or
+   * 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).
+   */
+  customTool,
+
   /**
    * The Code Interpreter tool allows models to write and run Python code in a
    * sandboxed environment to solve complex problems in domains like data analysis,
@@ -61,7 +73,7 @@ export const openaiTools = {
    * Local shell is a tool that allows agents to run shell commands locally
    * on a machine you or the user provides.
    *
-   * Supported models: `gpt-5-codex` and `codex-mini-latest`
+   * Supported models: `gpt-5-codex`
    */
   localShell,
 

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

@@ -22,6 +22,7 @@ import {
 } from '../tool/local-shell';
 import { shellInputSchema, shellOutputSchema } from '../tool/shell';
 import {
+  OpenAIResponsesCustomToolCallOutput,
   OpenAIResponsesFunctionCallOutput,
   OpenAIResponsesInput,
   OpenAIResponsesReasoning,
@@ -47,6 +48,7 @@ export async function convertToOpenAIResponsesInput({
   hasLocalShellTool = false,
   hasShellTool = false,
   hasApplyPatchTool = false,
+  customProviderToolNames,
 }: {
   prompt: LanguageModelV3Prompt;
   toolNameMapping: ToolNameMapping;
@@ -58,6 +60,7 @@ export async function convertToOpenAIResponsesInput({
   hasLocalShellTool?: boolean;
   hasShellTool?: boolean;
   hasApplyPatchTool?: boolean;
+  customProviderToolNames?: Set<string>;
 }): Promise<{
   input: OpenAIResponsesInput;
   warnings: Array<SharedV3Warning>;
@@ -277,6 +280,20 @@ export async function convertToOpenAIResponsesInput({
                 break;
               }
 
+              if (customProviderToolNames?.has(resolvedToolName)) {
+                input.push({
+                  type: 'custom_tool_call',
+                  call_id: part.toolCallId,
+                  name: resolvedToolName,
+                  input:
+                    typeof part.input === 'string'
+                      ? part.input
+                      : JSON.stringify(part.input),
+                  id,
+                });
+                break;
+              }
+
               input.push({
                 type: 'function_call',
                 call_id: part.toolCallId,
@@ -575,6 +592,63 @@ export async function convertToOpenAIResponsesInput({
             continue;
           }
 
+          if (customProviderToolNames?.has(resolvedToolName)) {
+            let outputValue: OpenAIResponsesCustomToolCallOutput['output'];
+            switch (output.type) {
+              case 'text':
+              case 'error-text':
+                outputValue = output.value;
+                break;
+              case 'execution-denied':
+                outputValue = output.reason ?? 'Tool execution denied.';
+                break;
+              case 'json':
+              case 'error-json':
+                outputValue = JSON.stringify(output.value);
+                break;
+              case 'content':
+                outputValue = output.value
+                  .map(item => {
+                    switch (item.type) {
+                      case 'text':
+                        return { type: 'input_text' as const, text: item.text };
+                      case 'image-data':
+                        return {
+                          type: 'input_image' as const,
+                          image_url: `data:${item.mediaType};base64,${item.data}`,
+                        };
+                      case 'image-url':
+                        return {
+                          type: 'input_image' as const,
+                          image_url: item.url,
+                        };
+                      case 'file-data':
+                        return {
+                          type: 'input_file' as const,
+                          filename: item.filename ?? 'data',
+                          file_data: `data:${item.mediaType};base64,${item.data}`,
+                        };
+                      default:
+                        warnings.push({
+                          type: 'other',
+                          message: `unsupported custom tool content part type: ${item.type}`,
+                        });
+                        return undefined;
+                    }
+                  })
+                  .filter(isNonNullable);
+                break;
+              default:
+                outputValue = '';
+            }
+            input.push({
+              type: 'custom_tool_call_output',
+              call_id: part.toolCallId,
+              output: outputValue,
+            } satisfies OpenAIResponsesCustomToolCallOutput);
+            continue;
+          }
+
           let contentValue: OpenAIResponsesFunctionCallOutput['output'];
           switch (output.type) {
             case 'text':

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

@@ -10,6 +10,8 @@ export type OpenAIResponsesInputItem =
   | OpenAIResponsesAssistantMessage
   | OpenAIResponsesFunctionCall
   | OpenAIResponsesFunctionCallOutput
+  | OpenAIResponsesCustomToolCall
+  | OpenAIResponsesCustomToolCallOutput
   | OpenAIResponsesMcpApprovalResponse
   | OpenAIResponsesComputerCall
   | OpenAIResponsesLocalShellCall
@@ -94,6 +96,20 @@ export type OpenAIResponsesFunctionCallOutput = {
       >;
 };
 
+export type OpenAIResponsesCustomToolCall = {
+  type: 'custom_tool_call';
+  id?: string;
+  call_id: string;
+  name: string;
+  input: string;
+};
+
+export type OpenAIResponsesCustomToolCallOutput = {
+  type: 'custom_tool_call_output';
+  call_id: string;
+  output: OpenAIResponsesFunctionCallOutput['output'];
+};
+
 export type OpenAIResponsesMcpApprovalResponse = {
   type: 'mcp_approval_response';
   approval_request_id: string;
@@ -326,6 +342,20 @@ export type OpenAIResponsesTool =
       server_description: string | undefined;
       server_url: string | undefined;
     }
+  | {
+      type: 'custom';
+      name: string;
+      description?: string;
+      format?:
+        | {
+            type: 'grammar';
+            syntax: 'regex' | 'lark';
+            definition: string;
+          }
+        | {
+            type: 'text';
+          };
+    }
   | {
       type: 'local_shell';
     }
@@ -527,6 +557,13 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
               }),
             ]),
           }),
+          z.object({
+            type: z.literal('custom_tool_call'),
+            id: z.string(),
+            call_id: z.string(),
+            name: z.string(),
+            input: z.string(),
+          }),
           z.object({
             type: z.literal('shell_call'),
             id: z.string(),
@@ -579,6 +616,14 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             arguments: z.string(),
             status: z.literal('completed'),
           }),
+          z.object({
+            type: z.literal('custom_tool_call'),
+            id: z.string(),
+            call_id: z.string(),
+            name: z.string(),
+            input: z.string(),
+            status: z.literal('completed'),
+          }),
           z.object({
             type: z.literal('code_interpreter_call'),
             id: z.string(),
@@ -778,6 +823,12 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
         output_index: z.number(),
         delta: z.string(),
       }),
+      z.object({
+        type: z.literal('response.custom_tool_call_input.delta'),
+        item_id: z.string(),
+        output_index: z.number(),
+        delta: z.string(),
+      }),
       z.object({
         type: z.literal('response.image_generation_call.partial_image'),
         item_id: z.string(),
@@ -1059,6 +1110,13 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
               arguments: z.string(),
               id: z.string(),
             }),
+            z.object({
+              type: z.literal('custom_tool_call'),
+              call_id: z.string(),
+              name: z.string(),
+              input: z.string(),
+              id: z.string(),
+            }),
             z.object({
               type: z.literal('computer_call'),
               id: z.string(),

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

@@ -194,6 +194,22 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
         'openai.mcp': 'mcp',
         'openai.apply_patch': 'apply_patch',
       },
+      resolveProviderToolName: tool =>
+        tool.id === 'openai.custom'
+          ? (tool.args as { name?: string }).name
+          : undefined,
+    });
+
+    const customProviderToolNames = new Set<string>();
+    const {
+      tools: openaiTools,
+      toolChoice: openaiToolChoice,
+      toolWarnings,
+    } = await prepareResponsesTools({
+      tools,
+      toolChoice,
+      toolNameMapping,
+      customProviderToolNames,
     });
 
     const { input, warnings: inputWarnings } =
@@ -212,6 +228,10 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
         hasLocalShellTool: hasOpenAITool('openai.local_shell'),
         hasShellTool: hasOpenAITool('openai.shell'),
         hasApplyPatchTool: hasOpenAITool('openai.apply_patch'),
+        customProviderToolNames:
+          customProviderToolNames.size > 0
+            ? customProviderToolNames
+            : undefined,
       });
 
     warnings.push(...inputWarnings);
@@ -408,15 +428,6 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
       delete (baseArgs as any).service_tier;
     }
 
-    const {
-      tools: openaiTools,
-      toolChoice: openaiToolChoice,
-      toolWarnings,
-    } = await prepareResponsesTools({
-      tools,
-      toolChoice,
-    });
-
     const shellToolEnvType = (
       tools?.find(
         tool => tool.type === 'provider' && tool.id === 'openai.shell',
@@ -716,6 +727,24 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
           break;
         }
 
+        case 'custom_tool_call': {
+          hasFunctionCall = true;
+          const toolName = toolNameMapping.toCustomToolName(part.name);
+
+          content.push({
+            type: 'tool-call',
+            toolCallId: part.call_id,
+            toolName,
+            input: JSON.stringify(part.input),
+            providerMetadata: {
+              [providerOptionsName]: {
+                itemId: part.id,
+              },
+            },
+          });
+          break;
+        }
+
         case 'web_search_call': {
           content.push({
             type: 'tool-call',
@@ -1062,6 +1091,20 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                   id: value.item.call_id,
                   toolName: value.item.name,
                 });
+              } else if (value.item.type === 'custom_tool_call') {
+                const toolName = toolNameMapping.toCustomToolName(
+                  value.item.name,
+                );
+                ongoingToolCalls[value.output_index] = {
+                  toolName,
+                  toolCallId: value.item.call_id,
+                };
+
+                controller.enqueue({
+                  type: 'tool-input-start',
+                  id: value.item.call_id,
+                  toolName,
+                });
               } else if (value.item.type === 'web_search_call') {
                 ongoingToolCalls[value.output_index] = {
                   toolName: toolNameMapping.toCustomToolName(
@@ -1275,6 +1318,29 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                     },
                   },
                 });
+              } else if (value.item.type === 'custom_tool_call') {
+                ongoingToolCalls[value.output_index] = undefined;
+                hasFunctionCall = true;
+                const toolName = toolNameMapping.toCustomToolName(
+                  value.item.name,
+                );
+
+                controller.enqueue({
+                  type: 'tool-input-end',
+                  id: value.item.call_id,
+                });
+
+                controller.enqueue({
+                  type: 'tool-call',
+                  toolCallId: value.item.call_id,
+                  toolName,
+                  input: JSON.stringify(value.item.input),
+                  providerMetadata: {
+                    [providerOptionsName]: {
+                      itemId: value.item.id,
+                    },
+                  },
+                });
               } else if (value.item.type === 'web_search_call') {
                 ongoingToolCalls[value.output_index] = undefined;
 
@@ -1585,6 +1651,16 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
             } else if (isResponseFunctionCallArgumentsDeltaChunk(value)) {
               const toolCall = ongoingToolCalls[value.output_index];
 
+              if (toolCall != null) {
+                controller.enqueue({
+                  type: 'tool-input-delta',
+                  id: toolCall.toolCallId,
+                  delta: value.delta,
+                });
+              }
+            } else if (isResponseCustomToolCallInputDeltaChunk(value)) {
+              const toolCall = ongoingToolCalls[value.output_index];
+
               if (toolCall != null) {
                 controller.enqueue({
                   type: 'tool-input-delta',
@@ -1923,6 +1999,15 @@ function isResponseFunctionCallArgumentsDeltaChunk(
 } {
   return chunk.type === 'response.function_call_arguments.delta';
 }
+
+function isResponseCustomToolCallInputDeltaChunk(
+  chunk: OpenAIResponsesChunk,
+): chunk is OpenAIResponsesChunk & {
+  type: 'response.custom_tool_call_input.delta';
+} {
+  return chunk.type === 'response.custom_tool_call_input.delta';
+}
+
 function isResponseImageGenerationCallPartialImageChunk(
   chunk: OpenAIResponsesChunk,
 ): chunk is OpenAIResponsesChunk & {

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

@@ -15,16 +15,10 @@ export const openaiResponsesReasoningModelIds = [
   'o1-2024-12-17',
   'o3',
   'o3-2025-04-16',
-  'o3-deep-research',
-  'o3-deep-research-2025-06-26',
   'o3-mini',
   'o3-mini-2025-01-31',
   'o4-mini',
   'o4-mini-2025-04-16',
-  'o4-mini-deep-research',
-  'o4-mini-deep-research-2025-06-26',
-  'codex-mini-latest',
-  'computer-use-preview',
   'gpt-5',
   'gpt-5-2025-08-07',
   'gpt-5-codex',
@@ -58,7 +52,6 @@ export const openaiResponsesModelIds = [
   'gpt-4o-2024-08-06',
   'gpt-4o-2024-11-20',
   'gpt-4o-audio-preview',
-  'gpt-4o-audio-preview-2024-10-01',
   'gpt-4o-audio-preview-2024-12-17',
   'gpt-4o-search-preview',
   'gpt-4o-search-preview-2025-03-11',
@@ -66,38 +59,23 @@ export const openaiResponsesModelIds = [
   'gpt-4o-mini-search-preview-2025-03-11',
   'gpt-4o-mini',
   'gpt-4o-mini-2024-07-18',
-  'gpt-4-turbo',
-  'gpt-4-turbo-2024-04-09',
-  'gpt-4-turbo-preview',
-  'gpt-4-0125-preview',
-  'gpt-4-1106-preview',
-  'gpt-4',
-  'gpt-4-0613',
-  'gpt-4.5-preview',
-  'gpt-4.5-preview-2025-02-27',
   'gpt-3.5-turbo-0125',
   'gpt-3.5-turbo',
   'gpt-3.5-turbo-1106',
-  'chatgpt-4o-latest',
   'gpt-5-chat-latest',
   ...openaiResponsesReasoningModelIds,
 ] as const;
 
 export type OpenAIResponsesModelId =
-  | 'chatgpt-4o-latest'
   | 'gpt-3.5-turbo-0125'
   | 'gpt-3.5-turbo-1106'
   | 'gpt-3.5-turbo'
-  | 'gpt-4-0613'
-  | 'gpt-4-turbo-2024-04-09'
-  | 'gpt-4-turbo'
   | 'gpt-4.1-2025-04-14'
   | 'gpt-4.1-mini-2025-04-14'
   | 'gpt-4.1-mini'
   | 'gpt-4.1-nano-2025-04-14'
   | 'gpt-4.1-nano'
   | 'gpt-4.1'
-  | 'gpt-4'
   | 'gpt-4o-2024-05-13'
   | 'gpt-4o-2024-08-06'
   | 'gpt-4o-2024-11-20'