Skip to content

Reflect and Retry Tool Plugin

反思和重试工具插件

Supported in ADKPython v1.16.0

The Reflect and Retry Tool plugin can help your agent recover from error responses from ADK Tools 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:

反思和重试工具插件可以帮助您的智能体从 ADK 工具 的错误响应中恢复,并自动重试工具请求。此插件会拦截工具失败,为 AI 模型提供结构化指导以进行反思和纠正,并重试操作,最多达到可配置的限制。此插件可以帮助您在智能体工作流中构建更强的弹性,包括以下功能:

  • 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. 自定义错误提取: 支持在正常工具响应中检测错误。

Add Reflect and Retry Plugin

添加反思和重试插件

Add this plugin to your ADK workflow by adding it to the plugins setting of your ADK project's App object, as shown below:

通过将此插件添加到 ADK 项目 App 对象的 plugins 设置中,将其添加到 ADK 工作流中,如下所示:

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=3),
    ],
)

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.

使用此配置,如果智能体调用的任何工具返回错误,请求将被更新并重试,每个工具最多 3 次。

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. (可选)系统为获得非错误响应而进行的额外尝试总数。默认值为 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. (可选)如果设置为 False,则当最终重试尝试失败时,系统不会引发错误。默认值为 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:

您可以通过扩展 ReflectAndRetryToolPlugin 类来进一步修改此插件的行为。以下代码示例演示了通过选择具有错误状态的响应来简单扩展行为:

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:
# 将此修改后的插件添加到您的 App 对象中:
error_handling_plugin = CustomRetryPlugin(max_retries=5)

Next steps

后续步骤

For complete code samples using the Reflect and Retry plugin, see the following:

有关使用反思和重试插件的完整代码示例,请参阅以下内容: