Model Gateway

#Overview

The ModelGateway class acts as a unified, provider-aware factory for the models of the Agno library. Its main purpose is to abstract the complexity of the different APIs of language model providers, offering a simple, consistent and safe interface to create instances of those models and agents that use them.

It solves the problem of the dispersion and variation in the interfaces of models from different providers (Anthropic, Google, Groq, OpenAI and OpenAI variants), allowing the developer to select the desired model through a single class, which manages the creation and automatic validation of the parameters. In this way, the practical use of the class simplifies integration with multiple models without needing to know the specific details of each one.

In practice, you can create a model or agent by specifying only the provider name and relevant parameters, while ModelGateway handles the mapping to the correct class and optionally validates the arguments, avoiding common errors and promoting greater productivity and safety in development.

#Execution Flow

1. Instantiate the class ModelGateway, optionally defining whether you want strict validation of the parameters (the default is True).
2. Call the method create_model passing the provider name, optionally the model_id, the openai_variant variant (if applicable), and any other model parameters.
3. The class internally resolves which constructor to use by mapping the provider and, if it is OpenAI, also the variant, to the appropriate model class.
4. If strict validation is enabled, ModelGateway validates that all the parameters provided are valid, based on the signature of the model class constructor.
5. The model instance is created and returned, ready to use.
6. Optionally, an agent can be created with create_agent, which internally calls create_model and instantiates an Agent object from the Agno library, configured with the selected model and additional parameters.
7. For convenience, there are convenience methods for each of the most common providers and variants, such as anthropic(), google(), openai_chat(), among others, allowing models to be created directly without having to specify the provider manually.

#Class Methods Table

#Environment Variables

This module imports and calls load_dotenv() at the start, indicating that it loads environment variables defined in a .env file. Although the class itself does not directly use environment variables, the underlying models probably depend on API keys and settings that are configured via ENV. Common example:

• OPENAI_API_KEY: API key for authentication with OpenAI models.
• ANTHROPIC_API_KEY: key for Anthropic.
• GEMINI_API_KEY: credentials for the Google service.
• Others specific to each provider.

#Important Architecture Points and Insights

• Factory Design: The class uses the factory pattern to create model instances based on normalized keys, promoting extensibility and centralization of creation.
• Aliases and Normalization: Uses dictionaries to allow multiple names for the same provider or OpenAI variants, improving usability.
• Parameter Validation: Inspects the constructor signature of the models to validate the arguments received, avoiding silent errors.
• Separation between Model and Agent: Although it creates models, it directly supports creating agents configured with those models, decoupling responsibilities.
• Dependency on the Agno Library: Uses classes from the agno.models package and agno.agent.Agent, so it is a wrapper specialized for this stack.

#Class and Methods Description

#ModelGateway Class

#Description

Responsible for unifying the creation of models from different providers in a safe and simple way. Allows specifying the provider and variants (in the case of OpenAI) and creating both model instances and agents that use them, ensuring that the parameters are correct and aligned with the specific implementations of each model.

#Constructor Arguments

#Methods

#1. __init__

Description

Initializes the class instance, defining the parameter validation behavior for the creation of the models.

Arguments

• strict_validation (bool): Enables/disables strict validation of the parameters. Default True.

Returns

• Does not return a value.

Raises

• None.

Examples

gateway = ModelGateway(strict_validation=False)

#2. supported_providers

Description

Returns a list of the model providers supported by the class.

Arguments

• None.

Returns

• Sequence[str]: Sequence of names of the supported providers, e.g. ("anthropic", "google", "groq", "openai").

Raises

• None.

Examples

print(ModelGateway.supported_providers())
# ('anthropic', 'google', 'groq', 'openai')

#3. supported_openai_variants

Description

Returns the specific OpenAI variants supported for model selection.

Arguments

• None.

Returns

• Sequence[str]: Sequence of supported OpenAI variants, example ("chat", "responses", "open_responses", "like").

Raises

• None.

Examples

print(ModelGateway.supported_openai_variants())
# ('chat', 'responses', 'open_responses', 'like')

#4. supported_parameters

Description

Returns the list of names of the parameters valid for the constructor of a given model/provider.

Arguments

• provider (str): Provider name (e.g. "openai", "google", "anthropic").
• openai_variant (str): OpenAI variant. Default "chat".

Returns

• List[str]: List of the names of the parameters accepted by the model constructor.

Raises

• ValueError: If the provider or variant is invalid.

Examples

params = gateway.supported_parameters(provider="openai", openai_variant="like")
print("temperature" in params)
# True (se for parâmetro válido)

#5. create_model

Description

Creates and returns an instance of the model corresponding to the provider and variant, passing the necessary parameters to the constructor. Validates the arguments if enabled.

Arguments

• provider (str): Provider name - "anthropic", "google", "groq" or "openai".
• model_id (Optional[str]): Model ID to override the constructor's id parameter.
• openai_variant (str, keyword-only): OpenAI variant to be used, default "chat".
• strict_validation (Optional[bool], keyword-only): Override for strict validation in the method, ignoring the instance configuration.
• **kwargs (Any): All the additional parameters accepted by the model constructor.

Returns

• Specific instance of the requested model.

Raises

• ValueError: If invalid parameters are passed (when validation is enabled).
• ValueError: If the provider or OpenAI variant is invalid.

Examples

model = gateway.create_model(
    provider="openai",
    openai_variant="chat",
    model_id="gpt-4.1-mini",
    temperature=0.2,
)

