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-6",
    "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에 다시 보내지 않고 Claude의 도구 사용 요청(2단계)만으로 충분할 수 있습니다.

서버 도구

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

Claude와 MCP 도구 사용

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

MCP 도구를 Claude 형식으로 변환

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

from mcp import ClientSession

async def get_claude_tools(mcp_session: ClientSession):
    """Convert MCP tools to Claude's tool format."""
    mcp_tools = await mcp_session.list_tools()

    claude_tools = []
    for tool in mcp_tools.tools:
        claude_tools.append({
            "name": tool.name,
            "description": tool.description or "",
            "input_schema": tool.inputSchema  # Rename inputSchema to input_schema
        })

    return claude_tools

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

import anthropic

client = anthropic.Anthropic()
claude_tools = await get_claude_tools(mcp_session)

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=claude_tools,
    messages=[{"role": "user", "content": "What tools do you have available?"}]
)

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

MCP 클라이언트 구축에 대한 전체 가이드는 MCP 클라이언트 구축을 참조하세요.

도구 사용 예제

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

가격

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 메트릭의 일부로 입력 및 출력 토큰 수가 모두 출력됩니다.

다음 단계

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