From 7733d1916b9448b317a6f339fcd8ab680fb5994e Mon Sep 17 00:00:00 2001 From: adk-bot Date: Wed, 22 Oct 2025 21:04:17 +0000 Subject: [PATCH 1/6] docs: Add documentation for ReflectAndRetryToolPlugin --- docs/plugins/reflect-and-retry.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs/plugins/reflect-and-retry.md diff --git a/docs/plugins/reflect-and-retry.md b/docs/plugins/reflect-and-retry.md new file mode 100644 index 000000000..c83ee084f --- /dev/null +++ b/docs/plugins/reflect-and-retry.md @@ -0,0 +1,29 @@ +# Reflect and Retry Tool Plugin + +The `ReflectAndRetryToolPlugin` provides self-healing, concurrent-safe error recovery for tool failures. + +**Key Features:** +- **Concurrency Safe**: Uses locking to safely handle parallel tool executions. +- **Configurable Scope**: Tracks failures per-invocation (default) or globally. +- **Granular Tracking**: Failure counts are tracked per-tool. +- **Custom Error Extraction**: Supports detecting errors in normal tool responses. + +## Basic Usage + +The following example shows how to use the plugin to retry a tool that can fail. + +```python +from google.adk.apps.app import App +from google.adk.plugins import ReflectAndRetryToolPlugin + +app = App( + name="my_app", + root_agent=root_agent, + plugins=[ + ReflectAndRetryToolPlugin( + max_retries=6, throw_exception_if_retry_exceeded=False + ), + ], +) +``` +For a complete example, see the [plugin_reflect_tool_retry sample](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry). From 92c975591db953c61fcf259f80c1bbaeb8e11677 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Wed, 5 Nov 2025 03:33:57 +0000 Subject: [PATCH 2/6] docs: add Reflect and Retry plugin page --- docs/plugins/reflect-and-retry.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/plugins/reflect-and-retry.md b/docs/plugins/reflect-and-retry.md index c83ee084f..ff8698f30 100644 --- a/docs/plugins/reflect-and-retry.md +++ b/docs/plugins/reflect-and-retry.md @@ -3,10 +3,11 @@ The `ReflectAndRetryToolPlugin` provides self-healing, concurrent-safe error recovery for tool failures. **Key Features:** -- **Concurrency Safe**: Uses locking to safely handle parallel tool executions. -- **Configurable Scope**: Tracks failures per-invocation (default) or globally. -- **Granular Tracking**: Failure counts are tracked per-tool. -- **Custom Error Extraction**: Supports detecting errors in normal tool responses. + +- **Concurrency Safe**: Uses locking to safely handle parallel tool executions. +- **Configurable Scope**: Tracks failures per-invocation (default) or globally. +- **Granular Tracking**: Failure counts are tracked per-tool. +- **Custom Error Extraction**: Supports detecting errors in normal tool responses. ## Basic Usage @@ -21,9 +22,15 @@ app = App( root_agent=root_agent, plugins=[ ReflectAndRetryToolPlugin( - max_retries=6, throw_exception_if_retry_exceeded=False + max_retries=6, + throw_exception_if_retry_exceeded=False ), ], ) ``` + For a complete example, see the [plugin_reflect_tool_retry sample](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry). + + +## Configuration settings + From ae8da9b38e0e3ee5896c684a71b242b1cdf585b0 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Wed, 5 Nov 2025 05:13:10 +0000 Subject: [PATCH 3/6] docs: Reflect and Retry Plugin page --- docs/plugins/index.md | 16 +++++++ docs/plugins/reflect-and-retry.md | 75 +++++++++++++++++++++++++------ mkdocs.yml | 1 + 3 files changed, 78 insertions(+), 14 deletions(-) diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 5408e9de2..c674b36d7 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -55,6 +55,22 @@ related callback functions together to be used across a workflow. This makes Plugins an ideal solution for implementing features that cut across your entire agent application. +## Prebuilt Plugins + +ADK includes several plugins that you can add to your agent workflows +immediately: + +* [**Reflect and Retry Tools**](/adk-docs/plugins/reflect-and-retry/): + Tracks tool failures and intelligently retries tool requests. +* [**BigQuery Logging**](https://github.com/google/adk-python/blob/main/src/google/adk/plugins/bigquery_logging_plugin.py): + Enables agent logging and analysis with BigQuery. +* [**Context Filter**](https://github.com/google/adk-python/blob/main/src/google/adk/plugins/context_filter_plugin.py): + Filters the generative AI context to reduce its size. +* [**Global Instruction**](https://github.com/google/adk-python/blob/main/src/google/adk/plugins/global_instruction_plugin.py): + Plugin that provides global instructions functionality at the App level. +* [**Save Files as Artifacts**](https://github.com/google/adk-python/blob/main/src/google/adk/plugins/save_files_as_artifacts_plugin.py): + Saves files included in user messages as Artifacts. + ## Define and register Plugins This section explains how to define Plugin classes and register them as part of diff --git a/docs/plugins/reflect-and-retry.md b/docs/plugins/reflect-and-retry.md index ff8698f30..909e26283 100644 --- a/docs/plugins/reflect-and-retry.md +++ b/docs/plugins/reflect-and-retry.md @@ -1,17 +1,25 @@ # Reflect and Retry Tool Plugin -The `ReflectAndRetryToolPlugin` provides self-healing, concurrent-safe error recovery for tool failures. +
+ Supported in ADKPython v1.16.0 +
-**Key Features:** +The Refect and Retry Tool plugin can help your agent recover from error +responses from ADK [Tools](/adk-docs/tools-custom/) and automatically retry the +tool request. This plugin intercepts tool failures, provides structured guidance +to the AI model for reflection and correction, and retries the operation up to a +configurable limit. This plugin can help you build more resilience into your +agent workflows, including the following capabilities: -- **Concurrency Safe**: Uses locking to safely handle parallel tool executions. -- **Configurable Scope**: Tracks failures per-invocation (default) or globally. -- **Granular Tracking**: Failure counts are tracked per-tool. -- **Custom Error Extraction**: Supports detecting errors in normal tool responses. +* **Concurrency safe**: Uses locking to safely handle parallel tool executions. +* **Configurable scope**: Tracks failures per-invocation (default) or globally. +* **Granular tracking**: Failure counts are tracked per-tool. +* **Custom error extraction**: Supports detecting errors in normal tool responses. -## Basic Usage +## Add Reflect and Retry Plugin -The following example shows how to use the plugin to retry a tool that can fail. +Add this plugin to your ADK workflow by adding it to the plugins setting of your +App object, as shown below: ```python from google.adk.apps.app import App @@ -21,16 +29,55 @@ app = App( name="my_app", root_agent=root_agent, plugins=[ - ReflectAndRetryToolPlugin( - max_retries=6, - throw_exception_if_retry_exceeded=False - ), + ReflectAndRetryToolPlugin(max_retries=3), ], ) ``` -For a complete example, see the [plugin_reflect_tool_retry sample](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry). - +With this configuration, if any tool called by an agent returns an error, the +request is updated and tried again, up to a maximum of 3 attempts, per tool. ## Configuration settings +The Reflect and Retry Plugin has the following configuration options: + +* **`max_retries`**: (optional) Total number of additional attempts the system + makes to receive a non-error response. Default value is 3. +* **`throw_exception_if_retry_exceeded`**: (optional) If set to `False`, the + system does not raise an error if the final retry attempt fails. Default + value is `True`. +* **`tracking_scope`**: (optional) + * **`TrackingScope.INVOCATION`**: Track tool failures across a single + invocation and user. This value is the default. + * **`TrackingScope.GLOBAL`**: Track tool failures across all invocations + and all users. + +### Advanced configuration + +You can further modify the behavior of this plugin by extending the +`ReflectAndRetryToolPlugin` class. The following code sample +demonstrates a simple extension of the behavior by selecting +responses with an error status: + +```python +class CustomRetryPlugin(ReflectAndRetryToolPlugin): + async def extract_error_from_result(self, *, tool, tool_args,tool_context, + result): + # Detect error based on response content + if result.get('status') == 'error': + return result + return None # No error detected + +# add this modified plugin to your App object: +error_handling_plugin = CustomRetryPlugin(max_retries=5) +``` + +For a complete implementation of this sample, see the +[Basic sample](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/basic). + +## Next steps + +For complete code samples using this plugin, see the following: + +* [Basic sample](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/basic) +* [Hallucinating function name](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/hallucinating_func_name) diff --git a/mkdocs.yml b/mkdocs.yml index 9eb3abbfd..2f3318a1d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -230,6 +230,7 @@ nav: - events/index.md - Plugins: - plugins/index.md + - Reflect and retry: plugins/reflect-and-retry.md - MCP: - mcp/index.md - A2A Protocol: From 215ce6a833a466a6144c6d67819ccfe36a283ee5 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Wed, 5 Nov 2025 22:29:09 +0000 Subject: [PATCH 4/6] resolve review comments --- docs/plugins/index.md | 2 ++ docs/plugins/reflect-and-retry.md | 8 ++++---- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/plugins/index.md b/docs/plugins/index.md index c674b36d7..d16fa12b7 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -70,6 +70,8 @@ immediately: Plugin that provides global instructions functionality at the App level. * [**Save Files as Artifacts**](https://github.com/google/adk-python/blob/main/src/google/adk/plugins/save_files_as_artifacts_plugin.py): Saves files included in user messages as Artifacts. +* [**Logging**](https://github.com/google/adk-python/blame/main/src/google/adk/plugins/logging_plugin.py): + Log important information at each agent workflow callback point. ## Define and register Plugins diff --git a/docs/plugins/reflect-and-retry.md b/docs/plugins/reflect-and-retry.md index 909e26283..20b95944b 100644 --- a/docs/plugins/reflect-and-retry.md +++ b/docs/plugins/reflect-and-retry.md @@ -4,7 +4,7 @@ Supported in ADKPython v1.16.0 -The Refect and Retry Tool plugin can help your agent recover from error +The Reflect and Retry Tool plugin can help your agent recover from error responses from ADK [Tools](/adk-docs/tools-custom/) and automatically retry the tool request. This plugin intercepts tool failures, provides structured guidance to the AI model for reflection and correction, and retries the operation up to a @@ -77,7 +77,7 @@ For a complete implementation of this sample, see the ## Next steps -For complete code samples using this plugin, see the following: +For complete code samples using the Reflect and Retry plugin, see the following: -* [Basic sample](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/basic) -* [Hallucinating function name](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/hallucinating_func_name) +* [Basic](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/basic) code sample +* [Hallucinating function name](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/hallucinating_func_name) code sample From ecb0df6e960e85c34f308ba38653cd5263023207 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Wed, 5 Nov 2025 22:38:12 +0000 Subject: [PATCH 5/6] final review comments --- docs/plugins/reflect-and-retry.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/plugins/reflect-and-retry.md b/docs/plugins/reflect-and-retry.md index 20b95944b..bed76a140 100644 --- a/docs/plugins/reflect-and-retry.md +++ b/docs/plugins/reflect-and-retry.md @@ -19,7 +19,7 @@ agent workflows, including the following capabilities: ## Add Reflect and Retry Plugin Add this plugin to your ADK workflow by adding it to the plugins setting of your -App object, as shown below: +ADK project's App object, as shown below: ```python from google.adk.apps.app import App @@ -72,12 +72,11 @@ class CustomRetryPlugin(ReflectAndRetryToolPlugin): error_handling_plugin = CustomRetryPlugin(max_retries=5) ``` -For a complete implementation of this sample, see the -[Basic sample](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/basic). - ## Next steps For complete code samples using the Reflect and Retry plugin, see the following: -* [Basic](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/basic) code sample -* [Hallucinating function name](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/hallucinating_func_name) code sample +* [Basic](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/basic) + code sample +* [Hallucinating function name](https://github.com/google/adk-python/tree/main/contributing/samples/plugin_reflect_tool_retry/hallucinating_func_name) + code sample From 64850f140a17bae9c1cc7d3205276656ad2daa74 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Wed, 5 Nov 2025 22:43:15 +0000 Subject: [PATCH 6/6] fix broken link --- docs/plugins/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/index.md b/docs/plugins/index.md index d16fa12b7..8ea1f8c74 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -209,7 +209,7 @@ Hello world: query is [hello world] For more information on running ADK agents, see the -[Quickstart](/get-started/quickstart/#run-your-agent) +[Quickstart](/adk-docs/get-started/quickstart/#run-your-agent) guide. ## Build workflows with Plugins