@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

Patch Changes

• openai: Preserve valid JSON string tool arguments and serialize BigInt and cycles in tool calls and results, retaining malformed argument replay fallbacks

• Forward languages and keywords transcription hints as repeated multipart fields instead of silently dropping them.

Patch Changes

• Defer validation schema construction until first use to reduce provider import time.

• openai: Support 12h prompt cache writes and cache prewarming

Patch Changes

• Restore raw OpenAI custom-tool input deltas for consumers that forward them to Responses API clients. Mark streamed input with inputEncoding: 'text' so UI clients can display it progressively without JSON parsing. Preserve the encoding when partial UI messages are saved and resumed. Final provider tool-call inputs remain JSON-encoded.

Patch Changes

• openai: Send assistant text with content instead of an item reference when its reasoning was removed

  With reasoning models, pruning reasoning (e.g. pruneMessages({ reasoning: 'all' })) caused follow-up requests to fail with "Item 'msg_...' of type 'message' was provided without its required 'reasoning' item". Assistant text parts are now only sent as item references, or with their item id, when they are preceded by reasoning in the same assistant message.

Patch Changes

• provider-utils: Preserve streamed tool calls with unreliable IDs and indices

Patch Changes

• openai: Expose Chat Completions audio transcripts as generated text

• openai: Preserve retryability for early stream errors

Patch Changes

• openai: Accept incomplete function_call and custom_tool_call items on the Responses stream, so a call truncated by max_output_tokens finishes with length instead of a TypeValidationError

• GPT-6 Sol and Luna model IDs

Patch Changes

• openai: Return an AI SDK error for empty chat completion choices

Patch Changes

• Prevent negative text output token counts when providers report reasoning tokens. Perplexity reasoning tokens are now treated as separate from completion tokens.

Patch Changes

• Keep client-executed function calls paired with their outputs when chaining OpenAI Responses with a previous response ID.

Patch Changes

• Accept serviceTier: 'fast' on OpenAI chat and responses models. OpenAI renamed priority processing to Fast mode and accepts service_tier: 'fast' and 'priority' interchangeably, so 'fast' is now passed through verbatim and gated on the same model capability as 'priority'.