도구 정의하기



모델 선택하기

복잡한 도구와 모호한 쿼리에는 최신 Claude Opus (4.8) 모델을 사용하세요. 이 모델은 여러 도구를 더 잘 처리하며 필요할 때 명확한 설명을 요청합니다.

간단한 도구에는 Claude Haiku 모델을 사용하되, 누락된 매개변수를 추론할 수 있다는 점에 유의하세요.



클라이언트 도구 지정하기

클라이언트 도구(Anthropic 스키마 및 사용자 정의 도구 모두)는 API 요청의 최상위 tools 매개변수에 지정됩니다. 각 도구 정의에는 다음이 포함됩니다:

cache_control, strict, defer_loading, allowed_callers를 포함하여 모든 도구 정의에서 사용할 수 있는 선택적 속성의 전체 목록은 도구 참조를 참조하세요.



도구 사용 시스템 프롬프트

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

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

좋은 설명은 도구가 수행하는 작업, 사용 시점, 반환하는 데이터 및 ticker 매개변수의 의미를 명확하게 설명합니다. 나쁜 설명은 너무 간략하여 Claude가 도구의 동작과 사용법에 대해 많은 의문을 갖게 합니다.



도구 사용 예제 제공하기

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



기본 사용법

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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가 도구를 호출하지 않고 직접 답변하려는 경우에도 사용자의 질문에 답변하기 위해 특정 도구를 사용하도록 할 수 있습니다. 요청의 tool_choice 필드에 도구를 지정하여 이를 수행할 수 있습니다. 강조 표시된 줄은 표준 도구 사용 요청과의 유일한 차이점입니다:

import anthropic

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-4-8",
    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가 자신의 작업을 설명할 때 다양한 표현과 접근 방식을 사용할 수 있다는 점에 유의하는 것이 중요합니다. 코드는 이러한 응답을 다른 어시스턴트 생성 텍스트와 동일하게 처리해야 하며, 특정 형식 규칙에 의존해서는 안 됩니다.



다음 단계