도구 사용 구현 방법

모델 선택

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

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

클라이언트 도구 지정

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

도구 사용 시스템 프롬프트

tools 매개변수를 사용하여 Claude 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 필드(베타)를 사용하여 스키마 검증된 예제를 제공할 수 있습니다. 자세한 내용은 도구 사용 예제 제공을 참조하세요.

좋은 설명은 도구가 무엇을 하는지, 언제 사용해야 하는지, 어떤 데이터를 반환하는지, ticker 매개변수가 무엇을 의미하는지 명확하게 설명합니다. 나쁜 설명은 너무 간략하여 Claude에게 도구의 동작과 사용법에 대한 많은 미해결 질문을 남깁니다.

도구 사용 예제 제공

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

기본 사용법

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    betas=["advanced-tool-use-2025-11-20"],
    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?"}
    ]
)

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

요구사항 및 제한사항

• 스키마 검증 - 각 예제는 도구의 input_schema에 따라 유효해야 합니다. 유효하지 않은 예제는 400 오류를 반환합니다
• 서버 측 도구에는 지원되지 않음 - 사용자 정의 도구만 입력 예제를 가질 수 있습니다
• 토큰 비용 - 예제는 프롬프트 토큰에 추가됩니다: 간단한 예제의 경우 ~20-50 토큰, 복잡한 중첩 객체의 경우 ~100-200 토큰

도구 러너 (베타)

도구 러너는 Claude와 함께 도구를 실행하기 위한 즉시 사용 가능한 솔루션을 제공합니다. 도구 호출, 도구 결과 및 대화 관리를 수동으로 처리하는 대신, 도구 러너가 자동으로:

• Claude가 도구를 호출할 때 실행합니다
• 요청/응답 주기를 처리합니다
• 대화 상태를 관리합니다
• 타입 안전성과 검증을 제공합니다

대부분의 도구 사용 구현에 도구 러너를 사용하는 것을 권장합니다.

기본 사용법

SDK 헬퍼를 사용하여 도구를 정의한 다음, 도구 러너를 사용하여 실행합니다.

도구 함수는 텍스트, 이미지 또는 문서 블록을 포함한 콘텐츠 블록 또는 콘텐츠 블록 배열을 반환해야 합니다. 이를 통해 도구가 풍부한 멀티모달 응답을 반환할 수 있습니다. 반환된 문자열은 텍스트 콘텐츠 블록으로 변환됩니다. 구조화된 JSON 객체를 Claude에 반환하려면 반환하기 전에 JSON 문자열로 인코딩하세요. 숫자, 불리언 또는 기타 비문자열 프리미티브도 문자열로 변환해야 합니다.

도구 러너 반복

도구 러너는 Claude의 메시지를 산출하는 이터러블입니다. 이를 흔히 "도구 호출 루프"라고 합니다. 각 반복에서 러너는 Claude가 도구 사용을 요청했는지 확인합니다. 요청한 경우, 도구를 호출하고 결과를 자동으로 Claude에 다시 보낸 다음, 루프를 계속하기 위해 Claude의 다음 메시지를 산출합니다.

break 문으로 어떤 반복에서든 루프를 종료할 수 있습니다. 러너는 Claude가 도구 사용 없이 메시지를 반환할 때까지 루프합니다.

중간 메시지가 필요하지 않은 경우, 최종 메시지를 직접 가져올 수 있습니다:

고급 사용법

루프 내에서 도구 러너의 Messages API에 대한 다음 요청을 완전히 사용자 정의할 수 있습니다. 러너는 자동으로 도구 결과를 메시지 기록에 추가하므로 수동으로 관리할 필요가 없습니다. 선택적으로 로깅이나 디버깅을 위해 도구 결과를 검사하고, 다음 API 호출 전에 요청 매개변수를 수정할 수 있습니다.

도구 실행 디버깅

도구가 예외를 발생시키면, 도구 러너가 이를 잡아서 is_error: true와 함께 도구 결과로 Claude에 오류를 반환합니다. 기본적으로 전체 스택 트레이스가 아닌 예외 메시지만 포함됩니다.

