How to Switch LLM Providers in aisuite: A Complete Guide

To switch LLM providers in aisuite, change the model identifier to provider_key:model_name and ensure the corresponding configuration is set in the Client.

aisuite is a Python library built around a provider-agnostic architecture that unifies access to multiple large language model APIs. Developed by Andrew Ng's team at the andrewyng/aisuite repository, the library abstracts vendor-specific SDKs behind a common interface, allowing you to switch LLM providers in aisuite seamlessly by modifying a single string parameter.

Understanding the Provider-Agnostic Architecture

aisuite implements a unified interface where every LLM provider adheres to a common contract. Each provider class implements the chat_completions_create method, which standardizes how requests are sent and responses are handled across different vendors.

When you initiate a request, you specify the model using the format:

provider_key:model_name

For example, openai:gpt-4o or anthropic:claude-3-sonnet-20240229. The provider_key determines which concrete implementation is instantiated, while model_name is passed directly to the provider's specific API.

How Provider Switching Works Internally

The switching mechanism relies on runtime provider discovery and lazy instantiation. Here is the exact workflow as implemented in the source code:

Step 1: Provider Key Extraction and Validation

When you call client.chat.completions.create(), the Client.create() method in aisuite/client.py extracts the provider key from the model string using model.split(":", 1). It validates this key against ProviderFactory.get_supported_providers() to ensure the provider is available (lines 68-78).

Step 2: Lazy Loading of Provider Classes

If the provider instance is not cached, ProviderFactory.create_provider() in aisuite/provider.py dynamically imports the matching module using importlib.import_module(f"aisuite.providers.{provider_key}_provider"). It then retrieves the class named {ProviderKey}Provider and instantiates it (lines 40-58). This lazy loading means providers are only initialized when first used.

Step 3: Configuration Injection

Provider-specific settings are injected during instantiation. The configuration dictionary passed to Client() or updated via client.configure() is unpacked directly into the provider's constructor. For example, the OpenAI provider receives api_key, base_url, and other SDK-specific kwargs in aisuite/provider.py (lines 15-33).

Step 4: Method Routing

Finally, the client forwards your request to the concrete provider's chat_completions_create() method. For instance, OpenaiProvider.chat_completions_create() in aisuite/providers/openai_provider.py handles message conversion and API communication (lines 39-50).

Practical Implementation: Switching Providers in Code

To switch LLM providers in aisuite within your application, configure multiple providers during client initialization, then alternate between them by changing the model string.

First, install the required SDKs for the providers you intend to use:

pip install openai anthropic

Initialize the client with configurations for all providers:

from aisuite.client import Client

client = Client(
    provider_configs={
        "openai": {"api_key": "sk-openai-key"},
        "anthropic": {"api_key": "sk-anthropic-key"},
        "groq": {"api_key": "sk-groq-key"}
    }
)

Switch between providers by changing the model parameter:

# Use OpenAI

response = client.chat.completions.create(
    model="openai:gpt-4o",
    messages=[{"role": "user", "content": "Explain neural networks"}]
)
print(response.choices[0].message.content)

# Switch to Anthropic

response = client.chat.completions.create(
    model="anthropic:claude-3-sonnet-20240229",
    messages=[{"role": "user", "content": "Explain neural networks"}]
)
print(response.choices[0].message.content)

You can also update provider configuration at runtime without recreating the client:

client.configure({"openai": {"api_key": "sk-new-key"}})

This updates the configuration dictionary that is passed to the provider constructor on the next call.

Environment Variables and Fallbacks

If you prefer not to hardcode API keys, aisuite providers automatically fall back to standard environment variables. The OpenAI provider checks for OPENAI_API_KEY, Anthropic checks for ANTHROPIC_API_KEY, and similarly for other providers. You can omit the provider_configs parameter entirely if your environment variables are set, though the dictionary approach is required for explicit configuration like custom base_url endpoints.

Summary

• Provider switching in aisuite requires only changing the model string to provider_key:model_name.
• Lazy loading occurs through ProviderFactory.create_provider() in aisuite/provider.py, which dynamically imports provider modules only when needed (lines 40-58).
• Validation happens in Client.create() (lines 68-78), ensuring the provider key exists in ProviderFactory.get_supported_providers().
• Configuration is injected directly into provider constructors via the provider_configs dictionary or client.configure() method.
• Runtime switching requires no code restructuring—simply modify the model parameter between API calls.

Frequently Asked Questions

How do I add a new provider that isn't officially supported?

To add an unsupported provider, create a new file in aisuite/providers/ following the naming convention {provider_key}_provider.py. Implement a class named {ProviderKey}Provider with a chat_completions_create() method that accepts the same parameters as existing providers. Ensure your module follows the dynamic import pattern used in ProviderFactory.create_provider() in aisuite/provider.py.

Can I switch providers without restarting my application?

Yes. Since aisuite uses lazy instantiation, you can switch providers at any time by calling client.chat.completions.create() with a different provider_key:model_name string. If the new provider is already configured in provider_configs, the switch happens immediately. You can also update configuration mid-session using client.configure() to modify API keys or endpoints before the next call.

What happens if I provide a model string with an unsupported provider key?

The Client.create() method in aisuite/client.py validates the provider key against ProviderFactory.get_supported_providers(). If the key is not found, it raises a ValueError indicating that the provider is not supported. This validation occurs before any network requests are made, preventing runtime errors from invalid provider configurations.

Do I need to install all provider SDKs upfront?

No. You only need to install the SDKs for providers you actually use. The dynamic import in ProviderFactory.create_provider() only executes when you first attempt to use a specific provider. If the required SDK is missing, you will receive an import error at that point, allowing you to install dependencies on-demand rather than bundling all possible providers initially.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}