@ai-sdk/open-responses 2.0.51 → 2.0.52

package/docs/06-open-responses.mdx

@@ -52,15 +52,31 @@ You can use the following optional settings to customize the Open Responses prov
 
   API key that is sent as a bearer token in the `Authorization` header.
 
-- **headers** _Record<string,string>_
+- **headers** _Record<string,string> | () => Record<string,string>_
 
-  Custom headers to include in the requests.
+  Custom headers to include in requests. Pass a function when headers must be
+  resolved lazily for each request.
 
 - **fetch** _(input: RequestInfo, init?: RequestInit) => Promise<Response>_
 
   Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
   Defaults to the global `fetch` function.
 
+- **failedResponseHandler** _ResponseHandler<APICallError>_
+
+  Custom handler for non-successful HTTP responses. Use this when an endpoint
+  returns an error envelope that differs from the default OpenAI-compatible
+  `{ error: { message, type, param, code } }` shape.
+
+- **getResponseErrorMetadata** _function_
+
+  Extracts optional `statusCode` and `isRetryable` metadata from a response error
+  object, including endpoint-specific fields. Applies to generation failures and
+  streaming `response.failed` and `error` events. The standard Open Responses
+  error fields are `code` and `message`; endpoint-specific status fields require
+  this callback. When only a status code is supplied, the SDK derives retryability
+  from it. HTTP failures are handled separately by `failedResponseHandler`.
+
 - **strictResponseInput** _boolean_
 
   Serializes assistant history using strict OpenAI Responses input schemas.
@@ -68,6 +84,21 @@ You can use the following optional settings to customize the Open Responses prov
   messages with a genuine provider item ID are sent as complete output items.
   Defaults to `false`.
 
+- **customToolId** _`${string}.${string}`_
+
+  Provider-tool ID used by `provider.tools.customTool`. Defaults to
+  `open-responses.custom`.
+
+- **structuredOutputs** _boolean_
+
+  Whether JSON response formats are sent to the endpoint. When `false`,
+  structured-output requests are omitted with an unsupported warning.
+  Defaults to `true`.
+
+- **userAgentSuffix** _string_
+
+  Overrides the default `ai-sdk/open-responses/<version>` user-agent suffix.
+
 ### Endpoint Examples
 
 For a local LM Studio server that does not require authentication:
@@ -199,6 +230,39 @@ combined with either reasoning effort setting. Reasoning support and accepted
 effort values depend on the endpoint and model; unsupported values may be
 rejected or ignored by the endpoint.
 
+## Custom Tools
+
+Endpoints with OpenAI-compatible custom-tool support can call tools with raw
+string inputs, optionally constrained by a regex or Lark grammar. These tools
+execute in your application:
+
+```ts
+import { generateText, isStepCount } from 'ai';
+
+const result = await generateText({
+  model: openResponses('your-model-id'),
+  prompt: 'Write a SQL query that lists active users.',
+  tools: {
+    write_sql: openResponses.tools.customTool({
+      description: 'Return a SQL SELECT query.',
+      format: {
+        type: 'grammar',
+        syntax: 'regex',
+        definition: 'SELECT .+',
+      },
+      execute: async sql => runReadOnlyQuery(sql),
+    }),
+  },
+  stopWhen: isStepCount(3),
+});
+```
+
+The endpoint must support the OpenAI-compatible `custom` tool,
+`custom_tool_call`, and `custom_tool_call_output` wire types, as OpenAI and
+QuiverAI do. These are compatibility extensions, not part of the Open Responses
+2026-04-24 specification. Custom-tool results can include text, images, and files
+when supported by the endpoint.
+
 ## File Inputs
 
 The provider supports image and non-image file inputs in user messages. Images

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/open-responses",
-  "version": "2.0.51",
+  "version": "2.0.52",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

package/src/index.ts

@@ -4,6 +4,7 @@ export type {
   OpenResponsesProvider,
   OpenResponsesProviderSettings,
 } from './open-responses-provider';
