Skip to content

Conversation

@neubig
Copy link
Contributor

@neubig neubig commented Nov 7, 2025

Summary

This PR adds documentation for the new FallbackRouter feature that provides automatic failover between multiple LLM models when the primary model fails.

Related PR

This documentation corresponds to the implementation in:

Changes

New Documentation File

sdk/guides/llm-fallback.mdx - Comprehensive guide covering:

  • Overview of the FallbackRouter feature
  • Full code example from examples/01_standalone_sdk/27_llm_fallback.py
  • How it works (step-by-step explanation)
  • Common use cases:
    • Rate limit handling
    • High availability
    • Cost optimization
    • Geographic redundancy
  • Configuration examples
  • Error handling behavior
  • Best practices
  • Links to related guides

Content Highlights

The guide explains how to:

  1. Configure a FallbackRouter with primary and fallback models
  2. Handle common LLM failures (rate limits, connection errors, service unavailability)
  3. Build resilient applications with automatic failover
  4. Optimize costs by using cheaper models as fallbacks

Code Example Reference

The documentation includes the complete example code that will be auto-synced from:

examples/01_standalone_sdk/27_llm_fallback.py

Links to Related Documentation

The guide includes navigation to related topics:

  • Model Routing
  • Error Handling
  • LLM Metrics

Checklist

  • Documentation follows existing mdx format and style
  • Code example properly referenced with auto-sync format
  • Includes practical use cases and examples
  • Links to related documentation
  • Covers best practices
  • Explains error handling behavior

Notes

This PR should be merged alongside OpenHands/software-agent-sdk#1103 to keep documentation synchronized with the codebase.

@neubig can click here to continue refining the PR

Document the new FallbackRouter feature that provides automatic
failover between multiple LLM models when the primary model fails.

The guide covers:
- How to configure FallbackRouter with primary and fallback models
- Common use cases (rate limits, high availability, cost optimization)
- Error handling behavior
- Best practices for fallback configurations
- Example code from examples/01_standalone_sdk/27_llm_fallback.py

This documentation corresponds to the FallbackRouter implementation
in OpenHands/software-agent-sdk PR #1103.

Co-authored-by: openhands <openhands@all-hands.dev>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants