Claude Tool Runner를 사용한 '커스텀 도구 호출 AI 에이전트' TypeScript 구현 가이드

요약

이 글은 Anthropic의 Claude API를 활용하여 커스텀 도구를 호출하는 AI 에이전트를 TypeScript로 구현하는 방법을 다룹니다. 작성자는 전체 기능이 포함된 'Claude Code' 기반 SDK 대신, 오직 정의한 툴의 루프 실행만 담당하는 `client.beta.messages.toolRunner` 사용을 권장합니다. 이를 활용하여 서비스 상태 확인 및 재시작 기능을 갖춘 소규모 운영 에이전트를 구축하고, 실제 구현 시 유의할 점들을 설명합니다.

핵심 포인트

• Tool Runner는 자체 정의한 도구의 루프 실행만 담당하는 경량 헬퍼로, 복잡한 제어 흐름이 필요 없는 경우에 적합하다.
• 서비스 재시작 거부와 같은 핵심 안전장치(Guard)는 프롬프트 지침보다 **툴 함수 내부**에 구현해야 신뢰성이 높다.
• Tool Runner 환경에서는 에러 상황도 '실패 여부 플래그'가 아닌, 모델이 다음 행동 판단의 근거로 삼을 수 있는 '문자열' 형태로 반환하는 것이 효과적이다.
• 운영 에이전트처럼 호출 빈도가 높은 경우, 비용 효율성을 위해 Claude Sonnet 5나 Haiku 4.5 사용을 우선 검토하는 것이 현실적이다.