Claude와 함께 도구 사용하기

도구 사용을 통해 Claude는 사용자가 정의하거나 Anthropic이 제공하는 함수를 호출할 수 있습니다. Claude는 사용자의 요청과 도구의 설명을 기반으로 도구를 호출할 시점을 결정한 다음, 애플리케이션이 실행하는(클라이언트 도구) 또는 Anthropic이 실행하는(서버 도구) 구조화된 호출을 반환합니다.

다음은 Anthropic이 실행을 처리하는 서버 도구를 사용하는 가장 간단한 예시입니다:

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

도구 사용 작동 방식

도구는 주로 코드가 실행되는 위치에 따라 구분됩니다. 클라이언트 도구(사용자 정의 도구와 bash 및 text_editor 같은 Anthropic 스키마 도구 포함)는 애플리케이션에서 실행됩니다. Claude는 stop_reason: "tool_use"와 하나 이상의 tool_use 블록으로 응답하고, 사용자의 코드가 해당 작업을 실행한 다음 tool_result를 다시 전송합니다. 서버 도구(web_search, code_execution, web_fetch, tool_search)는 Anthropic의 인프라에서 실행되므로 실행을 처리하지 않고도 결과를 직접 확인할 수 있습니다.

에이전트 루프와 각 접근 방식을 선택해야 하는 시점을 포함한 전체 개념 모델은 도구 사용 작동 방식을 참조하세요.

MCP 서버에 연결하려면 MCP 커넥터를 참조하세요. 자체 MCP 클라이언트를 구축하려면 modelcontextprotocol.io를 참조하세요.

도구 접근은 에이전트에 제공할 수 있는 가장 영향력이 큰 기본 요소 중 하나입니다. LAB-Bench FigQA(과학 도표 해석) 및 SWE-bench(실제 소프트웨어 엔지니어링)와 같은 벤치마크에서 기본적인 도구만 추가해도 상당한 역량 향상이 나타나며, 종종 인간 전문가 기준선을 능가합니다.

Claude가 도구를 사용하는 시점

기본 tool_choice인 {"type": "auto"}를 사용하면 Claude는 각 턴마다 도구를 호출할지 직접 응답할지 결정합니다. 요청이 해당 도구의 설명된 기능에 매핑되고 답변이 아직 컨텍스트에 없는 경우 도구를 호출하며, 안정적인 지식, 창의적인 작업, 대화형 턴에 대해서는 직접 응답합니다.

이 경계는 시스템 프롬프트를 통해 조정할 수 있습니다. 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를 사용하세요.

각 서버 도구의 페이지에서는 해당 도구의 트리거 경계를 더 자세히 설명합니다. 예를 들어 웹 검색 도구 또는 코드 실행 도구를 참조하세요.

도구 사용 예시

완전한 실습 안내는 튜토리얼을 참조하세요. 개별 개념에 대한 참조 예시는 도구 정의하기 및 도구 호출 처리하기를 참조하세요.

가격 책정

도구 사용 요청은 다음을 기준으로 가격이 책정됩니다:

1. 모델에 전송된 총 입력 토큰 수(tools 매개변수에 포함된 토큰 포함)
2. 생성된 출력 토큰 수
3. 서버 측 도구의 경우, 추가적인 사용량 기반 요금(예: 웹 검색은 수행된 검색당 요금 부과)

클라이언트 측 도구는 다른 Claude API 요청과 동일하게 가격이 책정되며, 서버 측 도구는 특정 사용량에 따라 추가 요금이 발생할 수 있습니다.

도구 사용으로 인한 추가 토큰은 다음에서 발생합니다:

• API 요청의 tools 매개변수(도구 이름, 설명 및 스키마)
• API 요청 및 응답의 tool_use 콘텐츠 블록
• API 요청의 tool_result 콘텐츠 블록

tools를 사용하면 API는 도구 사용을 활성화하는 특수 시스템 프롬프트를 모델에 자동으로 포함합니다. 각 모델에 필요한 도구 사용 토큰 수는 아래에 나열되어 있습니다(위에 나열된 추가 토큰 제외). 이 표는 최소 1개의 도구가 제공된다고 가정합니다. tools가 제공되지 않은 경우, none의 도구 선택은 추가 시스템 프롬프트 토큰을 0개 사용합니다.

이러한 토큰 수는 일반 입력 및 출력 토큰에 추가되어 요청의 총 비용을 계산합니다.

현재 모델별 가격은 모델 개요 표를 참조하세요.

도구 사용 프롬프트를 전송하면 다른 API 요청과 마찬가지로 응답에서 보고된 usage 메트릭의 일부로 입력 및 출력 토큰 수가 모두 출력됩니다.

다음 단계

경로 선택하기