도구 사용 (Tool Use)
도구 사용 (Tool Use)
Claude를 외부 도구와 API에 연결해요. 도구가 어디서 실행되는지, 언제 Claude가 도구를 호출하는지, 어떤 도구가 작업에 맞는지를 차례로 살펴볼게요.
도구 사용(Tool Use)을 통해 Claude는 여러분이 정의한 함수나 Anthropic이 제공하는 도구를 호출할 수 있어요. Claude는 사용자 요청과 도구의 설명을 보고 언제 도구를 호출할지를 스스로 결정해요. 그러면 도구 호출 요청이 구조화된 형태로 반환되는데, 이때 실행 주체에 따라 두 가지로 나뉘어요. 여러분의 애플리케이션에서 실행하는 클라이언트 도구(client tools) 와, Anthropic 쪽에서 실행하는 서버 도구(server tools) 입니다.
Anthropic이 대신 실행해 주는 서버 도구의 예로 Web search tool을 들 수 있어요.
Claude는 Anthropic의 인프라에서 검색을 실행하고, 인용된 결과를 같은 응답 안에 돌려줘요. 여러분이 정의한 함수를 Claude가 호출하게 하려면 input_schema를 가진 도구를 넘긴 뒤, Claude가 tool_use 블록을 반환하면 그 호출을 직접 실행하면 돼요. 이 왕복(round trip) 과정은 "How tool use works"에서 끝까지 다뤄요. 도구 정의와 도구 호출 처리도 더 자세히 볼 수 있어요.
도구 사용은 어떻게 동작하나요
도구는 주로 코드가 어디서 실행되느냐에 따라 달라져요.
클라이언트 도구(사용자 정의 도구와 Anthropic이 스키마를 정의한 도구, 예: bash, text_editor)는 여러분의 애플리케이션에서 실행돼요. Claude는 stop_reason: "tool_use"와 함께 하나 이상의 tool_use 블록으로 응답해요. 여러분의 코드가 그 작업을 실행하고 tool_result를 다시 보내는 구조죠.
서버 도구(예: web_search, web_fetch, code_execution, tool_search)는 Anthropic의 인프라에서 실행돼요. 별도로 실행을 처리하지 않아도 결과를 바로 볼 수 있어요. 다만 Claude가 여러분의 클라이언트 도구와 같은 병렬 도구 호출 그룹 안에서 서버 도구를 부르는 경우는 예외예요 (Stop reasons and fallback 참고).
클라이언트 도구의 왕복 과정을 전체로 보면 이렇습니다. 첫 요청에서 get_weather 도구를 정의하고, Claude가 질문에 답하기 위해 그 도구를 호출합니다. 응답에는 tool_use 블록이 담겨 있고, 여러분의 코드가 조회를 실행한 뒤 두 번째 요청에서 그 결과를 tool_result 블록으로 보내면, Claude가 최종 답변을 할 수 있어요.
도구 호출 처리에서 결과 포맷팅과 오류 신호를 포함한 각 단계를 자세히 다루고, 병렬 도구 사용에서 여러 도구를 한 번에 호출하는 응답을 다뤄요. 이 왕복을 직접 작성하지 않으려면 Tool Runner를 쓰면 돼요. SDK가 여러분의 도구를 실행하고 결과를 자동으로 다시 보내 주거든요.
에이전트 루프(agentic loop)를 포함한 전체 개념 모델과 접근 방식 선택 기준은 How tool use works를 참고하세요.
Model Context Protocol(MCP) 서버에 연결하려면 MCP 컨넥터를, 직접 MCP 클라이언트를 만들려면 Model Context Protocol의 MCP 클라이언트 구축 가이드를 봐요.
언제 Claude가 도구를 사용하나요
기본 tool_choice는 {"type": "auto"}라서, Claude는 매 턴마다 도구를 호출할지 아니면 바로 응답할지를 스스로 결정해요. 요청이 그 도구가 설명된 능력에 부합하고, 답이 이미 맥락 안에 없을 때 도구를 호출해요. 안정된 지식, 창의적인 작업, 대화형 턴 같은 경우에는 직접 응답하죠.
이 경계는 시스템 프롬프트로 조정할 수 있어요. 원하는 만큼 도구를 호출하지 않을 때는 "Use the tools to investigate before responding." 같은 가벼운 지시만으로도 도구 사용이 늘어나요. "Always call a tool first before responding."처럼 더 강한 형태로 밀어붙일 수도 있고, 반대로 "Use your judgment about whether to call a tool or respond directly."처럼 쓰면 호출 트리거가 보수적으로 유지돼요.
프롬프트에 기대지 않고 도구 호출을 강제하려면 tool_choice를 설정하면 돼요.
각 서버 도구 페이지에서 해당 도구의 트리거 경계를 더 자세히 설명해요.
도구 선택하기
type 문자열, 버전, 베타 헤더 정보는 Tool reference에서 확인할 수 있어요.
여러분이 직접 만든 도구
여러분이 정의한 도구는 스키마를 직접 작성하고, 각 호출을 애플리케이션에서 실행해요.
Anthropic 스키마 클라이언트 도구
Anthropic이 스키마를 공개하고 Claude를 그 위에서 훈련시켜요. 여기서도 각 호출은 여러분의 애플리케이션이 실행하고 tool_result를 반환해요.
서버 도구
서버 도구는 Anthropic의 인프라에서 실행되고, 여러분의 애플리케이션에는 핸들러 코드가 없어요. 공통적으로 적용되는 동작은 Server tools를 참고해요.
가격
도구 사용 요청의 가격은 다음에 따라 정해져요.
- 모델로 보낸 입력 토큰의 총 수(
tools파라미터에 포함된 것 포함) - 생성된 출력 토큰의 수
- 서버 측 도구의 경우 추가 사용량 기반 가격 (예: 웹 검색은 검색 1회당 비용 부과)
클라이언트 측 도구는 다른 Claude API 요청과 같은 방식으로 가격이 책정되지만, 서버 측 도구는 사용량에 따라 추가 비용이 발생할 수 있어요.
도구 사용에서 추가로 발생하는 토큰은 여기서 나와요.
- API 요청의
tools파라미터 (도구 이름, 설명, 스키마) - API 요청·응답의
tool_use콘텐츠 블록 - API 요청의
tool_result콘텐츠 블록
tools를 사용하면 API가 도구 사용을 활성화하는 특수 시스템 프롬프트를 모델에 자동으로 포함시켜요. 각 모델이 도구 사용에 필요한 토큰 수는 아래 표에 정리되어 있어요 (앞서 나열한 추가 토큰은 제외). 이 표는 최소한 도구 1개가 제공된다고 가정해요. tools를 제공하지 않으면 tool_choice가 none일 때 추가 시스템 프롬프트 토큰이 0개가 돼요.
| 모델 | Tool choice | 도구 사용 시스템 프롬프트 토큰 수 |
|---|---|---|
| Claude Opus 5 | auto, none --- any, tool |
286 토큰 --- 406 토큰 |
| Claude Opus 4.8 | auto, none --- any, tool |
290 토큰 --- 410 토큰 |
| Claude Opus 4.7 | auto, none --- any, tool |
675 토큰 --- 804 토큰 |
| Claude Opus 4.6 | auto, none --- any, tool |
497 토큰 --- 589 토큰 |
| Claude Opus 4.5 | auto, none --- any, tool |
496 토큰 --- 588 토큰 |
| Claude Opus 4.1 (retired, except on Bedrock and Google Cloud) | auto, none --- any, tool |
313 토큰 --- 315 토큰 |
| Claude Opus 4 (retired, except on Google Cloud) | auto, none --- any, tool |
313 토큰 --- 315 토큰 |
| Claude Sonnet 5 | auto, none --- any, tool |
354 토큰 --- 474 토큰 |
| Claude Sonnet 4.6 | auto, none --- any, tool |
497 토큰 --- 589 토큰 |
| Claude Sonnet 4.5 | auto, none --- any, tool |
496 토큰 --- 588 토큰 |
| Claude Sonnet 4 (retired, except on Bedrock and Google Cloud) | auto, none --- any, tool |
313 토큰 --- 315 토큰 |
| Claude Haiku 4.5 | auto, none --- any, tool |
496 토큰 --- 588 토큰 |
| Claude Haiku 3.5 (retired, except on Bedrock and Google Cloud) | auto, none --- any, tool |
264 토큰 --- 355 토큰 |
이 토큰 수는 정상 입력·출력 토큰에 더해져서 요청의 총 비용을 계산하는 데 쓰여요.
현재 모델별 가격은 Models overview 표에서 확인할 수 있어요.
도구 사용 프롬프트를 보내면 다른 API 요청과 마찬가지로, 응답의 usage 메트릭에 입력·출력 토큰 수가 모두 포함돼요.
일부 서버 도구는 토큰 위에 사용량 기반 요금을 추가해요. 각각의 요금은 웹 검색 도구와 코드 실행 도구 문서를 참고하세요.
다음 단계
이 페이지가 도움이 되었나요?