에이전트 루프는 정지 신호로 도는 while문이다
Claude API의 툴콜 루프는 사실 stop_reason 하나로 도는 while문입니다. 모델이 도구를 부르면 stop_reason은 tool_use이고, 애플리케이션은 도구를 실행해 결과를 메시지에 이어붙인 뒤 다시 호출합니다. 모델이 더 부를 도구가 없으면 stop_reason은 end_turn이 되어 루프가 끝납니다. 실무에서는 이 둘 외에도 토큰 한도의 max_tokens, 서버 도구 반복 한도의 pause_turn, 정책상 거부인 refusal까지 각각 다른 분기가 필요합니다.
콜봇·챗봇에서는 루프 한 바퀴가 그대로 사용자의 대기 시간이다
배치 리서치 에이전트는 툴콜이 몇 번 더 돌아도 티가 안 납니다. 하지만 콜봇은 수화기를 든 채, 챗봇은 화면을 보며 기다리므로 루프 한 바퀴가 그대로 체감 지연이 됩니다. 그래서 반복 종료 조건은 비용 통제 이전에 응대 품질 요건입니다.
웹훅 타임아웃이 루프 예산을 결정한다
루프의 각 턴은 보통 외부 웹훅이나 API를 부릅니다. Dialogflow CX는 웹훅 타임아웃 기본값을 5초로 두고 최대 30초까지만 늘릴 수 있게 제한하는데, 이 상한이 한 턴에 들어갈 수 있는 도구 호출 횟수를 사실상 정합니다. 타임아웃을 도구별로 나누지 않으면 느린 호출 하나가 턴 지연 예산을 혼자 다 씁니다.
설계에서 운영까지: 툴콜 루프 안전장치 구축 가이드
코드를 짜기 전에 반복 상한·턴 지연·웹훅 타임아웃을 숫자로 먼저 정합니다. Anthropic 문서는 서버 도구 샘플링 루프의 기본 반복 한도를 10회로, pause_turn 이후 이어갈 수 있는 연속 횟수를 최대 5회로 권장합니다. 이를 기준선 삼아 실시간 콜봇처럼 지연에 민감한 채널은 세션 전체 반복 상한 10회·웹훅 타임아웃 기본 5초(최대 15초)·턴 처리 p95 3초 이내를 배포 전 목표로 잡고, 웹 챗봇처럼 비실시간 채널은 반복 상한을 25회까지 늘려도 됩니다.
첫 번째 실패는 반복 상한 자체를 두지 않는 것입니다. Anthropic 문서의 예시 코드는 max_iterations=50이라는 값을 정상 종료 조건이 아니라 "안전망"으로 명시합니다. 이 한도에 실제로 도달하는 세션이 나온다면 그 자체를 장애 신호로 다뤄야지, 한도를 더 늘려 덮어버리면 안 됩니다.
두 번째는 tool_result 뒤에 텍스트 블록을 바로 붙이는 실수입니다. 문서에 따르면 이 패턴은 모델이 "도구 호출 다음엔 사용자 차례"로 학습하게 만들어, 2~3토큰짜리 빈 응답과 end_turn을 함께 반환하게 합니다. 콜봇에서는 이게 무음 구간으로, 챗봇에서는 빈 말풍선으로 그대로 드러납니다. 복구책은 tool_result 뒤에 별도 텍스트를 넣지 않는 것과, 빈 응답이 재발하면 새 사용자 메시지로 "계속하라"는 트리거를 넣어 재요청하는 것입니다.
세 번째는 웹훅 재시도 범위를 잘못 잡는 것입니다. Dialogflow CX 문서는 타임아웃·연결 오류 같은 비종료성 오류만 재시도하라고 명시합니다. 4xx처럼 다시 불러도 결코 성공하지 못할 오류까지 반복하면 루프만 헛돌며 지연이 쌓입니다. 재시도에는 지수 백오프를 적용하고, 결제·예약처럼 부작용이 있는 호출에는 멱등키를 붙여 중복 실행을 막습니다.
stop_reason별 분기는 코드에 명시적으로 남깁니다: tool_use는 실행 후 계속, pause_turn은 5회까지만 이어가고 초과 시 사람 상담으로 전환, refusal은 폴백 모델로 한 번 재시도 후 안전 응답, max_tokens로 도구 호출이 잘렸다면 그 턴만 큰 토큰 한도로 재요청합니다. 분기가 없으면 모든 실패가 "한 번 더 시도"로 뭉뚱그려집니다.
배포 전에는 항상 실패하는 도구, 5초 넘게 걸리는 도구, 스키마가 깨진 응답을 내는 도구 세 종류를 일부러 붙여 시나리오 테스트를 돌립니다. 턴마다 반복 횟수·stop_reason·웹훅 지연·재시도 횟수를 표준 로그 필드로 남기고, 통화·대화 내용에 섞인 계좌번호·전화번호 같은 개인정보는 로그에 적재하기 전에 마스킹합니다.
반복 상한이나 max_continuations에 실제로 걸린 세션은 주 단위로 모아 원인을 스키마 변경·하위 API 응답 변화·프롬프트 회귀 세 갈래로 분류합니다. 평균 반복 횟수가 주 단위로 늘어나는 추세라면 새 기능보다 그 원인 조사를 먼저 올립니다. 도구 계약을 바꿀 때는 로그 스키마 변경도 같은 커밋에 묶어야 대시보드 지표가 끊기지 않습니다.
바로 쓰는 체크리스트
챗봇·콜봇 에이전트 루프는 stop_reason별 분기와 반복 상한이 없으면 지연과 비용이 조용히 쌓입니다. 세션 반복 상한 10회·웹훅 타임아웃 기본 5초(최대 15초)·턴 처리 p95 3초 이내를 숫자로 못박고, tool_result 직후 텍스트 삽입 금지·비종료성 오류만 재시도·부작용 있는 호출에 멱등키 적용이라는 세 가지 복구 규칙을 코드에 넣어 두면 루프가 스스로 멈출 지점을 압니다.