OpenAI

The OpenAI provider contains language model support for the OpenAI responses, chat, and completion APIs, as well as embedding model support for the OpenAI embeddings API.

Setup

The OpenAI provider is available in the @ai-sdk/openai module. You can install it with

$ pnpm add @ai-sdk/openai

$ npm install @ai-sdk/openai

$ yarn add @ai-sdk/openai

$ bun add @ai-sdk/openai

Provider Instance

You can import the default provider instance openai from @ai-sdk/openai:

import { openai } from '@ai-sdk/openai';

If you need a customized setup, you can import createOpenAI from @ai-sdk/openai and create a provider instance with your settings:

import { createOpenAI } from '@ai-sdk/openai';

const openai = createOpenAI({
  // custom settings, e.g.
  headers: {
    'header-name': 'header-value',
  },
});

You can use the following optional settings to customize the OpenAI provider instance:

• batchResultDownloads object

  Settings for downloading JSON Lines batch results.

  • maxLineBytes number

    Maximum UTF-8 bytes per row, excluding the LF delimiter. Defaults to 64 MiB (67,108,864 bytes). Must be a positive safe integer. Oversized rows throw a DownloadError and cancel the download.

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers. It defaults to the OPENAI_BASE_URL environment variable, and then to https://api.openai.com/v1. The default OpenAI model factory (openai('model-id')) uses the Responses API. If your custom base URL only supports the Chat Completions API, create chat models with openai.chat('model-id') instead, or use the OpenAI-compatible provider.

• apiKey string

  API key that is being sent using the Authorization header. It defaults to the OPENAI_API_KEY environment variable.

• name string

  The provider name. You can set this when using OpenAI compatible providers to change the model provider property. Defaults to openai.

• organization string

  OpenAI Organization.

• project string

  OpenAI project.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. Defaults to the global fetch function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

Language Models

The OpenAI provider instance is a function that you can invoke to create a language model:

const model = openai('gpt-6-astra');

It automatically selects the correct API based on the model id. You can also pass additional settings in the second argument:

const model = openai('gpt-6-astra', {
  // additional settings
});

The available options depend on the API that's automatically chosen for the model (see below). If you want to explicitly select a specific model API, you can use .responses, .chat, or .completion.

Example

You can use OpenAI language models to generate text with the generateText function:

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: openai('gpt-6-astra'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

OpenAI language models can also be used in the streamText function and support structured data generation with Output (see AI SDK Core).

Responses Models

You can use the OpenAI responses API with the openai(modelId) or openai.responses(modelId) factory methods. It is the default API that is used by the OpenAI provider (since AI SDK 5).

const model = openai('gpt-6-astra');

Further configuration can be done using OpenAI provider options. You can validate the provider options using the OpenAILanguageModelResponsesOptions type.

import { openai, OpenAILanguageModelResponsesOptions } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-astra'), // or openai.responses('gpt-6-astra')
  providerOptions: {
    openai: {
      parallelToolCalls: false,
      store: false,
      user: 'user_123',
      // ...
    } satisfies OpenAILanguageModelResponsesOptions,
  },
  // ...
});

The following provider options are available:

• parallelToolCalls boolean Whether to use parallel tool calls. Defaults to true.

• store boolean

  Whether to store the generation. Defaults to true.

• passThroughUnsupportedFiles boolean

  Whether to pass through non-image file types as generic input files. Defaults to false, which restricts inline file inputs to images and PDFs. Enable this when the target OpenAI Responses model supports additional file media types.

• maxToolCalls integer The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored.

• metadata Record<string, string> Additional metadata to store with the generation.

• conversation string The ID of the OpenAI Conversation to continue. You must create a conversation first via the OpenAI API. Cannot be used in conjunction with previousResponseId. Defaults to undefined.

• previousResponseId string The ID of the previous response. You can use it to continue a conversation. Defaults to undefined.

• instructions string Instructions for the model. They can be used to change the system or developer message when continuing a conversation using the previousResponseId option. Defaults to undefined.

• logprobs boolean | number Return the log probabilities of the tokens. Including logprobs will increase the response size and can slow down response times. However, it can be useful to better understand how the model is behaving. Setting to true returns the log probabilities of the tokens that were generated. Setting to a number (1-20) returns the log probabilities of the top n tokens that were generated.

• user string A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Defaults to undefined.

• reasoningEffort 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' Reasoning effort for reasoning models. Defaults to medium. If you use providerOptions to set the reasoningEffort option, this model setting will be ignored.

• reasoningEffortUpdate 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' Updates the reasoning effort for GPT-6 and later models starting with the current response without changing the request-level effort. Use this with previousResponseId to preserve the original prompt prefix for caching. Configuration updates require standard, single-agent mode and cannot be combined with automatic compaction or automatic truncation.

  The SDK checks effort values against the selected model for both request-level and message-level updates. For example, GPT-6 Sol and Luna support none, while GPT-6 Astra does not.

• reasoningMode 'standard' | 'pro' Controls how much model work GPT-5.6 performs before returning a final answer. 'standard' is the default. Use 'pro' for difficult tasks where quality matters more than latency and token usage.

• reasoningContext 'auto' | 'current_turn' | 'all_turns' Controls which available reasoning items GPT-5.6 can reuse. 'auto' uses the model default, 'current_turn' excludes reasoning from earlier turns, and 'all_turns' makes compatible earlier reasoning available. The effective context is returned as providerMetadata.openai.reasoningContext.

• reasoningSummary 'auto' | 'detailed' | null Controls whether the model returns its reasoning process. Set to 'auto' for a condensed summary, 'detailed' for more comprehensive reasoning, or null to omit reasoning summaries. Defaults to 'detailed' when reasoningEffort is set to a value other than 'none', and to no reasoning summaries otherwise. When enabled, reasoning summaries appear in the stream as events with type 'reasoning' and in non-streaming responses within the reasoning field.

• strictJsonSchema boolean Whether to use strict JSON schema validation. Defaults to true.

• serviceTier 'auto' | 'flex' | 'priority' | 'fast' | 'ultrafast' | 'default' Service tier for the request. Set to 'flex' for 50% cheaper processing at the cost of increased latency (available for o3, o4-mini, and gpt-5 models). Set to 'priority' for faster processing with Enterprise access (available for gpt-4, gpt-5, gpt-5-mini, o3, o4-mini; gpt-5-nano is not supported). 'fast' is OpenAI's newer name for the 'priority' tier; the two are interchangeable, and responses from gpt-5.6 and earlier report serviceTier: 'priority' for either. Set to 'ultrafast' for access-controlled Ultrafast processing (available only for gpt-5.6-sol).

  Defaults to 'auto'.

