Fallback Models: Basic

Try fallback models in order after a retryable provider failure exhausts the primary model retries.

basic_fallback.py
"""
Fallback Models — Basic
=============================

When the primary model fails (after exhausting its own retries),
fallback models are tried in order until one succeeds.
"""

from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.models.openai import OpenAIChat

# ---------------------------------------------------------------------------
# Basic: pass a list of fallback models directly
# The primary model points to an unreachable server so it will fail
# with a connection error, then the fallback (Claude) handles the request.
# ---------------------------------------------------------------------------
agent = Agent(
    model=OpenAIChat(id="gpt-5.6-luna", base_url="http://localhost:1/v1", retries=0),
    fallback_models=[Claude(id="claude-sonnet-4-20250514")],
)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    agent.print_response("What is the meaning of life?", stream=True)

Use a current fallback model

Before running, replace every Claude(id="claude-sonnet-4-20250514") with Claude(id="claude-sonnet-4-6"). The original Sonnet 4 API model retired on June 15, 2026; see Claude model deprecations. The source is preserved above, and the setup still requires both providers' API keys.

Run the Example

Set up your virtual environment

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

Install dependencies

uv pip install -U agno anthropic openai

Export your API keys

export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
export OPENAI_API_KEY="your_openai_api_key_here"

Run the example

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

python basic_fallback.py

Full source: cookbook/02_agents/17_fallback_models/01_basic_fallback.py