도구 루프 감지

1. 루프 감지(enabled) - 기본적으로 비활성화됩니다. 순환식으로 유지되는 도구 호출 기록을 감시하여 반복 패턴과 알 수 없는 도구에 대한 재시도를 감지합니다.
2. Compaction 후 보호 장치(postCompactionGuard) - enabled가 명시적으로 false가 아닌 경우 활성화됩니다. Compaction 재시도 후마다 작동 준비 상태가 되며, 에이전트가 해당 범위 내에서 동일한 (tool, args, result) 삼중항을 반복하면 실행을 중단합니다.

​

이 기능이 필요한 이유

• 진행이 없는 반복 시퀀스를 감지합니다.
• 결과가 없는 고빈도 루프(동일한 도구, 동일한 입력, 반복되는 오류)를 감지합니다.
• 알려진 폴링 도구의 특정 반복 호출 패턴을 감지합니다.
• 컨텍스트 오버플로 -> Compaction -> 동일한 루프의 순환이 무한히 실행되지 않도록 중단합니다.

​

구성 블록

{
  tools: {
    loopDetection: {
      enabled: false, // 순환 기록 감지기의 마스터 스위치
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      unknownToolThreshold: 10,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
      postCompactionGuard: {
        windowSize: 3, // Compaction 재시도 후 작동 준비 상태가 됨. enabled가 명시적으로 false가 아니면 실행됨
      },
    },
  },
}

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

​

필드 동작

​

권장 설정

• 소형 모델의 경우 enabled: true를 설정하고 임계값은 기본값으로 유지합니다. 플래그십 모델에는 순환 기록 감지가 필요한 경우가 드물므로, 마스터 스위치를 false로 유지하면서도 Compaction 후 보호 장치의 이점을 얻을 수 있습니다.
• 임계값 순서를 warningThreshold < criticalThreshold < globalCircuitBreakerThreshold로 유지합니다. criticalThreshold 또는 globalCircuitBreakerThreshold를 반드시 초과해야 하는 임계값 이하로 설정하면 런타임이 해당 값을 상향 조정합니다.
• 오탐이 발생하는 경우:
  • warningThreshold 및/또는 criticalThreshold를 높입니다.
  • 필요한 경우 globalCircuitBreakerThreshold를 높입니다.
  • 문제를 일으키는 특정 감지기만 비활성화합니다(detectors.<name>: false).
  • 기록 범위를 줄이려면 historySize를 낮춥니다.
• Compaction 후 보호 장치를 포함한 모든 기능을 비활성화하려면 tools.loopDetection.enabled: false를 명시적으로 설정합니다.

​

Compaction 후 보호 장치

{
  tools: {
    loopDetection: {
      // 마스터 스위치. 보호 장치와 순환 감지기를 함께 비활성화하려면 false로 설정
      enabled: true,
      postCompactionGuard: {
        windowSize: 3, // 기본값
      },
    },
  },
}

• windowSize가 낮을수록 더 엄격합니다(중단 전 시도 횟수가 적음).
• windowSize가 높을수록 에이전트에 더 많은 복구 시도를 허용합니다.
• 결과가 변경되는 동안에는 보호 장치가 실행을 중단하지 않습니다. 범위 전체에서 바이트 단위로 동일한 결과가 발생하는 경우에만 작동합니다.
• 실행의 다른 시점이 아니라 Compaction 재시도 직후에만 작동 준비 상태가 됩니다.

​

로그 및 예상 동작

• 경고가 먼저 발생합니다.
• 패턴이 경고 임계값을 넘어 지속되면 차단됩니다.
• 위험 임계값에 도달하면 다음 도구 주기를 차단하고 실행 기록에 명확한 루프 감지 사유를 표시합니다.
• Compaction 후 보호 장치는 문제가 된 도구와 동일 호출 횟수를 명시하는 compaction_loop_persisted 오류를 발생시킵니다.

​

관련 항목