@ai-sdk/openai 3.0.117 → 3.0.119

package/docs/03-openai.mdx

@@ -325,55 +325,104 @@ The following OpenAI-specific metadata may be returned:
 
 #### Changing Reasoning Effort Mid-Conversation
 
-GPT-6 and later models can change reasoning effort between responses without
-changing the request-level `reasoningEffort` setting. The provider sends
-`reasoningEffortUpdate` as an OpenAI `configuration_update` input item before
-the next user message. Keeping the request-level effort unchanged preserves the
-original prompt prefix for prompt caching.
+You can increase reasoning effort for difficult work or reduce it for routine
+follow-ups while preserving the conversation prefix for prompt caching:
 
-```ts highlight="13,32,34"
+- Set the initial effort with request-level `providerOptions.openai.reasoningEffort` 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](https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation).
+
+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`.
+
+Set `allowSystemInMessages: true` to explicitly allow these trusted system messages
+and suppress the warning for system messages in `messages`.
+
+In this example, the conversation starts at low effort and switches to high
+effort for the follow-up. Both requests keep `providerOptions.openai.reasoningEffort: 'low'`.
+
+```ts
 import {
   openai,
-  type OpenAILanguageModelResponsesOptions,
-  type OpenaiResponsesProviderMetadata,
+  type OpenAIResponsesSystemMessageOptions,
 } from '@ai-sdk/openai';
-import { generateText } from 'ai';
+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'),
-  prompt: 'Draft a database migration plan.',
-  providerOptions: {
-    openai: {
-      reasoningEffort: 'low',
-    } satisfies OpenAILanguageModelResponsesOptions,
-  },
+  providerOptions: { openai: { reasoningEffort: 'low' } },
+  messages,
 });
 
-const metadata = first.providerMetadata as
-  | OpenaiResponsesProviderMetadata
-  | undefined;
-const previousResponseId = metadata?.openai.responseId;
-
-if (!previousResponseId) {
-  throw new Error('OpenAI did not return a response ID.');
-}
+messages.push(...first.response.messages);
+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'),
-  prompt: 'Analyze the failure modes and propose rollback steps.',
-  providerOptions: {
-    openai: {
-      previousResponseId,
-      reasoningEffort: 'low',
-      reasoningEffortUpdate: 'high',
-    } satisfies OpenAILanguageModelResponsesOptions,
-  },
+  providerOptions: { openai: { reasoningEffort: 'low' } },
+  allowSystemInMessages: true,
+  messages,
 });
+
+messages.push(...second.response.messages);
 ```
 
-The response metadata continues to report the request-level reasoning effort,
-not the effective effort selected by `reasoningEffortUpdate`. Configuration
-updates are not supported with `reasoningMode: 'pro'` or `truncation: 'auto'`.
+<Note>
+  The OpenAI Responses provider sends each message-level effort update as a
+  `configuration_update` input item.
+</Note>
+
+Message-level updates also work with `streamText` and `previousResponseId`.
+
+##### Restrictions
+
+Effort updates are supported on GPT-6-family models with these settings:
+
+| Setting             | Required value         |
+| ------------------- | ---------------------- |
+| `reasoningMode`     | `'standard'` (default) |
+| `truncation`        | `'disabled'` (default) |
+
+- 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.
+
+<Note>
+  Effort update messages are sent even if `systemMessageMode` is set to
+  `remove`.
+</Note>
+
+##### 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.117",
+  "version": "3.0.119",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -36,8 +36,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "3.0.17",
-    "@ai-sdk/provider-utils": "4.0.54"
+    "@ai-sdk/provider": "3.0.18",
+    "@ai-sdk/provider-utils": "4.0.55"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

package/src/index.ts

@@ -2,6 +2,7 @@ export { createOpenAI, openai } from './openai-provider';
 export type { OpenAIProvider, OpenAIProviderSettings } from './openai-provider';
 export type {
   OpenAILanguageModelResponsesOptions,
+  OpenAIResponsesSystemMessageOptions,
   /** @deprecated Use `OpenAILanguageModelResponsesOptions` instead. */
   OpenAILanguageModelResponsesOptions as OpenAIResponsesProviderOptions,
 } from './responses/openai-responses-options';

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

