Tool Runner (SDK)

Tool Runner는 에이전트 루프, 오류 래핑 및 타입 안전성을 처리하므로 직접 처리할 필요가 없습니다. 수동 루프는 인간의 승인, 사용자 정의 로깅 또는 조건부 실행이 필요한 경우에만 사용하세요. Python, TypeScript 및 Ruby SDK에서 사용 가능합니다.

Tool Runner는 Claude로 도구를 실행하기 위한 기본 솔루션을 제공합니다. 도구 호출, 도구 결과 및 대화 관리를 수동으로 처리하는 대신, Tool Runner는 자동으로 다음을 수행합니다:

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

대부분의 도구 사용 구현에는 Tool Runner를 사용하세요.

Tool Runner는 현재 베타 버전이며 Python, TypeScript 및 Ruby SDK에서 사용 가능합니다.

압축을 통한 자동 컨텍스트 관리

Tool Runner는 자동 압축을 지원하며, 토큰 사용량이 임계값을 초과할 때 요약을 생성합니다. 이를 통해 장기 실행 에이전트 작업이 컨텍스트 윈도우 제한을 초과하여 계속될 수 있습니다.

기본 사용법

SDK 헬퍼를 사용하여 도구를 정의한 다음 Tool Runner를 사용하여 실행합니다.

도구 함수는 텍스트, 이미지 또는 문서 블록을 포함한 콘텐츠 블록 또는 콘텐츠 블록 배열을 반환해야 합니다. 이를 통해 도구는 풍부한 멀티모달 응답을 반환할 수 있습니다. 반환된 문자열은 텍스트 콘텐츠 블록으로 변환됩니다. Claude에 구조화된 JSON 객체를 반환하려면 반환하기 전에 JSON 문자열로 인코딩하세요. 숫자, 부울 또는 기타 비문자열 기본 형식도 문자열로 변환해야 합니다.

Tool Runner 반복

Tool Runner는 Claude의 메시지를 생성하는 반복 가능한 객체입니다. 이를 종종 "도구 호출 루프"라고 합니다. 각 반복에서 Runner는 Claude가 도구 사용을 요청했는지 확인합니다. 그렇다면 도구를 호출하고 결과를 자동으로 Claude에 다시 보낸 다음 루프를 계속하기 위해 Claude의 다음 메시지를 생성합니다.

break 문으로 모든 반복에서 루프를 종료할 수 있습니다. Runner는 Claude가 도구 사용 없이 메시지를 반환할 때까지 루프합니다.

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

고급 사용법

루프 내에서 Tool Runner의 다음 Messages API 요청을 완전히 사용자 정의할 수 있습니다. Runner는 도구 결과를 메시지 기록에 자동으로 추가하므로 수동으로 관리할 필요가 없습니다. 로깅 또는 디버깅을 위해 도구 결과를 선택적으로 검사하고 다음 API 호출 전에 요청 매개변수를 수정할 수 있습니다.

도구 실행 디버깅

도구가 예외를 발생시키면 Tool Runner가 이를 포착하고 is_error: true인 도구 결과로 오류를 Claude에 반환합니다. 기본적으로 전체 스택 추적이 아닌 예외 메시지만 포함됩니다.

전체 스택 추적 및 디버그 정보를 보려면 ANTHROPIC_LOG 환경 변수를 설정하세요:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

활성화되면 SDK는 전체 예외 세부 정보를 로깅합니다 (Python의 logging 모듈, TypeScript의 콘솔 또는 Ruby의 로거 사용), 도구가 실패할 때 전체 스택 추적을 포함합니다.

도구 오류 가로채기

기본적으로 도구 오류는 Claude에 다시 전달되며, Claude는 적절하게 응답할 수 있습니다. 그러나 오류를 감지하고 다르게 처리하고 싶을 수 있습니다. 예를 들어 조기에 실행을 중지하거나 사용자 정의 오류 처리를 구현하기 위해입니다.

도구 응답 메서드를 사용하여 도구 결과를 가로채고 Claude에 전송되기 전에 오류를 확인하세요:

도구 결과 수정

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

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

도구 결과에 cache_control을 추가하는 것은 도구가 대량의 데이터 (문서 검색 결과 등)를 반환하고 후속 API 호출을 위해 캐시하려는 경우에 특히 유용합니다. 캐싱 전략에 대한 자세한 내용은 프롬프트 캐싱을 참조하세요.

스트리밍

스트리밍을 활성화하여 이벤트가 도착할 때 수신합니다. 각 반복은 이벤트를 반복할 수 있는 스트림 객체를 생성합니다.

다음 단계

도구 호출 루프에 대한 수동 제어는 도구 호출 처리를 참조하세요.
여러 도구를 동시에 실행하려면 병렬 도구 사용을 참조하세요.
전체 도구 사용 워크플로우는 도구 정의를 참조하세요.