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 응답은 Claude의 의도를 나타내는 tool_use의 stop_reason을 가집니다.

도구 실행 및 결과 반환

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 블록을 출력

Claude가 병렬 도구 호출을 할 때, 모든 도구 결과를 단일 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에 대한 도구 결과]
어시스턴트	샌프란시스코, CA에 있는 현재 위치를 기준으로 지금 날씨는 59°F (15°C)이고 대부분 흐립니다. 도시에서는 상당히 시원하고 흐린 날입니다. 외출할 예정이라면 가벼운 재킷을 가져가는 것이 좋겠습니다.

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

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

사고 연쇄 도구 사용

JSON 모드

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

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

일반적으로 단일 도구를 제공하려고 합니다
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와 도구 사용이 비구조화된 텍스트에서 구조화된 데이터를 추출하는 방법을 확인하세요.

Google Sheets 애드온 도구 사용 구현 방법

On this page

도구 사용 작동 방식
클라이언트 도구
서버 도구
도구 사용 예시
가격
다음 단계

첫 단계

모델 및 가격

Claude에 대해 알아보기

기능

도구

모델 컨텍스트 프로토콜 (MCP)

사용 사례

프롬프트 엔지니어링

테스트 및 평가

보안 강화

법무 센터

Claude와 함께하는 도구 사용

도구 사용 작동 방식

클라이언트 도구

서버 도구

도구 사용 예시

가격

다음 단계

계산기 도구

고객 서비스 에이전트

JSON 추출기

첫 단계

모델 및 가격

Claude에 대해 알아보기

기능

도구

모델 컨텍스트 프로토콜 (MCP)

사용 사례

프롬프트 엔지니어링

테스트 및 평가

보안 강화

법무 센터

​도구 사용 작동 방식

​클라이언트 도구

​서버 도구

​도구 사용 예시

​가격

​다음 단계

계산기 도구

고객 서비스 에이전트

JSON 추출기

도구 사용 작동 방식

클라이언트 도구

서버 도구

도구 사용 예시

가격

다음 단계