+export type { OpenResponsesCustomToolOptions } from './open-responses-tools';
 export type {
   OpenResponsesExtension as Experimental_OpenResponsesExtension,
   OpenResponsesExtensionContentPart as Experimental_OpenResponsesExtensionContentPart,

package/src/open-responses-provider.ts

@@ -1,4 +1,5 @@
 import {
+  type APICallError,
   NoSuchModelError,
   type LanguageModelV4,
   type ProviderV4,
@@ -7,16 +8,21 @@ import {
   generateId,
   withUserAgentSuffix,
   type FetchFunction,
+  type ResponseHandler,
 } from '@ai-sdk/provider-utils';
 import {
   createOpenResponsesExtensionRegistry,
   type OpenResponsesExtension,
 } from './open-responses-extension';
+import { createOpenResponsesTools } from './open-responses-tools';
 import { OpenResponsesLanguageModel } from './responses/open-responses-language-model';
 import { VERSION } from './version';
+import type { OpenResponsesConfig } from './responses/open-responses-config';
 
 export interface OpenResponsesProvider extends ProviderV4 {
   (modelId: string): LanguageModelV4;
+
+  tools: ReturnType<typeof createOpenResponsesTools>;
 }
 
 export interface OpenResponsesProviderSettings {
@@ -38,7 +44,7 @@ export interface OpenResponsesProviderSettings {
   /**
    * Custom headers to include in the requests.
    */
-  headers?: Record<string, string>;
+  headers?: Record<string, string> | (() => Record<string, string>);
 
   /**
    * Custom fetch implementation. You can use it as a middleware to intercept requests,
@@ -46,6 +52,17 @@ export interface OpenResponsesProviderSettings {
    */
   fetch?: FetchFunction;
 
+  /**
+   * Custom handler for non-successful HTTP responses.
+   */
+  failedResponseHandler?: ResponseHandler<APICallError>;
+
+  /**
+   * Extracts HTTP status and retryability metadata from endpoint-specific
+   * response errors. Applies to both generation and streaming errors.
+   */
+  getResponseErrorMetadata?: OpenResponsesConfig['getResponseErrorMetadata'];
+
   /**
    * Whether to serialize assistant history using the strict OpenAI Responses
    * input schemas. Assistant messages without an item ID are sent as easy input
@@ -55,6 +72,28 @@ export interface OpenResponsesProviderSettings {
    */
   strictResponseInput?: boolean;
 
+  /**
+   * Provider-tool ID used for caller-executed Open Responses custom tools.
+   *
+   * @default 'open-responses.custom'
+   */
+  customToolId?: `${string}.${string}`;
+
+  /**
+   * Whether JSON response formats are sent to the endpoint. When disabled,
+   * structured output requests produce an unsupported warning and are omitted.
+   *
+   * @default true
+   */
+  structuredOutputs?: boolean;
+
+  /**
+   * User-agent suffix for requests.
+   *
+   * @default `ai-sdk/open-responses/<version>`
+   */
+  userAgentSuffix?: string;
+
   /**
    * Codecs for Open Responses extension tools, items, and streaming events.
    *
@@ -67,6 +106,7 @@ export function createOpenResponses(
   options: OpenResponsesProviderSettings,
 ): OpenResponsesProvider {
   const providerName = options.name;
+  const customToolId = options.customToolId ?? 'open-responses.custom';
   const extensionRegistry = createOpenResponsesExtensionRegistry(
     options.experimental_extensions,
   );
@@ -79,9 +119,11 @@ export function createOpenResponses(
               Authorization: `Bearer ${options.apiKey}`,
             }
           : {}),
-        ...options.headers,
+        ...(typeof options.headers === 'function'
+          ? options.headers()
+          : options.headers),
       },
-      `ai-sdk/open-responses/${VERSION}`,
+      options.userAgentSuffix ?? `ai-sdk/open-responses/${VERSION}`,
     );
 
   const createResponsesModel = (modelId: string) => {
@@ -91,9 +133,13 @@ export function createOpenResponses(
       headers: getHeaders,
       url: options.url,
       fetch: options.fetch,
+      failedResponseHandler: options.failedResponseHandler,
+      getResponseErrorMetadata: options.getResponseErrorMetadata,
       generateId: () => generateId(),
       extensionRegistry,
       strictResponseInput: options.strictResponseInput,
+      customToolId,
+      structuredOutputs: options.structuredOutputs,
     });
   };
 
@@ -113,6 +159,7 @@ export function createOpenResponses(
 
   provider.specificationVersion = 'v4' as const;
   provider.languageModel = createLanguageModel;
+  provider.tools = createOpenResponsesTools({ customToolId });
 
   provider.embeddingModel = (modelId: string) => {
     throw new NoSuchModelError({ modelId, modelType: 'embeddingModel' });

package/src/open-responses-tools.ts

@@ -0,0 +1,52 @@
+import {
+  createProviderDefinedToolFactory,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export type OpenResponsesCustomToolOptions = {
+  /**
+   * An optional description of what the custom tool does.
+   */
+  description?: string;
+
+  /**
+   * The raw text format returned by the model.
+   */
+  format?:
+    | {
+        type: 'grammar';
+        syntax: 'regex' | 'lark';
+        definition: string;
+      }
+    | {
+        type: 'text';
+      };
+};
+
+const customInputSchema = lazySchema(() => zodSchema(z.string()));
+
+export function createOpenResponsesTools({
+  customToolId,
+}: {
+  customToolId: `${string}.${string}`;
+}) {
+  const customToolFactory = createProviderDefinedToolFactory<
+    string,
+    OpenResponsesCustomToolOptions
+  >({
+    id: customToolId,
+    inputSchema: customInputSchema,
+  });
+
+  return {
+    /**
+     * Creates a caller-executed OpenAI-compatible custom tool. Custom tools accept
+     * a raw string, optionally constrained by a grammar. Requires endpoint support.
+     */
+    customTool: (
+      options: Parameters<typeof customToolFactory>[0],
+    ): ReturnType<typeof customToolFactory> => customToolFactory(options),
+  };
+}

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

@@ -32,12 +32,14 @@ export async function convertToOpenResponsesInput({
   extensionRegistry,
   providerToolsByName = new Map(),
   strictResponseInput = false,
+  customToolId,
 }: {
   prompt: LanguageModelV4Prompt;
   providerOptionsName?: string;
   extensionRegistry?: OpenResponsesExtensionRegistry;
   providerToolsByName?: Map<string, LanguageModelV4ProviderTool>;
   strictResponseInput?: boolean;
+  customToolId?: `${string}.${string}`;
 }): Promise<{
   input: OpenResponsesRequestBody['input'];
   instructions: string | undefined;
@@ -312,13 +314,24 @@ export async function convertToOpenResponsesInput({
                   ? providerData.itemId
                   : undefined;
 
-              input.push({
-                type: 'function_call',
-                ...(itemId != null && { id: itemId }),
-                call_id: part.toolCallId,
-                name: part.toolName,
-                arguments: argumentsValue,
-              });
+              const providerTool = providerToolsByName.get(part.toolName);
+              if (customToolId != null && providerTool?.id === customToolId) {
+                input.push({
+                  type: 'custom_tool_call',
+                  ...(itemId != null && { id: itemId }),
+                  call_id: part.toolCallId,
+                  name: part.toolName,
+                  input: argumentsValue,
+                });
+              } else {
+                input.push({
+                  type: 'function_call',
+                  ...(itemId != null && { id: itemId }),
+                  call_id: part.toolCallId,
+                  name: part.toolName,
+                  arguments: argumentsValue,
+                });
+              }
               break;
             }
           }
@@ -460,7 +473,10 @@ export async function convertToOpenResponsesInput({
             }
 
             input.push({
-              type: 'function_call_output',
+              type:
+                customToolId != null && providerTool?.id === customToolId
+                  ? 'custom_tool_call_output'
+                  : 'function_call_output',
               call_id: part.toolCallId,
               output: contentValue,
             });

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

@@ -12,9 +12,9 @@ export const openResponsesErrorSchema = lazySchema(() =>
     z.object({
       error: z.object({
         message: z.string(),
-        type: z.string(),
-        param: z.string(),
-        code: z.string(),
+        type: z.string().nullish(),
+        param: z.string().nullish(),
+        code: z.string().nullish(),
       }),
     }),
   ),
@@ -231,6 +231,23 @@ export type FunctionCallOutputItemParam = {
   status?: FunctionCallStatus;
 };
 
+export type CustomToolCallItemParam = {
+  id?: string;
+  call_id: string;
+  type: 'custom_tool_call';
+  name: string;
+  input: string;
+  status?: FunctionCallStatus;
+};
+
+export type CustomToolCallOutputItemParam = {
+  id?: string;
+  call_id: string;
+  type: 'custom_tool_call_output';
+  output: FunctionCallOutputItemParam['output'];
+  status?: FunctionCallStatus;
+};
+
 // ============================================================================
 // Tool Types
 // ============================================================================
@@ -246,6 +263,19 @@ export type FunctionToolParam = {
   type: 'function';
 };
 
+export type CustomToolParam = {
+  name: string;
+  description?: string;
+  format?:
+    | { type: 'text' }
+    | {
+        type: 'grammar';
+        syntax: 'regex' | 'lark';
+        definition: string;
+      };
+  type: 'custom';
+};
+
 /**
  * A specific function tool choice.
  */
@@ -254,6 +284,11 @@ export type SpecificFunctionParam = {
   name: string;
 };
 
+export type SpecificCustomToolParam = {
+  type: 'custom';
+  name: string;
+};
+
 /**
  * Allowed tools parameter.
  */
@@ -269,6 +304,7 @@ export type AllowedToolsParam = {
 export type ToolChoiceParam =
   | ToolChoiceValueEnum
   | SpecificFunctionParam
+  | SpecificCustomToolParam
   | AllowedToolsParam
   | OpenResponsesExtensionRecord;
 
@@ -482,6 +518,23 @@ export type FunctionCallOutput = {
   status: FunctionCallStatus;
 };
 
+export type CustomToolCall = {
+  type: 'custom_tool_call';
+  id: string;
+  call_id: string;
+  name: string;
+  input: string;
+  status: FunctionCallStatus;
+};
+
+export type CustomToolCallOutput = {
+  type: 'custom_tool_call_output';
+  id: string;
+  call_id: string;
+  output: string;
+  status: FunctionCallStatus;
+};
+
 /**
  * A reasoning item that was generated by the model.
  */
@@ -499,6 +552,8 @@ export type ReasoningBody = {
 export type OutputItem =
   | FunctionCall
   | FunctionCallOutput
+  | CustomToolCall
+  | CustomToolCallOutput
   | Message
   | ReasoningBody
   | OpenResponsesExtensionItem;
@@ -516,6 +571,7 @@ export type IncompleteDetails = {
 export type ResponseError = {
   code: string;
   message: string;
+  [key: string]: unknown;
 };
 
 /**
@@ -588,6 +644,7 @@ export type TextField = {
  */
 export type InputTokensDetails = {
   cached_tokens: number;
+  cache_write_tokens?: number;
 };
 
 /**
@@ -644,6 +701,8 @@ export type OpenResponsesRequestBody = {
         | AssistantMessageItemParam
         | FunctionCallItemParam
         | FunctionCallOutputItemParam
+        | CustomToolCallItemParam
+        | CustomToolCallOutputItemParam
         | OpenResponsesExtensionRecord
       >;
 
@@ -662,7 +721,9 @@ export type OpenResponsesRequestBody = {
   /**
    * A list of tools that the model may call while generating the response.
    */
-  tools?: Array<FunctionToolParam | OpenResponsesExtensionRecord>;
+  tools?: Array<
+    FunctionToolParam | CustomToolParam | OpenResponsesExtensionRecord
+  >;
 
   /**
    * Controls which tool the model should use, if any.
@@ -1150,6 +1211,22 @@ export type ResponseFunctionCallArgumentsDoneEvent = {
   arguments: string;
 };
 
+export type ResponseCustomToolCallInputDeltaEvent = {
+  type: 'response.custom_tool_call_input.delta';
+  sequence_number: number;
+  item_id: string;
+  output_index: number;
+  delta: string;
+};
+
+export type ResponseCustomToolCallInputDoneEvent = {
+  type: 'response.custom_tool_call_input.done';
+  sequence_number: number;
+  item_id: string;
+  output_index: number;
+  input: string;
+};
+
 // ----------------------------------------------------------------------------
 // Delta Events - Reasoning
 // ----------------------------------------------------------------------------
@@ -1248,6 +1325,8 @@ export type OpenResponsesChunk =
   // Delta Events - Function Call Arguments
   | ResponseFunctionCallArgumentsDeltaEvent
   | ResponseFunctionCallArgumentsDoneEvent
+  | ResponseCustomToolCallInputDeltaEvent
+  | ResponseCustomToolCallInputDoneEvent
   // Delta Events - Reasoning
   | ResponseReasoningSummaryTextDeltaEvent
   | ResponseReasoningSummaryTextDoneEvent

package/src/responses/open-responses-config.ts

@@ -1,5 +1,7 @@
-import type { FetchFunction } from '@ai-sdk/provider-utils';
+import type { APICallError } from '@ai-sdk/provider';
+import type { FetchFunction, ResponseHandler } from '@ai-sdk/provider-utils';
 import type { OpenResponsesExtensionRegistry } from '../open-responses-extension';
+import type { ResponseError } from './open-responses-api';
 
 export type OpenResponsesConfig = {
   provider: string;
@@ -7,7 +9,14 @@ export type OpenResponsesConfig = {
   url: string;
   headers?: () => Record<string, string | undefined>;
   fetch?: FetchFunction;
+  failedResponseHandler?: ResponseHandler<APICallError>;
+  getResponseErrorMetadata?: (error: ResponseError) => {
+    statusCode?: number;
+    isRetryable?: boolean;
+  };
   generateId: () => string;
   extensionRegistry?: OpenResponsesExtensionRegistry;
   strictResponseInput?: boolean;
+  customToolId?: `${string}.${string}`;
+  structuredOutputs?: boolean;
 };