@ai-sdk/openai 3.0.35 → 3.0.37

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.35",
+  "version": "3.0.37",
   "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-language-model.ts

@@ -551,7 +551,10 @@ export class OpenAIChatLanguageModel implements LanguageModelV3 {
 
                 // Tool call start. OpenAI returns all information except the arguments in the first chunk.
                 if (toolCalls[index] == null) {
-                  if (toolCallDelta.type !== 'function') {
+                  if (
+                    toolCallDelta.type != null &&
+                    toolCallDelta.type !== 'function'
+                  ) {
                     throw new InvalidResponseDataError({
                       data: toolCallDelta,
                       message: `Expected 'function' type.`,

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,

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-prepare-tools.ts

@@ -3,10 +3,11 @@ import {
   SharedV3Warning,
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
-import { validateTypes } from '@ai-sdk/provider-utils';
+import { ToolNameMapping, validateTypes } from '@ai-sdk/provider-utils';
 import { codeInterpreterArgsSchema } from '../tool/code-interpreter';
 import { fileSearchArgsSchema } from '../tool/file-search';
 import { imageGenerationArgsSchema } from '../tool/image-generation';
+import { customArgsSchema } from '../tool/custom';
 import { mcpArgsSchema } from '../tool/mcp';
 import { shellArgsSchema } from '../tool/shell';
 import { webSearchArgsSchema } from '../tool/web-search';
@@ -16,9 +17,13 @@ import { OpenAIResponsesTool } from './openai-responses-api';
 export async function prepareResponsesTools({
   tools,
   toolChoice,
+  toolNameMapping,
+  customProviderToolNames,
 }: {
   tools: LanguageModelV3CallOptions['tools'];
   toolChoice: LanguageModelV3CallOptions['toolChoice'] | undefined;
+  toolNameMapping?: ToolNameMapping;
+  customProviderToolNames?: Set<string>;
 }): Promise<{
   tools?: Array<OpenAIResponsesTool>;
   toolChoice?:
@@ -29,6 +34,7 @@ export async function prepareResponsesTools({
     | { type: 'web_search_preview' }
     | { type: 'web_search' }
     | { type: 'function'; name: string }
+    | { type: 'custom'; name: string }
     | { type: 'code_interpreter' }
     | { type: 'mcp' }
     | { type: 'image_generation' }
@@ -45,6 +51,8 @@ export async function prepareResponsesTools({
   }
 
   const openaiTools: Array<OpenAIResponsesTool> = [];
+  const resolvedCustomProviderToolNames =
+    customProviderToolNames ?? new Set<string>();
 
   for (const tool of tools) {
     switch (tool.type) {
@@ -225,6 +233,21 @@ export async function prepareResponsesTools({
 
             break;
           }
+          case 'openai.custom': {
+            const args = await validateTypes({
+              value: tool.args,
+              schema: customArgsSchema,
+            });
+
+            openaiTools.push({
+              type: 'custom',
+              name: args.name,
+              description: args.description,
+              format: args.format,
+            });
+            resolvedCustomProviderToolNames.add(args.name);
+            break;
+          }
         }
         break;
       }
@@ -248,21 +271,28 @@ export async function prepareResponsesTools({
     case 'none':
     case 'required':
       return { tools: openaiTools, toolChoice: type, toolWarnings };
-    case 'tool':
+    case 'tool': {
+      const resolvedToolName =
+        toolNameMapping?.toProviderToolName(toolChoice.toolName) ??
+        toolChoice.toolName;
+
       return {
         tools: openaiTools,
         toolChoice:
-          toolChoice.toolName === 'code_interpreter' ||
-          toolChoice.toolName === 'file_search' ||
-          toolChoice.toolName === 'image_generation' ||
-          toolChoice.toolName === 'web_search_preview' ||
-          toolChoice.toolName === 'web_search' ||
-          toolChoice.toolName === 'mcp' ||
-          toolChoice.toolName === 'apply_patch'
-            ? { type: toolChoice.toolName }
-            : { type: 'function', name: toolChoice.toolName },
+          resolvedToolName === 'code_interpreter' ||
+          resolvedToolName === 'file_search' ||
+          resolvedToolName === 'image_generation' ||
+          resolvedToolName === 'web_search_preview' ||
+          resolvedToolName === 'web_search' ||
+          resolvedToolName === 'mcp' ||
+          resolvedToolName === 'apply_patch'
+            ? { type: resolvedToolName }
+            : resolvedCustomProviderToolNames.has(resolvedToolName)
+              ? { type: 'custom', name: resolvedToolName }
+              : { type: 'function', name: resolvedToolName },
         toolWarnings,
       };
+    }
     default: {
       const _exhaustiveCheck: never = type;
       throw new UnsupportedFunctionalityError({

package/src/tool/custom.ts

@@ -0,0 +1,64 @@
+import {
+  createProviderToolFactory,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const customArgsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      name: z.string(),
+      description: z.string().optional(),
+      format: z
+        .union([
+          z.object({
+            type: z.literal('grammar'),
+            syntax: z.enum(['regex', 'lark']),
+            definition: z.string(),
+          }),
+          z.object({
+            type: z.literal('text'),
+          }),
+        ])
+        .optional(),
+    }),
+  ),
+);
+
+const customInputSchema = lazySchema(() => zodSchema(z.string()));
+
+export const customToolFactory = createProviderToolFactory<
+  string,
+  {
+    /**
+     * The name of the custom tool, used to identify it in the API.
+     */
+    name: string;
+
+    /**
+     * An optional description of what the tool does.
+     */
+    description?: string;
+
+    /**
+     * The output format specification for the tool.
+     * Omit for unconstrained text output.
+     */
+    format?:
+      | {
+          type: 'grammar';
+          syntax: 'regex' | 'lark';
+          definition: string;
+        }
+      | {
+          type: 'text';
+        };
+  }
+>({
+  id: 'openai.custom',
+  inputSchema: customInputSchema,
+});
+
+export const customTool = (args: Parameters<typeof customToolFactory>[0]) =>
+  customToolFactory(args);