도구 정의하기

사전 요구 사항

• "tool use"(도구 사용) 개요에 대한 이해
• Claude API 키와 작동하는 SDK 또는 cURL 설정

클라이언트 도구 지정하기

"Client tools"(클라이언트 도구)는 API 요청의 최상위 매개변수인 tools에 지정됩니다. bash 및 텍스트 편집기 도구와 같은 Anthropic 스키마 클라이언트 도구는 날짜로 버전이 지정된 type으로 선언됩니다. 각 도구가 허용하는 필드는 도구 참조에서 링크된 각 도구의 페이지를 참조하세요. 컴퓨터 사용 및 브라우저 사용 도구는 클라이언트 도구 세트로, 고정된 멤버 도구 집합을 선언하는 name이 없는 단일 항목입니다. 사용자 정의 도구 정의에는 다음이 포함됩니다:

cache_control, strict, defer_loading, allowed_callers를 포함하여 단일 도구 정의에서 사용할 수 있는 선택적 속성의 전체 목록은 도구 참조를 참조하세요. 클라이언트 도구 세트 항목은 항목 자체에서 cache_control과 allowed_callers를 허용하며, defer_loading은 멤버별로 설정합니다. 클라이언트 도구 세트를 참조하세요.

{
  "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"]
  }
}

도구 사용 시스템 프롬프트

tools 매개변수와 함께 Claude API를 호출하면, API는 도구 정의, 도구 구성 및 사용자가 지정한 "system prompt"(시스템 프롬프트)로부터 특별한 시스템 프롬프트를 구성합니다. 구성된 프롬프트는 모델이 지정된 도구를 사용하도록 지시하고 도구가 올바르게 작동하는 데 필요한 컨텍스트를 제공하도록 설계되었습니다:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

도구 정의 모범 사례

도구를 사용할 때 Claude로부터 최상의 성능을 얻으려면 다음 지침을 따르세요:

• 매우 상세한 설명을 제공하세요. 이는 도구 성능에서 단연 가장 중요한 요소입니다. 설명에는 다음을 포함하여 도구에 대한 모든 세부 사항을 설명해야 합니다:
  • 도구가 수행하는 작업
  • 도구를 사용해야 하는 시점(그리고 사용하지 말아야 하는 시점)
  • 각 매개변수의 의미와 도구 동작에 미치는 영향
  • 도구 이름이 명확하지 않은 경우 도구가 반환하지 않는 정보와 같은 중요한 주의 사항이나 제한 사항. 도구에 대해 Claude에게 더 많은 컨텍스트를 제공할수록 Claude가 도구를 언제 어떻게 사용할지 더 잘 결정할 수 있습니다. 각 도구 설명은 최소 3~4문장을 목표로 하고, 도구가 복잡하다면 더 길게 작성하세요.
• 설명을 우선시하되, 복잡한 도구에는 input_examples 사용을 고려하세요. 명확한 설명이 가장 중요하지만, 복잡한 입력, 중첩된 객체 또는 형식에 민감한 매개변수가 있는 도구의 경우 input_examples 필드를 사용하여 스키마 검증을 거친 예시를 제공할 수 있습니다. 자세한 내용은 도구 사용 예시 제공하기를 참조하세요.
• 관련 작업을 더 적은 수의 도구로 통합하세요. 모든 작업마다 별도의 도구(create_pr, review_pr, merge_pr)를 만드는 대신, action 매개변수를 가진 단일 도구로 묶으세요. 더 적지만 더 유능한 도구는 선택의 모호성을 줄이고 Claude가 도구 구성을 더 쉽게 탐색할 수 있게 합니다.
• 도구 이름에 의미 있는 네임스페이스를 사용하세요. 도구가 여러 서비스나 리소스에 걸쳐 있는 경우, 이름 앞에 서비스 이름을 접두사로 붙이세요(예: github_list_prs, slack_send_message). 이렇게 하면 라이브러리가 커져도 도구 선택이 모호하지 않게 되며, 특히 도구 검색을 사용할 때 중요합니다.
• 신호 가치가 높은 정보만 반환하도록 도구 응답을 설계하세요. 불투명한 내부 참조 대신 의미 있고 안정적인 식별자(예: 슬러그 또는 UUID)를 반환하고, Claude가 다음 단계를 추론하는 데 필요한 필드만 포함하세요. 비대한 응답은 컨텍스트를 낭비하고 Claude가 중요한 정보를 추출하기 어렵게 만듭니다.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

좋은 설명은 도구가 수행하는 작업, 사용 시점, 반환하는 데이터, 그리고 ticker 매개변수의 의미를 명확하게 설명합니다. 나쁜 설명은 너무 짧아서 도구의 동작과 사용법에 대해 Claude에게 많은 의문을 남깁니다.

도구 사용 예시 제공하기

Claude가 도구를 더 효과적으로 사용하는 방법을 이해할 수 있도록 유효한 도구 입력의 구체적인 예시를 제공할 수 있습니다. 이는 중첩된 객체, 선택적 매개변수 또는 형식에 민감한 입력이 있는 복잡한 도구에 특히 유용합니다.