• textVerbosity 'low' | 'medium' | 'high' Controls the verbosity of the model's response. Lower values result in more concise responses, while higher values result in more verbose responses. Defaults to 'medium'.

• include Array<string> Specifies additional content to include in the response. Supported values: ['file_search_call.results'] for including file search results in responses. ['message.output_text.logprobs'] for logprobs. Defaults to undefined.

• truncation string The truncation strategy to use for the model response.

  • Auto: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation.
  • disabled (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.

• promptCacheKey string A cache key for manual prompt caching control. Used by OpenAI to cache responses for similar requests to optimize your cache hit rates.

• promptCacheOptions object Configures prompt caching for GPT-5.6 and later models. mode can be 'implicit' or 'explicit', and ttl currently only supports '30m'. In explicit mode, only content blocks marked with a prompt cache breakpoint are cached.

• promptCacheRetention 'in_memory' | '24h' The legacy retention policy for models before GPT-5.6. Set to '24h' to enable extended prompt caching on supported models. For GPT-5.6 and later models, use promptCacheOptions.ttl instead.

• safetyIdentifier string A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user.

• systemMessageMode 'system' | 'developer' | 'remove' Controls the role of the system message when making requests. By default (when omitted), for models that support reasoning the system message is automatically converted to a developer message. Setting systemMessageMode to system passes the system message as a system-level instruction; developer passes it as a developer message; remove omits the system message from the request.

• forceReasoning boolean Force treating this model as a reasoning model. This is useful for "stealth" reasoning models (e.g. via a custom baseURL) where the model ID is not recognized by the SDK's allowlist. When enabled, the SDK applies reasoning-model parameter compatibility rules and defaults systemMessageMode to developer unless overridden.

• contextManagement Array<object> Enable server-side context management (compaction). When configured, the server automatically compresses conversation context when token usage crosses a specified threshold. Each object in the array should have:

  • type: 'compaction'
  • compactThreshold: number — the token count at which compaction is triggered

• compactionTrigger boolean Request explicit server-side compaction. When true, the provider appends a terminal { type: 'compaction_trigger' } item to the Responses input. Support depends on the configured Responses-compatible endpoint and model.

The OpenAI responses provider also returns provider-specific metadata:

For Responses models, you can type this metadata using OpenaiResponsesProviderMetadata:

import { openai, type OpenaiResponsesProviderMetadata } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-astra'),
});

const providerMetadata = result.providerMetadata as
  | OpenaiResponsesProviderMetadata
  | undefined;

const { responseId, logprobs, serviceTier, reasoningContext } =
  providerMetadata?.openai ?? {};

// responseId can be used to continue a conversation (previousResponseId).
console.log(responseId);

The following OpenAI-specific metadata may be returned:

• responseId string | null | undefined The ID of the response. Can be used to continue a conversation.
• logprobs (optional) Log probabilities of output tokens (when enabled).
• serviceTier (optional) Service tier information returned by the API.
• reasoningContext (optional) Effective persisted-reasoning context returned by GPT-5.6 ('current_turn' or 'all_turns').

Changing Reasoning Effort Mid-Conversation

You can increase reasoning effort for difficult work or reduce it for routine follow-ups while preserving the conversation prefix for prompt caching:

• Set the initial effort with request-level reasoning and keep that setting unchanged throughout the conversation.
• For later changes, add a message-level reasoningEffortUpdate before the next user message, following OpenAI's configuration update guidance.

The new effort applies until another update changes it. When sending conversation history in messages, include earlier effort updates along with the other messages.

Represent an update as an empty system message with providerOptions.openai.reasoningEffortUpdate.

You must set allowSystemInMessages: true to allow these trusted system messages.

In this example, the conversation starts at low effort and switches to high effort for the follow-up. Both requests keep reasoning: 'low'.

import {
  openai,
  type OpenAIResponsesSystemMessageOptions,
} from '@ai-sdk/openai';
import { generateText, type ModelMessage } from 'ai';

const messages: ModelMessage[] = [
  { role: 'user', content: 'Draft a migration plan.' },
];

const first = await generateText({
  model: openai.responses('gpt-6-astra'),
  reasoning: 'low',
  messages,
});

messages.push(...first.responseMessages);
messages.push(
  {
    role: 'system',
    content: '',
    providerOptions: {
      openai: {
        reasoningEffortUpdate: 'high',
      } satisfies OpenAIResponsesSystemMessageOptions,
    },
  },
  { role: 'user', content: 'Analyze the failure modes.' },
);

const second = await generateText({
  model: openai.responses('gpt-6-astra'),
  reasoning: 'low',
  allowSystemInMessages: true,
  messages,
});

messages.push(...second.responseMessages);

Message-level updates also work with streamText and previousResponseId.

Restrictions

Effort updates are supported on GPT-6-family models with these settings:

• Each update must use exactly content: ''.
• Updates cannot be consecutive, even with the same effort. This also applies across the boundary with history referenced by previousResponseId or conversation.

Requests that violate these restrictions are rejected.

Compaction

Effort updates are incompatible with automatic compaction through providerOptions.openai.contextManagement or compaction through OpenAI's /responses/compact endpoint.

To compact conversations containing effort updates, use explicit compaction with providerOptions.openai.compactionTrigger.

After compaction, add a fresh effort update before the next user message, as OpenAI recommends. Keep request-level reasoning unchanged.

Request-Level Update Option

The request-level providerOptions.openai.reasoningEffortUpdate option is a convenience that prepends a configuration update to the input. When using message-level updates, omit this option.

The request-level option continues to warn and omit updates for unsupported models or configurations.

Reasoning Output

For reasoning models like gpt-6-astra, you can enable reasoning summaries to see the model's thought process. Different models support different summarizers—for example, o4-mini supports detailed summaries. Set reasoningSummary: "auto" to automatically receive the richest level available. When reasoningEffort is set to a value other than 'none', the OpenAI Responses provider defaults reasoningSummary to 'detailed'; set reasoningSummary: null to omit reasoning summaries.

import {
  openai,
  type OpenAILanguageModelResponsesOptions,
} from '@ai-sdk/openai';
import { streamText } from 'ai';

