feat: switch the default model to a newer mini model (affecting only when a model is unset) (#3147)

Author: seratch

src/agents/agent.py

@@ -34,8 +34,6 @@
 from .model_settings import ModelSettings
 from .models.default_models import (
     get_default_model_settings,
-    gpt_5_reasoning_settings_required,
-    is_gpt_5_default,
 )
 from .models.interface import Model
 from .prompts import DynamicPromptFunction, Prompt, PromptUtil
@@ -153,6 +151,20 @@ class MCPConfig(TypedDict):
     """
 
 
+def _initial_model_settings_for_model(model: str | Model | None) -> ModelSettings:
+    if model is None:
+        return get_default_model_settings()
+    if isinstance(model, str):
+        return get_default_model_settings(model)
+    return ModelSettings()
+
+
+def _model_settings_match_implicit_model_defaults(
+    model: str | Model | None, model_settings: ModelSettings
+) -> bool:
+    return model_settings == _initial_model_settings_for_model(model)
+
+
 @dataclass
 class AgentBase(Generic[TContext]):
     """Base class for `Agent` and `RealtimeAgent`."""
@@ -265,7 +277,7 @@ class Agent(AgentBase, Generic[TContext]):
     """The model implementation to use when invoking the LLM.
 
     By default, if not set, the agent will use the default model configured in
-    `agents.models.get_default_model()` (currently "gpt-4.1").
+    `agents.models.get_default_model()` (currently "gpt-5.4-mini").
     """
 
     model_settings: ModelSettings = field(default_factory=get_default_model_settings)
@@ -383,25 +395,8 @@ def __post_init__(self):
                 f"got {type(self.model_settings).__name__}"
             )
 
-        if (
-            # The user sets a non-default model
-            self.model is not None
-            and (
-                # The default model is gpt-5
-                is_gpt_5_default() is True
-                # However, the specified model is not a gpt-5 model
-                and (
-                    isinstance(self.model, str) is False
-                    or gpt_5_reasoning_settings_required(self.model) is False  # type: ignore
-                )
-                # The model settings are not customized for the specified model
-                and self.model_settings == get_default_model_settings()
-            )
-        ):
-            # 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.
-            self.model_settings = ModelSettings()
+        if self.model is not None and self.model_settings == get_default_model_settings():
+            self.model_settings = _initial_model_settings_for_model(self.model)
 
         if not isinstance(self.input_guardrails, list):
             raise TypeError(
@@ -467,6 +462,12 @@ def clone(self, **kwargs: Any) -> Agent[TContext]:
             new_agent = agent.clone(instructions="New instructions")
             ```
         """
+        if (
+            "model" in kwargs
+            and "model_settings" not in kwargs
+            and _model_settings_match_implicit_model_defaults(self.model, self.model_settings)
+        ):
+            kwargs["model_settings"] = _initial_model_settings_for_model(kwargs["model"])
         return dataclasses.replace(self, **kwargs)
 
     def as_tool(

src/agents/models/default_models.py

@@ -96,7 +96,7 @@ def get_default_model() -> str:
     """
     Returns the default model name.
     """
-    return os.getenv(OPENAI_DEFAULT_MODEL_ENV_VARIABLE_NAME, "gpt-4.1").lower()
+    return os.getenv(OPENAI_DEFAULT_MODEL_ENV_VARIABLE_NAME, "gpt-5.4-mini").lower()
 
 
 def get_default_model_settings(model: str | None = None) -> ModelSettings:

src/agents/run_internal/run_loop.py

@@ -179,6 +179,7 @@
     get_all_tools,
     get_handoffs,
     get_model,
+    get_model_settings,
     get_output_schema,
     maybe_filter_model_input,
     validate_run_hooks,
@@ -1341,7 +1342,7 @@ def _tool_search_fingerprint(raw_item: Any) -> str:
 
     handoffs = await get_handoffs(execution_agent, context_wrapper)
     model = get_model(execution_agent, run_config)
-    model_settings = execution_agent.model_settings.resolve(run_config.model_settings)
+    model_settings = get_model_settings(execution_agent, run_config)
     model_settings = maybe_reset_tool_choice(public_agent, tool_use_tracker, model_settings)
 
     final_response: ModelResponse | None = None
@@ -1825,7 +1826,7 @@ async def get_new_response(
         filtered.input = deduplicate_input_items_preferring_latest(filtered.input)
 
     model = get_model(execution_agent, run_config)
-    model_settings = execution_agent.model_settings.resolve(run_config.model_settings)
+    model_settings = get_model_settings(execution_agent, run_config)
     model_settings = maybe_reset_tool_choice(public_agent, tool_use_tracker, model_settings)
 
     if server_conversation_tracker is not None:

src/agents/run_internal/turn_preparation.py

@@ -10,6 +10,8 @@
 from ..handoffs import Handoff, handoff
 from ..items import TResponseInputItem
 from ..lifecycle import AgentHooksBase, RunHooks, RunHooksBase
+from ..model_settings import ModelSettings
+from ..models.default_models import get_default_model_settings
 from ..models.interface import Model
 from ..run_config import CallModelData, ModelInputData, RunConfig
 from ..run_context import RunContextWrapper, TContext
@@ -24,6 +26,7 @@
     "get_handoffs",
     "get_all_tools",
     "get_model",
+    "get_model_settings",
 ]
 
 
@@ -130,3 +133,27 @@ def get_model(agent: Agent[Any], run_config: RunConfig) -> Model:
         return agent.model
 
     return run_config.model_provider.get_model(agent.model)
+
+
+def _implicit_model_settings_for_agent(agent: Agent[Any]) -> ModelSettings:
+    if agent.model is None:
+        return get_default_model_settings()
+    if isinstance(agent.model, str):
+        return get_default_model_settings(agent.model)
+    return ModelSettings()
+
+
+def _model_settings_for_resolved_name(agent: Agent[Any], run_config: RunConfig) -> ModelSettings:
+    if isinstance(run_config.model, str):
+        return get_default_model_settings(run_config.model)
+    if isinstance(run_config.model, Model):
+        return ModelSettings()
+    return _implicit_model_settings_for_agent(agent)
+
+
+def get_model_settings(agent: Agent[Any], run_config: RunConfig) -> ModelSettings:
+    """Resolve model settings, keeping implicit defaults aligned with the resolved model name."""
+    model_settings = agent.model_settings
+    if model_settings == _implicit_model_settings_for_agent(agent):
+        model_settings = _model_settings_for_resolved_name(agent, run_config)
+    return model_settings.resolve(run_config.model_settings)

tests/models/test_default_models.py

@@ -22,11 +22,11 @@ def _gpt_5_default_settings(
     return ModelSettings(reasoning=Reasoning(effort=reasoning_effort), verbosity="low")
 
 
-def test_default_model_is_gpt_4_1():
-    assert get_default_model() == "gpt-4.1"
-    assert is_gpt_5_default() is False
-    assert gpt_5_reasoning_settings_required(get_default_model()) is False
-    assert get_default_model_settings().reasoning is None
+def test_default_model_is_gpt_5_4_mini():
+    assert get_default_model() == "gpt-5.4-mini"
+    assert is_gpt_5_default() is True
+    assert gpt_5_reasoning_settings_required(get_default_model()) is True
+    assert get_default_model_settings() == _gpt_5_default_settings("none")
 
 
 @patch.dict(os.environ, {"OPENAI_DEFAULT_MODEL": "gpt-5.4"})
@@ -139,6 +139,39 @@ def test_agent_uses_gpt_5_default_model_settings():
     assert agent.model_settings.verbosity == "low"
 
 
+def test_agent_uses_model_specific_settings_for_explicit_gpt_5_models():
+    """Agent should not apply the fallback model's GPT-5 settings to explicit GPT-5 models."""
+    agent = Agent(name="test", model="gpt-5")
+    assert agent.model == "gpt-5"
+    assert agent.model_settings == get_default_model_settings("gpt-5")
+    assert agent.model_settings.reasoning.effort == "low"  # type: ignore[union-attr]
+
+
+def test_agent_uses_empty_settings_for_explicit_non_gpt_5_models():
+    """Agent should not apply GPT-5 defaults to explicit non-GPT-5 models."""
+    agent = Agent(name="test", model="gpt-4.1")
+    assert agent.model == "gpt-4.1"
+    assert agent.model_settings == ModelSettings()
+
+
+def test_agent_clone_recomputes_implicit_settings_when_model_changes():
+    """Agent.clone should keep implicit model settings aligned with the cloned model."""
+    agent = Agent(name="test", model="gpt-5")
+    cloned = agent.clone(model="gpt-5.4-mini")
+    assert cloned.model == "gpt-5.4-mini"
+    assert cloned.model_settings == get_default_model_settings("gpt-5.4-mini")
+    assert cloned.model_settings.reasoning.effort == "none"  # type: ignore[union-attr]
+
+
+def test_agent_clone_preserves_explicit_settings_when_model_changes():
+    """Agent.clone should not recompute model settings that were explicitly customized."""
+    model_settings = ModelSettings(temperature=0.3)
+    agent = Agent(name="test", model="gpt-5", model_settings=model_settings)
+    cloned = agent.clone(model="gpt-5.4-mini")
+    assert cloned.model == "gpt-5.4-mini"
+    assert cloned.model_settings == model_settings
+
+
 @patch.dict(os.environ, {"OPENAI_DEFAULT_MODEL": "gpt-5"})
 def test_agent_resets_model_settings_for_non_gpt_5_models():
     """Agent should reset default GPT-5 settings when using a non-GPT-5 model."""

tests/test_run_config.py

@@ -3,6 +3,7 @@
 import pytest
 
 from agents import Agent, RunConfig, Runner
+from agents.model_settings import ModelSettings
 from agents.models.interface import Model, ModelProvider
 
 from .fake_model import FakeModel
@@ -56,6 +57,52 @@ async def test_run_config_model_name_override_takes_precedence() -> None:
     assert result.final_output == "override-name"
 
 
+@pytest.mark.asyncio
+async def test_run_config_model_name_override_uses_model_specific_default_settings(
+    monkeypatch,
+) -> None:
+    """
+    When RunConfig sets a model name, implicit settings should match that model name rather
+    than the default fallback model.
+    """
+    monkeypatch.setenv("OPENAI_DEFAULT_MODEL", "gpt-5.4-mini")
+    fake_model = FakeModel(initial_output=[get_text_message("override-name")])
+    provider = DummyProvider(model_to_return=fake_model)
+    agent = Agent(name="test")
+    run_config = RunConfig(model="gpt-5", model_provider=provider)
+    result = await Runner.run(agent, input="any", run_config=run_config)
+    assert result.final_output == "override-name"
+    assert fake_model.first_turn_args is not None
+    model_settings = fake_model.first_turn_args["model_settings"]
+    assert model_settings.reasoning.effort == "low"
+    assert model_settings.verbosity == "low"
+
+
+@pytest.mark.asyncio
+async def test_run_config_model_settings_override_implicit_model_specific_defaults(
+    monkeypatch,
+) -> None:
+    """
+    RunConfig model settings should overlay the implicit defaults for the resolved model name.
+    """
+    monkeypatch.setenv("OPENAI_DEFAULT_MODEL", "gpt-5.4-mini")
+    fake_model = FakeModel(initial_output=[get_text_message("override-name")])
+    provider = DummyProvider(model_to_return=fake_model)
+    agent = Agent(name="test")
+    run_config = RunConfig(
+        model="gpt-5",
+        model_provider=provider,
+        model_settings=ModelSettings(temperature=0.3),
+    )
+    result = await Runner.run(agent, input="any", run_config=run_config)
+    assert result.final_output == "override-name"
+    assert fake_model.first_turn_args is not None
+    model_settings = fake_model.first_turn_args["model_settings"]
+    assert model_settings.reasoning.effort == "low"
+    assert model_settings.verbosity == "low"
+    assert model_settings.temperature == 0.3
+
+
 @pytest.mark.asyncio
 async def test_run_config_model_override_object_takes_precedence() -> None:
     """