@@ -16,6 +16,7 @@ import {
   type ToolNameMapping,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
+import { openaiResponsesSystemMessageOptionsSchema } from './openai-responses-options';
 import {
   applyPatchInputSchema,
   applyPatchOutputSchema,
@@ -330,6 +331,7 @@ export async function convertToOpenAIResponsesInput({
   store,
   hasConversation = false,
   hasPreviousResponseId = false,
+  configurationUpdateUnsupportedReason,
   hasLocalShellTool = false,
   hasShellTool = false,
   hasApplyPatchTool = false,
@@ -346,6 +348,7 @@ export async function convertToOpenAIResponsesInput({
   store: boolean;
   hasConversation?: boolean; // when true, skip assistant messages that already have item IDs
   hasPreviousResponseId?: boolean; // when true, skip reasoning and function-call items that already exist in the previous response chain
+  configurationUpdateUnsupportedReason?: string;
   hasLocalShellTool?: boolean;
   hasShellTool?: boolean;
   hasApplyPatchTool?: boolean;
@@ -371,6 +374,42 @@ export async function convertToOpenAIResponsesInput({
   for (const { role, content, providerOptions } of prompt) {
     switch (role) {
       case 'system': {
+        // Keep effort updates at their original positions so they apply to
+        // the same parts of the conversation when the history is sent again.
+        let options = await parseProviderOptions({
+          provider: providerOptionsName,
+          providerOptions,
+          schema: openaiResponsesSystemMessageOptionsSchema,
+        });
+        if (options == null && providerOptionsName !== 'openai') {
+          options = await parseProviderOptions({
+            provider: 'openai',
+            providerOptions,
+            schema: openaiResponsesSystemMessageOptionsSchema,
+          });
+        }
+        const effort = options?.reasoningEffortUpdate;
+        if (effort != null) {
+          const unsupportedReason =
+            content !== ''
+              ? 'Message-level reasoningEffortUpdate requires empty system message content.'
+              : configurationUpdateUnsupportedReason;
+
+          if (unsupportedReason != null) {
+            throw new UnsupportedFunctionalityError({
+              functionality: 'Message-level reasoningEffortUpdate',
+              message: unsupportedReason,
+            });
+          }
+
+          input.push({
+            type: 'configuration_update',
+            reasoning: { effort },
+          });
+          // The control is independent of systemMessageMode's text handling.
+          break;
+        }
+
         switch (systemMessageMode) {
           case 'system': {
             const promptCacheBreakpoint = getPromptCacheBreakpoint(

package/src/responses/openai-responses-language-model.ts

@@ -1,4 +1,5 @@
 import {
+  UnsupportedFunctionalityError,
   APICallError,
   type JSONValue,
   type LanguageModelV3,
@@ -72,6 +73,7 @@ import {
 import {
   openaiLanguageModelResponsesOptionsSchema,
   TOP_LOGPROBS_MAX,
+  type OpenAILanguageModelResponsesOptions,
   type OpenAIResponsesModelId,
 } from './openai-responses-options';
 import { prepareResponsesTools } from './openai-responses-prepare-tools';
@@ -108,6 +110,30 @@ function extractApprovalRequestIdToToolCallIdMapping(
   return mapping;
 }
 
+/**
+ * Enforces OpenAI's configuration update restrictions for reasoningEffortUpdate,
+ * returning a string describing the unsupported reason if any.
+ *
+ * @see https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation
+ */
+function getConfigurationUpdateUnsupportedReason({
+  modelCapabilities,
+  options,
+}: {
+  modelCapabilities: { supportsConfigurationUpdate: boolean };
+  options: OpenAILanguageModelResponsesOptions | undefined;
+}): string | undefined {
+  if (!modelCapabilities.supportsConfigurationUpdate) {
+    return 'reasoningEffortUpdate is only supported by GPT-6 and later models';
+  }
+
+  if (options?.reasoningMode === 'pro' || options?.truncation === 'auto') {
+    return 'reasoningEffortUpdate requires standard reasoning mode without automatic truncation';
+  }
+
+  return undefined;
+}
+
 export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
   readonly specificationVersion = 'v3';
 
@@ -246,9 +272,16 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
       supportsAsyncToolCalling: modelCapabilities.supportsAsyncToolCalling,
     });
 
+    const configurationUpdateUnsupportedReason =
+      getConfigurationUpdateUnsupportedReason({
+        modelCapabilities,
+        options: openaiOptions,
+      });
+
     const { input, warnings: inputWarnings } =
       await convertToOpenAIResponsesInput({
         prompt,
+        configurationUpdateUnsupportedReason,
         toolNameMapping,
         systemMessageMode:
           openaiOptions?.systemMessageMode ??
@@ -276,25 +309,41 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
     warnings.push(...inputWarnings);
 
     const reasoningEffortUpdate = openaiOptions?.reasoningEffortUpdate;
-    const configurationUpdateIsSupported =
-      reasoningEffortUpdate == null ||
-      (modelCapabilities.supportsConfigurationUpdate &&
-        openaiOptions?.reasoningMode !== 'pro' &&
-        openaiOptions?.truncation !== 'auto');
-
-    if (reasoningEffortUpdate != null && !configurationUpdateIsSupported) {
+    if (
+      reasoningEffortUpdate != null &&
+      configurationUpdateUnsupportedReason != null
+    ) {
       warnings.push({
         type: 'unsupported',
         feature: 'reasoningEffortUpdate',
-        details: !modelCapabilities.supportsConfigurationUpdate
-          ? 'reasoningEffortUpdate is only supported by GPT-6 and later models'
-          : 'reasoningEffortUpdate requires standard reasoning mode without automatic truncation',
+        details: configurationUpdateUnsupportedReason,
       });
     } else if (reasoningEffortUpdate != null) {
-      input.unshift({
-        type: 'configuration_update',
-        reasoning: { effort: reasoningEffortUpdate },
-      });
+      const firstItem = input[0];
+      // If the first item already sets this effort, prepending another update
+      // would create an adjacent pair that OpenAI rejects.
+      if (
+        firstItem?.type !== 'configuration_update' ||
+        firstItem.reasoning.effort !== reasoningEffortUpdate
+      ) {
+        input.unshift({
+          type: 'configuration_update',
+          reasoning: { effort: reasoningEffortUpdate },
+        });
+      }
+    }
+
+    // Conversion and prepending can make updates adjacent, so check afterward
+    // to catch combinations that OpenAI would reject.
+    for (let i = 1; i < input.length; i++) {
+      if (
+        input[i - 1].type === 'configuration_update' &&
+        input[i].type === 'configuration_update'
+      ) {
+        throw new UnsupportedFunctionalityError({
+          functionality: 'Adjacent reasoning effort configuration updates',
+        });
+      }
     }
 
     const strictJsonSchema = openaiOptions?.strictJsonSchema ?? true;

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

@@ -405,3 +405,25 @@ export const openaiLanguageModelResponsesOptionsSchema = lazySchema(() =>
 export type OpenAILanguageModelResponsesOptions = InferSchema<
   typeof openaiLanguageModelResponsesOptionsSchema
 >;
+
+export const openaiResponsesSystemMessageOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /**
+       * Emit a configuration update at this position in Responses history.
+       * Requires empty system message content and the same supported
+       * configuration as the request-level reasoningEffortUpdate option.
+       * Unsupported historical updates throw instead of being omitted.
+       *
+       * @see https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation
+       */
+      reasoningEffortUpdate: z
+        .enum(['low', 'medium', 'high', 'xhigh', 'max'])
+        .optional(),
+    }),
+  ),
+);
+
+export type OpenAIResponsesSystemMessageOptions = InferSchema<
+  typeof openaiResponsesSystemMessageOptionsSchema
+>;