fix: #2778 keep LiteLLM reasoning_effort portable across providers (#2782)

Author: seratch

src/agents/extensions/models/litellm_model.py

@@ -159,6 +159,45 @@ def get_retry_advice(self, request: ModelRetryAdviceRequest) -> ModelRetryAdvice
         # Reuse the same normalization to expose retry-after and explicit retry/no-retry hints.
         return get_openai_retry_advice(request)
 
+    def _get_reasoning_effort(self, model_settings: ModelSettings) -> Any | None:
+        """
+        Resolve the top-level LiteLLM reasoning_effort argument for the chat-completions path.
+
+        LiteLLM's public acompletion() surface accepts a scalar reasoning_effort value. Keep the
+        ModelSettings.reasoning path aligned with that contract and leave extra_body / extra_args as
+        the explicit escape hatches for advanced provider-specific overrides.
+        """
+        reasoning_effort: Any | None = None
+
+        if model_settings.reasoning:
+            reasoning_effort = model_settings.reasoning.effort
+            if model_settings.reasoning.summary is not None:
+                logger.warning(
+                    "LitellmModel does not forward Reasoning.summary on the LiteLLM "
+                    "chat-completions path; ignoring summary and passing reasoning_effort only."
+                )
+
+        # Enable developers to pass non-OpenAI compatible reasoning_effort data like "none".
+        # Priority order:
+        #  1. model_settings.reasoning.effort
+        #  2. model_settings.extra_body["reasoning_effort"]
+        #  3. model_settings.extra_args["reasoning_effort"]
+        if (
+            reasoning_effort is None
+            and isinstance(model_settings.extra_body, dict)
+            and "reasoning_effort" in model_settings.extra_body
+        ):
+            reasoning_effort = model_settings.extra_body["reasoning_effort"]
+
+        if (
+            reasoning_effort is None
+            and model_settings.extra_args
+            and "reasoning_effort" in model_settings.extra_args
+        ):
+            reasoning_effort = model_settings.extra_args["reasoning_effort"]
+
+        return reasoning_effort
+
     async def get_response(
         self,
         system_instructions: str | None,
@@ -456,37 +495,7 @@ async def _fetch_response(
                 f"Response format: {response_format}\n"
             )
 
-        # Build reasoning_effort - use dict only when summary is present (OpenAI feature)
-        # Otherwise pass string for backward compatibility with all providers
-        reasoning_effort: dict[str, Any] | str | None = None
-        if model_settings.reasoning:
-            if model_settings.reasoning.summary is not None:
-                # Dict format when summary is needed (OpenAI only)
-                reasoning_effort = {
-                    "effort": model_settings.reasoning.effort,
-                    "summary": model_settings.reasoning.summary,
-                }
-            elif model_settings.reasoning.effort is not None:
-                # String format for compatibility with all providers
-                reasoning_effort = model_settings.reasoning.effort
-
-        # Enable developers to pass non-OpenAI compatible reasoning_effort data like "none"
-        # Priority order:
-        #  1. model_settings.reasoning (effort + summary)
-        #  2. model_settings.extra_body["reasoning_effort"]
-        #  3. model_settings.extra_args["reasoning_effort"]
-        if (
-            reasoning_effort is None  # Unset in model_settings
-            and isinstance(model_settings.extra_body, dict)
-            and "reasoning_effort" in model_settings.extra_body
-        ):
-            reasoning_effort = model_settings.extra_body["reasoning_effort"]
-        if (
-            reasoning_effort is None  # Unset in both model_settings and model_settings.extra_body
-            and model_settings.extra_args
-            and "reasoning_effort" in model_settings.extra_args
-        ):
-            reasoning_effort = model_settings.extra_args["reasoning_effort"]
+        reasoning_effort = self._get_reasoning_effort(model_settings)
 
         stream_options = None
         if stream and model_settings.include_usage is not None:

tests/models/test_litellm_extra_body.py

@@ -1,3 +1,5 @@
+import logging
+
 import litellm
 import pytest
 from litellm.types.utils import Choices, Message, ModelResponse, Usage
@@ -160,15 +162,22 @@ async def fake_acompletion(model, messages=None, **kwargs):
 
 @pytest.mark.allow_call_model_methods
 @pytest.mark.asyncio
-async def test_reasoning_summary_is_preserved(monkeypatch):
+@pytest.mark.parametrize(
+    "model_name",
+    [
+        "openai/gpt-5-mini",
+        "anthropic/claude-sonnet-4-5",
+        "gemini/gemini-2.5-pro",
+    ],
+)
+async def test_reasoning_summary_uses_scalar_effort_and_warns(
+    monkeypatch, caplog: pytest.LogCaptureFixture, model_name: str
+):
     """
-    Ensure reasoning.summary is preserved when passing ModelSettings.reasoning.
-
-    This test verifies the fix for GitHub issue:
-    https://github.com/BerriAI/litellm/issues/17428
+    Ensure reasoning.summary does not change the LiteLLM chat-completions argument shape.
 
-    Previously, only reasoning.effort was extracted, losing the summary field.
-    Now we pass a dict with both effort and summary to LiteLLM.
+    LitellmModel should continue to pass a scalar reasoning_effort value and warn that summary
+    is ignored on this path, regardless of the provider encoded in the model string.
     """
     from openai.types.shared import Reasoning
 
@@ -184,18 +193,24 @@ async def fake_acompletion(model, messages=None, **kwargs):
     settings = ModelSettings(
         reasoning=Reasoning(effort="medium", summary="auto"),
     )
-    model = LitellmModel(model="test-model")
-
-    await model.get_response(
-        system_instructions=None,
-        input=[],
-        model_settings=settings,
-        tools=[],
-        output_schema=None,
-        handoffs=[],
-        tracing=ModelTracing.DISABLED,
-        previous_response_id=None,
-    )
-
-    # Both effort and summary should be preserved in the dict
-    assert captured["reasoning_effort"] == {"effort": "medium", "summary": "auto"}
+    model = LitellmModel(model=model_name)
+
+    with caplog.at_level(logging.WARNING, logger="openai.agents"):
+        await model.get_response(
+            system_instructions=None,
+            input=[],
+            model_settings=settings,
+            tools=[],
+            output_schema=None,
+            handoffs=[],
+            tracing=ModelTracing.DISABLED,
+            previous_response_id=None,
+        )
+
+    assert captured["reasoning_effort"] == "medium"
+    warning_messages = [
+        record.message
+        for record in caplog.records
+        if "does not forward Reasoning.summary" in record.message
+    ]
+    assert len(warning_messages) == 1