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-5.6-luna",
        ],
    ),
    markdown=True,
)

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

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

if __name__ == "__main__":
    pass

Run the Example

Set up your virtual environment

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

Install dependencies

uv pip install -U agno openai

Export your OpenRouter API key

export OPENROUTER_API_KEY="your_openrouter_api_key_here"

Run the example

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

python fallback.py

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