Claude와 함께하는 도구 사용

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

새로운 강좌의 일부로 Claude와 함께 도구 사용을 마스터하는 데 필요한 모든 것을 배워보세요! 이 양식을 사용하여 계속해서 아이디어와 제안을 공유해 주세요.

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

Shell

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-1-20250805",
    "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는 두 가지 유형의 도구를 지원합니다:

1. 클라이언트 도구: 사용자 시스템에서 실행되는 도구로, 다음을 포함합니다:

   • 사용자가 생성하고 구현하는 사용자 정의 커스텀 도구
   • 클라이언트 구현이 필요한 컴퓨터 사용 및 텍스트 편집기와 같은 Anthropic 정의 도구

2. 서버 도구: 웹 검색 및 웹 가져오기 도구와 같이 Anthropic의 서버에서 실행되는 도구입니다. 이러한 도구는 API 요청에서 지정되어야 하지만 사용자 측에서 구현할 필요는 없습니다.

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

클라이언트 도구

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

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

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

   • Claude는 어떤 도구가 사용자의 쿼리에 도움이 될 수 있는지 평가합니다.
   • 그렇다면 Claude는 적절히 형식화된 도구 사용 요청을 구성합니다.
   • 클라이언트 도구의 경우, API 응답은 Claude의 의도를 나타내는 tool_use의 stop_reason을 가집니다.
3. 도구 실행 및 결과 반환

   • Claude의 요청에서 도구 이름과 입력을 추출합니다
   • 사용자 시스템에서 도구 코드를 실행합니다
   • tool_result 콘텐츠 블록을 포함하는 새로운 user 메시지로 결과를 반환합니다
4. Claude가 도구 결과를 사용하여 응답 작성

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

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

서버 도구

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

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

   • 웹 검색 및 웹 가져오기와 같은 서버 도구는 고유한 매개변수를 가집니다.
   • 이러한 도구가 필요할 수 있는 사용자 프롬프트를 포함합니다. 예: “AI에 대한 최신 뉴스를 검색해 주세요” 또는 “이 URL의 콘텐츠를 분석해 주세요.”
2. Claude가 서버 도구 실행

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

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

---

도구 사용 예시

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

단일 도구 예시

Shell

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-1-20250805",
    "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-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the current weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

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

Shell

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-1-20250805",
    "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": "I'll check the current weather in San Francisco for you."
                },
                {
                    "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-1-20250805",
  "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는 단일 응답 내에서 여러 도구를 병렬로 호출할 수 있으며, 이는 여러 독립적인 작업이 필요한 작업에 유용합니다. 병렬 도구를 사용할 때, 모든 tool_use 블록이 단일 어시스턴트 메시지에 포함되며, 모든 해당 tool_result 블록은 후속 사용자 메시지에서 제공되어야 합니다.

중요: 도구 결과는 API 오류를 방지하고 Claude가 병렬 도구를 계속 사용할 수 있도록 올바르게 형식화되어야 합니다. 자세한 형식 요구사항과 완전한 코드 예시는 구현 가이드를 참조하세요.

병렬 도구 호출 구현을 위한 포괄적인 예시, 테스트 스크립트, 모범 사례는 구현 가이드의 병렬 도구 사용 섹션을 참조하세요.

다중 도구 예시

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

Shell

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-1-20250805",
    "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 블록을 출력

Claude가 병렬 도구 호출을 수행할 때, 각 결과를 자체 tool_result 블록에 넣어 단일 user 메시지로 모든 도구 결과를 반환해야 합니다.

정보 누락

사용자의 프롬프트에 도구의 모든 필수 매개변수를 채우기에 충분한 정보가 포함되지 않은 경우, 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 도구에 전달하는 예시입니다:

Shell

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-1-20250805",
    "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를 호출하여 최종 답변을 얻습니다.

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

역할	내용
사용자	제가 있는 곳의 날씨는 어떤가요?
어시스턴트	먼저 현재 위치를 찾은 다음 그곳의 날씨를 확인하겠습니다. [get_location에 대한 도구 사용]
사용자	[일치하는 id와 San Francisco, CA 결과를 가진 get_location에 대한 도구 결과]
어시스턴트	[다음 입력을 가진 get_weather에 대한 도구 사용]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
사용자	[일치하는 id와 “59°F (15°C), 대부분 흐림” 결과를 가진 get_weather에 대한 도구 결과]
어시스턴트	샌프란시스코, CA에 있는 현재 위치를 기준으로, 지금 날씨는 59°F (15°C)이고 대부분 흐립니다. 꽤 시원하고 흐린 날입니다. 밖에 나가실 때는 가벼운 재킷을 가져가시는 것이 좋겠습니다.

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

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

사고 연쇄 도구 사용

기본적으로 Claude Opus는 도구 사용 쿼리에 답하기 전에 생각하도록 프롬프트되어 도구가 필요한지, 어떤 도구를 사용할지, 적절한 매개변수가 무엇인지를 가장 잘 결정합니다. Claude Sonnet과 Claude Haiku는 가능한 한 많은 도구를 사용하려고 시도하도록 프롬프트되며 불필요한 도구를 호출하거나 누락된 매개변수를 추론할 가능성이 더 높습니다. Sonnet이나 Haiku가 도구 호출을 하기 전에 사용자 쿼리를 더 잘 평가하도록 프롬프트하려면 다음 프롬프트를 사용할 수 있습니다:

사고 연쇄 프롬프트

관련 도구(사용 가능한 경우)를 사용하여 사용자의 요청에 답하세요. 도구를 호출하기 전에 분석을 수행하세요. 먼저, 제공된 도구 중 사용자의 요청에 답하는 데 관련된 도구가 무엇인지 생각해 보세요. 둘째, 관련 도구의 각 필수 매개변수를 살펴보고 사용자가 직접 제공했거나 값을 추론하기에 충분한 정보를 제공했는지 확인하세요. 매개변수를 추론할 수 있는지 결정할 때, 특정 값을 지원하는지 모든 컨텍스트를 신중히 고려하세요. 모든 필수 매개변수가 존재하거나 합리적으로 추론할 수 있다면 도구 호출을 진행하세요. 하지만 필수 매개변수의 값 중 하나가 누락된 경우, 함수를 호출하지 마세요(누락된 매개변수에 대한 채우기 값을 사용하더라도) 대신 사용자에게 누락된 매개변수를 제공하도록 요청하세요. 제공되지 않은 선택적 매개변수에 대해서는 더 많은 정보를 요청하지 마세요.

JSON 모드

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

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

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

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

Shell

#!/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-1-20250805",
    "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:

1. The total number of input tokens sent to the model (including in the tools parameter)
2. The number of output tokens generated
3. 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.1	auto, none any, tool	346 tokens 313 tokens
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) (deprecated)	auto, none any, tool	346 tokens 313 tokens
Claude Sonnet 3.5 (June) (deprecated)	auto, none any, tool	294 tokens 261 tokens
Claude Haiku 3.5	auto, none any, tool	264 tokens 340 tokens
Claude Opus 3 (deprecated)	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와 도구 사용이 구조화되지 않은 텍스트에서 구조화된 데이터를 추출하는 방법을 확인하세요.