Anthropic API 툴 사용은 Claude가 도구 설명에 따라 사용자 정의 함수나 Anthropic 제공 도구를 호출하게 하여 업무를 자동화하는 방법입니다. 클라이언트 도구는 앱이 실행하고 서버 도구는 Anthropic 인프라에서 실행되므로 역할을 먼저 나누면 설계가 단순해집니다. 기본값은 tool_choice auto이며 매 턴 도구를 쓸지 직접 답할지를 모델이 고릅니다.
사용자 정의 도구는 Messages API의 tools 배열에 name, description, input_schema를 넣어 전달합니다. 응답에 tool_use가 오면 실행한 뒤 같은 id의 tool_result를 다시 보내야 최종 답을 받습니다.
Anthropic API 툴 사용이 필요한 이유
Claude만으로 최신 검색, 사내 데이터, 계산을 끝내는 일은 어렵습니다. 도구를 붙이면 모델은 호출 시점만 정하고 실제 실행은 앱이나 Anthropic이 맡습니다. 반복 업무를 API 호출 루프로 묶을 수 있어 Anthropic API 툴 사용이 필요합니다.
클라이언트 도구는 내부 API와 파일, 권한을 앱이 통제할 때 맞습니다. 서버 도구는 web_search, code_execution, web_fetch, tool_search처럼 Anthropic이 실행하므로 앱이 tool_result를 직접 만들 필요가 없습니다. 외부 정보가 필요하면 서버 도구부터 검토하십시오.
Claude 도구 호출(tool use) 기본 구조
(출처: SOONSOON Labs)
요청에 tools 배열을 실으면 Claude는 도구를 쓸지 바로 답할지를 고릅니다. 도구가 필요하면 응답 stop_reason이 tool_use이고 content에 tool_use 블록이 들어갑니다. 앱은 name과 input을 읽어 함수를 실행한 뒤 결과를 다음 요청에 넣습니다. stop_reason이 tool_use인 동안 이 과정을 반복합니다.
기본 tool_choice는 auto라서 매 턴 모델이 결정합니다. 요청이 도구 능력에 맞고 답이 컨텍스트에 없을 때 호출하는 편입니다. 반드시 도구를 써야 하는 업무이면 타입을 바꿔 강제할 수 있습니다.
툴 스키마와 호출 루프
사용자 정의 도구는 tools 배열에 name, description, input_schema를 넣어 Messages API로 전달합니다. description은 언제 호출할지 조건이 드러나게 쓰는 것이 좋습니다. 응답 tool_use에는 name, 고유 id, input이 오므로 실행기는 이 세 값을 기준으로 함수를 고릅니다. JSON 스키마와 실제 input이 다르면 실행 전에 거절해야 사고가 줄어듭니다.
이름은 충돌 없이 짧게 두고 속성은 필요한 인자만 남기십시오. 설명이 모호하면 엉뚱한 도구를 고르거나 텍스트만 답할 수 있습니다. 스키마가 길면 토큰이 늘어나므로 필드 설명을 중복하지 마십시오.
결과 반환 후 후속 응답
tool_result는 대응 tool_use의 id를 tool_use_id로 연결합니다. 어시스턴트 tool_use 메시지 바로 다음 사용자 메시지에 넣어야 하며 순서가 바뀌면 모델이 결과를 못 붙입니다. 사용자 content 배열에서는 tool_result를 일반 텍스트보다 앞에 두는 편이 안전합니다. 실행 실패여도 빈 값 대신 오류 내용을 결과로 돌려 다음 추론이 이어지게 하십시오.
한 응답에 여러 tool_use 블록이 올 수 있습니다. 독립적인 호출은 모두 처리한 뒤 결과를 하나의 사용자 메시지로 함께 반환해야 합니다. 일부만 보내면 나머지 id가 끊겨 루프가 멈출 수 있습니다.
실무에서 자주 쓰는 툴 유형과 선택 기준
실무에서는 검색, 파일 읽기, 사내 함수 호출이 가장 자주 붙습니다. 최신 웹이 필요하면 서버 검색이 맞고 사내 권한 데이터면 클라이언트 함수가 맞습니다. Anthropic이 실행해도 되는 공개 작업은 서버 도구가 운영이 단순합니다. 실행 주체를 먼저 고른 뒤 스키마를 작성하십시오.
권한이 앱 쪽에 남아야 하면 클라이언트 도구를 고르십시오. 앱이 tool_result를 만들기 어려운 검색과 코드 실행은 서버 도구가 낫습니다. 아래 표는 유형별 실행 위치와 결과 처리 차이를 정리한 기준입니다.
| 도구 구분 | 실행 위치 | 결과 처리 |
|---|---|---|
| 클라이언트 도구 | 앱이 실행합니다 | 앱이 tool_result를 보냅니다 |
| 서버 도구 | Anthropic 인프라 | 앱이 tool_result를 만들 필요가 없습니다 |
| 서버 도구 예시 | web_search, code_execution, web_fetch, tool_search | 실행 결과를 바로 확인합니다 |
API로 툴을 연결하는 실제 사용 흐름
실제 사용 흐름은 도구 정의, 사용자 요청, tool_use 수신, 로컬 또는 서버 실행, tool_result 재요청, 최종 텍스트 확인 순입니다. 클라이언트 도구는 앱이 실행하고 서버 도구는 Anthropic이 실행하므로 앱이 결과를 만들지 않아도 됩니다. 한 턴에 여러 호출이 오면 모두 실행한 뒤 한 메시지에 모읍니다. 병렬 실행이 가능하면 왕복이 줄어 대기 시간이 짧아집니다.
Messages API 대화 히스토리에 도구 정의와 호출, 결과를 그대로 남겨야 다음 턴이 이어집니다. 중간 메시지를 지우면 id 연결이 끊깁니다. 로그에 stop_reason과 도구 이름을 남기면 장애 지점을 빨리 찾습니다.
검색·파일·함수 호출 시나리오
검색 시나리오는 서버 도구 web_search로 최신 페이지를 받고 앱이 tool_result를 직접 만들지 않습니다. web_fetch는 지정 URL 본문을 가져올 때 쓰며 역시 Anthropic이 실행합니다. 파일과 내부 API는 클라이언트 함수로 읽고 권한 검사는 앱에서 끝냅니다. 계산과 샌드박스 코드는 code_execution을 쓰면 실행 환경을 직접 운영하지 않아도 됩니다.
함수 호출 시나리오는 주문 조회, 일정 생성, 표 계산처럼 내부 상태를 바꾸는 일에 맞습니다. 읽기만 되는 도구와 쓰기가 되는 도구를 나누고 쓰기 도구는 추가 확인을 두십시오. 시나리오마다 누가 실행하는지를 문서에 고정해야 운영 실수가 줄어듭니다.
오류·권한·비용에서 자주 막히는 지점
가장 흔한 오류는 tool_use id와 tool_result의 연결이 어긋나는 경우입니다. 블록 순서를 바꾸거나 일부 결과만 보내면 후속 응답이 깨집니다. 권한은 모델이 아니라 앱이 검사해야 하며 스키마에 있다고 실행을 허용하면 안 됩니다. 실패 시에도 오류 문자열을 결과로 돌려 루프를 닫으십시오.
tools 정의와 tool_use, tool_result는 입력과 출력 토큰에 포함됩니다. tools를 쓰면 도구용 시스템 프롬프트 토큰이 추가로 붙습니다. 안 쓰는 도구를 매 요청에 넣지 말고 스키마 설명을 짧게 유지하십시오. 호출이 늘어날수록 왕복 비용도 같이 커집니다.
Anthropic API 툴 활용 정리와 다음 단계
Anthropic API 툴 사용은 실행 주체를 나누고 스키마를 명확히 쓴 뒤 호출 루프를 고정하는 일이 핵심입니다. 기본 auto로 시작하되 도구가 반드시 필요하면 tool_choice를 좁히면 됩니다. 토큰과 권한, stop_reason을 로그로 남기면 장애와 비용을 같이 볼 수 있습니다.
다음 단계로는 검색, 파일, 내부 함수 중 한 업무만 골라 루프를 안정화하십시오. 병렬 호출과 오류 결과 반환이 되면 같은 패턴을 다른 업무에 복제하면 됩니다. 스키마를 자주 바꿔도 대화 히스토리의 id 규칙은 그대로 지키십시오.
