Skip to content

ADK 的反思与重试插件

Supported in ADKPython v1.16.0Go v0.5.0

反思与重试插件可以帮助你的智能体从 ADK 工具 的错误响应中恢复，并自动重试工具请求。该插件拦截工具失败，为 AI 模型提供结构化的反思和修正指导，并在可配置的限制内重试操作。此插件可以帮助你在智能体工作流中构建更强的韧性，包括以下功能：

  • 并发安全：使用锁定安全地处理并行工具执行。
  • 可配置范围：按每次调用（默认）或全局跟踪失败。
  • 精细跟踪：按工具跟踪失败次数。
  • 自定义错误提取：支持检测正常工具响应中的错误。

添加反思与重试插件

通过将其添加到 ADK 项目的 App 对象的插件设置中，将此插件添加到你的 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),
    ],
)

import (
    "google.golang.org/adk/v2/plugin/retryandreflect"
    "google.golang.org/adk/v2/runner"
)

// ... 创建 rootAgent 和 sessionService ...

r, err := runner.New(runner.Config{
    AppName:        "my_app",
    Agent:          rootAgent,
    SessionService: sessionService,
    PluginConfig: runner.PluginConfig{
        Plugins: []*plugin.Plugin{
            retryandreflect.MustNew(retryandreflect.WithMaxRetries(3)),
        },
    },
})

使用此配置后，如果智能体调用的任何工具失败并返回错误， 该请求会被更新并重试，每个工具最多重试 3 次，总计最多 4 次尝试。 如果工具在其他方面成功的响应中报告了问题，默认不会重试； 请参阅高级配置了解如何启用该功能。

配置设置

反思与重试插件具有以下配置选项：

  • max_retries：（可选）系统为获得非错误响应所进行的额外尝试总次数。默认值为 3。
  • throw_exception_if_retry_exceeded：（可选）如果设置为 False， 当最终重试尝试失败时，系统不会引发错误。默认 值为 True。Go 中的等效参数 WithErrorIfRetryExceeded 默认为 false，因此当重试次数耗尽时，Go 会返回一条消息告诉 模型停止使用该工具，而 Python 则会引发原始错误。
  • tracking_scope：（可选）一个 TrackingScope 值，从 google.adk.plugins.reflect_retry_tool_plugin 导入：
    • TrackingScope.INVOCATION：在单次调用和单个用户范围内跟踪工具失败。此值为默认值。
    • TrackingScope.GLOBAL：跨所有调用和所有用户范围跟踪工具失败。

高级配置

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

class CustomRetryPlugin(ReflectAndRetryToolPlugin):
  async def extract_error_from_result(self, *, tool, tool_args, tool_context, result):
    # 根据响应内容检测错误
    if result.get('status') == 'error':
        return result
    return None  # 未检测到错误

# 将此修改后的插件添加到你的 App 对象中：
error_handling_plugin = CustomRetryPlugin(max_retries=5)

下一步

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