feat(plugins): add fallback plugin to automatically fallback between Gemini models

[benmizrahi]

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

google/adk-python-community#88

• Closes: feat(plugins): add fallback plugin to automatically fallback between Gemini models adk-python-community#88
• Related: feat(plugins): add fallback plugin to automatically fallback between Gemini models adk-python-community#88

Unit Tests:
All passed

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @benmizrahi, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a FallbackPlugin designed to enhance the robustness of LLM interactions by providing a mechanism for transparent, non-persistent model fallback. It intelligently resets the primary model for each request and, upon encountering configured HTTP errors, enriches the response with detailed fallback metadata. This allows external retry mechanisms, such as those in LiteLlm, to make informed decisions about retrying requests with alternative models, thereby improving system resilience against transient model failures like rate limits or timeouts.

Highlights

• New FallbackPlugin Introduced: A new plugin has been added to provide transparent, non-persistent model fallback for LLM requests, specifically designed to handle transient errors like rate limits or gateway timeouts.
• Non-Persistent Fallback Logic: The plugin utilizes a before_model_callback to ensure that every new request starts with the root_model, preventing fallback state from bleeding across turns. It does not re-issue requests itself but prepares the context for external retry mechanisms.
• Error Detection and Metadata Annotation: An after_model_callback detects responses with configured HTTP error codes (e.g., 429, 504) and annotates the LlmResponse.custom_metadata with structured tracking data, including fallback_triggered, original_model, fallback_model, fallback_attempt, and error_code.
• Memory Management for Fallback Attempts: The plugin includes logic to prune its internal tracking dictionary (_fallback_attempts) to prevent unbounded memory growth in long-running processes by removing older entries when a certain limit is exceeded.
• Comprehensive Sample and Documentation: A new sample (contributing/samples/plugin_fallback) has been added, complete with a README.md and an agent.py example, to clearly demonstrate how to configure and effectively use the FallbackPlugin.
• Extensive Unit Test Coverage: Thorough unit tests have been implemented for the FallbackPlugin, covering its initialization, before_model_callback and after_model_callback behaviors, error handling, memory management, and the non-persistent fallback mechanism.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• contributing/samples/plugin_fallback/README.md
  • Added documentation for the new FallbackPlugin, explaining its functionality, configuration, parameters, and usage.
• contributing/samples/plugin_fallback/init.py
  • Added an __init__.py file to mark the plugin_fallback directory as a Python package.
• contributing/samples/plugin_fallback/agent.py
  • Added a sample agent demonstrating the integration and usage of the FallbackPlugin within an App.
• src/google/adk/plugins/init.py
  • Updated the __all__ list to export the newly added FallbackPlugin.
• src/google/adk/plugins/fallback_plugin.py
  • Added the core implementation of the FallbackPlugin class, including its initialization, before_model_callback for model resetting, and after_model_callback for error detection and metadata annotation.
• tests/unittests/plugins/test_fallback_plugin.py
  • Added a new test file containing comprehensive unit tests for the FallbackPlugin, covering various scenarios including initialization, callback behavior, error handling, and memory management.

Activity

• Unit tests were run and all passed, ensuring the new plugin functions as expected.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[adk-bot]

Response from ADK Triaging Agent

Hello @benmizrahi, thank you for creating this PR!

It looks like the Contributor License Agreement (CLA) check has failed. Before we can review your contribution, you'll need to sign the CLA. You can find more information at https://cla.developers.google.com/.

Also, could you please add a testing plan section to your PR description? This will help reviewers understand how you have tested your changes.

Thank you!

[gemini-code-assist]

Code Review

This pull request introduces a FallbackPlugin to handle automatic model fallbacks, complete with documentation, a usage sample, and thorough unit tests. The implementation is well-structured and the feature is a valuable addition. My review includes suggestions to enhance the clarity of the sample agent's configuration, improve the plugin's initialization for better safety and performance, replace magic numbers with constants for maintainability, and address minor style and logic issues in the unit tests.

[gemini-code-assist]

Code Review

This pull request introduces a FallbackPlugin to handle model fallbacks for specific HTTP error codes. The implementation is solid, with good documentation and comprehensive unit tests. My main feedback is to ensure consistency in the model names used in the README examples to align with the sample code, which will improve clarity for users.

[gemini-code-assist]

The model names in this configuration example are inconsistent with the sample agent code (agent.py). To avoid confusion, please update the model names to match the sample implementation (gemini-3-flash-preview and gemini-2.5-pro).

Suggested change

	root_model="gemini-2.0-flash", # Primary model, always tried first.
	fallback_model="gemini-1.5-pro", # Backup model recorded in metadata.
	root_model="gemini-3-flash-preview", # Primary model, always tried first.
	fallback_model="gemini-2.5-pro", # Backup model recorded in metadata.