Fallback Routing

Configure ordered OpenRouter fallback models for unavailable primary routes.

Model fallback example using OpenRouter with the Responses API.

fallback.py

"""Model fallback example using OpenRouter with the Responses API.

This demonstrates using fallback models with OpenRouter's dynamic model routing.
If the primary model fails due to rate limits, timeouts, or unavailability,
OpenRouter will automatically try the fallback models in order.

Requirements:
- Set OPENROUTER_API_KEY environment variable
"""

from agno.agent import Agent
from agno.models.openrouter import OpenRouterResponses

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------

agent = Agent(
    model=OpenRouterResponses(
        id="openai/gpt-oss-20b",
        # Fallback models if primary fails
        models=[
            "openai/gpt-oss-20b",
            "openai/gpt-4o",
        ],
    ),
    markdown=True,
)

agent.print_response("Write a haiku about coding", stream=True)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    pass

Run the Example

1. Set up your virtual environment

   Mac

   uv venv --python 3.12
   source .venv/bin/activate
   

   uv venv --python 3.12
   .venv\Scripts\activate
   
2. Install dependencies

   uv pip install -U agno openai
   
3. Export your OpenRouter API key

   Mac/Linux

   export OPENROUTER_API_KEY="your_openrouter_api_key_here"
   

   $Env:OPENROUTER_API_KEY="your_openrouter_api_key_here"
   
4. Run the example

   Save the code above as fallback.py, then run:

   python fallback.py
   

Full source: cookbook/90_models/openrouter/responses/fallback.py