스택트레이스는 파이썬에만 남는다: Tool Runner 전환기의 에이전트 하네스 재설계 체크리스트

Tool Runner가 대체하는 것

Tool Runner(베타)는 Claude가 tool_use를 반환하면 해당 도구를 직접 실행하고 결과를 tool_result로 붙여 다음 요청까지 보내는 반복 루프를 SDK 내부로 옮깁니다. Python·TypeScript·C#·Go·Java·PHP·Ruby 7개 SDK가 모두 지원하며, 턴 수 상한은 max_iterations(언어별로 maxIterations·MaxIterations로 표기)로 걸 수 있습니다. 도구 함수가 예외를 던지면 러너가 이를 잡아 is_error: true tool_result로 바꿔 돌려주므로, 수동 루프에서 매번 작성하던 try/except → tool_result 변환 코드가 사라집니다.

기본값이 지우는 실패 정보

이 자동 변환에는 손실이 따릅니다. tool_result에는 예외 메시지(Python은 타입까지)만 담기고 전체 스택트레이스는 빠집니다. SDK 로그 방식도 언어마다 다릅니다 — ANTHROPIC_LOG 환경변수는 Python·TypeScript·Java에서만 요청·응답 로그를 켜고 Go·Ruby·C#·PHP는 이 변수를 읽지 않습니다. 실패한 도구 호출을 Claude에게 보내기 전에 들여다보는 훅도 Python의 generate_tool_call_response()와 TypeScript의 generateToolResponse()뿐이라, C#·Go·Java·PHP는 그 지점에 개입할 수 없어 로그를 도구 함수 안에서 직접 남겨야 합니다.

도입에서 운영까지: Tool Runner 전환 체크리스트

전환은 하네스 전체 교체가 아니라 도구 단위 분류로 시작합니다. 결제·배포처럼 사람 승인이 필요한 도구는 공식 문서도 수동 루프 유지를 권하므로 Tool Runner 대상에서 뺍니다. 목표 지표는 전환 전에 수치로 선언합니다 — 수동 tool_use 파싱·tool_result 포맷팅 코드의 60% 이상 제거, 턴 상한 max_iterations 10회, 기본 max_tokens 1024에서 실패마다 2배씩 올려 8192에서 멈추는 비용 상한이 출발선으로 적당합니다.

실패 패턴 1은 Go·Ruby·C#·PHP에서 도구 예외가 자동으로 is_error 처리되는 것을 "로그가 남았다"로 오해하는 경우입니다. 복구는 도구 함수 내부에서 예외를 catch한 뒤 반환 전에 직접 로그를 남기도록 모든 도구 코드에 규칙을 거는 것입니다. 실패 패턴 2는 응답이 max_tokens에서 잘렸는데 그대로 내보내는 경우입니다. 복구는 stop_reason이 max_tokens일 때 러너의 메시지 히스토리를 직접 받아(Python은 append_messages, TypeScript는 setMessagesParams) max_tokens를 2배씩 올려 재요청하고 8192 선에서 멈추는 패턴입니다. 실패 패턴 3은 턴마다 자동으로 쌓이는 대화 상태가 컨텍스트 한도를 넘기는 경우로, TypeScript·Ruby의 클라이언트 측 압축은 이미 지원 종료가 예고돼 있어 신규 연동은 context_management 파라미터의 서버 측 압축을 기본값으로 걸어야 합니다.

배포 전 운영 체크리스트에는 다음을 넣습니다. 도구별로 사람 승인·조건부 실행이 필요한지 분류해 Tool Runner와 수동 루프를 나누고, 쓰는 SDK가 generate_tool_call_response류의 가로채기 훅을 제공하는지 확인해 없으면 로그·마스킹을 도구 함수 안으로 옮기며, 운영 로그 필드에는 러너가 기본으로 주지 않는 값인 is_error 비율·예외 타입·호출 턴 수를 반드시 남깁니다. 도구 결과에 PII가 섞여도 러너가 걸러주지 않으므로 반환 전 마스킹은 도구 쪽 책임으로 명문화합니다.

지속 개선은 주간 단위로 돌립니다. 도구별 is_error 비율과 예외 타입 분포를 뽑아 입력 파싱 오류가 잦은 도구는 설명을 보강하거나 strict: true로 전환합니다. 공식 문서는 파라미터가 빠졌을 때 Claude가 스스로 고쳐 2~3회 재시도한다고 밝히는데, 재시도가 그보다 잦으면 설명 보강이나 strict 전환이 밀린 신호로 봅니다. max_iterations 상한에 걸리는 빈도도 함께 추적해 상한을 올릴지 작업을 더 작은 단계로 쪼갤지를 매주 판단합니다.

바로 쓰는 체크리스트

Tool Runner는 수동 루프의 반복 코드를 줄여 주지만 예외 가시성과 압축 전략까지 그대로 옮겨 주지는 않습니다. 승인이 필요한 도구는 수동 루프에 남기고, 나머지는 max_iterations·max_tokens 상한을 수치로 건 뒤, 쓰는 SDK가 실패를 가로챌 훅을 주는지 먼저 확인하고 없으면 로그·마스킹을 도구 함수 안에 넣는 순서로 전환해야 전환 이후의 장애를 줄일 수 있습니다.

참고 링크

Tool runner (SDK) — Claude Docs

Handle tool calls — Claude Docs