Tool Runner (SDK)

"Tool runner"(도구 실행기)는 에이전틱 루프, 오류 래핑, 타입 안전성을 자동으로 처리하므로 직접 구현할 필요가 없습니다. 사람의 승인이 필요한 "human-in-the-loop"(인간 개입형) 방식, 커스텀 로깅, 또는 조건부 실행이 필요한 경우에는 대신 수동 루프를 사용하세요.

도구 호출, 도구 결과, 대화 관리를 수동으로 처리하는 대신, tool runner는 다음을 자동으로 수행합니다:

• Claude가 도구를 호출하면 해당 도구를 실행
• 요청/응답 사이클 처리
• 대화 상태 관리
• 타입 안전성 및 유효성 검사 제공



기본 사용법

SDK 헬퍼를 사용하여 도구를 정의한 다음, tool runner를 사용하여 실행하세요.

SDK의 도구 시그니처에 따라 도구는 결과를 문자열 또는 콘텐츠 블록(텍스트, 이미지, 문서 블록)으로 반환하므로, 도구는 멀티모달 결과를 반환할 수 있습니다. 반환된 문자열은 단일 텍스트 콘텐츠 블록이 됩니다. JSON 객체나 숫자와 같은 구조화된 데이터를 반환하려면 먼저 문자열로 인코딩하세요.



Tool runner 반복하기

Tool runner는 Claude의 메시지를 생성하는 이터러블입니다. 각 반복에서 runner는 Claude가 도구 사용을 요청했는지 확인합니다. 요청한 경우, 도구를 실행하고 결과를 자동으로 Claude에게 다시 보낸 다음, 루프를 계속하기 위해 Claude의 다음 메시지를 생성합니다.

break 문으로 어느 반복에서든 루프를 종료할 수 있습니다. Runner는 Claude가 도구 사용이 없는 메시지를 반환할 때까지, 또는 max_iterations를 설정한 경우 해당 값에 도달할 때까지 반복합니다.

중간 메시지가 필요하지 않은 경우, 최종 메시지를 직접 가져올 수 있습니다:



고급 사용법

루프 내에서 각 응답 메시지를 읽고 다음 API 호출 전에 runner의 상태를 수정할 수 있습니다. 각 반복은 다음 라이프사이클을 따릅니다:

1. Runner가 현재 상태로 Messages API에 요청을 보냅니다.
2. Runner가 응답 메시지를 루프 본문에 전달합니다.
3. 루프 본문이 실행됩니다. 메시지를 읽고 선택적으로 runner의 상태를 수정할 수 있습니다.
4. 루프 본문이 반환되면, runner는 메시지 히스토리를 수정했는지 확인합니다.
   • 메시지 히스토리를 수정하지 않은 경우: Runner는 어시스턴트 메시지를 자신의 상태에 추가합니다. 메시지에 도구 호출이 포함되어 있으면 runner가 이를 실행하고 결과를 추가합니다. 도구 호출이 없으면 루프가 종료됩니다.
   • 메시지 히스토리를 수정한 경우: Runner는 자동 추가를 건너뛰고 수정된 상태를 그대로 사용합니다. 메시지 히스토리 직접 관리하기를 참조하세요.



메시지 히스토리 직접 관리하기

기본적으로 runner는 대화 상태를 자동으로 관리합니다. 각 턴이 끝나면 어시스턴트 메시지와 도구 결과를 자체 메시지 히스토리에 추가합니다. 턴을 재시도하거나(응답을 버리고 다시 전송), 후속 메시지를 삽입하거나, 도구 결과를 직접 구성하려는 경우 메시지 히스토리를 직접 관리할 수 있습니다.

루프 본문 내부에서 runner의 메시지를 수정하면 직접 관리 모드가 됩니다. 정확한 방법은 SDK에 따라 다릅니다. 아래의 언어별 탭을 참조하세요.

