Claude와 함께하는 도구 사용

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

다음은 Anthropic이 대신 실행해 주는 서버 도구인 웹 검색 도구를 사용하는 최소한의 예시입니다:

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5",
    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)

Claude는 Anthropic의 인프라에서 검색을 실행하고 동일한 응답에서 인용된 결과를 반환합니다. Claude가 사용자가 정의한 함수를 호출하도록 하려면 input_schema가 포함된 도구를 전달한 다음, Claude가 tool_use 블록을 반환할 때 해당 호출을 실행하세요. 도구 사용 작동 방식에서 이 왕복 과정을 처음부터 끝까지 보여줍니다. 도구 정의 및 도구 호출 처리에 대해 자세히 알아보세요.

도구 사용 작동 방식

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

다음은 클라이언트 도구에 대한 전체 왕복 과정입니다. 첫 번째 요청은 get_weather 도구를 정의하고, Claude는 이를 호출하여 질문에 답합니다. 응답에는 tool_use 블록이 포함되고, 코드가 조회를 실행하며, 두 번째 요청이 결과를 tool_result 블록에 담아 다시 보내면 Claude가 답변으로 응답할 수 있습니다.

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude는 도구 이름과 인수를 담은 tool_use 블록으로 응답합니다.
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    # 턴당 최대 한 번의 도구 호출만 요청합니다.
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# 도구를 실행한 다음 결과를 tool_result 블록에 담아 다시 보냅니다.
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude는 그 결과를 사용해 원래 질문에 답합니다.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

도구 호출 처리에서는 결과 형식 지정 및 오류 신호 전달을 포함하여 각 단계를 자세히 다룹니다. 병렬 도구 사용에서는 여러 도구를 한 번에 호출하는 응답을 다룹니다. 이 왕복 과정을 직접 작성하지 않으려면 Tool Runner를 사용하세요. SDK가 도구를 실행하고 결과를 자동으로 다시 보냅니다.

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

"Model Context Protocol", 즉 MCP 서버에 연결하려면 MCP 커넥터를 참조하세요. 자체 MCP 클라이언트를 구축하려면 Model Context Protocol 가이드의 MCP 클라이언트 구축을 참조하세요.

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를 설정하세요.

각 서버 도구의 페이지에서는 해당 도구의 트리거 경계를 더 자세히 설명합니다.

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": { "location": "New York, NY", "unit": "fahrenheit" }
}

도구 선택

type 문자열, 버전 및 베타 헤더는 도구 레퍼런스를 참조하세요.

자체 도구

사용자가 정의하는 도구의 경우, 사용자가 스키마를 작성하고 애플리케이션이 각 호출을 실행합니다.

Anthropic 스키마 클라이언트 도구

Anthropic이 스키마를 게시하고 Claude를 해당 스키마로 학습시킵니다. 애플리케이션은 여전히 각 호출을 실행하고 tool_result를 반환합니다.

서버 도구

서버 도구는 애플리케이션에 핸들러 코드 없이 Anthropic의 인프라에서 실행됩니다. 이들이 공유하는 메커니즘은 서버 도구를 참조하세요.

가격

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

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

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

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

• API 요청의 tools 파라미터(도구 이름, 설명 및 스키마)
• API 요청 및 응답의 tool_use 콘텐츠 블록
• API 요청의 tool_result 콘텐츠 블록

tools를 사용하면 API는 도구 사용을 가능하게 하는 특별한 "system prompt"(시스템 프롬프트)를 모델에 자동으로 포함합니다. 각 모델에 필요한 도구 사용 토큰 수는 다음 표에 나와 있습니다(앞서 나열한 추가 토큰 제외). 이 표는 최소 1개의 도구가 제공된다고 가정합니다. tools가 제공되지 않으면 none 도구 선택은 추가 시스템 프롬프트 토큰을 0개 사용합니다.

이러한 토큰 수는 일반 입력 및 출력 토큰에 더해져 요청의 총 비용을 계산하는 데 사용됩니다.

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

도구 사용 프롬프트를 보내면 다른 API 요청과 마찬가지로 응답에는 보고된 usage 지표에 입력 및 출력 토큰 수가 모두 포함됩니다.

일부 서버 도구는 토큰 외에 사용량 기반 요금을 추가합니다. 해당 요금은 웹 검색 도구 및 코드 실행 도구를 참조하세요.

다음 단계