Add a quick opt-in option to switch to gpt-5 and fix issues around gpt-5

Author: seratch

examples/basic/hello-world-gpt-5.ts

@@ -21,7 +21,8 @@ async function main() {
     outputType: output,
   });
 
-  const prompt = 'Tell me about recursion in programming.';
+  const prompt =
+    'Tell me about recursion in programming. Quickly responding with a single answer is fine.';
   const result = await run(agent, prompt);
   console.log(result.finalOutput);
 

examples/basic/hello-world.ts

@@ -6,7 +6,10 @@ async function main() {
     instructions: 'You only respond in haikus.',
   });
 
-  const result = await run(agent, 'Tell me about recursion in programming.');
+  const result = await run(
+    agent,
+    'Tell me about recursion in programming. Quickly responding with a single answer is fine.',
+  );
   console.log(result.finalOutput);
   // Example output:
   // Function calls itself,

examples/basic/reasoning.ts

@@ -7,13 +7,16 @@ const THINKING_PREFIX = styleText(['bgGray', 'black'], 'Thought');
 async function main() {
   const agent = new Agent({
     name: 'Agent',
-    model: 'o3',
+    model: 'gpt-5',
     modelSettings: {
       providerData: {
         reasoning: {
           effort: 'high',
           summary: 'auto',
         },
+        text: {
+          verbosity: 'high',
+        },
       },
     },
   });

examples/financial-research-agent/agents.ts

@@ -46,7 +46,7 @@ export type FinancialSearchPlan = z.infer<typeof FinancialSearchPlan>;
 export const plannerAgent = new Agent({
   name: 'FinancialPlannerAgent',
   instructions: plannerPrompt,
-  model: 'o3-mini',
+  model: 'gpt-5-mini',
   outputType: FinancialSearchPlan,
 });
 
@@ -69,6 +69,7 @@ Focus on key numbers, events, or quotes that will be useful to a financial analy
 export const searchAgent = new Agent({
   name: 'FinancialSearchAgent',
   instructions: searchAgentPrompt,
+  model: 'gpt-4.1',
   tools: [webSearchTool()],
   modelSettings: { toolChoice: 'required' },
 });
@@ -92,7 +93,7 @@ export type VerificationResult = z.infer<typeof VerificationResult>;
 export const verifierAgent = new Agent({
   name: 'VerificationAgent',
   instructions: verifierPrompt,
-  model: 'gpt-4o',
+  model: 'gpt-4.1',
   outputType: VerificationResult,
 });
 

packages/agents-core/src/agent.ts

@@ -4,6 +4,11 @@ import type { InputGuardrail, OutputGuardrail } from './guardrail';
 import { AgentHooks } from './lifecycle';
 import { getAllMcpTools, type MCPServer } from './mcp';
 import type { Model, ModelSettings, Prompt } from './model';
+import {
+  getDefaultModelSettings,
+  gpt5ReasoningSettingsRequired,
+  isGpt5Default,
+} from './defaultModel';
 import type { RunContext } from './runContext';
 import {
   type FunctionTool,
@@ -165,8 +170,10 @@ export interface AgentConfiguration<
   handoffOutputTypeWarningEnabled?: boolean;
 
   /**
-   * The model implementation to use when invoking the LLM. By default, if not set, the agent will
-   * use the default model configured in modelSettings.defaultModel
+   * The model implementation to use when invoking the LLM.
+   *
+   * By default, if not set, the agent will use the default model returned by
+   * getDefaultModel (currently "gpt-4.1").
    */
   model: string | Model;
 
@@ -348,7 +355,7 @@ export class Agent<
     this.handoffDescription = config.handoffDescription ?? '';
     this.handoffs = config.handoffs ?? [];
     this.model = config.model ?? '';
-    this.modelSettings = config.modelSettings ?? {};
+    this.modelSettings = config.modelSettings ?? getDefaultModelSettings();
     this.tools = config.tools ?? [];
     this.mcpServers = config.mcpServers ?? [];
     this.inputGuardrails = config.inputGuardrails ?? [];
@@ -359,6 +366,23 @@ export class Agent<
     this.toolUseBehavior = config.toolUseBehavior ?? 'run_llm_again';
     this.resetToolChoice = config.resetToolChoice ?? true;
 
+    if (
+      // The user sets a non-default model
+      config.model !== undefined &&
+      // The default model is gpt-5
+      isGpt5Default() &&
+      // However, the specified model is not a gpt-5 model
+      (typeof config.model !== 'string' ||
+        !gpt5ReasoningSettingsRequired(config.model)) &&
+      // The model settings are not customized for the specified model
+      config.modelSettings === undefined
+    ) {
+      // In this scenario, we should use a generic model settings
+      // because non-gpt-5 models are not compatible with the default gpt-5 model settings.
+      // This is a best-effort attempt to make the agent work with non-gpt-5 models.
+      this.modelSettings = {};
+    }
+
     // --- Runtime warning for handoff output type compatibility ---
     if (
       config.handoffOutputTypeWarningEnabled === undefined ||

packages/agents-core/src/defaultModel.ts

@@ -0,0 +1,56 @@
+import { loadEnv } from './config';
+import { ModelSettings } from './model';
+
+export const OPENAI_DEFAULT_MODEL_ENV_VARIABLE_NAME = 'OPENAI_DEFAULT_MODEL';
+
+/**
+ * Returns True if the model name is a GPT-5 model and reasoning settings are required.
+ */
+export function gpt5ReasoningSettingsRequired(modelName: string): boolean {
+  if (modelName.startsWith('gpt-5-chat')) {
+    // gpt-5-chat-latest does not require reasoning settings
+    return false;
+  }
+  // matches any of gpt-5 models
+  return modelName.startsWith('gpt-5');
+}
+
+/**
+ * Returns True if the default model is a GPT-5 model.
+ * This is used to determine if the default model settings are compatible with GPT-5 models.
+ * If the default model is not a GPT-5 model, the model settings are compatible with other models.
+ */
+export function isGpt5Default(): boolean {
+  return gpt5ReasoningSettingsRequired(getDefaultModel());
+}
+
+/**
+ * Returns the default model name.
+ */
+export function getDefaultModel(): string {
+  const env = loadEnv();
+  return (
+    env[OPENAI_DEFAULT_MODEL_ENV_VARIABLE_NAME]?.toLowerCase() ?? 'gpt-4.1'
+  );
+}
+
+/**
+ * Returns the default model settings.
+ * If the default model is a GPT-5 model, returns the GPT-5 default model settings.
+ * Otherwise, returns the legacy default model settings.
+ */
+export function getDefaultModelSettings(model?: string): ModelSettings {
+  const _model = model ?? getDefaultModel();
+  if (gpt5ReasoningSettingsRequired(_model)) {
+    return {
+      providerData: {
+        // We chose "low" instead of "minimal" because some of the built-in tools
+        // (e.g., file search, image generation, etc.) do not support "minimal"
+        // If you want to use "minimal" reasoning effort, you can pass your own model settings
+        reasoning: { effort: 'low' },
+        text: { verbosity: 'low' },
+      },
+    };
+  }
+  return {};
+}

packages/agents-core/src/index.ts

@@ -94,6 +94,13 @@ export {
   SerializedTool,
   SerializedOutputType,
 } from './model';
+export {
+  OPENAI_DEFAULT_MODEL_ENV_VARIABLE_NAME,
+  gpt5ReasoningSettingsRequired,
+  getDefaultModel,
+  getDefaultModelSettings,
+  isGpt5Default,
+} from './defaultModel';
 export { setDefaultModelProvider } from './providers';
 export { RunResult, StreamedRunResult } from './result';
 export {

packages/agents-core/src/run.ts

@@ -54,6 +54,7 @@ import { RunAgentUpdatedStreamEvent, RunRawModelStreamEvent } from './events';
 import { RunState } from './runState';
 import { StreamEventResponseCompleted } from './types/protocol';
 import { convertAgentOutputTypeToSerializable } from './utils/tools';
+import { gpt5ReasoningSettingsRequired, isGpt5Default } from './defaultModel';
 
 const DEFAULT_MAX_TURNS = 10;
 
@@ -369,6 +370,14 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
               ...this.config.modelSettings,
               ...state._currentAgent.modelSettings,
             };
+            const agentModel = state._currentAgent.model;
+            const agentModelSettings = state._currentAgent.modelSettings;
+            modelSettings = sanitizeModelSettingsForNonGpt5Runner(
+              agentModel,
+              agentModelSettings,
+              model,
+              modelSettings,
+            );
             modelSettings = maybeResetToolChoice(
               state._currentAgent,
               state._toolUseTracker,
@@ -709,6 +718,14 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
             ...this.config.modelSettings,
             ...currentAgent.modelSettings,
           };
+          const agentModel = currentAgent.model;
+          const agentModelSettings = currentAgent.modelSettings;
+          modelSettings = sanitizeModelSettingsForNonGpt5Runner(
+            agentModel,
+            agentModelSettings,
+            model,
+            modelSettings,
+          );
           modelSettings = maybeResetToolChoice(
             currentAgent,
             result.state._toolUseTracker,
@@ -1029,3 +1046,36 @@ export async function run<TAgent extends Agent<any, any>, TContext = undefined>(
     return await runner.run(agent, input, options);
   }
 }
+
+/**
+ * When the default model is a GPT-5 variant, agents may carry GPT-5-specific providerData
+ * (e.g., reasoning effort, text verbosity). If a run resolves to a non-GPT-5 model and the
+ * agent relied on the default model (i.e., no explicit model set), these GPT-5-only settings
+ * are incompatible and should be stripped to avoid runtime errors.
+ */
+function sanitizeModelSettingsForNonGpt5Runner(
+  agentModel: string | Model,
+  agentModelSettings: ModelSettings,
+  runnerModel: string | Model,
+  modelSettings: ModelSettings,
+): ModelSettings {
+  if (
+    // gpt-5 is enabled for the default model for agents
+    isGpt5Default() &&
+    // no explicitly set model for the agent
+    typeof agentModel === 'string' &&
+    agentModel === Agent.DEFAULT_MODEL_PLACEHOLDER &&
+    // this runner uses a non-gpt-5 model
+    (typeof runnerModel !== 'string' ||
+      !gpt5ReasoningSettingsRequired(runnerModel)) &&
+    (agentModelSettings.providerData?.reasoning ||
+      agentModelSettings.providerData?.text?.verbosity ||
+      (agentModelSettings.providerData as any)?.reasoning_effort)
+  ) {
+    // the incompatible parameters should be removed to avoid runtime errors
+    delete modelSettings.providerData?.reasoning;
+    delete (modelSettings.providerData as any)?.text?.verbosity;
+    delete (modelSettings.providerData as any)?.reasoning_effort;
+  }
+  return modelSettings;
+}

packages/agents-openai/src/openaiProvider.ts

@@ -1,7 +1,6 @@
-import { Model, ModelProvider } from '@openai/agents-core';
+import { Model, ModelProvider, getDefaultModel } from '@openai/agents-core';
 import OpenAI from 'openai';
 import {
-  DEFAULT_OPENAI_MODEL,
   getDefaultOpenAIClient,
   getDefaultOpenAIKey,
   shouldUseResponsesByDefault,
@@ -65,7 +64,7 @@ export class OpenAIProvider implements ModelProvider {
   }
 
   async getModel(modelName?: string | undefined): Promise<Model> {
-    const model = modelName || DEFAULT_OPENAI_MODEL;
+    const model = modelName || getDefaultModel();
     const useResponses = this.#useResponses ?? shouldUseResponsesByDefault();
 
     if (useResponses) {