const result = streamText({
  model: openai('gpt-6-astra'),
  prompt: 'Tell me about the Mission burrito debate in San Francisco.',
  providerOptions: {
    openai: {
      reasoningSummary: 'detailed', // 'auto' for condensed or 'detailed' for comprehensive
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

for await (const part of result.stream) {
  if (part.type === 'reasoning') {
    console.log(`Reasoning: ${part.textDelta}`);
  } else if (part.type === 'text-delta') {
    process.stdout.write(part.textDelta);
  }
}

For non-streaming calls with generateText, the reasoning summaries are available in the reasoning field of the response:

import {
  openai,
  type OpenAILanguageModelResponsesOptions,
} from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-astra'),
  prompt: 'Tell me about the Mission burrito debate in San Francisco.',
  providerOptions: {
    openai: {
      reasoningSummary: 'auto',
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});
console.log('Reasoning:', result.reasoning);

Learn more about reasoning summaries in the OpenAI documentation.

WebSocket Transport

OpenAI's WebSocket API keeps a persistent connection open, which can significantly reduce Time-to-First-Byte (TTFB) in agentic workflows with many tool calls. After the initial connection, subsequent requests skip TCP/TLS/HTTP negotiation entirely.

The ai-sdk-openai-websocket-fetch package provides a drop-in fetch replacement that routes streaming requests through a persistent WebSocket connection.

$ pnpm add ai-sdk-openai-websocket-fetch

$ npm install ai-sdk-openai-websocket-fetch

$ yarn add ai-sdk-openai-websocket-fetch

$ bun add ai-sdk-openai-websocket-fetch

Pass the WebSocket fetch to createOpenAI via the fetch option:

import { createOpenAI } from '@ai-sdk/openai';
import { createWebSocketFetch } from 'ai-sdk-openai-websocket-fetch';
import { streamText } from 'ai';

// Create a WebSocket-backed fetch instance
const wsFetch = createWebSocketFetch();
const openai = createOpenAI({ fetch: wsFetch });

const result = streamText({
  model: openai('gpt-6-luna'),
  prompt: 'Hello!',
  tools: {
    // ...
  },
  onFinish: () => wsFetch.close(), // close the WebSocket when done
});

The first request will be slower because it must establish the WebSocket connection (DNS + TCP + TLS + WebSocket upgrade). After that, subsequent steps in a multi-step tool-calling loop reuse the open connection, resulting in lower TTFB per step.

You can see a live side-by-side comparison of HTTP vs WebSocket streaming performance in the demo app.

Verbosity Control

You can control the length and detail of model responses using the textVerbosity parameter:

import {
  openai,
  type OpenAILanguageModelResponsesOptions,
} from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-luna'),
  prompt: 'Write a poem about a boy and his first pet dog.',
  providerOptions: {
    openai: {
      textVerbosity: 'low', // 'low' for concise, 'medium' (default), or 'high' for verbose
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

The textVerbosity parameter scales output length without changing the underlying prompt:

• 'low': Produces terse, minimal responses
• 'medium': Balanced detail (default)
• 'high': Verbose responses with comprehensive detail

Namespaced Function Calls

OpenAI supports grouping related function tools into 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.

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:

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.

Async Tool Calling

GPT-6 Astra and later Responses models support async tool calling. An async tool lets the model continue generating independent output after issuing the call instead of waiting for its result. Your application still executes the tool and sends its result in a later request using the original tool call ID.

Enable async calling on a function tool with providerOptions.openai.async:

import { openai, type OpenAIToolOptions } from '@ai-sdk/openai';
import { generateText, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: openai.responses('gpt-6-astra'),
  tools: {
    getWeather: tool({
      description: 'Get the weather for a city.',
      inputSchema: z.object({ city: z.string() }),
      outputSchema: z.object({
        city: z.string(),
        temperatureC: z.number(),
      }),
      providerOptions: {
        openai: { async: true } satisfies OpenAIToolOptions,
      },
    }),
  },
  prompt:
    'Start the weather lookup for Paris, then list three general packing essentials without waiting.',
});

The generated tool call exposes the provider marker as providerMetadata.openai.async. Use providerMetadata.openai.responseId as the next request's previousResponseId, and submit the result in a tool message with the original toolCallId.

With streamText, OpenAI can continue streaming text after the completed tool-call part. Use the tool's onInputAvailable callback to start work as soon as that part arrives. If execute returns the same already-running promise, tool execution overlaps the rest of the model stream. Omit execute when the job should outlive the current generation and submit its result in a later request.

Async calling applies to directly called function and custom tools. It does not apply to hosted tools and should not be combined with programmatic tool calling.

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.

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-6-astra'),
  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.

const result = await generateText({
  model: openai('gpt-6-astra'),
  prompt: 'What happened in San Francisco last week?',
  tools: {
    web_search: openai.tools.webSearch({
      // optional configuration:
      externalWebAccess: true,
      searchContextSize: 'high',
      userLocation: {
        type: 'approximate',
        city: 'San Francisco',
        region: 'California',
      },
      filters: {
        allowedDomains: ['sfchronicle.com', 'sfgate.com'],
        blockedDomains: ['example.com'],
      },
    }),
  },
  // Force web search tool (optional):
  toolChoice: { type: 'tool', toolName: 'web_search' },
});

// URL sources directly from `results`
const sources = result.sources;

// Or access sources from tool results
for (const toolResult of result.toolResults) {
  if (toolResult.toolName === 'web_search') {
    console.log('Query:', toolResult.output.action.query);
    console.log('Sources:', toolResult.output.sources);
    // `sources` is an array of object: { type: 'url', url: string }
  }
}

result.sources and source stream events expose the URLs returned in web_search_call.action.sources. These may include uncited URLs. Inline references are available separately on text.citations and text-end.citations, including titles and provider-supplied text ranges. Raw annotations remain in text provider metadata. Citation-only responses and web_search_preview responses without retrieval data retain citation-derived sources.

The web search tool supports the following configuration options:

• externalWebAccess boolean - Whether to use external web access for fetching live content. Defaults to true.
• searchContextSize 'low' | 'medium' | 'high' - Controls the amount of context used for the search. Higher values provide more comprehensive results but may have higher latency and cost.
• userLocation - Optional location information to provide geographically relevant results. Includes type (always 'approximate'), country, city, region, and timezone.
• filters - Optional filter configuration to restrict search results.
  • allowedDomains string[] - Up to 100 allowed domains for the search.
  • blockedDomains string[] - Up to 100 blocked domains for the search.

Omit the HTTP or HTTPS prefix from domain filters. Subdomains of configured domains are automatically included or excluded.

For detailed information on configuration options see the OpenAI Web Search Tool documentation.

File Search Tool

The OpenAI responses API supports file search through the openai.tools.fileSearch tool.

You can force the use of the file search tool by setting the toolChoice parameter to { type: 'tool', toolName: 'file_search' }.

const result = await generateText({
  model: openai('gpt-6-astra'),
  prompt: 'What does the document say about user authentication?',
  tools: {
    file_search: openai.tools.fileSearch({
      vectorStoreIds: ['vs_123'],
      // configuration below is optional:
      maxNumResults: 5,
      filters: {
        key: 'author',
        type: 'eq',
        value: 'Jane Smith',
      },
      ranking: {
        ranker: 'auto',
        scoreThreshold: 0.5,
      },
    }),
  },
  providerOptions: {
    openai: {
      // optional: include results
      include: ['file_search_call.results'],
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

The file search tool supports filtering with both comparison and compound filters:

Comparison filters - Filter by a single attribute:

• eq - Equal to
• ne - Not equal to
• gt - Greater than
• gte - Greater than or equal to
• lt - Less than
• lte - Less than or equal to
• in - Value is in array
• nin - Value is not in array

// Single comparison filter
filters: { key: 'year', type: 'gte', value: 2023 }

// Filter with array values
filters: { key: 'status', type: 'in', value: ['published', 'reviewed'] }

Compound filters - Combine multiple filters with and or or:

// Compound filter with AND
filters: {
  type: 'and',
  filters: [
    { key: 'author', type: 'eq', value: 'Jane Smith' },
    { key: 'year', type: 'gte', value: 2023 },
  ],
}

// Compound filter with OR
filters: {
  type: 'or',
  filters: [
    { key: 'department', type: 'eq', value: 'Engineering' },
    { key: 'department', type: 'eq', value: 'Research' },
  ],
}

Image Generation Tool

OpenAI's Responses API supports multi-modal image generation as a provider-defined tool. Availability is restricted to specific models (for example, gpt-5 variants).

You can use the image tool with either generateText or streamText:

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-astra'),
  prompt:
    'Generate an image of an echidna swimming across the Mozambique channel.',
  tools: {
    image_generation: openai.tools.imageGeneration({ outputFormat: 'webp' }),
  },
});

for (const toolResult of result.staticToolResults) {
  if (toolResult.toolName === 'image_generation') {
    const base64Image = toolResult.output.result;
  }
}

import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';

const result = streamText({
  model: openai('gpt-6-astra'),
  prompt:
    'Generate an image of an echidna swimming across the Mozambique channel.',
  tools: {
    image_generation: openai.tools.imageGeneration({
      outputFormat: 'webp',
      quality: 'low',
    }),
  },
});

for await (const part of result.stream) {
  if (part.type == 'tool-result' && !part.dynamic) {
    const base64Image = part.output.result;
  }
}

To use xhigh or max quality, select gpt-image-2.5-flare or gpt-image-2.5-sunburst as the image generation tool's model:

openai.tools.imageGeneration({
  model: 'gpt-image-2.5-flare',
  quality: 'xhigh',
});

For complete details on model availability, image quality controls, supported sizes, and tool-specific parameters, refer to the OpenAI documentation:

• Image generation overview and models: OpenAI Image Generation
• Image generation tool parameters (background, size, quality, format, etc.): Image Generation Tool Options

Code Interpreter Tool

The OpenAI responses API supports the code interpreter tool through the openai.tools.codeInterpreter tool. This allows models to write and execute Python code.

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-astra'),
  prompt: 'Write and run Python code to calculate the factorial of 10',
  tools: {
    code_interpreter: openai.tools.codeInterpreter({
      // optional configuration:
      container: {
        fileIds: ['file-123', 'file-456'], // optional file IDs to make available
      },
    }),
  },
});

The code interpreter tool can be configured with:

• container: Either a container ID string or an object with fileIds to specify uploaded files that should be available to the code interpreter

MCP Tool

The OpenAI responses API supports connecting to Model Context Protocol (MCP) servers through the openai.tools.mcp tool. This allows models to call tools exposed by remote MCP servers or service connectors.

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-astra'),
  prompt: 'Search the web for the latest news about AI developments',
  tools: {
    mcp: openai.tools.mcp({
      serverLabel: 'web-search',
      serverUrl: 'https://mcp.exa.ai/mcp',
      serverDescription: 'A web-search API for AI agents',
    }),
  },
});

The MCP tool can be configured with:

• serverLabel string (required)

  A label to identify the MCP server. This label is used in tool calls to distinguish between multiple MCP servers.

• serverUrl string (required if connectorId is not provided)

  The URL for the MCP server. Either serverUrl or connectorId must be provided.

• connectorId string (required if serverUrl is not provided)

  Identifier for a service connector. Either serverUrl or connectorId must be provided.

• serverDescription string (optional)

  Optional description of the MCP server that helps the model understand its purpose.

• allowedTools string[] | object (optional)

  Controls which tools from the MCP server are available. Can be:

  • An array of tool names: ['tool1', 'tool2']
  • An object with filters:

    {
      readOnly: true, // Only allow read-only tools
      toolNames: ['tool1', 'tool2'] // Specific tool names
    }

• authorization string (optional)

  OAuth access token for authenticating with the MCP server or connector.

• headers Record<string, string> (optional)

  Optional HTTP headers to include in requests to the MCP server.

• requireApproval 'always' | 'never' | object (optional)

  Controls which MCP tool calls require user approval before execution. Can be:

  • 'always': All MCP tool calls require approval
  • 'never': No MCP tool calls require approval (default)
  • An object with filters:

    {
      never: {
        toolNames: ['safe_tool', 'another_safe_tool']; // Skip approval for these tools
      }
    }

  When approval is required, the model will return a tool-approval-request content part that you can use to prompt the user for approval. See Human in the Loop for more details on implementing approval workflows.

Computer Tool

The OpenAI Responses API supports the GA computer tool through openai.tools.computer. The model returns an ordered batch of browser or desktop actions for your application to execute, and your application returns an updated screenshot.

import { openai } from '@ai-sdk/openai';
import { generateText, isStepCount } from 'ai';
import { captureScreenshot, executeComputerAction } from '@/utils/computer-use';

const result = await generateText({
  model: openai.responses('gpt-6-astra'),
  tools: {
    computer: openai.tools.computer({
      needsApproval: ({ pendingSafetyChecks }) =>
        pendingSafetyChecks.length > 0,

      execute: async ({ actions, pendingSafetyChecks }) => {
        for (const action of actions) {
          await executeComputerAction(action);
        }

        return {
          output: {
            type: 'computer_screenshot',
            imageUrl: `data:image/png;base64,${await captureScreenshot()}`,
            detail: 'original',
          },
          acknowledgedSafetyChecks: pendingSafetyChecks,
        };
      },
    }),
  },
  prompt: 'Open the settings page and enable dark mode.',
  stopWhen: isStepCount(10),
});

The execute callback receives:

• actions - An ordered array of click, double_click, drag, keypress, move, screenshot, scroll, type, and wait actions. Execute every action in order before capturing the next screenshot.
• pendingSafetyChecks - Safety checks returned by OpenAI. Review these before continuing and include accepted checks in acknowledgedSafetyChecks.
• status - The computer call status.

The action union is also exported as OpenAIComputerAction. Action-specific fields are:

Safety checks use the exported OpenAIComputerSafetyCheck type.

Return a computer_screenshot with either:

• imageUrl - A fully qualified URL or image data URL.
• fileId - The ID of an uploaded screenshot file.

detail can be auto, low, high, or original. original preserves the captured resolution and is recommended when accurate coordinates are important.

Computer calls and computer_call_output screenshot results are carried through multi-step generations when using store, previousResponseId, or OpenAI conversations. You can also set store: false; the provider will serialize the complete call and screenshot result into each follow-up request.

Local Shell Tool

The OpenAI responses API support the local shell tool for Codex models through the openai.tools.localShell tool. Local shell is a tool that allows agents to run shell commands locally on a machine you or the user provides.

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai.responses('gpt-5-codex'),
  tools: {
    local_shell: openai.tools.localShell({
      execute: async ({ action }) => {
        // ... your implementation, e.g. sandbox access ...
        return { output: stdout };
      },
    }),
  },
  prompt: 'List the files in my home directory.',
  stopWhen: isStepCount(2),
});

Shell Tool

The OpenAI Responses API supports the shell tool through the openai.tools.shell tool. The shell tool allows running bash commands and interacting with a command line. The model proposes shell commands; your integration executes them and returns the outputs.

The shell tool supports three environment modes that control where commands are executed:

Local Execution (default)

When no environment is specified (or type: 'local' is used), commands are executed locally via your execute callback:

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-astra'),
  tools: {
    shell: openai.tools.shell({
      execute: async ({ action }) => {
        // ... your implementation, e.g. sandbox access ...
        return { output: results };
      },
    }),
  },
  prompt: 'List the files in the current directory and show disk usage.',
});