기본 사용법

도구 정의에 예시 입력 객체의 배열을 담은 선택적 input_examples 필드를 추가하세요. 각 예시는 도구의 input_schema에 따라 유효해야 합니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

예시는 도구 스키마와 함께 프롬프트에 포함되어, 올바른 형식의 도구 호출에 대한 구체적인 패턴을 Claude에게 보여줍니다. 이는 Claude가 선택적 매개변수를 언제 포함해야 하는지, 어떤 형식을 사용해야 하는지, 복잡한 입력을 어떻게 구성해야 하는지 이해하는 데 도움이 됩니다.

요구 사항 및 제한 사항

• 스키마 검증 - 각 예시는 도구의 input_schema에 따라 유효해야 합니다. 유효하지 않은 예시는 400 오류를 반환합니다
• 서버 측 도구 또는 클라이언트 도구 세트에서는 지원되지 않음 - 입력 예시는 사용자 정의 도구와 컴퓨터 사용 및 브라우저 사용 도구 세트를 제외한 Anthropic 스키마 클라이언트 도구에서 작동하지만, 웹 검색이나 코드 실행과 같은 서버 도구에서는 작동하지 않습니다
• 토큰 비용 - 예시는 프롬프트 토큰을 증가시킵니다: 간단한 예시는 약 20~50 토큰, 복잡한 중첩 객체는 약 100~200 토큰

Claude의 출력 제어하기

도구 사용 강제하기

경우에 따라 Claude가 도구를 호출하지 않고 직접 답변할 수 있는 상황에서도, 사용자의 질문에 답하기 위해 Claude가 특정 도구를 사용하도록 하고 싶을 수 있습니다. 요청의 tool_choice 필드에 도구를 지정하여 이를 수행할 수 있습니다.

모든 모델과 설정이 강제 도구 사용을 지원하는 것은 아닙니다. 지원되지 않는 경우 tool_choice: {"type": "any"}와 tool_choice: {"type": "tool", "name": "..."}는 실패하지만, tool_choice: {"type": "auto"}(기본값)와 tool_choice: {"type": "none"}은 여전히 작동합니다:

이를 지원하는 모델에서는 강조 표시된 줄만이 표준 도구 사용 요청과의 유일한 차이점입니다:

client = anthropic.Anthropic()

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"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

tool_choice 매개변수를 사용할 때는 네 가지 옵션이 있습니다:

• auto는 Claude가 제공된 도구를 호출할지 여부를 스스로 결정하도록 합니다. tools가 제공된 경우의 기본값입니다.
• any는 Claude에게 제공된 도구 중 하나를 반드시 사용해야 한다고 알리지만, 특정 도구를 강제하지는 않습니다.
• tool은 Claude가 항상 특정 도구를 사용하도록 강제합니다.
• none은 Claude가 어떤 도구도 사용하지 못하도록 합니다. tools가 제공되지 않은 경우의 기본값입니다.

다음 다이어그램은 각 옵션이 작동하는 방식을 보여줍니다:

tool_choice가 any 또는 tool인 경우, API는 도구 사용을 강제하기 위해 어시스턴트 메시지를 미리 채웁니다. 이는 명시적으로 요청하더라도 모델이 tool_use 콘텐츠 블록 앞에 자연어 응답이나 설명을 출력하지 않는다는 것을 의미합니다.

테스트 결과 이로 인해 성능이 저하되지는 않는 것으로 나타났습니다. 모델이 특정 도구를 사용하도록 요청하면서도 자연어 컨텍스트나 설명을 제공하기를 원한다면, tool_choice에 {"type": "auto"}(기본값)를 사용하고 user 메시지에 명시적인 지시를 추가할 수 있습니다. 예: What's the weather like in London? Use the get_weather tool in your response.

도구 사용 시 모델 응답

도구를 사용할 때 Claude는 도구를 호출하기 전에 자신이 수행하는 작업에 대해 설명하거나 사용자에게 자연스럽게 응답하는 경우가 많습니다.

예를 들어, "What's the weather like in San Francisco right now, and what time is it there?"라는 프롬프트가 주어지면 Claude는 다음과 같이 응답할 수 있습니다:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

이러한 자연스러운 응답 스타일은 사용자가 Claude가 무엇을 하고 있는지 이해하는 데 도움이 되며, 보다 대화적인 상호작용을 만들어 냅니다. 시스템 프롬프트를 통해, 그리고 프롬프트에 <examples>를 제공하여 이러한 응답의 스타일과 내용을 안내할 수 있습니다.

Claude는 자신의 행동을 설명할 때 다양한 표현과 접근 방식을 사용할 수 있다는 점에 유의해야 합니다. 코드에서는 이러한 응답을 다른 어시스턴트 생성 텍스트와 동일하게 취급해야 하며, 특정 형식 규칙에 의존해서는 안 됩니다.

다음 단계