Allow arbitrary kwargs in model (#842)

Sometimes users want to provide parameters specific to a model provider.
This is an escape hatch.

src/agents/extensions/models/litellm_model.py

@@ -284,6 +284,10 @@ class LitellmModel(Model):
         if model_settings.extra_body and isinstance(model_settings.extra_body, dict):
             extra_kwargs.update(model_settings.extra_body)
 
+        # Add kwargs from model_settings.extra_args, filtering out None values
+        if model_settings.extra_args:
+            extra_kwargs.update(model_settings.extra_args)
+
         ret = await litellm.acompletion(
             model=self.model,
             messages=converted_messages,

src/agents/model_settings.py

@@ -73,6 +73,11 @@ class ModelSettings:
     """Additional headers to provide with the request.
     Defaults to None if not provided."""
 
+    extra_args: dict[str, Any] | None = None
+    """Arbitrary keyword arguments to pass to the model API call.
+    These will be passed directly to the underlying model provider's API.
+    Use with caution as not all models support all parameters."""
+
     def resolve(self, override: ModelSettings | None) -> ModelSettings:
         """Produce a new ModelSettings by overlaying any non-None values from the
         override on top of this instance."""
@@ -84,6 +89,16 @@ class ModelSettings:
             for field in fields(self)
             if getattr(override, field.name) is not None
         }
+
+        # Handle extra_args merging specially - merge dictionaries instead of replacing
+        if self.extra_args is not None or override.extra_args is not None:
+            merged_args = {}
+            if self.extra_args:
+                merged_args.update(self.extra_args)
+            if override.extra_args:
+                merged_args.update(override.extra_args)
+            changes["extra_args"] = merged_args if merged_args else None
+
         return replace(self, **changes)
 
     def to_json_dict(self) -> dict[str, Any]:

src/agents/models/openai_chatcompletions.py

@@ -281,6 +281,7 @@ class OpenAIChatCompletionsModel(Model):
             extra_query=model_settings.extra_query,
             extra_body=model_settings.extra_body,
             metadata=self._non_null_or_not_given(model_settings.metadata),
+            **(model_settings.extra_args or {}),
         )
 
         if isinstance(ret, ChatCompletion):

src/agents/models/openai_responses.py

@@ -266,6 +266,7 @@ class OpenAIResponsesModel(Model):
             store=self._non_null_or_not_given(model_settings.store),
             reasoning=self._non_null_or_not_given(model_settings.reasoning),
             metadata=self._non_null_or_not_given(model_settings.metadata),
+            **(model_settings.extra_args or {}),
         )
 
     def _get_client(self) -> AsyncOpenAI:

tests/model_settings/test_serialization.py

@@ -47,6 +47,7 @@ def test_all_fields_serialization() -> None:
         extra_query={"foo": "bar"},
         extra_body={"foo": "bar"},
         extra_headers={"foo": "bar"},
+        extra_args={"custom_param": "value", "another_param": 42},
     )
 
     # Verify that every single field is set to a non-None value
@@ -57,3 +58,76 @@ def test_all_fields_serialization() -> None:
 
     # Now, lets serialize the ModelSettings instance to a JSON string
     verify_serialization(model_settings)
