Detecção de loop de ferramentas

1. Detecção de loops (enabled) - desabilitada por padrão. Monitora o histórico contínuo de chamadas de ferramentas em busca de padrões repetidos e novas tentativas com ferramentas desconhecidas.
2. Proteção pós-Compaction (postCompactionGuard) - habilitada sempre que enabled não for explicitamente false. É armada após cada nova tentativa decorrente de Compaction e interrompe a execução se o agente repetir a mesma tripla (tool, args, result) dentro da janela.

​

Por que isso existe

• Detectar sequências repetitivas que não produzem progresso.
• Detectar loops de alta frequência sem resultados (mesma ferramenta, mesmas entradas e erros repetidos).
• Detectar padrões específicos de chamadas repetidas para ferramentas de sondagem conhecidas.
• Interromper ciclos de estouro de contexto -> Compaction -> mesmo loop, em vez de permitir que continuem indefinidamente.

​

Bloco de configuração

{
  tools: {
    loopDetection: {
      enabled: false, // master switch for the rolling-history detectors
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      unknownToolThreshold: 10,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
      postCompactionGuard: {
        windowSize: 3, // armed after compaction-retry; runs unless enabled is explicitly false
      },
    },
  },
}

{
  agents: {
    list: [
      {
        id: "safe-runner",
        tools: {
          loopDetection: {
            enabled: true,
            warningThreshold: 8,
            criticalThreshold: 16,
          },
        },
      },
    ],
  },
}

​

Comportamento dos campos

​

Configuração recomendada

• Para modelos menores, defina enabled: true e mantenha os valores padrão dos limites. Modelos de ponta raramente precisam da detecção por histórico contínuo e podem manter a chave principal como false, ainda se beneficiando da proteção pós-Compaction.
• Mantenha os limites na ordem warningThreshold < criticalThreshold < globalCircuitBreakerThreshold; o runtime aumenta criticalThreshold e globalCircuitBreakerThreshold se você os definir com valor igual ou inferior ao limite que eles precisam exceder.
• Se ocorrerem falsos positivos:
  • Aumente warningThreshold e/ou criticalThreshold.
  • Opcionalmente, aumente globalCircuitBreakerThreshold.
  • Desabilite somente o detector específico que está causando problemas (detectors.<name>: false).
  • Reduza historySize para usar uma janela histórica mais curta.
• Para desabilitar tudo, incluindo a proteção pós-Compaction, defina explicitamente tools.loopDetection.enabled: false.

​

Proteção pós-Compaction

{
  tools: {
    loopDetection: {
      // master switch; set false to disable the guard along with the rolling detectors
      enabled: true,
      postCompactionGuard: {
        windowSize: 3, // default
      },
    },
  },
}

• Um windowSize menor é mais rigoroso (menos tentativas antes da interrupção).
• Um windowSize maior oferece ao agente mais tentativas de recuperação.
• A proteção nunca interrompe a execução enquanto os resultados estiverem mudando; somente resultados idênticos byte a byte ao longo da janela a acionam.
• Ela é armada somente imediatamente após uma nova tentativa de Compaction, e não em outros pontos de uma execução.

​

Logs e comportamento esperado

• Os avisos ocorrem primeiro.
• O bloqueio ocorre quando um padrão persiste além do limite de aviso.
• Os limites críticos bloqueiam o próximo ciclo de ferramenta e apresentam um motivo claro de detecção de loop no registro da execução.
• A proteção pós-Compaction emite erros compaction_loop_persisted que identificam a ferramenta responsável e a contagem de chamadas idênticas.

​

Conteúdo relacionado