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-sonnet-4-5",
    "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 요청에서 지정해야 하지만 사용자 측에서 구현할 필요가 없습니다.

클라이언트 도구

다음 단계에서 Claude와 클라이언트 도구를 통합합니다:

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

서버 도구

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

Claude와 함께 MCP 도구 사용

Model Context Protocol (MCP)을 사용하는 애플리케이션을 구축하는 경우 MCP 서버의 도구를 Claude의 Messages API와 함께 직접 사용할 수 있습니다. MCP 도구 정의는 Claude의 도구 형식과 유사한 스키마 형식을 사용합니다. inputSchema를 input_schema로 이름을 바꾸기만 하면 됩니다.

MCP 도구를 Claude 형식으로 변환

MCP 클라이언트를 구축하고 MCP 서버에서 list_tools()를 호출하면 inputSchema 필드가 있는 도구 정의를 받게 됩니다. Claude와 함께 이러한 도구를 사용하려면 Claude의 형식으로 변환하세요:

그런 다음 이러한 변환된 도구를 Claude에 전달합니다:

Claude가 tool_use 블록으로 응답할 때 MCP 서버에서 call_tool()을 사용하여 도구를 실행하고 결과를 tool_result 블록의 Claude에 반환합니다.

MCP 클라이언트 구축에 대한 완전한 가이드는 Build an MCP client를 참조하세요.

도구 사용 예제

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

가격 책정

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.

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

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

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

다음 단계

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