Hosted Container (auto)

Set environment.type to 'containerAuto' to run commands in an OpenAI-hosted container. No execute callback is needed — OpenAI handles execution server-side:

const result = await generateText({
  model: openai('gpt-6-astra'),
  tools: {
    shell: openai.tools.shell({
      environment: {
        type: 'containerAuto',
        // optional configuration:
        memoryLimit: '4g',
        fileIds: ['file-abc123'],
        networkPolicy: {
          type: 'allowlist',
          allowedDomains: ['example.com'],
        },
      },
    }),
  },
  prompt: 'Install numpy and compute the eigenvalues of a 3x3 matrix.',
});

The containerAuto environment supports:

• fileIds string[] - File IDs to make available in the container
• memoryLimit '1g' | '4g' | '16g' | '64g' - Memory limit for the container
• networkPolicy - Network access policy:
  • { type: 'disabled' } — no network access
  • { type: 'allowlist', allowedDomains: string[], domainSecrets?: Array<{ domain, name, value }> } — allow specific domains with optional secrets

Existing Container Reference

Set environment.type to 'containerReference' to use an existing container by ID:

const result = await generateText({
  model: openai('gpt-6-astra'),
  tools: {
    shell: openai.tools.shell({
      environment: {
        type: 'containerReference',
        containerId: 'cntr_abc123',
      },
    }),
  },
  prompt: 'Check the status of running processes.',
});

