@ai-sdk/openai 4.0.19 → 4.0.20

package/docs/03-openai.mdx

@@ -457,6 +457,68 @@ 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.
 
+#### Programmatic Tool Calling
+
+OpenAI Programmatic Tool Calling lets supported Responses models generate and run
+hosted JavaScript that coordinates client-side function tools. Add the hosted tool
+with `openai.tools.programmaticToolCalling()`, then opt each eligible function into
+programmatic calls with `allowedCallers`.
+
+```ts
+import { openai, type OpenAIToolOptions } from '@ai-sdk/openai';
+import { generateText, isStepCount, tool } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: openai('gpt-5.6'),
+  stopWhen: isStepCount(10),
+  prompt: 'Compare inventory with demand for sku_123.',
+  tools: {
+    program: openai.tools.programmaticToolCalling(),
+    getInventory: tool({
+      description: 'Get available inventory for a SKU.',
+      inputSchema: z.object({ sku: z.string() }),
+      execute: async ({ sku }) => ({ sku, availableUnits: 42 }),
+      providerOptions: {
+        openai: {
+          allowedCallers: ['programmatic'],
+          outputSchema: {
+            type: 'object',
+            properties: {
+              sku: { type: 'string' },
+              availableUnits: { type: 'number' },
+            },
+            required: ['sku', 'availableUnits'],
+            additionalProperties: false,
+          },
+        } satisfies OpenAIToolOptions,
+      },
+    }),
+  },
+});
+```
+
+`allowedCallers` supports:
+
+- `['direct']` (or omitted): only direct model tool calls
+- `['programmatic']`: only calls from hosted JavaScript
+- `['direct', 'programmatic']`: both invocation modes
+
+Use `outputSchema` to describe the JSON value returned by the function. This schema
+is sent to OpenAI as `output_schema` so generated JavaScript can safely use the
+returned fields. It does not replace the tool's AI SDK output validation or execution
+logic.
+
+The provider preserves program code, replay fingerprints, program outputs, and nested
+function caller metadata across the `generateText` and `streamText` tool loops,
+including stateless requests with `store: false`. Programmatic invocation is
+currently supported for AI SDK function tools; other OpenAI tool types remain
+direct-only through this integration.
+
+Treat generated programs and tool arguments as untrusted. Enforce authorization and
+approval inside every tool, avoid programmatic access to side-effecting tools unless
+the operation is idempotent, and set explicit step limits.
+
 #### Web Search Tool
 
 The OpenAI responses API supports web search through the `openai.tools.webSearch` tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "4.0.19",
+  "version": "4.0.20",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
   /** @deprecated Use `OpenAILanguageModelResponsesOptions` instead. */
   OpenAILanguageModelResponsesOptions as OpenAIResponsesProviderOptions,
 } from './responses/openai-responses-language-model-options';