특정 반복에서 직접 관리하는 경우, runner는 해당 턴의 어시스턴트 메시지나 도구 결과를 추가하지 않습니다. 대화를 유효하게 유지하는 책임은 사용자에게 있습니다. 해당 턴을 반영하려면 어시스턴트 메시지와 도구 결과를 직접 추가하고, 도구 호출이 없을 때 루프가 종료될 수 있도록 조건부로 상태를 수정하며, 루프를 제한하기 위해 max_iterations를 전달하세요. 7개 SDK 모두 max_iterations를 지원합니다.



자동 컨텍스트 관리

장기 실행 에이전틱 작업의 경우, Python, TypeScript, Ruby tool runner는 자동 압축을 지원합니다. 이는 토큰 사용량이 임계값을 초과할 때 요약을 생성하여 대화가 컨텍스트 윈도우 제한을 넘어 계속될 수 있도록 합니다. 세 SDK 모두 이 클라이언트 측 옵션을 더 이상 사용하지 않으며(deprecated), 모든 SDK에서 사용 가능한 서버 측 컨텍스트 편집을 권장합니다. Go, Java, C#, PHP tool runner에는 클라이언트 측 압축이 포함되어 있지 않습니다.



도구 실행 디버깅

도구가 예외를 발생시키면 tool runner가 이를 포착하여 is_error: true가 설정된 도구 결과로 Claude에게 오류를 반환합니다. 도구 결과에는 전체 스택 트레이스가 아니라 예외의 메시지(Python의 경우 타입과 메시지)가 포함됩니다.

SDK가 로깅하는 내용은 언어별로 다릅니다. Python SDK는 도구가 처리되지 않은 예외를 발생시킬 때마다 표준 logging 모듈을 통해 스택 트레이스를 포함한 전체 예외를 로깅합니다. Python, TypeScript, Java SDK는 ANTHROPIC_LOG 환경 변수를 읽어 요청 및 응답 세부 정보를 포함한 SDK 로깅을 활성화합니다:

# info 레벨로 로깅
export ANTHROPIC_LOG=info

# 더 자세한 출력을 위해 debug 레벨로 로깅
export ANTHROPIC_LOG=debug

Go, Ruby, C#, PHP SDK는 ANTHROPIC_LOG를 읽지 않습니다. Python 외에는 실패한 도구를 로깅하는 SDK가 없습니다. 도구가 실패한 이유를 확인하려면 도구 함수 내부에서 예외를 포착하고 로깅한 후 반환하거나 다시 던지세요.



도구 오류 가로채기

기본적으로 도구 오류는 Claude에게 다시 전달되며, Claude는 이에 적절히 응답할 수 있습니다. 그러나 오류를 감지하여 다르게 처리하고 싶을 수 있습니다. 예를 들어, 실행을 조기에 중단하거나 커스텀 오류 처리를 구현하는 경우입니다.

Python 및 TypeScript SDK에서는 도구 응답 메서드(Python의 generate_tool_call_response(), TypeScript의 generateToolResponse())를 사용하여 도구 결과를 가로채고 Claude에게 전송되기 전에 오류를 확인하세요. 다른 SDK는 해당 훅을 노출하지 않습니다. 각 탭에서 가장 가까운 대안을 설명합니다:



도구 결과 수정하기

도구 결과를 Claude에게 다시 보내기 전에 수정할 수 있습니다. 이는 도구 결과에 프롬프트 캐싱을 활성화하기 위해 cache_control과 같은 메타데이터를 추가하거나, 도구 출력을 변환하는 데 유용합니다.

Python 및 TypeScript SDK에서는 도구 응답 메서드를 사용하여 도구 결과를 가져온 다음, runner가 진행하기 전에 수정하세요. 수정된 결과를 명시적으로 추가할지 제자리에서 변경할지는 SDK에 따라 다릅니다. 각 탭의 코드 주석을 참조하세요.



스트리밍

스트리밍을 활성화하여 각 턴의 응답을 점진적으로 처리하세요. 각 반복은 이벤트를 반복할 수 있는 스트림 객체를 생성합니다.



다음 단계