Execute Callback

For local execution (default or type: 'local'), your execute function must return an output array with results for each command:

• stdout string - Standard output from the command
• stderr string - Standard error from the command
• outcome - Either { type: 'timeout' } or { type: 'exit', exitCode: number }

Skills

Skills are versioned bundles of files with a SKILL.md manifest that extend the shell tool's capabilities. They can be attached to both containerAuto and local environments.

Container skills support two formats — by reference (for skills uploaded to OpenAI) or inline (as a base64-encoded zip):

const result = await generateText({
  model: openai('gpt-6-astra'),
  tools: {
    shell: openai.tools.shell({
      environment: {
        type: 'containerAuto',
        skills: [
          // By reference:
          { type: 'skillReference', skillId: 'skill_abc123' },
          // Or inline:
          {
            type: 'inline',
            name: 'my-skill',
            description: 'What this skill does',
            source: {
              type: 'base64',
              mediaType: 'application/zip',
              data: readFileSync('./my-skill.zip').toString('base64'),
            },
          },
        ],
      },
    }),
  },
  prompt: 'Use the skill to solve this problem.',
});

Local skills point to a directory on disk containing a SKILL.md file:

const result = await generateText({
  model: openai('gpt-6-astra'),
  tools: {
    shell: openai.tools.shell({
      execute: async ({ action }) => {
        // ... your local execution implementation ...
        return { output: results };
      },
      environment: {
        type: 'local',
        skills: [
          {
            name: 'my-skill',
            description: 'What this skill does',
            path: resolve('path/to/skill-directory'),
          },
        ],
      },
    }),
  },
  prompt: 'Use the skill to solve this problem.',
  stopWhen: isStepCount(5),
});

For more details on creating skills, see the OpenAI Skills documentation.

Apply Patch Tool

The OpenAI Responses API supports the apply patch tool for GPT-5.1 models through the openai.tools.applyPatch tool. The apply patch tool lets the model create, update, and delete files in your codebase using structured diffs. Instead of just suggesting edits, the model emits patch operations that your application applies and reports back on, enabling iterative, multi-step code editing workflows.

import { openai } from '@ai-sdk/openai';
import { generateText, isStepCount } from 'ai';

const result = await generateText({
  model: openai('gpt-6-astra'),
  tools: {
    apply_patch: openai.tools.applyPatch({
      execute: async ({ callId, operation }) => {
        // ... your implementation for applying the diffs.
        return { status: 'completed' };
      },
    }),
  },
  prompt: 'Create a python file that calculates the factorial of a number',
  stopWhen: isStepCount(5),
});

Your execute function must return:

• status 'completed' | 'failed' - Whether the patch was applied successfully
• output string (optional) - Human-readable log text (e.g., results or error messages)

Tool Search

Tool search allows the model to dynamically search for and load tools into context as needed, rather than loading all tool definitions up front. This can reduce token usage, cost, and latency when you have many tools. Mark the tools you want to make searchable with deferLoading: true in their providerOptions.

There are two execution modes:

• Server-executed (hosted): OpenAI searches across the deferred tools declared in the request and returns the loaded subset in the same response. No extra round-trip is needed.
• Client-executed: The model emits a tool_search_call, your application performs the lookup, and you return the matching tools via the execute callback.

Server-Executed (Hosted) Tool Search

Use hosted tool search when the candidate tools are already known at request time. Add openai.tools.toolSearch() with no arguments and mark your tools with deferLoading: true:

import { openai } from '@ai-sdk/openai';
import { generateText, tool, isStepCount } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: openai.responses('gpt-6-astra'),
  prompt: 'What is the weather in San Francisco?',
  stopWhen: isStepCount(10),
  tools: {
    toolSearch: openai.tools.toolSearch(),

    get_weather: tool({
      description: 'Get the current weather at a specific location',
      inputSchema: z.object({
        location: z.string(),
        unit: z.enum(['celsius', 'fahrenheit']),
      }),
      execute: async ({ location, unit }) => ({
        location,
        temperature: unit === 'celsius' ? 18 : 64,
      }),
      providerOptions: {
        openai: { deferLoading: true },
      },
    }),

    search_files: tool({
      description: 'Search through files in the workspace',
      inputSchema: z.object({ query: z.string() }),
      execute: async ({ query }) => ({
        results: [`Found 3 files matching "${query}"`],
      }),
      providerOptions: {
        openai: { deferLoading: true },
      },
    }),
  },
});

In hosted mode, the model internally searches the deferred tools, loads the relevant ones, and 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:

const crmNamespace = {
  name: 'crm',
  description: 'CRM tools for customer lookup and order management.',
};

const result = await generateText({
  model: openai.responses('gpt-6-astra'),
  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, tools that vary per tenant, project, or external system. Pass execution: 'client' along with a description, parameters schema, and an execute callback:

import { openai } from '@ai-sdk/openai';
import { generateText, tool, isStepCount } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: openai.responses('gpt-6-astra'),
  prompt: 'What is the weather in San Francisco?',
  stopWhen: isStepCount(10),
  tools: {
    toolSearch: openai.tools.toolSearch({
      execution: 'client',
      description: 'Search for available tools based on what the user needs.',
      parameters: {
        type: 'object',
        properties: {
          goal: {
            type: 'string',
            description: 'What the user is trying to accomplish',
          },
        },
        required: ['goal'],
        additionalProperties: false,
      },
      execute: async ({ arguments: args }) => {
        // Your custom tool discovery logic here.
        // Return the tools that match the search goal.
        return {
          tools: [
            {
              type: 'function',
              name: 'get_weather',
              description: 'Get the current weather at a specific location',
              deferLoading: true,
              parameters: {
                type: 'object',
                properties: {
                  location: { type: 'string' },
                },
                required: ['location'],
                additionalProperties: false,
              },
            },
          ],
        };
      },
    }),

    get_weather: tool({
      description: 'Get the current weather at a specific location',
      inputSchema: z.object({ location: z.string() }),
      execute: async ({ location }) => ({
        location,
        temperature: 64,
        condition: 'Partly cloudy',
      }),
      providerOptions: {
        openai: { deferLoading: true },
      },
    }),
  },
});

In client mode, the flow spans two steps:

1. Step 1: The model emits a tool_search_call with execution: 'client' and a non-null call_id. The SDK calls your execute callback with the search arguments. Your callback returns the discovered tools.
2. Step 2: The SDK sends the tool_search_output (with the matching call_id) back to the model. The model can now call the loaded tools as normal function calls.

For more details, see the OpenAI Tool Search documentation.

Custom Tool

The OpenAI Responses API supports custom tools through the openai.tools.customTool tool. Custom tools return a raw string instead of JSON, optionally constrained to a grammar (regex or Lark syntax). This makes them useful for generating structured text like SQL queries, code snippets, or any output that must match a specific pattern.

import { openai } from '@ai-sdk/openai';
import { generateText, isStepCount } from 'ai';

const result = await generateText({
  model: openai.responses('gpt-6-sol'),
  tools: {
    write_sql: openai.tools.customTool({
      description: 'Write a SQL SELECT query to answer the user question.',
      format: {
        type: 'grammar',
        syntax: 'regex',
        definition: 'SELECT .+',
      },
      execute: async input => {
        // input is a raw string matching the grammar, e.g. "SELECT * FROM users WHERE age > 25"
        const rows = await db.query(input);
        return JSON.stringify(rows);
      },
    }),
  },
  toolChoice: 'required',
  prompt: 'Write a SQL query to get all users older than 25.',
  stopWhen: isStepCount(3),
});

Custom tools also work with streamText:

import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';

const result = streamText({
  model: openai.responses('gpt-6-sol'),
  tools: {
    write_sql: openai.tools.customTool({
      description: 'Write a SQL SELECT query to answer the user question.',
      format: {
        type: 'grammar',
        syntax: 'regex',
        definition: 'SELECT .+',
      },
    }),
  },
  toolChoice: 'required',
  prompt: 'Write a SQL query to get all users older than 25.',
});

for await (const chunk of result.stream) {
  if (chunk.type === 'tool-call') {
    console.log(`Tool: ${chunk.toolName}`);
    console.log(`Input: ${chunk.input}`);
  }
}

The custom tool can be configured with:

• description string (optional) - A description of what the tool does, to help the model understand when to use it.
• format object (optional) - The output format constraint. Omit for unconstrained text output.
  • type 'grammar' | 'text' - The format type. Use 'grammar' for constrained output or 'text' for explicit unconstrained text.
  • syntax 'regex' | 'lark' - (grammar only) The grammar syntax. Use 'regex' for regular expression patterns or 'lark' for Lark parser grammar.
  • definition string - (grammar only) The grammar definition string (a regex pattern or Lark grammar).
• execute function (optional) - An async function that receives the raw string input and returns a string result. Enables multi-turn tool calling.

Restricting Callable Tools

The allowedTools provider option restricts which of the tools you declared the model is allowed to call, while still sending the full tools list to OpenAI. Because the tools list stays byte-identical across requests, the prompt cache is preserved — unlike activeTools, which removes tools from the request and invalidates the cache whenever the allow-list changes.

