Skip to content

Multi Provider

MultiProviderMap

A map of model name prefixes to ModelProviders.

Source code in src/agents/models/multi_provider.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
class MultiProviderMap:
    """A map of model name prefixes to ModelProviders."""

    def __init__(self):
        self._mapping: dict[str, ModelProvider] = {}

    def has_prefix(self, prefix: str) -> bool:
        """Returns True if the given prefix is in the mapping."""
        return prefix in self._mapping

    def get_mapping(self) -> dict[str, ModelProvider]:
        """Returns a copy of the current prefix -> ModelProvider mapping."""
        return self._mapping.copy()

    def set_mapping(self, mapping: dict[str, ModelProvider]):
        """Overwrites the current mapping with a new one."""
        self._mapping = mapping

    def get_provider(self, prefix: str) -> ModelProvider | None:
        """Returns the ModelProvider for the given prefix.

        Args:
            prefix: The prefix of the model name e.g. "openai" or "my_prefix".
        """
        return self._mapping.get(prefix)

    def add_provider(self, prefix: str, provider: ModelProvider):
        """Adds a new prefix -> ModelProvider mapping.

        Args:
            prefix: The prefix of the model name e.g. "openai" or "my_prefix".
            provider: The ModelProvider to use for the given prefix.
        """
        self._mapping[prefix] = provider

    def remove_provider(self, prefix: str):
        """Removes the mapping for the given prefix.

        Args:
            prefix: The prefix of the model name e.g. "openai" or "my_prefix".
        """
        del self._mapping[prefix]

has_prefix 

has_prefix(prefix: str) -> bool

Returns True if the given prefix is in the mapping.

Source code in src/agents/models/multi_provider.py 
16
17
18
def has_prefix(self, prefix: str) -> bool:
    """Returns True if the given prefix is in the mapping."""
    return prefix in self._mapping

get_mapping 

get_mapping() -> dict[str, ModelProvider]

Returns a copy of the current prefix -> ModelProvider mapping.

Source code in src/agents/models/multi_provider.py 
20
21
22
def get_mapping(self) -> dict[str, ModelProvider]:
    """Returns a copy of the current prefix -> ModelProvider mapping."""
    return self._mapping.copy()

set_mapping 

set_mapping(mapping: dict[str, ModelProvider])

Overwrites the current mapping with a new one.

Source code in src/agents/models/multi_provider.py 
24
25
26
def set_mapping(self, mapping: dict[str, ModelProvider]):
    """Overwrites the current mapping with a new one."""
    self._mapping = mapping

get_provider 

get_provider(prefix: str) -> ModelProvider | None

Returns the ModelProvider for the given prefix.

Parameters:

Name Type Description Default
prefix str

The prefix of the model name e.g. "openai" or "my_prefix".

 required
Source code in src/agents/models/multi_provider.py 
28
29
30
31
32
33
34
def get_provider(self, prefix: str) -> ModelProvider | None:
    """Returns the ModelProvider for the given prefix.

    Args:
        prefix: The prefix of the model name e.g. "openai" or "my_prefix".
    """
    return self._mapping.get(prefix)

add_provider 

add_provider(prefix: str, provider: ModelProvider)

Adds a new prefix -> ModelProvider mapping.

Parameters:

Name Type Description Default
prefix str

The prefix of the model name e.g. "openai" or "my_prefix".

 required
provider ModelProvider

The ModelProvider to use for the given prefix.

 required
Source code in src/agents/models/multi_provider.py 
36
37
38
39
40
41
42
43
def add_provider(self, prefix: str, provider: ModelProvider):
    """Adds a new prefix -> ModelProvider mapping.

    Args:
        prefix: The prefix of the model name e.g. "openai" or "my_prefix".
        provider: The ModelProvider to use for the given prefix.
    """
    self._mapping[prefix] = provider

remove_provider 

remove_provider(prefix: str)

Removes the mapping for the given prefix.

Parameters:

Name Type Description Default
prefix str

The prefix of the model name e.g. "openai" or "my_prefix".

 required
Source code in src/agents/models/multi_provider.py 
45
46
47
48
49
50
51
def remove_provider(self, prefix: str):
    """Removes the mapping for the given prefix.

    Args:
        prefix: The prefix of the model name e.g. "openai" or "my_prefix".
    """
    del self._mapping[prefix]

MultiProvider

Bases: ModelProvider

This ModelProvider maps to a Model based on the prefix of the model name. By default, the mapping is: - "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.

