Détection des boucles d’outils

1. Détection des boucles (enabled) — désactivée par défaut. Surveille l’historique glissant des appels d’outils afin de repérer les schémas répétitifs et les nouvelles tentatives d’utilisation d’outils inconnus.
2. Garde post-Compaction (postCompactionGuard) — activée tant que enabled n’est pas explicitement défini sur false. Elle s’arme après chaque nouvelle tentative suivant une Compaction et interrompt l’exécution si l’agent répète le même triplet (outil, arguments, résultat) dans la fenêtre.

​

Pourquoi ce mécanisme existe

• Détecter les séquences répétitives qui ne produisent aucune progression.
• Détecter les boucles à haute fréquence sans résultat (même outil, mêmes entrées, erreurs répétées).
• Détecter des schémas spécifiques d’appels répétés pour les outils d’interrogation connus.
• Interrompre les cycles dépassement de contexte -> Compaction -> même boucle au lieu de les laisser s’exécuter indéfiniment.

​

Bloc de configuration

{
  tools: {
    loopDetection: {
      enabled: false, // commutateur principal des détecteurs basés sur l’historique glissant
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      unknownToolThreshold: 10,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
      postCompactionGuard: {
        windowSize: 3, // armé après une nouvelle tentative suivant une Compaction ; s’exécute sauf si enabled vaut explicitement false
      },
    },
  },
}

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

​

Comportement des champs

​

Configuration recommandée

• Pour les modèles plus petits, définissez enabled: true et conservez les seuils par défaut. Les modèles de pointe ont rarement besoin de la détection basée sur l’historique glissant et peuvent conserver le commutateur principal sur false tout en bénéficiant de la garde post-Compaction.
• Conservez les seuils dans l’ordre warningThreshold < criticalThreshold < globalCircuitBreakerThreshold ; à l’exécution, criticalThreshold et globalCircuitBreakerThreshold sont augmentés si vous les définissez à une valeur inférieure ou égale au seuil qu’ils doivent dépasser.
• En cas de faux positifs :
  • Augmentez warningThreshold et/ou criticalThreshold.
  • Augmentez éventuellement globalCircuitBreakerThreshold.
  • Désactivez uniquement le détecteur précis à l’origine des problèmes (detectors.<name>: false).
  • Réduisez historySize pour raccourcir la fenêtre historique.
• Pour tout désactiver, y compris la garde post-Compaction, définissez explicitement tools.loopDetection.enabled: false.

​

Garde post-Compaction

{
  tools: {
    loopDetection: {
      // commutateur principal ; définissez-le sur false pour désactiver la garde avec les détecteurs basés sur l’historique glissant
      enabled: true,
      postCompactionGuard: {
        windowSize: 3, // valeur par défaut
      },
    },
  },
}

• Une valeur windowSize plus faible est plus stricte (moins de tentatives avant l’interruption).
• Une valeur windowSize plus élevée accorde davantage de tentatives de récupération à l’agent.
• La garde n’interrompt jamais l’exécution tant que les résultats changent ; seuls des résultats identiques octet par octet dans toute la fenêtre la déclenchent.
• Elle ne s’arme que juste après une nouvelle tentative suivant une Compaction, et non à d’autres moments de l’exécution.

​

Journaux et comportement attendu

• Les avertissements surviennent en premier.
• Le blocage intervient lorsqu’un schéma persiste au-delà du seuil d’avertissement.
• Les seuils critiques bloquent le cycle d’outil suivant et indiquent clairement la raison de la détection de boucle dans l’enregistrement de l’exécution.
• La garde post-Compaction émet des erreurs compaction_loop_persisted qui indiquent l’outil en cause et le nombre d’appels identiques.

​

Voir aussi