#6. create_agent

Description

Creates an Agent object configured with the model created according to the provider and variant, including parameters specific to the model and to the agent.

Arguments

• provider (str): Provider name.
• model_id (Optional[str]): Model ID (optional).
• openai_variant (str, keyword-only): OpenAI variant, default "chat".
• model_kwargs (Optional[Dict[str, Any]]): Dictionary of parameters for the model.
• **agent_kwargs (Any): Extra parameters forwarded to the agent constructor.

Returns

• Agent: Instance of the Agent class configured with the model and parameters provided.

Raises

• Same as create_model for the creation of the model.

Examples

agent = gateway.create_agent(
    provider="openai",
    openai_variant="chat",
    model_kwargs={"id": "gpt-4.1-mini", "temperature": 0.2},
    markdown=True,
)

#7. anthropic

Description

Convenience method to create the Anthropic Claude model with optional parameters.

Arguments

• model_id (Optional[str]): Model ID.
• **kwargs (Any): Parameters for the Claude constructor.

Returns

• Claude: Instance of the Claude model.

Raises

• Same as create_model.

Examples

claude = gateway.anthropic(model_id="claude-v1", temperature=0.5)

#8. google

Description

Convenience method to create the Google Gemini model with optional parameters.

Arguments

• model_id (Optional[str]): Model ID.
• **kwargs (Any): Parameters for the Gemini constructor.

Returns

• Gemini: Instance of the Gemini model.

Raises

• Same as create_model.

Examples

gemini = gateway.google(model_id="gemini-pro", max_tokens=1000)

#9. groq

Description

Convenience method to create the Groq model with optional parameters.

Arguments

• model_id (Optional[str]): Model ID.
• **kwargs (Any): Parameters for the Groq constructor.

Returns

• Groq: Instance of the Groq model.

Raises

• Same as create_model.

Examples

groq_model = gateway.groq(model_id="groq-xyz")

#10. openai_chat

Description

Convenience method to create the OpenAIChat model with optional parameters.

Arguments

• model_id (Optional[str]): Model ID.
• **kwargs (Any): Parameters for the OpenAIChat constructor.

Returns

• OpenAIChat: Instance of the OpenAIChat model.

Raises

• Same as create_model.

Examples

chat = gateway.openai_chat(model_id="gpt-4")

#11. openai_responses

Description

Convenience method to create the OpenAIResponses model with optional parameters.

Arguments

• model_id (Optional[str]): Model ID.
• **kwargs (Any): Parameters for the OpenAIResponses constructor.

Returns

• OpenAIResponses: Instance of the OpenAIResponses model.

Raises

• Same as create_model.

Examples

responses = gateway.openai_responses(model_id="some-id")

#12. open_responses

Description

Convenience method to create the OpenResponses model with optional parameters.

Arguments

• model_id (Optional[str]): Model ID.
• **kwargs (Any): Parameters for the OpenResponses constructor.

Returns

• OpenResponses: Instance of the OpenResponses model.

Raises

• Same as create_model.

Examples

open_resp = gateway.open_responses(model_id="openresp-1")

#13. openai_like

Description

Convenience method to create the OpenAILike model with optional parameters.

Arguments

• model_id (Optional[str]): Model ID.
• **kwargs (Any): Parameters for the OpenAILike constructor.

Returns

• OpenAILike: Instance of the OpenAILike model.

Raises

• Same as create_model.

Examples

like_model = gateway.openai_like(model_id="like-1")

#14. _resolve_factory_key

Description

Resolves the internal key used to access the model constructor given the provider name and variant (if OpenAI).

Arguments

• provider (str): Provider name.
• openai_variant (str): OpenAI variant. Default "chat".

Returns

• str: Key of the factories dictionary to obtain the constructor.

Raises

• ValueError: If the provider or variant is invalid.

Examples

key = gateway._resolve_factory_key("openai", "like")
print(key)  # "openai.like"

#15. _get_constructor_param_names

Description

Returns the names of the constructor parameters of the model class associated with a factory key.

Arguments

• factory_key (str): Key of the model constructor.

Returns

• List[str]: List of parameter names, except self.

Examples

params = gateway._get_constructor_param_names("openai.chat")
print("temperature" in params)

#16. _validate_kwargs

Description

Validates whether the keys of the parameters dictionary are valid for the model constructor.

Arguments

• factory_key (str): Constructor key.
• kwargs (Dict[str, Any]): Parameters to validate.

Raises

• ValueError: If invalid parameters are found.

Examples

gateway._validate_kwargs("openai.chat", {"temperature": 0.7, "foo": 123})
# Gera ValueError: parâmetro 'foo' inválido

#Real Usage Examples

if __name__ == "__main__":
    gateway = ModelGateway(strict_validation=True)

    # Criando um modelo OpenAI Chat com ID e temperatura ajustada
    chat_model = gateway.create_model(
        provider="openai",
        openai_variant="chat",
        model_id="gpt-4.1-mini",
        temperature=0.2,
    )

    # Criando um agente com o mesmo modelo e opção markdown ativada
    agent = gateway.create_agent(
        provider="openai",
        openai_variant="chat",
        model_kwargs={"id": "gpt-4.1-mini", "temperature": 0.2},
        markdown=True,
    )

    _ = chat_model
    agent.print_response("Hello!")

    # python -m src.agents.utils.model_gateway

This documentation allows developers to quickly integrate models from multiple providers in a safe, robust and intuitive way using the powerful abstraction offered by the ModelGateway class.