fix(openai): default reasoning effort for mini models (#1824)

Co-authored-by: rosetta-livekit-bot[bot] <282703043+rosetta-livekit-bot[bot]@users.noreply.github.com>
Co-authored-by: Chenghao Mou <chenghao.mou@livekit.io>

Author: rosetta-livekit-bot[bot]

.changeset/openai-reasoning-effort-mini.md

@@ -0,0 +1,5 @@
+---
+"@livekit/agents-plugin-openai": patch
+---
+
+Default OpenAI reasoning effort to `none` for `gpt-5.4-mini`. `*-chat-latest` models no longer send a default `reasoning_effort` (Python parity, and the API only accepts `medium` for them).

agents/src/inference/llm.ts

@@ -80,7 +80,7 @@ export interface ChatCompletionOptions extends Record<string, unknown> {
   presence_penalty?: number;
   prompt_cache_key?: string;
   prompt_cache_retention?: 'in_memory' | '24h';
-  reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
+  reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high';
   safety_identifier?: string;
   seed?: number;
   service_tier?: 'auto' | 'default' | 'flex' | 'scale' | 'priority';

plugins/openai/src/llm.ts

@@ -12,10 +12,12 @@ import type {
   MetaChatModels,
   OctoChatModels,
   PerplexityChatModels,
+  ReasoningEffort,
   TelnyxChatModels,
   TogetherChatModels,
   XAIChatModels,
 } from './models.js';
+import { defaultReasoningEffort } from './models.js';
 
 export interface LLMOptions {
   model: string | ChatModels;
@@ -31,6 +33,7 @@ export interface LLMOptions {
   maxCompletionTokens?: number;
   serviceTier?: string;
   store?: boolean;
+  reasoningEffort?: ReasoningEffort;
   strictToolSchema?: boolean;
 }
 
@@ -66,6 +69,7 @@ export class LLM extends llm.LLM {
     super();
 
     this.#opts = { ...defaultLLMOptions, ...opts };
+    this.#opts.reasoningEffort ??= defaultReasoningEffort(this.#opts.model);
     this.#providerFmt = providerFmt;
     if (this.#opts.apiKey === undefined && !this.#opts.client) {
       throw new Error('OpenAI API key is required, whether as an argument or as $OPENAI_API_KEY');
@@ -513,6 +517,10 @@ export class LLM extends llm.LLM {
       extras.store = this.#opts.store;
     }
 
+    if (this.#opts.reasoningEffort !== undefined) {
+      extras.reasoning_effort = this.#opts.reasoningEffort;
+    }
+
     parallelToolCalls =
       parallelToolCalls !== undefined ? parallelToolCalls : this.#opts.parallelToolCalls;
     if (

plugins/openai/src/models.ts

@@ -4,6 +4,7 @@
 
 export type ChatModels =
   | 'gpt-5.4'
+  | 'gpt-5.4-mini'
   | 'gpt-5.3-chat-latest'
   | 'gpt-5.2'
   | 'gpt-5.2-chat-latest'
@@ -205,16 +206,30 @@ export type MetaChatModels =
   | 'Llama-3.3-70B-Instruct'
   | 'Llama-3.3-8B-Instruct';
 
+export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high';
+
+export type Reasoning = { effort?: ReasoningEffort | null; [key: string]: unknown };
+
 export function supportsReasoningEffort(model: ChatModels | string): boolean {
   return [
     'gpt-5.4',
-    'gpt-5.3-chat-latest',
+    'gpt-5.4-mini',
     'gpt-5.2',
-    'gpt-5.2-chat-latest',
     'gpt-5.1',
-    'gpt-5.1-chat-latest',
     'gpt-5',
     'gpt-5-mini',
     'gpt-5-nano',
   ].includes(model);
 }
+
+export function defaultReasoningEffort(model: ChatModels | string): ReasoningEffort | undefined {
+  if (!supportsReasoningEffort(model)) {
+    return undefined;
+  }
+
+  if (['gpt-5.1', 'gpt-5.2', 'gpt-5.4', 'gpt-5.4-mini'].includes(model)) {
+    return 'none';
+  }
+
+  return 'minimal';
+}

plugins/openai/src/responses/llm.ts

@@ -12,7 +12,8 @@ import {
   toError,
 } from '@livekit/agents';
 import OpenAI from 'openai';
-import type { ChatModels } from '../models.js';
+import type { ChatModels, Reasoning } from '../models.js';
+import { defaultReasoningEffort } from '../models.js';
 import { toResponsesTools } from '../tool_utils.js';
 import { WSLLM } from '../ws/llm.js';
 
@@ -31,6 +32,8 @@ export interface LLMOptions {
   serviceTier?: string;
   /** Upper bound for the number of tokens that can be generated for a response. */
   maxOutputTokens?: number;
+  /** Configuration options for reasoning models. */
+  reasoning?: Reasoning | null;
 
   /**
    * Whether to use the WebSocket API.
@@ -56,6 +59,13 @@ class ResponsesHttpLLM extends llm.LLM {
     super();
 
     this.#opts = { ...defaultLLMOptions, ...opts };
+    if (this.#opts.reasoning === undefined) {
+      const effort = defaultReasoningEffort(this.#opts.model);
+      if (effort !== undefined) {
+        this.#opts.reasoning = { effort };
+      }
+    }
+
     if (this.#opts.apiKey === undefined && this.#opts.client === undefined) {
       throw new Error('OpenAI API key is required, whether as an argument or as $OPENAI_API_KEY');
     }
@@ -132,6 +142,10 @@ class ResponsesHttpLLM extends llm.LLM {
       modelOptions.max_output_tokens = this.#opts.maxOutputTokens;
     }
 
+    if (this.#opts.reasoning !== undefined) {
+      modelOptions.reasoning = this.#opts.reasoning;
+    }
+
     return new ResponsesHttpLLMStream(this, {
       model: this.#opts.model,
       client: this.#client,

plugins/openai/src/ws/llm.ts

@@ -14,7 +14,8 @@ import {
 } from '@livekit/agents';
 import type OpenAI from 'openai';
 import { WebSocket } from 'ws';
-import type { ChatModels } from '../models.js';
+import type { ChatModels, Reasoning } from '../models.js';
+import { defaultReasoningEffort } from '../models.js';
 import { toResponsesTools } from '../tool_utils.js';
 import type {
   WsOutputItemDoneEvent,
@@ -170,6 +171,8 @@ export interface WSLLMOptions {
   serviceTier?: string;
   /** Upper bound for the number of tokens that can be generated for a response. */
   maxOutputTokens?: number;
+  /** Configuration options for reasoning models. */
+  reasoning?: Reasoning | null;
 }
 
 const defaultLLMOptions: WSLLMOptions = {
@@ -204,6 +207,13 @@ export class WSLLM extends llm.LLM {
     super();
 
     this.#opts = { ...defaultLLMOptions, ...opts };
+    if (this.#opts.reasoning === undefined) {
+      const effort = defaultReasoningEffort(this.#opts.model);
+      if (effort !== undefined) {
+        this.#opts.reasoning = { effort };
+      }
+    }
+
     if (!this.#opts.apiKey) {
       throw new Error('OpenAI API key is required, whether as an argument or as $OPENAI_API_KEY');
     }
@@ -306,6 +316,10 @@ export class WSLLM extends llm.LLM {
       modelOptions.max_output_tokens = this.#opts.maxOutputTokens;
     }
 
+    if (this.#opts.reasoning !== undefined) {
+      modelOptions.reasoning = this.#opts.reasoning;
+    }
+
     let inputChatCtx = chatCtx;
     let prevResponseId: string | undefined;
     const canUseStoredResponse = modelOptions.store !== false;