Repetir e refletir

O crate adk-retry-reflect fornece um plugin que intercepta falhas de ferramentas, insere prompts de reflexão no contexto de LLM e repete a tentativa com recuo exponencial. Isso dá aos agentes a capacidade de se autocorrigir após erros transitórios ou chamadas de ferramenta malformadas.

Visão geral

Quando uma chamada de ferramenta falha, o comportamento padrão é retornar o erro para LLM e permitir que ele decida o que fazer. O plugin Retry & Reflect adiciona uma recuperação estruturada:

1. Intercepta a falha da ferramenta antes que ela chegue a LLM
2. Insere um prompt de reflexão solicitando que o modelo analise o que deu errado
3. Repete a chamada da ferramenta com argumentos corrigidos
4. Aumenta o recuo exponencialmente se as falhas persistirem
5. Interrompe o circuito após falhas repetidas para evitar loops infinitos

Instalação

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

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

Início rápido

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

Configuração

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

Referência de configuração

Disjuntor

O disjuntor impede loops infinitos de novas tentativas quando uma ferramenta falha persistentemente:

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

Quando o circuito está aberto:

• As chamadas de ferramentas falham imediatamente com um erro de disjuntor
• Nenhuma nova tentativa é realizada
• Após circuit_breaker_reset_ms, a próxima chamada é permitida (meio-aberto)
• Se for bem-sucedida, o circuito fecha; se falhar, o circuito permanece aberto

Como a Reflexão Funciona

Quando uma chamada de ferramenta falha, o plugin injeta um prompt de reflexão na conversa:

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

O prompt de reflexão fornece ao LLM um contexto explícito sobre a falha, para que ele possa se autocorrigir em vez de repetir o mesmo erro.

Quando Usar

Boa opção:

• Ferramentas que chamam APIs externos com falhas transitórias
• Ferramentas nas quais o LLM pode fornecer argumentos ligeiramente malformados
• Consultas ao banco de dados que podem falhar devido a problemas de conexão
• Operações de arquivo em armazenamento conectado à rede

Não é uma boa opção:

• Ferramentas que estão quebradas de forma determinística (corrija a ferramenta)
• Ferramentas de execução longa, nas quais novas tentativas são dispendiosas
• Ferramentas com efeitos colaterais que não são idempotentes (por exemplo, enviar e-mails)
• Ferramentas de fluxo de controle, como exit_loop

Combinação com Outros Plugins

Retry & Reflect respeita a ordenação de prioridade dos 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()?;

Observabilidade

O plugin emite spans de rastreamento para as tentativas:

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

Relacionado

• Plugins — Arquitetura do sistema de plugins
• Function Tools — Criação de ferramentas
• Evaluation — Teste da resiliência do agente

---

Anterior: ← ACP Tools | Próximo: Action Nodes →