전체 스택 트레이스와 디버그 정보를 보려면 ANTHROPIC_LOG 환경 변수를 설정하세요:

# 도구 오류를 포함한 info 수준 로그 보기
export ANTHROPIC_LOG=info

# 더 자세한 출력을 위한 debug 수준 로그 보기
export ANTHROPIC_LOG=debug

활성화되면, SDK는 도구가 실패할 때 완전한 스택 트레이스를 포함한 전체 예외 세부 정보를 로깅합니다 (Python의 logging 모듈, TypeScript의 콘솔 또는 Ruby의 로거 사용).

도구 오류 가로채기

기본적으로 도구 오류는 Claude에 다시 전달되어 적절하게 응답할 수 있습니다. 그러나 오류를 감지하고 다르게 처리하고 싶을 수 있습니다—예를 들어, 실행을 조기에 중지하거나 사용자 정의 오류 처리를 구현하기 위해.

도구 응답 메서드를 사용하여 도구 결과를 가로채고 Claude에 전송되기 전에 오류를 확인하세요:

도구 결과 수정

도구 결과를 Claude에 다시 보내기 전에 수정할 수 있습니다. 이는 도구 결과에 프롬프트 캐싱을 활성화하기 위해 cache_control과 같은 메타데이터를 추가하거나 도구 출력을 변환하는 데 유용합니다.

도구 응답 메서드를 사용하여 도구 결과를 가져오고, 수정한 다음, 수정된 버전을 메시지에 추가하세요:

스트리밍

스트리밍을 활성화하여 이벤트가 도착하는 대로 수신합니다. 각 반복은 이벤트를 반복할 수 있는 스트림 객체를 산출합니다.

Claude의 출력 제어

도구 사용 강제하기

경우에 따라 Claude가 도구를 사용하지 않고도 답변할 수 있다고 판단하더라도 특정 도구를 사용하여 사용자의 질문에 답변하도록 하고 싶을 수 있습니다. 이는 tool_choice 필드에 도구를 지정하여 수행할 수 있습니다:

tool_choice = {"type": "tool", "name": "get_weather"}

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

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

이 다이어그램은 각 옵션이 어떻게 작동하는지 보여줍니다:

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

테스트 결과 이것이 성능을 저하시키지 않는 것으로 나타났습니다. 모델이 특정 도구를 사용하도록 요청하면서도 자연어 컨텍스트나 설명을 제공하도록 하려면, tool_choice에 {"type": "auto"}(기본값)를 사용하고 user 메시지에 명시적인 지시를 추가할 수 있습니다. 예: 런던의 날씨는 어때? 응답에 get_weather 도구를 사용해.

JSON 출력

도구가 반드시 클라이언트 함수일 필요는 없습니다 — 모델이 제공된 스키마를 따르는 JSON 출력을 반환하도록 하고 싶을 때 언제든지 도구를 사용할 수 있습니다. 예를 들어, 특정 스키마를 가진 record_summary 도구를 사용할 수 있습니다. 전체 작동 예제는 Claude와 도구 사용을 참조하세요.

도구를 사용한 모델 응답

도구를 사용할 때 Claude는 종종 도구를 호출하기 전에 자신이 무엇을 하고 있는지 설명하거나 사용자에게 자연스럽게 응답합니다.

예를 들어, "지금 샌프란시스코의 날씨는 어떻고, 거기 시간은 몇 시야?"라는 프롬프트가 주어지면 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가 자신의 행동을 설명할 때 다양한 표현과 접근 방식을 사용할 수 있다는 점에 유의하는 것이 중요합니다. 코드에서는 이러한 응답을 다른 어시스턴트 생성 텍스트와 동일하게 처리하고, 특정 형식 규칙에 의존하지 않아야 합니다.

병렬 도구 사용

기본적으로 Claude는 사용자 쿼리에 답변하기 위해 여러 도구를 사용할 수 있습니다. 다음과 같이 이 동작을 비활성화할 수 있습니다:

• tool_choice 유형이 auto일 때 disable_parallel_tool_use=true를 설정하면 Claude가 최대 하나의 도구를 사용하도록 보장합니다
• tool_choice 유형이 any 또는 tool일 때 disable_parallel_tool_use=true를 설정하면 Claude가 정확히 하나의 도구를 사용하도록 보장합니다

