@ai-sdk/openai

Major Changes

• breaking

  ai: Add support for uploading provider skills using the provider references abstraction

• breaking

  Remove CommonJS exports from all packages. All packages are now ESM-only ("type": "module"). Consumers using require() must switch to ESM import syntax.

• breaking

  provider: Add support for provider references and uploading files as supported per provider

• breaking

  provider: Add new top-level reasoning parameter to spec and support it in generateText and streamText

• breaking

  @ai-sdk/openai: remove redundant name argument from openai.tools.customTool()

  openai.tools.customTool() no longer accepts a name field. the tool name is now derived from the sdk tool key (the object key in the tools object).

  migration: remove the name property from customTool() calls. the object key is now used as the tool name sent to the openai api.

  before:

  tools: {
    write_sql: openai.tools.customTool({
      name: 'write_sql',
      description: '...',
    }),
  }

  after:

  tools: {
    write_sql: openai.tools.customTool({
      description: '...',
    }),
  }

@ai-sdk/provider-utils: createToolNameMapping() no longer accepts the resolveProviderToolName parameter

before: tool name can be set dynamically

```ts
const toolNameMapping = createToolNameMapping({
  tools,
  providerToolNames: {
    "openai.code_interpreter": "code_interpreter",
    "openai.file_search": "file_search",
    "openai.image_generation": "image_generation",
    "openai.local_shell": "local_shell",
    "openai.shell": "shell",
    "openai.web_search": "web_search",
    "openai.web_search_preview": "web_search_preview",
    "openai.mcp": "mcp",
    "openai.apply_patch": "apply_patch",
  },
  resolveProviderToolName: (tool) =>
    tool.id === "openai.custom"
      ? (tool.args as { name?: string }).name
      : undefined,
});
```

after: tool name is static based on `tools` keys

    const toolNameMapping = createToolNameMapping({  
      tools,  
      providerToolNames: {  
        'openai.code_interpreter': 'code_interpreter',  
        'openai.file_search': 'file_search',  
        'openai.image_generation': 'image_generation',  
        'openai.local_shell': 'local_shell',  
        'openai.shell': 'shell',  
        'openai.web_search': 'web_search',  
        'openai.web_search_preview': 'web_search_preview',  
        'openai.mcp': 'mcp',  
        'openai.apply_patch': 'apply_patch',  
      }  
    });

• Start v7 pre-release

Patch Changes

• Add allowedTools provider option for OpenAI Responses

• Add AI Gateway hint to provider READMEs

• provider/openai: Drop reasoning parts without encrypted content when store: false

• provider/openai: Add GPT-5.4 model support

• Add gpt-5.4-mini, gpt-5.4-mini-2026-03-17, gpt-5.4-nano, and gpt-5.4-nano-2026-03-17 models.

• Default OpenAI Responses reasoning summaries to detailed when reasoning effort is enabled.

• openai: Upgrade v3 specs to v4

• security: Prevent streaming tool calls from finalizing on parsable partial JSON

  Streaming tool call arguments were finalized using isParsableJson() as a heuristic for completion. If partial accumulated JSON happened to be valid JSON before all chunks arrived, the tool call would be executed with incomplete arguments. Tool call finalization now only occurs in flush() after the stream is fully consumed.

• provider/gateway: Add speech and transcription model support

• openai: Add GPT-5.5 chat model IDs

• feat(provider/azure):web search tool in the Azure OpenAI Responses API.

• openai: Support file-url parts in tool output content

• ai: Force template check on 'kind' param

• openai: Default undefined tool-call input to empty object before serializing tool arguments

• Trigger release for all packages after provenance setup

• More precise default message for tool execution denial

• openai: Add namespaces for tool definitions

• openai: Throw retryable errors for OpenAI stream failures before output starts

• openai: Add orchestration token usage details to Responses API usage

• openai: Preserve namespace on function_call output items

• openai: Forward web_search_call.action.queries from Responses API

• openai: round-trip namespace on function_call input items

  When tool_search dispatches a deferred tool, the resulting function_call carries a namespace field identifying which deferred-tool group the model picked. #14789 preserved this on the read side (providerMetadata.openai.namespace), but the write side still serialized function_call input items without namespace. Multi-step / multi-turn conversations then failed with Missing namespace for function_call '<name>'. ... Round-trip the model's function_call item with its namespace field included.

  convert-to-openai-responses-input.ts now reads namespace from providerOptions.openai.namespace (or providerMetadata.openai.namespace) on tool-call parts and includes it on the serialized function_call item, mirroring how itemId is round-tripped.

• provider/openai: Forward imageDetail providerOptions on tool-result image content

• openai: Add new tool search tool

• Revert incorrect fix #13172

• breaking

  Raise minimum supported Node.js version to 22. Supported versions: 22, 24, and 26.

• Extract shared StreamingToolCallTracker class into @ai-sdk/provider-utils to deduplicate streaming tool call handling across OpenAI-compatible providers. Also adds missing generateId() fallback for toolCallId in Alibaba's doGenerate path and ensures all providers finalize unfinished tool calls during stream flush.

• openai: Add server side compaction for openai

• Trigger initial canary release

• provider/openai: Add gpt-5.3-chat-latest

• provider: Preserve error type prefix in getErrorMessage

• openai, openai-compatible: Only send null content for assistant messages with tool calls

• openai: Preserve raw finish reason for failed responses stream events

  Handle response.failed chunks in Responses API streaming so finishReason.raw is preserved from incomplete_details.reason (e.g. max_output_tokens), and map failed-without-reason cases to unified error instead of other.

• provider: Add experimental Realtime API support for voice conversations

  Adds first-class support for realtime (speech-to-speech) APIs:

  • Experimental_RealtimeModelV4 spec in @ai-sdk/provider with normalized event types and factory

  • OpenAI, Google, and xAI realtime provider implementations

  • openai.experimental_realtime() / google.experimental_realtime() / xai.experimental_realtime() work in both server and browser

  • .getToken() static method on each provider for server-side ephemeral token creation

  • experimental_getRealtimeToolDefinitions helper for provider session tool definitions

  • experimental_useRealtime hook in @ai-sdk/react returning UIMessage (aligned with useChat), with onToolCall and addToolOutput for client-driven tool execution

  • inputAudioTranscription session config for showing transcribed user audio messages when supported by the provider

• ai: Allow passing provider instance to uploadFile and uploadSkill as shorthand

• provider: Change file part data property to be tagged with a type and remove the image part type

• openai: Add opt-in pass-through for unsupported file media types

• provider/openai: Send client-executed tool calls as full function_call items in the Responses API so they pair with their function_call_output by call_id

• provider: Align tool result output content file part types with top-level message file part types

• Trigger initial beta release

• Patch - send content: null instead of empty string for tool-only assistant messages

• openai: Skip passing reasoning items when using previous response id

• Add workflow serialization support to all provider models.

  @ai-sdk/provider-utils: New serializeModel() helper that extracts only serializable properties from a model instance, filtering out functions and objects containing functions. Third-party provider authors can use this to add workflow support to their own models.

  All providers: headers is now optional in provider config types. This is non-breaking — existing code that passes headers continues to work. Custom provider implementations that construct model configs manually can now omit headers, which is useful when models are deserialized from a workflow step boundary where auth is provided separately.

  All provider model classes now include WORKFLOW_SERIALIZE and WORKFLOW_DESERIALIZE static methods, enabling them to cross workflow step boundaries without serialization errors.

• Roll image-* tool output types into their equivalent file-* types

• provider/openai: Add gpt-image-2 model support