Claude와 함께하는 도구 사용

도구 사용(tool use)을 통해 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 문자열, 버전, 베타 헤더에 대해서는 도구 참조를 참조하세요.



직접 만드는 도구

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



Anthropic 스키마 클라이언트 도구

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



서버 도구

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



가격

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

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

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

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

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

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

이러한 토큰 수는 요청의 총 비용을 계산하기 위해 일반 입력 및 출력 토큰에 추가됩니다.

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

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

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



다음 단계