Claude와 함께하는 도구 사용

Claude는 도구 및 함수와 상호작용할 수 있어 Claude의 기능을 확장하여 더 다양한 작업을 수행할 수 있습니다.

새로운 종합적인 도구 사용 과정을 통해 Claude와 함께하는 도구 사용의 모든 것을 배워보세요! 이 양식을 사용하여 아이디어와 제안을 계속 공유해 주세요.

다음은 Messages API를 사용하여 Claude에 도구를 제공하는 방법의 예시입니다:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in San Francisco?"
      }
    ]
  }'

도구 사용 작동 방식

Claude는 두 가지 유형의 도구를 지원합니다:

클라이언트 도구: 사용자의 시스템에서 실행되는 도구로, 다음을 포함합니다:
- 사용자가 정의하고 구현한 커스텀 도구
- 컴퓨터 사용(베타) 및 텍스트 에디터와 같이 클라이언트 구현이 필요한 Anthropic이 정의한 도구
서버 도구: 웹 검색 도구와 같이 Anthropic의 서버에서 실행되는 도구입니다. 이러한 도구는 API 요청에 지정되어야 하지만 사용자 측에서 구현할 필요는 없습니다.

Anthropic이 정의한 도구는 버전이 지정된 유형(예: web_search_20250305, text_editor_20250124)을 사용하여 모델 버전 간의 호환성을 보장합니다.

클라이언트 도구

다음 단계에 따라 클라이언트 도구를 Claude와 통합하세요:

Claude에게 도구와 사용자 프롬프트 제공

API 요청에 이름, 설명 및 입력 스키마가 포함된 클라이언트 도구를 정의합니다.
“샌프란시스코의 날씨는 어떤가요?”와 같이 이러한 도구가 필요할 수 있는 사용자 프롬프트를 포함합니다.

Claude가 도구 사용을 결정

Claude는 사용자의 쿼리에 도움이 될 수 있는 도구가 있는지 평가합니다.
있다면, Claude는 적절하게 형식이 지정된 도구 사용 요청을 구성합니다.
클라이언트 도구의 경우, API 응답의 stop_reason가 tool_use로 표시되어 Claude의 의도를 알립니다.

도구 실행 및 결과 반환

Claude의 요청에서 도구 이름과 입력을 추출합니다
사용자 시스템에서 도구 코드를 실행합니다
tool_result 콘텐츠 블록이 포함된 새 user 메시지로 결과를 반환합니다

Claude가 도구 결과를 사용하여 응답 작성

Claude는 도구 결과를 분석하여 원래 사용자 프롬프트에 대한 최종 응답을 작성합니다.

참고: 3단계와 4단계는 선택 사항입니다. 일부 워크플로우의 경우, Claude의 도구 사용 요청(2단계)만으로 충분하며 결과를 Claude에 다시 보낼 필요가 없을 수 있습니다.

서버 도구

서버 도구는 다른 워크플로우를 따릅니다:

Claude에게 도구와 사용자 프롬프트 제공

웹 검색과 같은 서버 도구에는 고유한 매개변수가 있습니다.
“AI에 관한 최신 뉴스를 검색해 주세요”와 같이 이러한 도구가 필요할 수 있는 사용자 프롬프트를 포함합니다.

Claude가 서버 도구 실행

Claude는 사용자의 쿼리에 서버 도구가 도움이 될 수 있는지 평가합니다.
그렇다면, Claude는 도구를 실행하고 결과는 자동으로 Claude의 응답에 통합됩니다.

Claude가 서버 도구 결과를 사용하여 응답 작성

Claude는 서버 도구 결과를 분석하여 원래 사용자 프롬프트에 대한 최종 응답을 작성합니다.
서버 도구 실행에는 추가적인 사용자 상호작용이 필요하지 않습니다.

도구 사용 예시

다음은 다양한 도구 사용 패턴과 기술을 보여주는 몇 가지 코드 예시입니다. 간결함을 위해 도구는 간단한 도구이며, 도구 설명은 최상의 성능을 보장하기 위해 이상적인 것보다 짧습니다.

단일 도구 예시

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [{
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The unit of temperature, either \"celsius\" or \"fahrenheit\""
                }
            },
            "required": ["location"]
        }
    }],
    "messages": [{"role": "user", "content": "What is the weather like in San Francisco?"}]
}'

Claude는 다음과 유사한 응답을 반환합니다:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to call the get_weather function, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

그런 다음 제공된 입력으로 get_weather 함수를 실행하고 새 user 메시지로 결과를 반환해야 합니다:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either \"celsius\" or \"fahrenheit\""
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather like in San Francisco?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "<thinking>I need to use get_weather, and the user wants SF, which is likely San Francisco, CA.</thinking>"
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01A09q90qw90lq917835lq9",
                    "name": "get_weather",
                    "input": {
                        "location": "San Francisco, CA",
                        "unit": "celsius"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 degrees"
                }
            ]
        }
    ]
}'