Source code in src/agents/models/multi_provider.py 
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
class MultiProvider(ModelProvider):
    """This ModelProvider maps to a Model based on the prefix of the model name. By default, the
    mapping is:
    - "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.
    """

    def __init__(
        self,
        *,
        provider_map: MultiProviderMap | None = None,
        openai_api_key: str | None = None,
        openai_base_url: str | None = None,
        openai_client: AsyncOpenAI | None = None,
        openai_organization: str | None = None,
        openai_project: str | None = None,
        openai_use_responses: bool | None = None,
    ) -> None:
        """Create a new OpenAI provider.

        Args:
            provider_map: A MultiProviderMap that maps prefixes to ModelProviders. If not provided,
                we will use a default mapping. See the documentation for this class to see the
                default mapping.
            openai_api_key: The API key to use for the OpenAI provider. If not provided, we will use
                the default API key.
            openai_base_url: The base URL to use for the OpenAI provider. If not provided, we will
                use the default base URL.
            openai_client: An optional OpenAI client to use. If not provided, we will create a new
                OpenAI client using the api_key and base_url.
            openai_organization: The organization to use for the OpenAI provider.
            openai_project: The project to use for the OpenAI provider.
            openai_use_responses: Whether to use the OpenAI responses API.
        """
        self.provider_map = provider_map
        self.openai_provider = OpenAIProvider(
            api_key=openai_api_key,
            base_url=openai_base_url,
            openai_client=openai_client,
            organization=openai_organization,
            project=openai_project,
            use_responses=openai_use_responses,
        )

        self._fallback_providers: dict[str, ModelProvider] = {}

    def _get_prefix_and_model_name(self, model_name: str | None) -> tuple[str | None, str | None]:
        if model_name is None:
            return None, None
        elif "/" in model_name:
            prefix, model_name = model_name.split("/", 1)
            return prefix, model_name
        else:
            return None, model_name

    def _create_fallback_provider(self, prefix: str) -> ModelProvider:
        if prefix == "litellm":
            from ..extensions.models.litellm_provider import LitellmProvider

            return LitellmProvider()
        else:
            raise UserError(f"Unknown prefix: {prefix}")

    def _get_fallback_provider(self, prefix: str | None) -> ModelProvider:
        if prefix is None or prefix == "openai":
            return self.openai_provider
        elif prefix in self._fallback_providers:
            return self._fallback_providers[prefix]
        else:
            self._fallback_providers[prefix] = self._create_fallback_provider(prefix)
            return self._fallback_providers[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
        the OpenAI provider.

        Args:
            model_name: The name of the model to get.

        Returns:
            A Model.
        """
        prefix, model_name = self._get_prefix_and_model_name(model_name)

        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)

__init__ 

__init__(
    *,
    provider_map: MultiProviderMap | None = None,
    openai_api_key: str | None = None,
    openai_base_url: str | None = None,
    openai_client: AsyncOpenAI | None = None,
    openai_organization: str | None = None,
    openai_project: str | None = None,
    openai_use_responses: bool | None = None,
) -> None

Create a new OpenAI provider.

Parameters:

Name Type Description Default
provider_map MultiProviderMap | None

A MultiProviderMap that maps prefixes to ModelProviders. If not provided, we will use a default mapping. See the documentation for this class to see the default mapping.

 None
openai_api_key str | None

The API key to use for the OpenAI provider. If not provided, we will use the default API key.

 None
openai_base_url str | None

The base URL to use for the OpenAI provider. If not provided, we will use the default base URL.

 None
openai_client AsyncOpenAI | None

An optional OpenAI client to use. If not provided, we will create a new OpenAI client using the api_key and base_url.

 None
openai_organization str | None

The organization to use for the OpenAI provider.

 None
openai_project str | None

The project to use for the OpenAI provider.

 None
openai_use_responses bool | None

Whether to use the OpenAI responses API.

 None
Source code in src/agents/models/multi_provider.py 
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def __init__(
    self,
    *,
    provider_map: MultiProviderMap | None = None,
    openai_api_key: str | None = None,
    openai_base_url: str | None = None,
    openai_client: AsyncOpenAI | None = None,
    openai_organization: str | None = None,
    openai_project: str | None = None,
    openai_use_responses: bool | None = None,
) -> None:
    """Create a new OpenAI provider.

    Args:
        provider_map: A MultiProviderMap that maps prefixes to ModelProviders. If not provided,
            we will use a default mapping. See the documentation for this class to see the
            default mapping.
        openai_api_key: The API key to use for the OpenAI provider. If not provided, we will use
            the default API key.
        openai_base_url: The base URL to use for the OpenAI provider. If not provided, we will
            use the default base URL.
        openai_client: An optional OpenAI client to use. If not provided, we will create a new
            OpenAI client using the api_key and base_url.
        openai_organization: The organization to use for the OpenAI provider.
        openai_project: The project to use for the OpenAI provider.
        openai_use_responses: Whether to use the OpenAI responses API.
    """
    self.provider_map = provider_map
    self.openai_provider = OpenAIProvider(
        api_key=openai_api_key,
        base_url=openai_base_url,
        openai_client=openai_client,
        organization=openai_organization,
        project=openai_project,
        use_responses=openai_use_responses,
    )

    self._fallback_providers: dict[str, ModelProvider] = {}

get_model 

get_model(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 the OpenAI provider.

Parameters:

Name Type Description Default
model_name str | None

The name of the model to get.

 required

Returns:

Type Description
Model

A Model.
Source code in src/agents/models/multi_provider.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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
    the OpenAI provider.

    Args:
        model_name: The name of the model to get.

    Returns:
        A Model.
    """
    prefix, model_name = self._get_prefix_and_model_name(model_name)

    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)