+export type { OpenAIToolOptions } from './responses/openai-responses-prepare-tools';
 export type {
   OpenAILanguageModelChatOptions,
   /** @deprecated Use `OpenAILanguageModelChatOptions` instead. */

package/src/internal/index.ts

@@ -16,5 +16,6 @@ export * from '../tool/apply-patch';
 export * from '../tool/code-interpreter';
 export * from '../tool/file-search';
 export * from '../tool/image-generation';
+export * from '../tool/programmatic-tool-calling';
 export * from '../tool/web-search';
 export * from '../tool/web-search-preview';

package/src/openai-tools.ts

@@ -10,6 +10,7 @@ import { toolSearch } from './tool/tool-search';
 import { webSearch } from './tool/web-search';
 import { webSearchPreview } from './tool/web-search-preview';
 import { mcp } from './tool/mcp';
+import { programmaticToolCalling } from './tool/programmatic-tool-calling';
 
 export const openaiTools = {
   /**
@@ -135,6 +136,12 @@ export const openaiTools = {
    */
   mcp,
 
+  /**
+   * Programmatic Tool Calling lets OpenAI Responses models write and execute
+   * JavaScript that orchestrates eligible tools.
+   */
+  programmaticToolCalling,
+
   /**
    * 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

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

@@ -33,16 +33,34 @@ import type {
   OpenAIResponsesFunctionCallOutput,
   OpenAIResponsesInput,
   OpenAIResponsesReasoning,
+  OpenAIResponsesToolCaller,
 } from './openai-responses-api';
 import {
   toolSearchInputSchema,
   toolSearchOutputSchema,
 } from '../tool/tool-search';
+import {
+  programmaticToolCallingInputSchema,
+  programmaticToolCallingOutputSchema,
+} from '../tool/programmatic-tool-calling';
 
 function serializeToolCallArguments(input: unknown): string {
   return JSON.stringify(input === undefined ? {} : input);
 }
 
+function mapToolCaller(
+  caller:
+    | { type: 'direct' }
+    | { type: 'program'; callerId: string }
+    | undefined,
+): OpenAIResponsesToolCaller | undefined {
+  return caller == null
+    ? undefined
+    : caller.type === 'program'
+      ? { type: 'program', caller_id: caller.callerId }
+      : caller;
+}
+
 type OpenAIPromptCacheBreakpoint = { mode: 'explicit' };
 
 function getPromptCacheBreakpoint(
@@ -350,6 +368,11 @@ export async function convertToOpenAIResponsesInput({
                 ).providerMetadata?.[providerOptionsName]?.namespace) as
                 | string
                 | undefined;
+              const caller = part.providerOptions?.[providerOptionsName]
+                ?.caller as
+                | { type: 'direct' }
+                | { type: 'program'; callerId: string }
+                | undefined;
 
               if (hasConversation && id != null) {
                 break;
@@ -390,6 +413,27 @@ export async function convertToOpenAIResponsesInput({
                 break;
               }
 
+              if (resolvedToolName === 'programmatic_tool_calling') {
+                if (store && id != null) {
+                  input.push({ type: 'item_reference', id });
+                  break;
+                }
+
+                const parsedInput = await validateTypes({
+                  value: part.input,
+                  schema: programmaticToolCallingInputSchema,
+                });
+
+                input.push({
+                  type: 'program',
+                  id: id ?? part.toolCallId,
+                  call_id: part.toolCallId,
+                  code: parsedInput.code,
+                  fingerprint: parsedInput.fingerprint,
+                });
+                break;
+              }
+
               if (part.providerExecuted) {
                 if (store && id != null) {
                   input.push({ type: 'item_reference', id });
@@ -552,6 +596,9 @@ export async function convertToOpenAIResponsesInput({
                 name: resolvedToolName,
                 arguments: serializeToolCallArguments(part.input),
                 ...(namespace != null && { namespace }),
+                ...(caller != null && {
+                  caller: mapToolCaller(caller),
+                }),
               });
               break;
             }
@@ -613,6 +660,37 @@ export async function convertToOpenAIResponsesInput({
                 break;
               }
 
+              if (resolvedResultToolName === 'programmatic_tool_calling') {
+                const itemId = (part.providerOptions?.[providerOptionsName]
+                  ?.itemId ??
+                  (
+                    part as {
+                      providerMetadata?: {
+                        [providerOptionsName]?: { itemId?: string };
+                      };
+                    }
+                  ).providerMetadata?.[providerOptionsName]?.itemId ??
+                  part.toolCallId) as string;
+
+                if (store) {
+                  input.push({ type: 'item_reference', id: itemId });
+                } else if (part.output.type === 'json') {
+                  const parsedOutput = await validateTypes({
+                    value: part.output.value,
+                    schema: programmaticToolCallingOutputSchema,
+                  });
+
+                  input.push({
+                    type: 'program_output',
+                    id: itemId,
+                    call_id: part.toolCallId,
+                    result: parsedOutput.result,
+                    status: parsedOutput.status,
+                  });
+                }
+                break;
+              }
+
               /*
                * Shell tool results are separate output items (shell_call_output)
                * with their own item IDs distinct from the shell_call's item ID.
@@ -1163,10 +1241,18 @@ export async function convertToOpenAIResponsesInput({
               break;
           }
 
+          const caller = mapToolCaller(
+            part.providerOptions?.[providerOptionsName]?.caller as
+              | { type: 'direct' }
+              | { type: 'program'; callerId: string }
+              | undefined,
+          );
+
           input.push({
             type: 'function_call_output',
             call_id: part.toolCallId,
             output: contentValue,
+            ...(caller != null && { caller }),
           });
         }
 

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

@@ -84,6 +84,30 @@ const openaiResponsesComputerCallSchema = z.object({
     .nullish(),
 });
 
+const openaiResponsesToolCallerSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('direct') }),
+  z.object({
+    type: z.literal('program'),
+    caller_id: z.string(),
+  }),
+]);
+
+const openaiResponsesProgramSchema = z.object({
+  type: z.literal('program'),
+  id: z.string(),
+  call_id: z.string(),
+  code: z.string(),
+  fingerprint: z.string(),
+});
+
+const openaiResponsesProgramOutputSchema = z.object({
+  type: z.literal('program_output'),
+  id: z.string(),
+  call_id: z.string(),
+  result: z.string(),
+  status: z.enum(['completed', 'incomplete']),
+});
+
 export type OpenAIResponsesInput = Array<OpenAIResponsesInputItem>;
 
 export type OpenAIResponsesInputItem =
@@ -92,6 +116,8 @@ export type OpenAIResponsesInputItem =
   | OpenAIResponsesAssistantMessage
   | OpenAIResponsesFunctionCall
   | OpenAIResponsesFunctionCallOutput
+  | OpenAIResponsesProgram
+  | OpenAIResponsesProgramOutput
   | OpenAIResponsesCustomToolCall
   | OpenAIResponsesCustomToolCallOutput
   | OpenAIResponsesMcpApprovalResponse
@@ -201,6 +227,7 @@ export type OpenAIResponsesFunctionCall = {
   arguments: string;
   id?: string;
   namespace?: string;
+  caller?: OpenAIResponsesToolCaller;
 };
 
 export type OpenAIResponsesFunctionCallOutput = {
@@ -231,6 +258,27 @@ export type OpenAIResponsesFunctionCallOutput = {
             prompt_cache_breakpoint?: { mode: 'explicit' };
           }
       >;
+  caller?: OpenAIResponsesToolCaller;
+};
+
+export type OpenAIResponsesToolCaller =
+  | { type: 'direct' }
+  | { type: 'program'; caller_id: string };
+
+export type OpenAIResponsesProgram = {
+  type: 'program';
+  id: string;
+  call_id: string;
+  code: string;
+  fingerprint: string;
+};
+
+export type OpenAIResponsesProgramOutput = {
+  type: 'program_output';
+  id: string;
+  call_id: string;
+  result: string;
+  status: 'completed' | 'incomplete';
 };
 
 export type OpenAIResponsesCustomToolCall = {
@@ -428,6 +476,8 @@ export type OpenAIResponsesFunctionTool = {
   parameters: JSONSchema7;
   strict?: boolean;
   defer_loading?: boolean;
+  allowed_callers?: Array<'direct' | 'programmatic'>;
+  output_schema?: JSONSchema7;
 };
 
 export type OpenAIResponsesTool =
@@ -604,6 +654,9 @@ export type OpenAIResponsesTool =
       execution?: 'server' | 'client';
       description?: string;
       parameters?: Record<string, unknown>;
+    }
+  | {
+      type: 'programmatic_tool_calling';
     };
 
 export type OpenAIResponsesReasoning = {
@@ -761,7 +814,10 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             name: z.string(),
             arguments: z.string(),
             namespace: z.string().nullish(),
+            caller: openaiResponsesToolCallerSchema.nullish(),
           }),
+          openaiResponsesProgramSchema,
+          openaiResponsesProgramOutputSchema,
           z.object({
             type: z.literal('web_search_call'),
             id: z.string(),
@@ -905,9 +961,12 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             call_id: z.string(),
             name: z.string(),
             arguments: z.string(),
-            status: z.literal('completed'),
+            status: z.enum(['in_progress', 'completed', 'incomplete']),
             namespace: z.string().nullish(),
+            caller: openaiResponsesToolCallerSchema.nullish(),
           }),
+          openaiResponsesProgramSchema,
+          openaiResponsesProgramOutputSchema,
           z.object({
             type: z.literal('custom_tool_call'),
             id: z.string(),
@@ -1413,7 +1472,10 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
               arguments: z.string(),
               id: z.string(),
               namespace: z.string().nullish(),
+              caller: openaiResponsesToolCallerSchema.nullish(),
             }),
+            openaiResponsesProgramSchema,
+            openaiResponsesProgramOutputSchema,
             z.object({
               type: z.literal('custom_tool_call'),
               call_id: z.string(),

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

@@ -48,6 +48,10 @@ import type {
   toolSearchInputSchema,
   toolSearchOutputSchema,
 } from '../tool/tool-search';
+import type {
+  programmaticToolCallingInputSchema,
+  programmaticToolCallingOutputSchema,
+} from '../tool/programmatic-tool-calling';
 import type { webSearchOutputSchema } from '../tool/web-search';
 import {
   convertOpenAIResponsesUsage,
@@ -313,6 +317,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
         'openai.mcp': 'mcp',
         'openai.apply_patch': 'apply_patch',
         'openai.tool_search': 'tool_search',
+        'openai.programmatic_tool_calling': 'programmatic_tool_calling',
       },
     });
 
@@ -940,6 +945,56 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
               [providerOptionsName]: {
                 itemId: part.id,
                 ...(part.namespace != null && { namespace: part.namespace }),
+                ...(part.caller != null && {
+                  caller:
+                    part.caller.type === 'program'
+                      ? {
+                          type: 'program',
+                          callerId: part.caller.caller_id,
+                        }
+                      : part.caller,
+                }),
+              },
+            },
+          });
+          break;
+        }
+
+        case 'program': {
+          content.push({
+            type: 'tool-call',
+            toolCallId: part.call_id,
+            toolName: toolNameMapping.toCustomToolName(
+              'programmatic_tool_calling',
+            ),
+            input: JSON.stringify({
+              code: part.code,
+              fingerprint: part.fingerprint,
+            } satisfies InferSchema<typeof programmaticToolCallingInputSchema>),
+            providerExecuted: true,
+            providerMetadata: {
+              [providerOptionsName]: {
+                itemId: part.id,
+              },
+            },
+          });
+          break;
+        }
+
+        case 'program_output': {
+          content.push({
+            type: 'tool-result',
+            toolCallId: part.call_id,
+            toolName: toolNameMapping.toCustomToolName(
+              'programmatic_tool_calling',
+            ),
+            result: {
+              result: part.result,
+              status: part.status,
+            } satisfies InferSchema<typeof programmaticToolCallingOutputSchema>,
+            providerMetadata: {
+              [providerOptionsName]: {
+                itemId: part.id,
               },
             },
           });
@@ -1631,6 +1686,54 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
                       ...(value.item.namespace != null && {
                         namespace: value.item.namespace,
                       }),
+                      ...(value.item.caller != null && {
+                        caller:
+                          value.item.caller.type === 'program'
+                            ? {
+                                type: 'program',
+                                callerId: value.item.caller.caller_id,
+                              }
+                            : value.item.caller,
+                      }),
+                    },
+                  },
+                });
+              } else if (value.item.type === 'program') {
+                controller.enqueue({
+                  type: 'tool-call',
+                  toolCallId: value.item.call_id,
+                  toolName: toolNameMapping.toCustomToolName(
+                    'programmatic_tool_calling',
+                  ),
+                  input: JSON.stringify({
+                    code: value.item.code,
+                    fingerprint: value.item.fingerprint,
+                  } satisfies InferSchema<
+                    typeof programmaticToolCallingInputSchema
+                  >),
+                  providerExecuted: true,
+                  providerMetadata: {
+                    [providerOptionsName]: {
+                      itemId: value.item.id,
+                    },
+                  },
+                });
+              } else if (value.item.type === 'program_output') {
+                controller.enqueue({
+                  type: 'tool-result',
+                  toolCallId: value.item.call_id,
+                  toolName: toolNameMapping.toCustomToolName(
+                    'programmatic_tool_calling',
+                  ),
+                  result: {
+                    result: value.item.result,
+                    status: value.item.status,
+                  } satisfies InferSchema<
+                    typeof programmaticToolCallingOutputSchema
+                  >,
+                  providerMetadata: {
+                    [providerOptionsName]: {
+                      itemId: value.item.id,
                     },
                   },
                 });

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

@@ -1,5 +1,7 @@
 import {
   UnsupportedFunctionalityError,
+  type JSONSchema7,
+  type JSONObject,
   type LanguageModelV4CallOptions,
   type LanguageModelV4FunctionTool,
   type SharedV4ProviderReference,
@@ -24,8 +26,10 @@ import type {
   OpenAIResponsesTool,
 } from './openai-responses-api';
 
-type OpenAIToolOptions = {
+export type OpenAIToolOptions = {
+  allowedCallers?: Array<'direct' | 'programmatic'>;
   deferLoading?: boolean;
+  outputSchema?: JSONObject;
   namespace?: {
     name: string;
     description: string;
@@ -63,6 +67,7 @@ export async function prepareResponsesTools({
     | { type: 'image_generation' }
     | { type: 'apply_patch' }
     | { type: 'computer' }
+    | { type: 'programmatic_tool_calling' }
     | {
         type: 'allowed_tools';
         mode: 'auto' | 'required';
@@ -312,6 +317,12 @@ export async function prepareResponsesTools({
             resolvedCustomProviderToolNames.add(tool.name);
             break;
           }
+          case 'openai.programmatic_tool_calling': {
+            openaiTools.push({
+              type: 'programmatic_tool_calling',
+            });
+            break;
+          }
           case 'openai.tool_search': {
             const args = await validateTypes({
               value: tool.args,
@@ -382,7 +393,8 @@ export async function prepareResponsesTools({
           resolvedToolName === 'web_search' ||
           resolvedToolName === 'mcp' ||
           resolvedToolName === 'apply_patch' ||
-          resolvedToolName === 'computer'
+          resolvedToolName === 'computer' ||
+          resolvedToolName === 'programmatic_tool_calling'
             ? { type: resolvedToolName }
             : resolvedCustomProviderToolNames.has(resolvedToolName)
               ? { type: 'custom', name: resolvedToolName }
@@ -415,6 +427,12 @@ function prepareFunctionTool({
     parameters: tool.inputSchema,
     ...(tool.strict != null ? { strict: tool.strict } : {}),
     ...(deferLoading != null ? { defer_loading: deferLoading } : {}),
+    ...(options?.allowedCallers != null
+      ? { allowed_callers: options.allowedCallers }
+      : {}),
+    ...(options?.outputSchema != null
+      ? { output_schema: options.outputSchema as JSONSchema7 }
+      : {}),
   };
 }
 

package/src/tool/programmatic-tool-calling.ts

@@ -0,0 +1,57 @@
+import {
+  createProviderExecutedToolFactory,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const programmaticToolCallingInputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      code: z.string(),
+      fingerprint: z.string(),
+    }),
+  ),
+);
+
+export const programmaticToolCallingOutputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      result: z.string(),
+      status: z.enum(['completed', 'incomplete']),
+    }),
+  ),
+);
+
+const programmaticToolCallingFactory = createProviderExecutedToolFactory<
+  {
+    /**
+     * JavaScript source generated and executed by OpenAI.
+     */
+    code: string;
+
+    /**
+     * Opaque replay fingerprint that must be preserved across requests.
+     */
+    fingerprint: string;
+  },
+  {
+    /**
+     * The result emitted by the hosted JavaScript program.
+     */
+    result: string;
+
+    /**
+     * Whether the program completed or stopped before producing a final result.
+     */
+    status: 'completed' | 'incomplete';
+  },
+  {}
+>({
+  id: 'openai.programmatic_tool_calling',
+  inputSchema: programmaticToolCallingInputSchema,
+  outputSchema: programmaticToolCallingOutputSchema,
+  supportsDeferredResults: true,
+});
+
+export const programmaticToolCalling = () => programmaticToolCallingFactory({});