Model fallbacks

[krissetto]

Allows users to define fallback models per agent in the yaml config.

If something goes wrong calling a model, retry a few times with exp backoff + jitter or fallback to the next model in the list based on the type of error encountered

Makes cagent a more reliable platform for users, avoiding much pain and frustration and blocking workflows when an inference provider goes down

Has sane defaults to keep user configs minimal while still getting big advantages

Covers title generation as well

Minimal example

agents:
  root:
    model: anthropic/claude-opus-4-5
    fallback:
      models:
        - openai/gpt-5.2
    description: A reliable assistant with automatic failover
    instruction: You are a helpful and resilient assistant.

[github-actions]

Model Fallback Implementation Review

✅ No issues found - This is a well-implemented feature with comprehensive testing and proper safeguards.

What Was Reviewed

This PR adds a robust model fallback system with:

• Retry logic with exponential backoff for retryable errors (5xx, timeouts)
• Immediate fallback switching for non-retryable errors (429, 4xx)
• Cooldown mechanism to stick with successful fallbacks
• Configurable retry counts and cooldown durations
• Comprehensive test coverage (779 lines of tests)

Code Quality Highlights

Strengths:

• ✅ Thread-safe cooldown state management with proper mutex usage
• ✅ Proper resource cleanup (stream.Close() via defer)
• ✅ Comprehensive error classification (retryable vs non-retryable)
• ✅ Context cancellation handling throughout
• ✅ Extensive test coverage including edge cases
• ✅ Well-documented configuration with sensible defaults

Architecture:

• Clean separation of concerns (fallback logic in dedicated file)
• Proper use of Go idioms (defer for cleanup, mutex for thread safety)
• Good error wrapping and logging

Verification Process

I analyzed the implementation for common bug patterns:

• ✅ Resource leaks - None found (proper defer usage)
• ✅ Race conditions - None found (local variables + mutex protection)
• ✅ Bounds checking - Properly validated
• ✅ Nil pointer dereferences - Properly guarded
• ✅ Off-by-one errors - Calculations are correct

Conclusion

This feature adds significant value by making cagent more resilient to provider outages. The implementation is solid with proper safeguards and comprehensive testing.

[github-actions]

Review Summary

I've reviewed the model fallback implementation and found no bugs in the changed code. The implementation demonstrates solid engineering practices:

✅ Proper concurrency control - Mutex protection for cooldown state access
✅ Defensive programming - Nil checks and bounds validation throughout
✅ Error handling - Clear classification of retryable vs non-retryable errors
✅ Context handling - Proper cancellation checks in retry loops
✅ Code organization - Clean separation of concerns between fallback logic and model switching

The feature adds robust failover capabilities with sensible defaults. Good work!