클로드 에이전트 루프 핵심: stop_reason 처리와 대화 기록 append 규칙

핵심 메시지

• 클로드는 스스로 아무것도 실행하지 않고 구조화된 요청만 내보내며, 실제 실행과 결과 전달은 개발자 코드의 몫이다. 이 왕복이 반복되는 것이 에이전트 루프다.
• 루프의 종료 조건은 반복 횟수나 텍스트 매칭이 아니라 응답에 항상 담기는 stop_reason 필드여야 한다.
• tool_use와 end_turn만 처리하는 두 갈래 루프는 불완전한 것을 넘어 버그다. max_tokens, stop_sequence, refusal, 그리고 서버 측 도구를 쓸 때의 pause_turn까지 처리해야 한다.
• 도구 호출 뒤에는 항상 두 개의 항목을 대화 기록에 넣어야 한다. 클로드의 tool_use 블록이 담긴 어시스턴트 메시지와, 같은 ID를 가진 tool_result가 담긴 사용자 메시지다.
• stop_reason은 모델이 말을 멈췄다는 뜻일 뿐 작업이 성공했다는 보증이 아니므로, 결과 검증은 루프 밖에서 별도 코드로 해야 한다.

쉽게 이해하기

환불 처리 같은 작업을 시키면 클로드는 고객 확인, 주문 조회, 환불 실행을 스스로 순서까지 정해 호출한다. 이 자율성이 어디서 오는지 짚기 전에 영상이 먼저 바로잡는 것은 역할 분담이다. 모델은 수술실의 집도의처럼 '메스'라고 말할 뿐이고, 도구를 손에 쥐여 주는 것은 개발자 코드다. 요청을 보내고, 도구 호출을 받고, 실행하고, 결과를 돌려주고, 끝났다고 할 때까지 반복하는 다섯 단계가 에이전트 루프의 전부다.

여기서 가장 흔한 오해는 에이전트를 잘 만든 if-else 트리로 여기는 것이다. 확인·조회·환불을 코드에 순서대로 박아 두면 데모에서는 완벽하게 돌지만, 주문이 존재하지 않거나 고객이 환불이 아니라 설명을 원하거나 사람에게 넘겨야 하는 순간 대응할 분기가 없다. 영상은 앤트로픽 엔지니어링 팀의 구분을 인용해, 미리 정해진 코드 경로로 모델을 조율하면 워크플로이고 모델이 스스로 진행과 도구 사용을 결정하면 에이전트라고 정리한다. 인쇄된 길 안내와 내비게이션의 차이라는 것이다.

그 자율 실행을 통제하는 신호가 응답마다 실려 오는 stop_reason이다. tool_use면 도구를 실행하고 결과를 붙여 다시 호출하고, end_turn이면 사용자에게 답을 돌려준다. 그래서 정석은 이 필드를 조건으로 삼는 while 루프다. 문제는 대부분의 튜토리얼이 여기서 멈춘다는 점이다. 앤트로픽 문서는 tool_use가 아닌 모든 값에서 루프가 끝난다고 적고 있고, 나머지 값들은 저마다 다른 사고를 뜻한다. max_tokens는 출력 한도에 걸려 답이 잘린 것이라 그대로 반환하면 반쪽짜리 답이 나가고, refusal은 아예 내용이 없을 수 있어 첫 번째 콘텐츠 블록을 읽는 코드가 그 자리에서 죽는다. 서버 측 웹 검색 등을 쓸 때 나오는 pause_turn은 종료가 아니라 '이어서 다시 보내 달라'는 신호다.

영상 제작자가 직접 겪었다는 버그는 대화 기록 쪽이다. 도구를 호출했으면 클로드의 tool_use 블록이 담긴 어시스턴트 메시지와 그에 대응하는 tool_result 메시지를 둘 다 넣어야 하는데, 결과만 붙이고 모델의 발화를 빠뜨리기 쉽다. 재판 속기록에 답변만 남기고 질문을 지우는 격이라, 모델은 아무도 묻지 않은 결과를 보게 된다. tool_use ID는 정확히 일치해야 하고, 병렬로 세 개를 호출했다면 세 결과를 하나의 사용자 메시지에 담아야 한다. 나눠 보내면 오류 없이 조용히 병렬 호출을 하지 않는 쪽으로 학습돼 에이전트가 느려질 뿐이다.

잘못된 루프는 세 가지로 정리된다. 응답 텍스트에서 '완료'를 찾는 문자열 파싱, 반복 횟수를 종료 조건으로 삼는 for 루프, 그리고 어시스턴트 턴을 빠뜨리는 기록 누락이다. 특히 횟수 상한은 없애는 게 아니라 역할을 바꾸는 편이 낫다. 50 정도로 두되 요리 타이머가 아니라 화재경보기로 취급하라는 것이다. 타이머가 울리면 저녁이 준비된 것이지만 경보기가 울렸다면 무언가 타고 있다는 뜻이며, 상한에 걸렸다는 것은 느린 작업이 아니라 무한 루프를 뜻한다.

주요 인사이트

• 앤트로픽 문서의 한 문장이 설계 원칙을 압축한다. 모델 출력에서 결정을 뽑아내려고 정규식을 쓰고 있다면, 그 결정은 애초에 도구 호출이었어야 한다는 것이다.
• 가장 위험한 실패는 예외가 아니라 침묵이다. 잘린 응답이나 잘못된 기록 구조는 오류를 내지 않고 그럴듯한 결과를 반환하기 때문에 운영에서야 드러난다.
• 비용 구조도 루프에서 나온다. 반복할 때마다 대화 기록 전체를 다시 보내므로 15단계 작업은 한 번 호출의 15배가 아니라 그보다 빠르게 불어난다.
• 실제 서비스에서는 SDK가 제공하는 도구 실행기를 쓰는 편이 낫지만, 한 번은 직접 손으로 짜 볼 가치가 있다. 깨진 루프를 보고 무엇이 잘못됐는지 짚어 낼 수 있어야 하기 때문이다.
• Claude Code 자체가 이 구분의 사례로 제시된다. 누구도 특정 코드베이스를 위한 결정 트리를 미리 짜 두지 않았고, 읽고 고치고 테스트하는 매 단계를 실행 중에 선택한다.

자주 묻는 질문

관련 AI 소식