병렬 도구 사용 극대화

Claude 4 모델은 기본적으로 우수한 병렬 도구 사용 기능을 갖추고 있지만, 타겟팅된 프롬프팅을 통해 모든 모델에서 병렬 도구 실행 가능성을 높일 수 있습니다:

도구 사용 및 도구 결과 콘텐츠 블록 처리

Claude의 응답은 클라이언트 도구를 사용하는지 서버 도구를 사용하는지에 따라 다릅니다.

클라이언트 도구의 결과 처리

응답의 stop_reason은 tool_use이며, 다음을 포함하는 하나 이상의 tool_use 콘텐츠 블록이 있습니다:

• id: 이 특정 도구 사용 블록의 고유 식별자입니다. 나중에 도구 결과를 매칭하는 데 사용됩니다.
• name: 사용되는 도구의 이름입니다.
• input: 도구의 input_schema를 따르는, 도구에 전달되는 입력을 포함하는 객체입니다.

클라이언트 도구에 대한 도구 사용 응답을 받으면 다음을 수행해야 합니다:

1. tool_use 블록에서 name, id, input을 추출합니다.
2. 해당 도구 이름에 해당하는 실제 도구를 코드베이스에서 실행하고, 도구 input을 전달합니다.
3. role이 user이고, tool_result 유형과 다음 정보를 포함하는 content 블록이 있는 새 메시지를 보내 대화를 계속합니다:
   • tool_use_id: 이 결과가 해당하는 도구 사용 요청의 id입니다.
   • content: 도구의 결과로, 문자열(예: "content": "15 degrees"), 중첩된 콘텐츠 블록 목록(예: "content": [{"type": "text", "text": "15 degrees"}]), 또는 문서 블록 목록(예: "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}])입니다. 이러한 콘텐츠 블록은 text, image, 또는 document 유형을 사용할 수 있습니다.
   • is_error (선택 사항): 도구 실행이 오류를 발생시킨 경우 true로 설정합니다.

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ tool_result 앞에 텍스트
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "What should I do next?"}  // ✅ tool_result 뒤에 텍스트
]}

도구 결과를 받은 후 Claude는 해당 정보를 사용하여 원래 사용자 프롬프트에 대한 응답을 계속 생성합니다.

서버 도구의 결과 처리

Claude는 도구를 내부적으로 실행하고 추가적인 사용자 상호작용 없이 결과를 응답에 직접 통합합니다.

max_tokens 중지 사유 처리

Claude의 응답이 max_tokens 제한에 도달하여 잘린 경우, 잘린 응답에 불완전한 도구 사용 블록이 포함되어 있다면, 전체 도구 사용을 얻기 위해 더 높은 max_tokens 값으로 요청을 재시도해야 합니다.

# Check if response was truncated during tool use
if response.stop_reason == "max_tokens":
    # Check if the last content block is an incomplete tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Send the request with higher max_tokens
        response = client.messages.create(
            model="claude-opus-4-6",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools
        )

pause_turn 중지 사유 처리

웹 검색과 같은 서버 도구를 사용할 때, API가 장시간 실행되는 턴을 일시 중지했음을 나타내는 pause_turn 중지 사유를 반환할 수 있습니다.

다음은 pause_turn 중지 사유를 처리하는 방법입니다:

import anthropic

client = anthropic.Anthropic()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {"role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"},
        {"role": "assistant", "content": response.content}
    ]

    # Send the continuation request
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )

    print(continuation)
else:
    print(response)

pause_turn을 처리할 때:

• 대화 계속하기: 일시 중지된 응답을 그대로 후속 요청에 전달하여 Claude가 턴을 계속하도록 합니다
• 필요시 수정: 대화를 중단하거나 방향을 변경하려면 계속하기 전에 선택적으로 콘텐츠를 수정할 수 있습니다
• 도구 상태 보존: 기능을 유지하기 위해 계속 요청에 동일한 도구를 포함합니다

오류 문제 해결

Claude와 도구를 사용할 때 발생할 수 있는 몇 가지 유형의 오류가 있습니다: