feat: #2492 add explicit MultiProvider prefix modes (#2593)

Author: seratch

src/agents/models/multi_provider.py

@@ -1,11 +1,16 @@
 from __future__ import annotations
 
+from typing import Literal, cast
+
 from openai import AsyncOpenAI
 
 from ..exceptions import UserError
 from .interface import Model, ModelProvider
 from .openai_provider import OpenAIProvider
 
+MultiProviderOpenAIPrefixMode = Literal["alias", "model_id"]
+MultiProviderUnknownPrefixMode = Literal["error", "model_id"]
+
 
 class MultiProviderMap:
     """A map of model name prefixes to ModelProviders."""
@@ -57,7 +62,11 @@ class MultiProvider(ModelProvider):
     - "openai/" prefix or no prefix -> OpenAIProvider. e.g. "openai/gpt-4.1", "gpt-4.1"
     - "litellm/" prefix -> LitellmProvider. e.g. "litellm/openai/gpt-4.1"
 
-    You can override or customize this mapping.
+    You can override or customize this mapping. The ``openai`` prefix is ambiguous for some
+    OpenAI-compatible backends because a string like ``openai/gpt-4.1`` could mean either "route
+    to the OpenAI provider and use model ``gpt-4.1``" or "send the literal model ID
+    ``openai/gpt-4.1`` to the configured OpenAI-compatible endpoint." The prefix mode options let
+    callers opt into the second behavior without breaking the historical alias semantics.
     """
 
     def __init__(
@@ -72,6 +81,8 @@ def __init__(
         openai_use_responses: bool | None = None,
         openai_use_responses_websocket: bool | None = None,
         openai_websocket_base_url: str | None = None,
+        openai_prefix_mode: MultiProviderOpenAIPrefixMode = "alias",
+        unknown_prefix_mode: MultiProviderUnknownPrefixMode = "error",
     ) -> None:
         """Create a new OpenAI provider.
 
@@ -92,6 +103,15 @@ def __init__(
                 responses API.
             openai_websocket_base_url: The websocket base URL to use for the OpenAI provider.
                 If not provided, the provider will use `OPENAI_WEBSOCKET_BASE_URL` when set.
+            openai_prefix_mode: Controls how ``openai/...`` model strings are interpreted.
+                ``"alias"`` preserves the historical behavior and strips the ``openai/`` prefix
+                before calling the OpenAI provider. ``"model_id"`` keeps the full string and is
+                useful for OpenAI-compatible endpoints that expect literal namespaced model IDs.
+            unknown_prefix_mode: Controls how prefixes outside the explicit provider map and
+                built-in fallbacks are handled. ``"error"`` preserves the historical fail-fast
+                behavior and raises ``UserError``. ``"model_id"`` passes the full string through to
+                the OpenAI provider so OpenAI-compatible endpoints can receive namespaced model IDs
+                such as ``openrouter/openai/gpt-4o``.
         """
         self.provider_map = provider_map
         self.openai_provider = OpenAIProvider(
@@ -104,6 +124,8 @@ def __init__(
             use_responses=openai_use_responses,
             use_responses_websocket=openai_use_responses_websocket,
         )
+        self._openai_prefix_mode = self._validate_openai_prefix_mode(openai_prefix_mode)
+        self._unknown_prefix_mode = self._validate_unknown_prefix_mode(unknown_prefix_mode)
 
         self._fallback_providers: dict[str, ModelProvider] = {}
 
@@ -124,6 +146,20 @@ def _create_fallback_provider(self, prefix: str) -> ModelProvider:
         else:
             raise UserError(f"Unknown prefix: {prefix}")
 
+    @staticmethod
+    def _validate_openai_prefix_mode(mode: str) -> MultiProviderOpenAIPrefixMode:
+        if mode not in {"alias", "model_id"}:
+            raise UserError("MultiProvider openai_prefix_mode must be one of: 'alias', 'model_id'.")
+        return cast(MultiProviderOpenAIPrefixMode, mode)
+
+    @staticmethod
+    def _validate_unknown_prefix_mode(mode: str) -> MultiProviderUnknownPrefixMode:
+        if mode not in {"error", "model_id"}:
+            raise UserError(
+                "MultiProvider unknown_prefix_mode must be one of: 'error', 'model_id'."
+            )
+        return cast(MultiProviderUnknownPrefixMode, mode)
+
     def _get_fallback_provider(self, prefix: str | None) -> ModelProvider:
         if prefix is None or prefix == "openai":
             return self.openai_provider
@@ -133,6 +169,31 @@ def _get_fallback_provider(self, prefix: str | None) -> ModelProvider:
             self._fallback_providers[prefix] = self._create_fallback_provider(prefix)
             return self._fallback_providers[prefix]
 
+    def _resolve_prefixed_model(
+        self,
+        *,
+        original_model_name: str,
+        prefix: str,
+        stripped_model_name: str | None,
+    ) -> tuple[ModelProvider, str | None]:
+        # Explicit provider_map entries are the least surprising routing mechanism, so they always
+        # win over the built-in OpenAI alias and unknown-prefix fallback behavior.
+        if self.provider_map and (provider := self.provider_map.get_provider(prefix)):
+            return provider, stripped_model_name
+
+        if prefix == "litellm":
+            return self._get_fallback_provider(prefix), stripped_model_name
+
+        if prefix == "openai":
+            if self._openai_prefix_mode == "alias":
+                return self.openai_provider, stripped_model_name
+            return self.openai_provider, original_model_name
+
+        if self._unknown_prefix_mode == "model_id":
+            return self.openai_provider, original_model_name
+
+        raise UserError(f"Unknown prefix: {prefix}")
+
     def get_model(self, model_name: str | None) -> Model:
         """Returns a Model based on the model name. The model name can have a prefix, ending with
         a "/", which will be used to look up the ModelProvider. If there is no prefix, we will use
@@ -144,12 +205,21 @@ def get_model(self, model_name: str | None) -> Model:
         Returns:
             A Model.
         """
-        prefix, model_name = self._get_prefix_and_model_name(model_name)
+        # Bare model names are always delegated directly to the OpenAI provider. That provider can
+        # still point at an OpenAI-compatible endpoint via ``base_url``.
+        if model_name is None:
+            return self.openai_provider.get_model(None)
 
-        if prefix and self.provider_map and (provider := self.provider_map.get_provider(prefix)):
-            return provider.get_model(model_name)
-        else:
-            return self._get_fallback_provider(prefix).get_model(model_name)
+        prefix, stripped_model_name = self._get_prefix_and_model_name(model_name)
+        if prefix is None:
+            return self.openai_provider.get_model(stripped_model_name)
+
+        provider, resolved_model_name = self._resolve_prefixed_model(
+            original_model_name=model_name,
+            prefix=prefix,
+            stripped_model_name=stripped_model_name,
+        )
+        return provider.get_model(resolved_model_name)
 
     async def aclose(self) -> None:
         """Close cached resources held by child providers."""

src/agents/responses_websocket_session.py

@@ -7,7 +7,11 @@
 
 from .agent import Agent
 from .items import TResponseInputItem
-from .models.multi_provider import MultiProvider
+from .models.multi_provider import (
+    MultiProvider,
+    MultiProviderOpenAIPrefixMode,
+    MultiProviderUnknownPrefixMode,
+)
 from .models.openai_provider import OpenAIProvider
 from .result import RunResult, RunResultStreaming
 from .run import Runner
@@ -80,6 +84,8 @@ async def responses_websocket_session(
     websocket_base_url: str | None = None,
     organization: str | None = None,
     project: str | None = None,
+    openai_prefix_mode: MultiProviderOpenAIPrefixMode = "alias",
+    unknown_prefix_mode: MultiProviderUnknownPrefixMode = "error",
 ) -> AsyncIterator[ResponsesWebSocketSession]:
     """Create a shared OpenAI Responses websocket session for multiple Runner calls.
 
@@ -89,6 +95,10 @@ async def responses_websocket_session(
     connections warm across turns and nested agent-as-tool runs that inherit the same
     ``run_config``.
 
+    Use ``openai_prefix_mode="model_id"`` and/or ``unknown_prefix_mode="model_id"`` when the
+    configured OpenAI-compatible endpoint expects literal namespaced model IDs instead of the SDK's
+    historical routing-prefix behavior.
+
     Drain or close streamed iterators before the context exits. Exiting the context while a
     websocket request is still in flight may force-close the shared connection.
     """
@@ -100,6 +110,8 @@ async def responses_websocket_session(
         openai_project=project,
         openai_use_responses=True,
         openai_use_responses_websocket=True,
+        openai_prefix_mode=openai_prefix_mode,
+        unknown_prefix_mode=unknown_prefix_mode,
     )
     provider = model_provider.openai_provider
     session = ResponsesWebSocketSession(

tests/models/test_map.py

@@ -1,5 +1,17 @@
-from agents import Agent, MultiProvider, OpenAIResponsesModel, OpenAIResponsesWSModel, RunConfig
+from typing import Any, cast
+
+import pytest
+
+from agents import (
+    Agent,
+    MultiProvider,
+    OpenAIResponsesModel,
+    OpenAIResponsesWSModel,
+    RunConfig,
+    UserError,
+)
 from agents.extensions.models.litellm_model import LitellmModel
+from agents.models.multi_provider import MultiProviderMap
 from agents.run_internal.run_loop import get_model
 
 
@@ -53,3 +65,107 @@ def get_model(self, model_name):
 
     MultiProvider(openai_websocket_base_url="wss://proxy.example.test/v1")
     assert captured_kwargs["websocket_base_url"] == "wss://proxy.example.test/v1"
+
+
+def test_openai_prefix_defaults_to_alias_mode(monkeypatch):
+    captured_model: dict[str, Any] = {}
+
+    class FakeOpenAIProvider:
+        def __init__(self, **kwargs):
+            pass
+
+        def get_model(self, model_name):
+            captured_model["value"] = model_name
+            return object()
+
+    monkeypatch.setattr("agents.models.multi_provider.OpenAIProvider", FakeOpenAIProvider)
+
+    provider = MultiProvider()
+    provider.get_model("openai/gpt-4o")
+    assert captured_model["value"] == "gpt-4o"
+
+
+def test_openai_prefix_can_be_preserved_as_literal_model_id(monkeypatch):
+    captured_model: dict[str, Any] = {}
+
+    class FakeOpenAIProvider:
+        def __init__(self, **kwargs):
+            pass
+
+        def get_model(self, model_name):
+            captured_model["value"] = model_name
+            return object()
+
+    monkeypatch.setattr("agents.models.multi_provider.OpenAIProvider", FakeOpenAIProvider)
+
+    provider = MultiProvider(openai_prefix_mode="model_id")
+    provider.get_model("openai/gpt-4o")
+    assert captured_model["value"] == "openai/gpt-4o"
+
+
+def test_unknown_prefix_defaults_to_error():
+    provider = MultiProvider()
+
+    with pytest.raises(UserError, match="Unknown prefix: openrouter"):
+        provider.get_model("openrouter/openai/gpt-4o")
+
+
+def test_unknown_prefix_can_be_preserved_for_openai_compatible_model_ids(monkeypatch):
+    captured_model: dict[str, Any] = {}
+    captured_result: dict[str, Any] = {}
+
+    class FakeOpenAIProvider:
+        def __init__(self, **kwargs):
+            pass
+
+        def get_model(self, model_name):
+            captured_model["value"] = model_name
+            fake_model = object()
+            captured_result["value"] = fake_model
+            return fake_model
+
+    monkeypatch.setattr("agents.models.multi_provider.OpenAIProvider", FakeOpenAIProvider)
+
+    provider = MultiProvider(unknown_prefix_mode="model_id")
+    result = provider.get_model("openrouter/openai/gpt-4o")
+    assert result is captured_result["value"]
+    assert captured_model["value"] == "openrouter/openai/gpt-4o"
+
+
+def test_provider_map_entries_override_openai_prefix_mode(monkeypatch):
+    captured_model: dict[str, Any] = {}
+
+    class FakeCustomProvider:
+        def get_model(self, model_name):
+            captured_model["value"] = model_name
+            return object()
+
+    class FakeOpenAIProvider:
+        def __init__(self, **kwargs):
+            pass
+
+        def get_model(self, model_name):
+            raise AssertionError("Expected the explicit provider_map entry to win.")
+
+    monkeypatch.setattr("agents.models.multi_provider.OpenAIProvider", FakeOpenAIProvider)
+
+    provider_map = MultiProviderMap()
+    provider_map.add_provider("openai", cast(Any, FakeCustomProvider()))
+
+    provider = MultiProvider(
+        provider_map=provider_map,
+        openai_prefix_mode="model_id",
+    )
+    provider.get_model("openai/gpt-4o")
+    assert captured_model["value"] == "gpt-4o"
+
+
+def test_multi_provider_rejects_invalid_prefix_modes():
+    bad_openai_prefix_mode: Any = "invalid"
+    bad_unknown_prefix_mode: Any = "invalid"
+
+    with pytest.raises(UserError, match="openai_prefix_mode"):
+        MultiProvider(openai_prefix_mode=bad_openai_prefix_mode)
+
+    with pytest.raises(UserError, match="unknown_prefix_mode"):
+        MultiProvider(unknown_prefix_mode=bad_unknown_prefix_mode)

tests/test_responses_websocket_session.py

@@ -35,6 +35,42 @@ def fake_get_model(model_name):
         assert captured["model_name"] == "gpt-4.1"
 
 
+@pytest.mark.asyncio
+async def test_responses_websocket_session_can_preserve_openai_prefix_model_ids(monkeypatch):
+    captured: dict[str, object] = {}
+    sentinel = object()
+
+    def fake_get_model(model_name):
+        captured["model_name"] = model_name
+        return sentinel
+
+    async with responses_websocket_session(openai_prefix_mode="model_id") as ws:
+        monkeypatch.setattr(ws.provider, "get_model", fake_get_model)
+
+        result = ws.run_config.model_provider.get_model("openai/gpt-4.1")
+
+        assert result is sentinel
+        assert captured["model_name"] == "openai/gpt-4.1"
+
+
+@pytest.mark.asyncio
+async def test_responses_websocket_session_can_preserve_unknown_prefix_model_ids(monkeypatch):
+    captured: dict[str, object] = {}
+    sentinel = object()
+
+    def fake_get_model(model_name):
+        captured["model_name"] = model_name
+        return sentinel
+
+    async with responses_websocket_session(unknown_prefix_mode="model_id") as ws:
+        monkeypatch.setattr(ws.provider, "get_model", fake_get_model)
+
+        result = ws.run_config.model_provider.get_model("openrouter/openai/gpt-4.1")
+
+        assert result is sentinel
+        assert captured["model_name"] == "openrouter/openai/gpt-4.1"
+
+
 @pytest.mark.asyncio
 async def test_responses_websocket_session_run_streamed_injects_run_config(monkeypatch):
     agent = Agent(name="test", instructions="Be concise.", model="gpt-4")