リトライと振り返り

adk-retry-reflect crate は、ツールの失敗をインターセプトし、LLM コンテキストに振り返りプロンプトを注入し、指数バックオフで再試行するプラグインを提供します。これにより、エージェントは一時的なエラーや不正なツール呼び出しの後に自己修正できるようになります。

概要

ツール呼び出しが失敗すると、デフォルトの動作ではエラーをLLMに返し、何をするかを判断させます。Retry & Reflect プラグインは、構造化された復旧機能を追加します。

1. ツールの失敗がLLMに到達する前にインターセプトする
2. 何が問題だったのかをモデルに分析させる振り返りプロンプトを注入する
3. 修正された引数でツール呼び出しを再試行する
4. 失敗が続く場合は指数関数的にバックオフする
5. 無限ループを防ぐため、失敗を繰り返した後にサーキットブレーカーを作動させる

インストール

[dependencies]
adk-retry-reflect = "2.1.0"

# Or via umbrella crate (included in standard tier)
adk-rust = { version = "2.1.0", features = ["standard"] }

クイックスタート

use adk_retry_reflect::RetryReflectPlugin;
use adk_agent::LlmAgentBuilder;
use std::sync::Arc;

let plugin = RetryReflectPlugin::builder()
    .max_retries(3)
    .initial_backoff_ms(500)
    .backoff_multiplier(2.0)
    .build();

let agent = LlmAgentBuilder::new("resilient_agent")
    .model(model)
    .instruction("You are a helpful assistant with access to external APIs.")
    .tool(Arc::new(flaky_api_tool))
    .plugin(Arc::new(plugin))
    .build()?;

設定

use adk_retry_reflect::{RetryReflectPlugin, RetryReflectConfig};

let plugin = RetryReflectPlugin::builder()
    // Retry settings
    .max_retries(3)                    // Maximum retry attempts [default: 3]
    .initial_backoff_ms(500)           // First retry delay in ms [default: 500]
    .backoff_multiplier(2.0)           // Multiply delay each retry [default: 2.0]
    .max_backoff_ms(30_000)            // Cap delay at this value [default: 30000]

    // Circuit breaker
    .circuit_breaker_threshold(5)      // Open circuit after N failures [default: 5]
    .circuit_breaker_reset_ms(60_000)  // Reset circuit after this duration [default: 60000]

    // Reflection
    .reflection_prompt(                // Custom reflection prompt template
        "The tool '{tool_name}' failed with: {error}. \
         Analyze what went wrong and provide corrected arguments."
    )

    // Scope
    .include_tools(&["api_call", "db_query"])  // Only retry these tools
    .exclude_tools(&["exit_loop"])             // Never retry these tools

    .build();

設定リファレンス

サーキットブレーカー

サーキットブレーカーは、ツールが継続的に失敗する場合に、無限の再試行ループを防ぎます。

Closed (normal) ─── failure count >= threshold ──→ Open (all calls fail fast)
       ↑                                                    │
       └──────── reset_ms elapsed, next call succeeds ──────┘
                              (Half-Open)

サーキットが開いている場合:

• ツール呼び出しはサーキットブレーカーエラーで直ちに失敗します
• 再試行は行われません
• circuit_breaker_reset_ms後、次の呼び出しが通過できるようになります（ハーフオープン）
• 成功した場合、サーキットは閉じます。失敗した場合、サーキットは開いたままになります

リフレクションの仕組み

ツール呼び出しが失敗すると、プラグインは会話にリフレクションプロンプトを挿入します。

[User]: What's the weather in NYC?
[Model]: *calls get_weather({"city": "nyc", "units": "kelvin"})*
[Tool Error]: Invalid units. Supported: celsius, fahrenheit
[Plugin injects]: The tool 'get_weather' failed with: "Invalid units. 
    Supported: celsius, fahrenheit". Analyze what went wrong and provide 
    corrected arguments.
[Model]: *calls get_weather({"city": "NYC", "units": "celsius"})*
[Tool Success]: {"temperature": 22, "condition": "sunny"}

リフレクションプロンプトは、LLMに失敗に関する明示的なコンテキストを提供するため、同じ間違いを繰り返すのではなく自己修正できます。

使用する場合

適しているケース:

• 一時的な失敗が発生する外部APIsを呼び出すツール
• LLMがわずかに不正な引数を提供する可能性があるツール
• 接続の問題によって失敗する可能性があるデータベースクエリ
• ネットワーク接続されたストレージ上のファイル操作

適していないケース:

• 決定論的に壊れているツール（代わりにツールを修正してください）
• 再試行のコストが高い長時間実行ツール
• 副作用があり、べき等でないツール（例: メールの送信）
• exit_loopのような制御フローツール

他のプラグインとの組み合わせ

Retry & Reflectは、プラグインの優先度順序を尊重します。

use adk_plugin::PluginManager;

let agent = LlmAgentBuilder::new("agent")
    .model(model)
    .plugin(Arc::new(logging_plugin))         // Priority 1 (runs first)
    .plugin(Arc::new(retry_reflect_plugin))   // Priority 2
    .plugin(Arc::new(guardrail_plugin))       // Priority 3 (runs last)
    .build()?;

可観測性

プラグインは再試行の試みに対するトレーシングスパンを出力します。

WARN adk_retry_reflect: tool call failed, retrying
    tool_name=get_weather attempt=1 max=3 backoff_ms=500
    error="Invalid units"

INFO adk_retry_reflect: retry succeeded
    tool_name=get_weather attempt=2

WARN adk_retry_reflect: circuit breaker opened
    tool_name=broken_api failures=5 reset_ms=60000

関連項目

• プラグイン — プラグインシステムのアーキテクチャ
• Function Tools — ツールの作成
• 評価 — エージェントの耐障害性のテスト

---

前へ: ← ACP Tools | 次へ: Action Nodes →