allowedTools is only supported by the Responses API, and it overrides the request-level toolChoice.

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai.responses('gpt-6-astra'),
  tools: {
    weather: weatherTool,
    cityAttractions: cityAttractionsTool,
    search: openai.tools.webSearch(),
  },
  providerOptions: {
    openai: {
      allowedTools: { toolNames: ['weather', 'search'], mode: 'auto' },
    },
  },
  prompt: 'What is the weather in San Francisco?',
});

• toolNames string[] - The tools the model may call, named as you declared them in tools. For provider-defined tools you may also use the canonical OpenAI name (for example web_search).
• mode 'auto' | 'required' (optional) - 'auto' (default) lets the model pick one of the allowed tools or answer with a message; 'required' forces it to call at least one of them.

Both function tools and provider-defined tools can be allow-listed, including web search, file search, image generation, code interpreter, computer, apply patch, shell, programmatic tool calling, custom tools, and MCP servers.

If a name matches both a tool you declared and the canonical OpenAI name of a different tool, the tool you declared under that name wins, and a warning reports the ambiguity. If several tools share the same canonical name — two MCP servers, for example — that name is ambiguous, so it is dropped with a warning; name those tools as you declared them instead.

Image Inputs

The OpenAI Responses API supports Image inputs for appropriate models. You can pass Image files as part of the message content using the file type with an image media type:

const result = await generateText({
  model: openai('gpt-6-astra'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Please describe the image.',
        },
        {
          type: 'file',
          mediaType: 'image',
          data: readFileSync('./data/image.png'),
        },
      ],
    },
  ],
});

The model will have access to the image and will respond to questions about it. The image should be passed using the data field.

You can also pass a file-id from the OpenAI Files API.

{
  type: 'file',
  mediaType: 'image',
  data: 'file-8EFBcWHsQxZV7YGezBC1fq'
}

You can also pass the URL of an image.

{
  type: 'file',
  mediaType: 'image',
  data: 'https://sample.edu/image.png',
}

PDF Inputs

The OpenAI Responses API supports reading PDF files. You can pass PDF files as part of the message content using the file type:

const result = await generateText({
  model: openai('gpt-6-astra'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'What is an embedding model?',
        },
        {
          type: 'file',
          data: readFileSync('./data/ai.pdf'),
          mediaType: 'application/pdf',
          filename: 'ai.pdf', // optional
        },
      ],
    },
  ],
});

You can also pass a file-id from the OpenAI Files API.

{
  type: 'file',
  data: 'file-8EFBcWHsQxZV7YGezBC1fq',
  mediaType: 'application/pdf',
}

You can also pass the URL of a pdf.

{
  type: 'file',
  data: 'https://sample.edu/example.pdf',
  mediaType: 'application/pdf',
  filename: 'ai.pdf', // optional
}

The model will have access to the contents of the PDF file and respond to questions about it. The PDF file should be passed using the data field, and the mediaType should be set to 'application/pdf'.

Structured Outputs

The OpenAI Responses API supports structured outputs. You can use generateText or streamText with Output to enforce structured outputs.

const result = await generateText({
  model: openai('gpt-6-astra'),
  output: Output.object({
    schema: z.object({
      recipe: z.object({
        name: z.string(),
        ingredients: z.array(
          z.object({
            name: z.string(),
            amount: z.string(),
          }),
        ),
        steps: z.array(z.string()),
      }),
    }),
  }),
  prompt: 'Generate a lasagna recipe.',
});

Typed providerMetadata in Text Parts

When using the OpenAI Responses API, the SDK attaches OpenAI-specific metadata to output parts via providerMetadata.

This metadata can be used on the client side for tasks such as rendering citations or downloading files generated by the Code Interpreter. To enable type-safe handling of this metadata, the AI SDK exports dedicated TypeScript types.

For text parts, when part.type === 'text', the providerMetadata is provided in the form of OpenaiResponsesTextProviderMetadata.

This metadata includes the following fields:

• itemId The ID of the output item in the Responses API.

• annotations (optional) An array of annotation objects generated by the model. If no annotations are present, this property itself may be omitted (undefined).

  Each element in annotations is a discriminated union with a required type field. Supported types include, for example:

  • url_citation
  • file_citation
  • container_file_citation
  • file_path

  These annotations directly correspond to the annotation objects defined by the Responses API and can be used for inline reference rendering or output analysis. For details, see the official OpenAI documentation: Responses API – output text annotations.

import {
  openai,
  type OpenaiResponsesTextProviderMetadata,
} from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-luna'),
  prompt:
    'Create a program that generates five random numbers between 1 and 100 with two decimal places, and show me the execution results. Also save the result to a file.',
  tools: {
    code_interpreter: openai.tools.codeInterpreter(),
    web_search: openai.tools.webSearch(),
    file_search: openai.tools.fileSearch({ vectorStoreIds: ['vs_1234'] }), // requires a configured vector store
  },
});

for (const part of result.content) {
  if (part.type === 'text') {
    const providerMetadata = part.providerMetadata as
      | OpenaiResponsesTextProviderMetadata
      | undefined;
    if (!providerMetadata) continue;
    const { itemId: _itemId, annotations } = providerMetadata.openai;

    if (!annotations) continue;
    for (const annotation of annotations) {
      switch (annotation.type) {
        case 'url_citation':
          // url_citation is returned from web_search and provides:
          // properties: type, url, title, start_index and end_index
          break;
        case 'file_search':
          // Retrieved file-search result; provides fileId.
          // The filename is available as part.filename.
          break;
        case 'file_citation':
          // file_citation is returned from file_search and provides:
          // properties: type, file_id, filename and index
          break;
        case 'container_file_citation':
          // container_file_citation is returned from code_interpreter and provides:
          // properties: type, container_id, file_id, filename, start_index and end_index
          break;
        case 'file_path':
          // file_path provides:
          // properties: type, file_id and index
          break;
        default: {
          const _exhaustiveCheck: never = annotation;
          throw new Error(
            `Unhandled annotation: ${JSON.stringify(_exhaustiveCheck)}`,
          );
        }
      }
    }
  }
}

Typed providerMetadata in Reasoning Parts

When using the OpenAI Responses API, reasoning output parts can include provider metadata. To handle this metadata in a type-safe way, use OpenaiResponsesReasoningProviderMetadata.

For reasoning parts, when part.type === 'reasoning', the providerMetadata is provided in the form of OpenaiResponsesReasoningProviderMetadata.