이는 날씨 데이터를 포함한 Claude의 최종 응답을 출력합니다:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The current weather in San Francisco is 15 degrees Celsius (59 degrees Fahrenheit). It's a cool day in the city by the bay!"
    }
  ]
}

다중 도구 예시

단일 요청에서 Claude에게 선택할 수 있는 여러 도구를 제공할 수 있습니다. 다음은 get_weather와 get_time 도구가 모두 있는 예시와 두 가지를 모두 요청하는 사용자 쿼리입니다.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [{
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given time zone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The IANA time zone name, e.g. America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "What is the weather like right now in New York? Also what time is it there?"
    }]
}'

이 경우, Claude는 사용자의 질문에 완전히 답하기 위해 대부분 한 번에 하나씩 두 개의 별도 도구(get_weather와 get_time)를 사용하려고 할 것입니다. 그러나 특히 서로 의존하지 않는 경우 가끔 두 개의 tool_use 블록을 한 번에 출력할 수도 있습니다. 각 도구를 실행하고 단일 user 메시지 내에서 별도의 tool_result 블록으로 결과를 반환해야 합니다.

누락된 정보

사용자의 프롬프트에 도구에 필요한 모든 매개변수를 채울 만큼 충분한 정보가 포함되어 있지 않은 경우, Claude Opus는 매개변수가 누락되었음을 인식하고 이를 요청할 가능성이 훨씬 높습니다. Claude Sonnet는 특히 도구 요청을 출력하기 전에 생각하라는 프롬프트가 있을 때 질문할 수 있습니다. 하지만 합리적인 값을 추론하기 위해 최선을 다할 수도 있습니다.

예를 들어, 위의 get_weather 도구를 사용하여 위치를 지정하지 않고 “날씨가 어떤가요?”라고 물으면, Claude, 특히 Claude Sonnet는 도구 입력에 대해 추측할 수 있습니다:

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

이 동작은 특히 더 모호한 프롬프트와 덜 지능적인 모델의 경우 보장되지 않습니다. Claude Opus가 필요한 매개변수를 채울 만큼 충분한 컨텍스트가 없는 경우, 도구 호출을 하는 대신 명확한 질문으로 응답할 가능성이 훨씬 높습니다.

순차적 도구

일부 작업은 한 도구의 출력을 다른 도구의 입력으로 사용하여 여러 도구를 순차적으로 호출해야 할 수 있습니다. 이러한 경우 Claude는 한 번에 하나의 도구를 호출합니다. 모든 도구를 한 번에 호출하라는 프롬프트가 있으면, Claude는 상류 도구의 도구 결과에 의존하는 경우 하류 도구의 매개변수를 추측할 가능성이 높습니다.

다음은 get_location 도구를 사용하여 사용자의 위치를 가져온 다음, 해당 위치를 get_weather 도구에 전달하는 예시입니다:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Get the current user location based on their IP address. This tool has no parameters or arguments.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What is the weather like where I am?"
    }]
}'

이 경우, Claude는 먼저 get_location 도구를 호출하여 사용자의 위치를 가져옵니다. tool_result로 위치를 반환한 후, Claude는 해당 위치로 get_weather를 호출하여 최종 답변을 얻습니다.

전체 대화는 다음과 같을 수 있습니다:

역할	내용
사용자	내가 있는 곳의 날씨는 어떤가요?
어시스턴트	<thinking>이에 답하기 위해, 먼저 get_location 도구를 사용하여 사용자의 위치를 확인해야 합니다. 그런 다음 해당 위치를 get_weather 도구에 전달하여 현재 날씨를 찾을 수 있습니다.</thinking>[get_location에 대한 도구 사용]
사용자	[일치하는 id와 San Francisco, CA 결과가 있는 get_location에 대한 도구 결과]
어시스턴트	[다음 입력이 있는 get_weather에 대한 도구 사용]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
사용자	[일치하는 id와 “59°F (15°C), 대체로 흐림” 결과가 있는 get_weather에 대한 도구 결과]
어시스턴트	현재 위치인 San Francisco, CA의 날씨는 현재 59°F (15°C)이고 대체로 흐립니다. 도시는 꽤 시원하고 흐린 날입니다. 밖으로 나갈 예정이라면 가벼운 재킷을 가져가는 것이 좋을 수 있습니다.

이 예시는 Claude가 다른 소스에서 데이터를 수집해야 하는 질문에 답하기 위해 여러 도구 호출을 함께 연결하는 방법을 보여줍니다. 주요 단계는 다음과 같습니다:

Claude는 먼저 날씨 질문에 답하기 위해 사용자의 위치가 필요하다는 것을 깨닫고 get_location 도구를 호출합니다.
사용자(즉, 클라이언트 코드)는 실제 get_location 함수를 실행하고 tool_result 블록에 “San Francisco, CA” 결과를 반환합니다.
이제 위치를 알게 된 Claude는 get_weather 도구를 호출하여 location 매개변수로 “San Francisco, CA”를 전달합니다(그리고 unit은 필수 매개변수가 아니므로 추측된 unit 매개변수도 함께 전달합니다).
사용자는 다시 제공된 인수로 실제 get_weather 함수를 실행하고 다른 tool_result 블록에 날씨 데이터를 반환합니다.
마지막으로, Claude는 날씨 데이터를 원래 질문에 대한 자연어 응답으로 통합합니다.

사고 연쇄 도구 사용

JSON 모드

도구 출력을 도구나 함수를 통해 실행할 의도가 없더라도 스키마를 따르는 JSON 출력을 생성하도록 Claude에게 도구를 사용할 수 있습니다.

이런 방식으로 도구를 사용할 때:

일반적으로 단일 도구를 제공하고자 합니다
모델에게 해당 도구를 명시적으로 사용하도록 지시하기 위해 tool_choice를 설정해야 합니다(도구 사용 강제하기 참조)
모델이 input을 도구에 전달할 것이므로 도구의 이름과 설명은 모델의 관점에서 작성되어야 함을 기억하세요.

다음은 특정 형식에 따라 이미지를 설명하기 위해 record_summary 도구를 사용하는 예시입니다.

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Record summary of an image using well-structured JSON.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "red value [0.0, 1.0]" },
"g": { "type": "number", "description": "green value [0.0, 1.0]" },
"b": { "type": "number", "description": "blue value [0.0, 1.0]" },
"name": { "type": "string", "description": "Human-readable color name in snake_case, e.g. \"olive_green\" or \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Key colors in the image. Limit to less than four."
                },
                "description": {
                    "type": "string",
                    "description": "Image description. One to two sentences max."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Estimated year that the image was taken, if it is a photo. Only set this if the image appears to be non-fictional. Rough estimates are okay!"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Describe this image."}
        ]}
    ]
}'

가격 책정

Tool use requests are priced based on:

The total number of input tokens sent to the model (including in the tools parameter)
The number of output tokens generated
For server-side tools, additional usage-based pricing (e.g., web search charges per search performed)

Client-side tools are priced the same as any other Claude API request, while server-side tools may incur additional charges based on their specific usage.

The additional tokens from tool use come from:

The tools parameter in API requests (tool names, descriptions, and schemas)
tool_use content blocks in API requests and responses
tool_result content blocks in API requests

When you use tools, we also automatically include a special system prompt for the model which enables tool use. The number of tool use tokens required for each model are listed below (excluding the additional tokens listed above). Note that the table assumes at least 1 tool is provided. If no tools are provided, then a tool choice of none uses 0 additional system prompt tokens.

Model	Tool choice	Tool use system prompt token count
Claude Opus 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.7	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (Oct)	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (June)	`auto`, `none` `any`, `tool`	294 tokens 261 tokens
Claude Haiku 3.5	`auto`, `none` `any`, `tool`	264 tokens 340 tokens
Claude Opus 3	`auto`, `none` `any`, `tool`	530 tokens 281 tokens
Claude Sonnet 3	`auto`, `none` `any`, `tool`	159 tokens 235 tokens
Claude Haiku 3	`auto`, `none` `any`, `tool`	264 tokens 340 tokens

These token counts are added to your normal input and output tokens to calculate the total cost of a request.

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

도구 사용 프롬프트를 보낼 때, 다른 API 요청과 마찬가지로 응답은 보고된 usage 메트릭의 일부로 입력 및 출력 토큰 수를 모두 출력합니다.

다음 단계

쿡북에서 바로 구현할 수 있는 도구 사용 코드 예시 저장소를 살펴보세요:

계산기 도구

정확한 수치 계산을 위해 간단한 계산기 도구를 Claude와 통합하는 방법을 알아보세요.

고객 서비스 에이전트

지원을 강화하기 위해 클라이언트 도구를 활용하는 반응형 고객 서비스 봇을 구축하세요.

JSON 추출기

Claude와 도구 사용이 비정형 텍스트에서 구조화된 데이터를 추출하는 방법을 확인하세요.

첫 단계

기능 살펴보기

모델 & 가격

Claude에 대해 알아보기

테스트 및 평가

법률 센터

에이전트 구성요소

Claude와 함께하는 도구 사용

도구 사용 작동 방식

클라이언트 도구

서버 도구

도구 사용 예시

가격 책정

다음 단계

계산기 도구

고객 서비스 에이전트

JSON 추출기

첫 단계

기능 살펴보기

모델 & 가격

Claude에 대해 알아보기

테스트 및 평가

법률 센터

에이전트 구성요소

​도구 사용 작동 방식

​클라이언트 도구

​서버 도구

​도구 사용 예시

​가격 책정

​다음 단계

계산기 도구

고객 서비스 에이전트

JSON 추출기

도구 사용 작동 방식

클라이언트 도구

서버 도구

도구 사용 예시

가격 책정

다음 단계