Team Fallback Models: Error-Specific

Use FallbackConfig for error-specific fallback routing on Teams.

error_specific_fallbacks.py
"""
Team Fallback Models — Error-Specific
=======================================

Use FallbackConfig for error-specific fallback routing on Teams.

- on_error: tried on any error from the primary model.
- on_rate_limit: tried specifically on rate-limit (429) errors.
- on_context_overflow: tried on context-window-exceeded errors.
"""

from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.models.fallback import FallbackConfig
from agno.models.openai import OpenAIChat
from agno.team import Team

researcher = Agent(
    name="Researcher",
    role="You research topics and provide detailed findings.",
    model=OpenAIChat(id="gpt-5.6-luna"),
)

writer = Agent(
    name="Writer",
    role="You write clear, concise summaries from research findings.",
    model=OpenAIChat(id="gpt-5.6-luna"),
)

team = Team(
    name="Research Team",
    model=OpenAIChat(id="gpt-5.6-luna"),
    fallback_config=FallbackConfig(
        on_rate_limit=[
            OpenAIChat(id="gpt-5.6-luna"),
            Claude(id="claude-sonnet-4-20250514"),
        ],
        on_context_overflow=[
            Claude(id="claude-sonnet-4-20250514"),
        ],
        on_error=[
            Claude(id="claude-sonnet-4-20250514"),
        ],
    ),
    members=[researcher, writer],
    instructions=[
        "Coordinate with the researcher and writer to answer the user question.",
    ],
    markdown=True,
    show_members_responses=True,
)

if __name__ == "__main__":
    team.print_response("What are the benefits of sleep?", stream=True)

Before running

on_error handles eligible provider failures, including network and server errors. It does not mask ordinary non-retryable client errors such as 401/403. A configured rate-limit or context-overflow list takes precedence over the general list; Agno does not append on_error to that specific list. This example does not deliberately trigger a failure, so a successful primary request will not demonstrate fallback.

The configuration belongs to the team leader. Configure fallbacks on individual members too if their model calls need the same behavior.

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 error_specific_fallbacks.py, then run:

python error_specific_fallbacks.py

Full source: cookbook/03_teams/17_fallback_models/02_error_specific_fallbacks.py