@ai-sdk/openai 3.0.68 → 3.0.69

package/docs/03-openai.mdx

@@ -434,6 +434,38 @@ The `textVerbosity` parameter scales output length without changing the underlyi
 - `'medium'`: Balanced detail (default)
 - `'high'`: Verbose responses with comprehensive detail
 
+#### Namespaced Function Calls
+
+OpenAI supports grouping related function tools into
+[namespaces](https://developers.openai.com/api/docs/guides/function-calling#defining-namespaces).
+When the Responses API returns a `function_call` with a `namespace`, the OpenAI provider
+exposes this value on the generated `tool-call` part as
+`providerMetadata.openai.namespace`.
+
+```ts
+for (const part of result.content) {
+  if (part.type === 'tool-call') {
+    console.log(part.providerMetadata?.openai?.namespace);
+  }
+}
+```
+
+When using `streamText`, the namespace is available on the `tool-input-end` event and on
+the final `tool-call` event:
+
+```ts
+for await (const part of result.stream) {
+  if (part.type === 'tool-input-end' || part.type === 'tool-call') {
+    console.log(part.providerMetadata?.openai?.namespace);
+  }
+}
+```
+
+If you persist or reconstruct messages for later turns, preserve the OpenAI provider
+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.
+
 #### Web Search Tool
 
 The OpenAI responses API supports web search through the `openai.tools.webSearch` tool.
@@ -1024,6 +1056,52 @@ In hosted mode, the model internally searches the deferred tools, loads the rele
 proceeds to call them — all within a single response. The `tool_search_call` and
 `tool_search_output` items appear in the response with `execution: 'server'` and `call_id: null`.
 
+##### Namespaces
+
+Use `providerOptions.openai.namespace` to group related function tools for OpenAI.
+The SDK keeps each tool executable as a normal AI SDK tool, but serializes grouped
+tools as OpenAI `namespace` entries in the request:
+
+```ts
+const crmNamespace = {
+  name: 'crm',
+  description: 'CRM tools for customer lookup and order management.',
+};
+
+const result = await generateText({
+  model: openai.responses('gpt-5.4'),
+  prompt: 'List open orders for customer cust_123.',
+  tools: {
+    toolSearch: openai.tools.toolSearch(),
+
+    get_customer_profile: tool({
+      description: 'Fetch a customer profile by customer ID.',
+      inputSchema: z.object({ customer_id: z.string() }),
+      execute: async ({ customer_id }) => ({ customer_id }),
+      providerOptions: {
+        openai: { namespace: crmNamespace },
+      },
+    }),
+
+    list_open_orders: tool({
+      description: 'List open orders for a customer ID.',
+      inputSchema: z.object({ customer_id: z.string() }),
+      execute: async ({ customer_id }) => ({ customer_id, orders: [] }),
+      providerOptions: {
+        openai: {
+          namespace: crmNamespace,
+          deferLoading: true,
+        },
+      },
+    }),
+  },
+});
+```
+
+Tools in the same namespace must use the same namespace `name` and `description`.
+For best results with tool search, keep namespace descriptions concise and put
+detailed usage guidance on the individual function tools.
+
 ##### Client-Executed Tool Search
 
 Use client-executed tool search when tool discovery depends on runtime state — for example,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.68",
+  "version": "3.0.69",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -44,8 +44,8 @@
     "tsup": "^8",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "1.0.5",
-    "@vercel/ai-tsconfig": "0.0.0"
+    "@vercel/ai-tsconfig": "0.0.0",
+    "@ai-sdk/test-server": "1.0.5"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

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

@@ -279,14 +279,22 @@ export type OpenAIResponsesFileSearchToolCompoundFilter = {
   >;
 };
 
+export type OpenAIResponsesFunctionTool = {
+  type: 'function';
+  name: string;
+  description: string | undefined;
+  parameters: JSONSchema7;
+  strict?: boolean;
+  defer_loading?: boolean;
+};
+
 export type OpenAIResponsesTool =
+  | OpenAIResponsesFunctionTool
   | {
-      type: 'function';
+      type: 'namespace';
       name: string;
-      description: string | undefined;
-      parameters: JSONSchema7;
-      strict?: boolean;
-      defer_loading?: boolean;
+      description: string;
+      tools: Array<OpenAIResponsesFunctionTool>;
     }
   | {
       type: 'apply_patch';

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

@@ -1,6 +1,7 @@
 import {
   UnsupportedFunctionalityError,
   type LanguageModelV3CallOptions,
+  type LanguageModelV3FunctionTool,
   type SharedV3Warning,
 } from '@ai-sdk/provider';
 import { validateTypes, type ToolNameMapping } from '@ai-sdk/provider-utils';
@@ -13,7 +14,18 @@ import { shellArgsSchema } from '../tool/shell';
 import { toolSearchArgsSchema } from '../tool/tool-search';
 import { webSearchArgsSchema } from '../tool/web-search';
 import { webSearchPreviewArgsSchema } from '../tool/web-search-preview';
-import type { OpenAIResponsesTool } from './openai-responses-api';
+import type {
+  OpenAIResponsesFunctionTool,
+  OpenAIResponsesTool,
+} from './openai-responses-api';
+
+type OpenAIToolOptions = {
+  deferLoading?: boolean;
+  namespace?: {
+    name: string;
+    description: string;
+  };
+};
 
 export async function prepareResponsesTools({
   tools,
@@ -62,6 +74,10 @@ export async function prepareResponsesTools({
   }
 
   const openaiTools: Array<OpenAIResponsesTool> = [];
+  const namespaceTools = new Map<
+    string,
+    Extract<OpenAIResponsesTool, { type: 'namespace' }>
+  >();
   const resolvedCustomProviderToolNames =
     customProviderToolNames ?? new Set<string>();
 
@@ -69,18 +85,36 @@ export async function prepareResponsesTools({
     switch (tool.type) {
       case 'function': {
         const openaiOptions = tool.providerOptions?.openai as
-          | { deferLoading?: boolean }
+          | OpenAIToolOptions
           | undefined;
-        const deferLoading = openaiOptions?.deferLoading;
-
-        openaiTools.push({
-          type: 'function',
-          name: tool.name,
-          description: tool.description,
-          parameters: tool.inputSchema,
-          ...(tool.strict != null ? { strict: tool.strict } : {}),
-          ...(deferLoading != null ? { defer_loading: deferLoading } : {}),
+        const openaiFunctionTool = prepareFunctionTool({
+          tool,
+          options: openaiOptions,
         });
+        const namespace = openaiOptions?.namespace;
+
+        if (namespace == null) {
+          openaiTools.push(openaiFunctionTool);
+        } else {
+          let namespaceTool = namespaceTools.get(namespace.name);
+
+          if (namespaceTool == null) {
+            namespaceTool = {
+              type: 'namespace',
+              name: namespace.name,
+              description: namespace.description,
+              tools: [],
+            };
+            namespaceTools.set(namespace.name, namespaceTool);
+            openaiTools.push(namespaceTool);
+          } else if (namespaceTool.description !== namespace.description) {
+            throw new UnsupportedFunctionalityError({
+              functionality: `conflicting descriptions for OpenAI tool namespace "${namespace.name}"`,
+            });
+          }
+
+          namespaceTool.tools.push(openaiFunctionTool);
+        }
         break;
       }
       case 'provider': {
@@ -352,6 +386,25 @@ export async function prepareResponsesTools({
   }
 }
 
+function prepareFunctionTool({
+  tool,
+  options,
+}: {
+  tool: LanguageModelV3FunctionTool;
+  options: OpenAIToolOptions | undefined;
+}): OpenAIResponsesFunctionTool {
+  const deferLoading = options?.deferLoading;
+
+  return {
+    type: 'function',
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.inputSchema,
+    ...(tool.strict != null ? { strict: tool.strict } : {}),
+    ...(deferLoading != null ? { defer_loading: deferLoading } : {}),
+  };
+}
+
 function mapShellEnvironment(environment: {
   type?: string;
   [key: string]: unknown;