This metadata includes the following fields:

• itemId
  The ID of the reasoning item in the Responses API.
• reasoningEncryptedContent (optional)
  Encrypted reasoning content (only returned when requested via include: ['reasoning.encrypted_content']).

import {
  openai,
  type OpenaiResponsesReasoningProviderMetadata,
  type OpenAILanguageModelResponsesOptions,
} from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-astra'),
  prompt: 'How many "r"s are in the word "strawberry"?',
  providerOptions: {
    openai: {
      store: false,
      include: ['reasoning.encrypted_content'],
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

for (const part of result.content) {
  if (part.type === 'reasoning') {
    const providerMetadata = part.providerMetadata as
      | OpenaiResponsesReasoningProviderMetadata
      | undefined;

    const { itemId, reasoningEncryptedContent } =
      providerMetadata?.openai ?? {};
    console.log(itemId, reasoningEncryptedContent);
  }
}

When file-search results are included in the API response, each retrieved file is exposed once as a document source, even if it has multiple matching passages or is not cited. Inline file citations are available on text.citations and text-end.citations. If the response omits file-search results, file citations also remain document sources for compatibility. Generated file paths remain source parts and are not treated as citations.

Typed providerMetadata in Source Document Parts

For source document parts, when part.type === 'source' and sourceType === 'document', the providerMetadata is provided as OpenaiResponsesSourceDocumentProviderMetadata.

This metadata is also a discriminated union with a required type field. Supported types include:

• file_search (retrieved file; includes fileId)
• file_citation
• container_file_citation
• file_path

Each type includes the identifiers required to work with the referenced resource, such as fileId and containerId.

import {
  openai,
  type OpenaiResponsesSourceDocumentProviderMetadata,
} from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-luna'),
  prompt:
    'Create a program that generates five random numbers between 1 and 100 with two decimal places, and show me the execution results. Also save the result to a file.',
  tools: {
    code_interpreter: openai.tools.codeInterpreter(),
    web_search: openai.tools.webSearch(),
    file_search: openai.tools.fileSearch({ vectorStoreIds: ['vs_1234'] }), // requires a configured vector store
  },
});

for (const part of result.content) {
  if (part.type === 'source') {
    if (part.sourceType === 'document') {
      const providerMetadata = part.providerMetadata as
        | OpenaiResponsesSourceDocumentProviderMetadata
        | undefined;
      if (!providerMetadata) continue;
      const annotation = providerMetadata.openai;
      switch (annotation.type) {
        case 'file_citation':
          // file_citation is returned from file_search and provides:
          // properties: type, fileId and index
          // The filename can be accessed via part.filename.
          break;
        case 'container_file_citation':
          // container_file_citation is returned from code_interpreter and provides:
          // properties: type, containerId and fileId
          // The filename can be accessed via part.filename.
          break;
        case 'file_path':
          // file_path provides:
          // properties: type, fileId and index
          break;
        default: {
          const _exhaustiveCheck: never = annotation;
          throw new Error(
            `Unhandled annotation: ${JSON.stringify(_exhaustiveCheck)}`,
          );
        }
      }
    }
  }
}

Compaction

The OpenAI Responses API supports server-side context compaction. When enabled, the server automatically compresses conversation context when token usage crosses a configured threshold. This is useful for long-running conversations or agent loops where you want to stay within token limits without manually managing context.

The compaction item returned by the server is opaque and encrypted — it carries forward key prior state and reasoning into the next turn using fewer tokens. The AI SDK handles this automatically: compaction items are returned as text parts with special providerMetadata, and when passed back in subsequent requests they are sent as compaction input items.

import {
  openai,
  type OpenAILanguageModelResponsesOptions,
} from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai.responses('gpt-6-astra'),
  messages: conversationHistory,
  providerOptions: {
    openai: {
      store: false,
      contextManagement: [{ type: 'compaction', compactThreshold: 50000 }],
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

Configuration:

• type — Must be 'compaction'
• compactThreshold — The token count at which compaction is triggered. When the rendered input token count crosses this threshold, the server runs a compaction pass before continuing inference.

Explicit Compaction

For Responses-compatible endpoints that support explicit compaction, set compactionTrigger: true. The provider appends the required { type: 'compaction_trigger' } request control after all converted messages and input items.

import {
  openai,
  type OpenAILanguageModelResponsesOptions,
} from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai.responses('gpt-5.3-codex'),
  messages: conversationHistory,
  providerOptions: {
    openai: {
      store: false,
      compactionTrigger: true,
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

This is distinct from contextManagement, which configures automatic, threshold-based compaction. When omitted or false, compactionTrigger does not add an input item. The resulting compaction output uses the existing openai.compaction custom part representation. Endpoint and model support can vary.

Detecting Compaction in Streams

When using streamText, you can detect compaction by checking the providerMetadata on text-start and text-end events:

import {
  openai,
  type OpenAILanguageModelResponsesOptions,
} from '@ai-sdk/openai';
import { streamText } from 'ai';

const result = streamText({
  model: openai.responses('gpt-6-astra'),
  messages: conversationHistory,
  providerOptions: {
    openai: {
      store: false,
      contextManagement: [{ type: 'compaction', compactThreshold: 50000 }],
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

for await (const part of result.stream) {
  switch (part.type) {
    case 'text-start': {
      const isCompaction = part.providerMetadata?.openai?.type === 'compaction';
      if (isCompaction) {
        // ... your logic
      }
      break;
    }
    case 'text-end': {
      const isCompaction = part.providerMetadata?.openai?.type === 'compaction';
      if (isCompaction) {
        // ... your logic
      }
      break;
    }
    case 'text-delta': {
      process.stdout.write(part.text);
      break;
    }
  }
}

Compaction in UI Applications

When using useChat or other UI hooks, compaction items appear as text parts with providerMetadata. You can detect and style them differently in your UI:

{
  message.parts.map((part, index) => {
    if (part.type === 'text') {
      const isCompaction =
        (part.providerMetadata?.openai as { type?: string } | undefined)
          ?.type === 'compaction';

      if (isCompaction) {
        return (
          <div
            key={index}
            className="bg-yellow-100 border-l-4 border-yellow-500 p-2"
          >
            <span className="font-bold">[Context Compacted]</span>
            <p className="text-sm text-yellow-700">
              The server compressed the conversation context to reduce token
              usage.
            </p>
          </div>
        );
      }
      return <div key={index}>{part.text}</div>;
    }
  });
}