Wiederholen und reflektieren

Der adk-retry-reflect-Crate stellt ein Plugin bereit, das Tool-Fehler abfängt, Reflexionsaufforderungen in den LLM-Kontext einfügt und Wiederholungsversuche mit exponentiellem Backoff durchführt. Dadurch können sich Agents nach vorübergehenden Fehlern oder fehlerhaften Tool-Aufrufen selbst korrigieren.

Übersicht

Wenn ein Tool-Aufruf fehlschlägt, besteht das Standardverhalten darin, den Fehler an den LLM zurückzugeben und ihn entscheiden zu lassen, wie weiter verfahren werden soll. Das Plugin Retry & Reflect fügt eine strukturierte Wiederherstellung hinzu:

1. Fängt den Tool-Fehler ab, bevor er den LLM erreicht
2. Fügt eine Reflexionsaufforderung ein, in der das Modell aufgefordert wird, zu analysieren, was schiefgelaufen ist
3. Wiederholt den Tool-Aufruf mit korrigierten Argumenten
4. Vergrößert die Wartezeit exponentiell, wenn die Fehler bestehen bleiben
5. Unterbricht den Ablauf nach wiederholten Fehlern, um Endlosschleifen zu verhindern

Installation

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

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

Schnellstart

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()?;

Konfiguration

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();

Konfigurationsreferenz

Schutzschalter

Der Schutzschalter verhindert endlose Wiederholungsschleifen, wenn ein Tool dauerhaft fehlschlägt:

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

Wenn der Schutzschalter geöffnet ist:

• Tool-Aufrufe schlagen sofort mit einem Schutzschalterfehler fehl
• Es werden keine Wiederholungsversuche unternommen
• Nach circuit_breaker_reset_ms wird der nächste Aufruf durchgelassen (halb geöffnet)
• Bei Erfolg schließt sich der Schutzschalter; bei einem Fehlschlag bleibt er geöffnet

Funktionsweise der Reflexion

Wenn ein Tool-Aufruf fehlschlägt, fügt das Plugin eine Reflexionsaufforderung in die Unterhaltung ein:

[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"}

Die Reflexionsaufforderung gibt LLM einen ausdrücklichen Kontext zum Fehlschlag, damit es sich selbst korrigieren kann, anstatt denselben Fehler zu wiederholen.

Wann sollte dies verwendet werden?

Gut geeignet:

• Tools, die externe APIs mit vorübergehenden Fehlern aufrufen
• Tools, bei denen LLM möglicherweise leicht fehlerhafte Argumente bereitstellt
• Datenbankabfragen, die aufgrund von Verbindungsproblemen fehlschlagen können
• Dateioperationen auf vernetztem Speicher

Nicht gut geeignet:

• Tools, die deterministisch fehlerhaft sind (stattdessen das Tool korrigieren)
• Lang laufende Tools, bei denen Wiederholungsversuche kostspielig sind
• Tools mit Seiteneffekten, die nicht idempotent sind (z. B. das Senden von E-Mails)
• Ablaufsteuerungstools wie exit_loop

Kombination mit anderen Plugins

Retry & Reflect berücksichtigt die Prioritätsreihenfolge der Plugins:

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()?;

Beobachtbarkeit

Das Plugin gibt Tracing-Spans für Wiederholungsversuche aus:

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

Verwandte Themen

• Plugins — Architektur des Pluginsystems
• Function Tools — Erstellen von Tools
• Evaluation — Testen der Resilienz des Agenten

---

Zurück: ← ACP Tools | Weiter: Action Nodes →