+
+
+def test_extra_args_serialization() -> None:
+    """Test that extra_args are properly serialized."""
+    model_settings = ModelSettings(
+        temperature=0.5,
+        extra_args={"custom_param": "value", "another_param": 42, "nested": {"key": "value"}},
+    )
+
+    json_dict = model_settings.to_json_dict()
+    assert json_dict["extra_args"] == {
+        "custom_param": "value",
+        "another_param": 42,
+        "nested": {"key": "value"},
+    }
+
+    # Verify serialization works
+    verify_serialization(model_settings)
+
+
+def test_extra_args_resolve() -> None:
+    """Test that extra_args are properly merged in the resolve method."""
+    base_settings = ModelSettings(
+        temperature=0.5, extra_args={"param1": "base_value", "param2": "base_only"}
+    )
+
+    override_settings = ModelSettings(
+        top_p=0.9, extra_args={"param1": "override_value", "param3": "override_only"}
+    )
+
+    resolved = base_settings.resolve(override_settings)
+
+    # Check that regular fields are properly resolved
+    assert resolved.temperature == 0.5  # from base
+    assert resolved.top_p == 0.9  # from override
+
+    # Check that extra_args are properly merged
+    expected_extra_args = {
+        "param1": "override_value",  # override wins
+        "param2": "base_only",  # from base
+        "param3": "override_only",  # from override
+    }
+    assert resolved.extra_args == expected_extra_args
+
+
+def test_extra_args_resolve_with_none() -> None:
+    """Test that resolve works properly when one side has None extra_args."""
+    # Base with extra_args, override with None
+    base_settings = ModelSettings(extra_args={"param1": "value1"})
+    override_settings = ModelSettings(temperature=0.8)
+
+    resolved = base_settings.resolve(override_settings)
+    assert resolved.extra_args == {"param1": "value1"}
+    assert resolved.temperature == 0.8
+
+    # Base with None, override with extra_args
+    base_settings = ModelSettings(temperature=0.5)
+    override_settings = ModelSettings(extra_args={"param2": "value2"})
+
+    resolved = base_settings.resolve(override_settings)
+    assert resolved.extra_args == {"param2": "value2"}
+    assert resolved.temperature == 0.5
+
+
+def test_extra_args_resolve_both_none() -> None:
+    """Test that resolve works when both sides have None extra_args."""
+    base_settings = ModelSettings(temperature=0.5)
+    override_settings = ModelSettings(top_p=0.9)
+
+    resolved = base_settings.resolve(override_settings)
+    assert resolved.extra_args is None
+    assert resolved.temperature == 0.5
+    assert resolved.top_p == 0.9

tests/models/test_kwargs_functionality.py

@@ -0,0 +1,177 @@
+import litellm
+import pytest
+from litellm.types.utils import Choices, Message, ModelResponse, Usage
+from openai.types.chat.chat_completion import ChatCompletion, Choice
+from openai.types.chat.chat_completion_message import ChatCompletionMessage
+from openai.types.completion_usage import CompletionUsage
+
+from agents.extensions.models.litellm_model import LitellmModel
+from agents.model_settings import ModelSettings
+from agents.models.interface import ModelTracing
+from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+
+
+@pytest.mark.allow_call_model_methods
+@pytest.mark.asyncio
+async def test_litellm_kwargs_forwarded(monkeypatch):
+    """
+    Test that kwargs from ModelSettings are forwarded to litellm.acompletion.
+    """
+    captured: dict[str, object] = {}
+
+    async def fake_acompletion(model, messages=None, **kwargs):
+        captured.update(kwargs)
+        msg = Message(role="assistant", content="test response")
+        choice = Choices(index=0, message=msg)
+        return ModelResponse(choices=[choice], usage=Usage(0, 0, 0))
+
+    monkeypatch.setattr(litellm, "acompletion", fake_acompletion)
+
+    settings = ModelSettings(
+        temperature=0.5,
+        extra_args={
+            "custom_param": "custom_value",
+            "seed": 42,
+            "stop": ["END"],
+            "logit_bias": {123: -100},
+        },
+    )
+    model = LitellmModel(model="test-model")
+
+    await model.get_response(
+        system_instructions=None,
+        input="test input",
+        model_settings=settings,
+        tools=[],
+        output_schema=None,
+        handoffs=[],
+        tracing=ModelTracing.DISABLED,
+        previous_response_id=None,
+    )
+
+    # Verify that all kwargs were passed through
+    assert captured["custom_param"] == "custom_value"
+    assert captured["seed"] == 42
+    assert captured["stop"] == ["END"]
+    assert captured["logit_bias"] == {123: -100}
+
+    # Verify regular parameters are still passed
+    assert captured["temperature"] == 0.5
+
+
+@pytest.mark.allow_call_model_methods
+@pytest.mark.asyncio
+async def test_openai_chatcompletions_kwargs_forwarded(monkeypatch):
+    """
+    Test that kwargs from ModelSettings are forwarded to OpenAI chat completions API.
+    """
+    captured: dict[str, object] = {}
+
+    class MockChatCompletions:
+        async def create(self, **kwargs):
+            captured.update(kwargs)
+            msg = ChatCompletionMessage(role="assistant", content="test response")
+            choice = Choice(index=0, message=msg, finish_reason="stop")
+            return ChatCompletion(
+                id="test-id",
+                created=0,
+                model="gpt-4",
+                object="chat.completion",
+                choices=[choice],
+                usage=CompletionUsage(completion_tokens=5, prompt_tokens=10, total_tokens=15),
+            )
+
+    class MockChat:
+        def __init__(self):
+            self.completions = MockChatCompletions()
+
+    class MockClient:
+        def __init__(self):
+            self.chat = MockChat()
+            self.base_url = "https://api.openai.com/v1"
+
+    settings = ModelSettings(
+        temperature=0.7,
+        extra_args={
+            "seed": 123,
+            "logit_bias": {456: 10},
+            "stop": ["STOP", "END"],
+            "user": "test-user",
+        },
+    )
+
+    mock_client = MockClient()
+    model = OpenAIChatCompletionsModel(model="gpt-4", openai_client=mock_client)  # type: ignore
+
+    await model.get_response(
+        system_instructions="Test system",
+        input="test input",
+        model_settings=settings,
+        tools=[],
+        output_schema=None,
+        handoffs=[],
+        tracing=ModelTracing.DISABLED,
+        previous_response_id=None,
+    )
+
+    # Verify that all kwargs were passed through
+    assert captured["seed"] == 123
+    assert captured["logit_bias"] == {456: 10}
+    assert captured["stop"] == ["STOP", "END"]
+    assert captured["user"] == "test-user"
+
+    # Verify regular parameters are still passed
+    assert captured["temperature"] == 0.7
+
+
+@pytest.mark.allow_call_model_methods
+@pytest.mark.asyncio
+async def test_empty_kwargs_handling(monkeypatch):
+    """
+    Test that empty or None kwargs are handled gracefully.
+    """
+    captured: dict[str, object] = {}
+
+    async def fake_acompletion(model, messages=None, **kwargs):
+        captured.update(kwargs)
+        msg = Message(role="assistant", content="test response")
+        choice = Choices(index=0, message=msg)
+        return ModelResponse(choices=[choice], usage=Usage(0, 0, 0))
+
+    monkeypatch.setattr(litellm, "acompletion", fake_acompletion)
+
+    # Test with None kwargs
+    settings_none = ModelSettings(temperature=0.5, extra_args=None)
+    model = LitellmModel(model="test-model")
+
+    await model.get_response(
+        system_instructions=None,
+        input="test input",
+        model_settings=settings_none,
+        tools=[],
+        output_schema=None,
+        handoffs=[],
+        tracing=ModelTracing.DISABLED,
+        previous_response_id=None,
+    )
+
+    # Should work without error and include regular parameters
+    assert captured["temperature"] == 0.5
+
+    # Test with empty dict
+    captured.clear()
+    settings_empty = ModelSettings(temperature=0.3, extra_args={})
+
+    await model.get_response(
+        system_instructions=None,
+        input="test input",
+        model_settings=settings_empty,
+        tools=[],
+        output_schema=None,
+        handoffs=[],
+        tracing=ModelTracing.DISABLED,
+        previous_response_id=None,
+    )
+
+    # Should work without error and include regular parameters
+    assert captured["temperature"] == 0.3