도구 사용 구현 방법

모델 선택

일반적으로 복잡한 도구와 모호한 쿼리에는 Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (deprecated) 또는 Claude Opus 3 (deprecated)을 사용하세요. 이들은 여러 도구를 더 잘 처리하고 필요할 때 명확화를 요청합니다.

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

도구 사용과 확장된 사고를 함께 사용하는 Claude Sonnet 3.7을 사용하는 경우, 자세한 정보는 여기 가이드를 참조하세요.

클라이언트 도구 지정

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

매개변수	설명
name	도구의 이름. ^[a-zA-Z0-9_-]{1,64}$ 정규식과 일치해야 합니다.
description	도구가 무엇을 하는지, 언제 사용해야 하는지, 어떻게 작동하는지에 대한 자세한 일반 텍스트 설명.
input_schema	도구에 대한 예상 매개변수를 정의하는 JSON Schema 객체.

간단한 도구 정의 예시

JSON

{
  "name": "get_weather",
  "description": "주어진 위치의 현재 날씨를 가져옵니다",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "도시와 주, 예: San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "온도 단위, 'celsius' 또는 'fahrenheit' 중 하나"
      }
    },
    "required": ["location"]
  }
}

이 get_weather라는 이름의 도구는 필수 location 문자열과 “celsius” 또는 “fahrenheit” 중 하나여야 하는 선택적 unit 문자열이 포함된 입력 객체를 예상합니다.

도구 사용 시스템 프롬프트

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

이 환경에서는 사용자의 질문에 답하는 데 사용할 수 있는 도구 세트에 액세스할 수 있습니다.
{{ FORMATTING INSTRUCTIONS }}
문자열 및 스칼라 매개변수는 그대로 지정해야 하며, 목록과 객체는 JSON 형식을 사용해야 합니다. 문자열 값의 공백은 제거되지 않습니다. 출력은 유효한 XML이 될 것으로 예상되지 않으며 정규 표현식으로 구문 분석됩니다.
다음은 JSONSchema 형식으로 사용 가능한 함수입니다:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

도구 정의 모범 사례

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

• 매우 자세한 설명을 제공하세요. 이것은 도구 성능에서 가장 중요한 요소입니다. 설명에는 도구에 대한 모든 세부 사항을 설명해야 합니다:
  • 도구가 무엇을 하는지
  • 언제 사용해야 하는지(그리고 언제 사용하지 말아야 하는지)
  • 각 매개변수가 무엇을 의미하고 도구의 동작에 어떤 영향을 미치는지
  • 도구 이름이 불분명한 경우 도구가 반환하지 않는 정보와 같은 중요한 주의사항이나 제한사항. Claude에게 도구에 대한 더 많은 컨텍스트를 제공할수록 언제 어떻게 사용할지 더 잘 결정할 수 있습니다. 도구 설명당 최소 3-4문장을 목표로 하고, 도구가 복잡한 경우 더 많이 작성하세요.
• 예시보다 설명을 우선시하세요. 설명이나 함께 제공되는 프롬프트에 도구 사용 방법의 예시를 포함할 수 있지만, 이는 도구의 목적과 매개변수에 대한 명확하고 포괄적인 설명을 갖는 것보다 덜 중요합니다. 설명을 완전히 작성한 후에만 예시를 추가하세요.

좋은 도구 설명의 예시

JSON

{
  "name": "get_stock_price",
  "description": "주어진 티커 기호에 대한 현재 주가를 검색합니다. 티커 기호는 NYSE 또는 NASDAQ과 같은 주요 미국 증권 거래소에서 공개적으로 거래되는 회사의 유효한 기호여야 합니다. 이 도구는 USD로 최신 거래 가격을 반환합니다. 사용자가 특정 주식의 현재 또는 최근 가격에 대해 질문할 때 사용해야 합니다. 주식이나 회사에 대한 다른 정보는 제공하지 않습니다.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "주식 티커 기호, 예: Apple Inc.의 경우 AAPL"
      }
    },
    "required": ["ticker"]
  }
}

나쁜 도구 설명의 예시

JSON

{
  "name": "get_stock_price",
  "description": "티커의 주가를 가져옵니다.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

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

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 매개변수의 변경은 캐시된 메시지 블록을 무효화합니다. 도구 정의와 시스템 프롬프트는 캐시된 상태로 유지되지만 메시지 내용은 다시 처리되어야 합니다.

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

tool_choice가 any 또는 tool일 때 도구를 강제로 사용하도록 어시스턴트 메시지를 미리 채웁니다. 이는 명시적으로 요청하더라도 모델이 tool_use 콘텐츠 블록 이전에 사고의 연쇄 text 콘텐츠 블록을 출력하지 않음을 의미합니다.

도구 사용과 함께 확장된 사고를 사용할 때 tool_choice: {"type": "any"}와 tool_choice: {"type": "tool", "name": "..."}는 지원되지 않으며 오류가 발생합니다. 확장된 사고와 호환되는 것은 tool_choice: {"type": "auto"}(기본값)와 tool_choice: {"type": "none"}뿐입니다.

우리의 테스트에 따르면 이것이 성능을 저하시키지 않아야 합니다. 특정 도구를 사용하도록 요청하면서 사고의 연쇄를 유지하고 싶다면(특히 Opus와 함께), tool_choice에 {"type": "auto"}(기본값)를 사용하고 user 메시지에 명시적인 지시를 추가할 수 있습니다. 예: 런던의 날씨는 어떤가요? 응답에서 get_weather 도구를 사용하세요.

JSON 출력

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

사고의 연쇄

도구를 사용할 때 Claude는 종종 “사고의 연쇄”, 즉 문제를 분해하고 어떤 도구를 사용할지 결정하는 데 사용하는 단계별 추론을 보여줍니다. Claude Opus 3 (deprecated) 모델은 tool_choice가 auto로 설정된 경우 이를 수행합니다(이는 기본값입니다. 도구 사용 강제 참조). Sonnet과 Haiku는 프롬프트를 통해 이를 수행하도록 할 수 있습니다.

예를 들어, “지금 샌프란시스코의 날씨는 어떻고, 그곳의 시간은 몇 시인가요?”라는 프롬프트가 주어지면 Claude는 다음과 같이 응답할 수 있습니다:

JSON

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "이 질문에 답하기 위해 다음을 수행하겠습니다: 1. get_weather 도구를 사용하여 샌프란시스코의 현재 날씨를 가져옵니다. 2. get_time 도구를 사용하여 샌프란시스코, CA를 포함하는 America/Los_Angeles 시간대의 현재 시간을 가져옵니다."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

이 사고의 연쇄는 Claude의 추론 과정에 대한 통찰을 제공하고 예상치 못한 동작을 디버그하는 데 도움이 될 수 있습니다.

Claude가 사고의 연쇄를 나타내기 위해 다양한 형식을 사용할 수 있다는 점에 유의하는 것이 중요합니다. 코드는 사고의 연쇄를 다른 어시스턴트 생성 텍스트처럼 처리해야 하며 특정 형식 규칙에 의존해서는 안 됩니다.

병렬 도구 사용

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

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

완전한 병렬 도구 사용 예시

다음은 메시지 기록에서 병렬 도구 호출을 올바르게 형식화하는 방법을 보여주는 완전한 예시입니다:

Python

import anthropic

client = anthropic.Anthropic()

# 도구 정의
tools = [
    {
        "name": "get_weather",
        "description": "주어진 위치의 현재 날씨를 가져옵니다",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "도시와 주, 예: San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "주어진 시간대의 현재 시간을 가져옵니다",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "시간대, 예: America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# 초기 요청
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "SF와 NYC의 날씨는 어떻고, 그곳의 시간은 몇 시인가요?"
        }
    ]
)

# 병렬 도구 호출과 함께 Claude의 응답
print("Claude가 도구를 사용하려고 합니다:", response.stop_reason == "tool_use")
print("도구 호출 수:", len([c for c in response.content if c.type == "tool_use"]))

# 도구 결과와 함께 대화 구성
messages = [
    {
        "role": "user",
        "content": "SF와 NYC의 날씨는 어떻고, 그곳의 시간은 몇 시인가요?"
    },
    {
        "role": "assistant",
        "content": response.content  # 여러 tool_use 블록 포함
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # tool_use의 ID와 일치해야 함
                "content": "샌프란시스코: 68°F, 부분적으로 흐림"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "뉴욕: 45°F, 맑음"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "샌프란시스코 시간: 오후 2:30 PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "뉴욕 시간: 오후 5:30 EST"
            }
        ]
    }
]

# 최종 응답 가져오기
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)

병렬 도구 호출이 있는 어시스턴트 메시지는 다음과 같습니다:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "샌프란시스코와 뉴욕시 모두의 날씨와 시간을 확인하겠습니다."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}

병렬 도구를 위한 완전한 테스트 스크립트

다음은 병렬 도구 호출을 테스트하고 올바르게 작동하는지 확인하는 완전하고 실행 가능한 스크립트입니다:

Python

#!/usr/bin/env python3
"""Anthropic API로 병렬 도구 호출을 확인하는 테스트 스크립트"""

import os
from anthropic import Anthropic

# 클라이언트 초기화
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# 도구 정의
tools = [
    {
        "name": "get_weather",
        "description": "주어진 위치의 현재 날씨를 가져옵니다",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "도시와 주, 예: San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "주어진 시간대의 현재 시간을 가져옵니다",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "시간대, 예: America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# 병렬 도구 호출로 테스트 대화
messages = [
    {
        "role": "user",
        "content": "SF와 NYC의 날씨는 어떻고, 그곳의 시간은 몇 시인가요?"
    }
]

# 초기 요청 만들기
print("병렬 도구 호출 요청 중...")
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# 병렬 도구 호출 확인
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude가 {len(tool_uses)}개의 도구 호출을 했습니다")

if len(tool_uses) > 1:
    print("✓ 병렬 도구 호출이 감지되었습니다!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ 병렬 도구 호출이 감지되지 않았습니다")

# 도구 실행 시뮬레이션 및 결과 올바르게 형식화
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "샌프란시스코: 68°F, 부분적으로 흐림"
        else:
            result = "뉴욕: 45°F, 맑음"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "오후 2:30 PST"
        else:
            result = "오후 5:30 EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# 도구 결과와 함께 대화 계속
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # 모든 결과를 하나의 메시지에!
])

# 최종 응답 가져오기
print("\n최종 응답 가져오는 중...")
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nClaude의 응답:\n{final_response.content[0].text}")

# 형식 확인
print("\n--- 확인 ---")
print(f"✓ 단일 사용자 메시지로 전송된 도구 결과: {len(tool_results)}개 결과")
print("✓ 콘텐츠 배열에서 도구 결과 앞에 텍스트 없음")
print("✓ 향후 병렬 도구 사용을 위해 대화가 올바르게 형식화됨")

이 스크립트는 다음을 보여줍니다:

• 병렬 도구 호출과 결과를 올바르게 형식화하는 방법
• 병렬 호출이 이루어지고 있는지 확인하는 방법
• 향후 병렬 도구 사용을 장려하는 올바른 메시지 구조
• 피해야 할 일반적인 실수(도구 결과 앞의 텍스트 등)

이 스크립트를 실행하여 구현을 테스트하고 Claude가 병렬 도구 호출을 효과적으로 수행하고 있는지 확인하세요.

병렬 도구 사용 최대화

Claude 4 모델은 기본적으로 뛰어난 병렬 도구 사용 기능을 가지고 있지만, 대상 프롬프팅을 통해 모든 모델에서 병렬 도구 실행 가능성을 높일 수 있습니다:

병렬 도구 사용을 위한 시스템 프롬프트

Claude 4 모델(Opus 4.1, Opus 4, Sonnet 4)의 경우 시스템 프롬프트에 다음을 추가하세요:

최대 효율성을 위해 여러 독립적인 작업을 수행해야 할 때마다 관련 도구를 순차적이 아닌 동시에 호출하세요.

더 강력한 병렬 도구 사용을 위해(기본값이 충분하지 않은 경우 권장):

<use_parallel_tool_calls>
최대 효율성을 위해 여러 독립적인 작업을 수행할 때마다 관련 도구를 순차적이 아닌 동시에 호출하세요. 가능할 때마다 도구를 병렬로 호출하는 것을 우선시하세요. 예를 들어, 3개의 파일을 읽을 때 3개의 도구 호출을 병렬로 실행하여 모든 3개 파일을 동시에 컨텍스트로 읽어들이세요. `ls` 또는 `list_dir`과 같은 여러 읽기 전용 명령을 실행할 때는 항상 모든 명령을 병렬로 실행하세요. 너무 많은 도구를 순차적으로 실행하기보다는 병렬 도구 호출을 최대화하는 쪽으로 기울어지세요.
</use_parallel_tool_calls>

사용자 메시지 프롬프팅

특정 사용자 메시지 내에서 병렬 도구 사용을 장려할 수도 있습니다:

# 다음 대신:
"파리의 날씨는 어떤가요? 런던도 확인해 주세요."

# 다음을 사용:
"파리와 런던의 날씨를 동시에 확인하세요."

# 또는 명시적으로:
"병렬 도구 호출을 사용하여 파리, 런던, 도쿄의 날씨를 동시에 가져와 주세요."

Claude Sonnet 3.7과 병렬 도구 사용

Claude Sonnet 3.7은 disable_parallel_tool_use를 설정하지 않았더라도 응답에서 병렬 도구 호출을 할 가능성이 낮을 수 있습니다. 이를 해결하려면 Claude가 병렬 도구를 사용하도록 장려하는 데 도움이 되는 토큰 효율적인 도구 사용을 활성화하는 것을 권장합니다. 이 베타 기능은 또한 지연 시간을 줄이고 출력 토큰을 평균 14% 절약합니다.

토큰 효율적인 도구 사용 베타에 참여하지 않으려면 다른 도구에 대한 호출을 동시에 래핑하는 메타 도구 역할을 할 수 있는 “배치 도구”를 도입할 수도 있습니다. 이 도구가 있으면 모델이 이를 사용하여 여러 도구를 병렬로 동시에 호출한다는 것을 발견했습니다.

이 해결 방법을 사용하는 방법은 쿡북의 이 예시를 참조하세요.

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

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

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

응답은 tool_use의 stop_reason과 다음을 포함하는 하나 이상의 tool_use 콘텐츠 블록을 가집니다:

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

`tool_use` 콘텐츠 블록이 있는 API 응답 예시

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "get_weather를 사용해야 하고, 사용자가 SF를 원하는데 이는 아마도 San Francisco, CA일 것입니다."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

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

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

중요한 형식 요구사항:

• 도구 결과 블록은 메시지 기록에서 해당 도구 사용 블록 바로 다음에 와야 합니다. 어시스턴트의 도구 사용 메시지와 사용자의 도구 결과 메시지 사이에 메시지를 포함할 수 없습니다.
• 도구 결과가 포함된 사용자 메시지에서 tool_result 블록은 콘텐츠 배열에서 먼저 와야 합니다. 모든 텍스트는 모든 도구 결과 다음에 와야 합니다.

예를 들어, 다음은 400 오류를 발생시킵니다:

{"role": "user", "content": [
  {"type": "text", "text": "결과는 다음과 같습니다:"},  // ❌ tool_result 앞의 텍스트
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

다음이 올바릅니다:

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "다음에 무엇을 해야 할까요?"}  // ✅ tool_result 다음의 텍스트
]}

“tool_use ids were found without tool_result blocks immediately after”와 같은 오류가 발생하면 도구 결과가 올바르게 형식화되었는지 확인하세요.

성공적인 도구 결과 예시

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15도"
    }
  ]
}

이미지가 있는 도구 결과 예시

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15도"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

빈 도구 결과 예시

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

문서가 있는 도구 결과 예시

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "날씨는"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15도"
          }
        }
      ]
    }
  ]
}

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

서버 도구의 결과 처리

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

다른 API와의 차이점

도구 사용을 분리하거나 tool 또는 function과 같은 특수 역할을 사용하는 API와 달리 Anthropic의 API는 도구를 user 및 assistant 메시지 구조에 직접 통합합니다.

메시지에는 text, image, tool_use, tool_result 블록의 배열이 포함됩니다. user 메시지에는 클라이언트 콘텐츠와 tool_result가 포함되고, assistant 메시지에는 AI 생성 콘텐츠와 tool_use가 포함됩니다.

max_tokens 중지 이유 처리

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

Python

# 도구 사용 중 응답이 잘렸는지 확인
if response.stop_reason == "max_tokens":
    # 마지막 콘텐츠 블록이 불완전한 tool_use인지 확인
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # 더 높은 max_tokens로 요청 보내기
        response = client.messages.create(
            model="claude-opus-4-1-20250805",
            max_tokens=4096,  # 증가된 제한
            messages=messages,
            tools=tools
        )

pause_turn 중지 이유 처리

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

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

Python

import anthropic

client = anthropic.Anthropic()

# 웹 검색을 사용한 초기 요청
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "2025년 양자 컴퓨팅 혁신에 대한 포괄적인 정보를 검색하세요"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# 응답에 pause_turn 중지 이유가 있는지 확인
if response.stop_reason == "pause_turn":
    # 일시 중지된 콘텐츠로 대화 계속
    messages = [
        {"role": "user", "content": "2025년 양자 컴퓨팅 혁신에 대한 포괄적인 정보를 검색하세요"},
        {"role": "assistant", "content": response.content}
    ]
    
    # 계속 요청 보내기
    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와 도구를 사용할 때 발생할 수 있는 몇 가지 다른 유형의 오류가 있습니다:

도구 실행 오류

도구 자체가 실행 중에 오류를 발생시키는 경우(예: 날씨 데이터를 가져올 때 네트워크 오류), "is_error": true와 함께 content에 오류 메시지를 반환할 수 있습니다:

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: 날씨 서비스 API를 사용할 수 없습니다 (HTTP 500)",
      "is_error": true
    }
  ]
}

그러면 Claude는 이 오류를 사용자에 대한 응답에 통합합니다. 예: “죄송합니다. 날씨 서비스 API를 사용할 수 없어서 현재 날씨를 검색할 수 없었습니다. 나중에 다시 시도해 주세요.”

잘못된 도구 이름

Claude의 도구 사용 시도가 유효하지 않은 경우(예: 필수 매개변수 누락), 일반적으로 Claude가 도구를 올바르게 사용할 수 있는 충분한 정보가 없었음을 의미합니다. 개발 중에 가장 좋은 방법은 도구 정의에서 더 자세한 description 값으로 요청을 다시 시도하는 것입니다.

그러나 오류를 나타내는 tool_result로 대화를 계속 진행할 수도 있으며, Claude는 누락된 정보를 채워서 도구를 다시 사용하려고 시도합니다:

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "오류: 필수 'location' 매개변수가 누락되었습니다",
      "is_error": true
    }
  ]
}

도구 요청이 유효하지 않거나 매개변수가 누락된 경우 Claude는 사용자에게 사과하기 전에 수정과 함께 2-3번 재시도합니다.

<search_quality_reflection> 태그

Claude가 <search_quality_reflection> 태그로 검색 품질을 반영하지 않도록 하려면 프롬프트에 “응답에서 반환된 검색 결과의 품질을 반영하지 마세요”를 추가하세요.

서버 도구 오류

서버 도구에서 오류가 발생하는 경우(예: 웹 검색의 네트워크 문제), Claude는 이러한 오류를 투명하게 처리하고 사용자에게 대안적인 응답이나 설명을 제공하려고 시도합니다. 클라이언트 도구와 달리 서버 도구에 대해서는 is_error 결과를 처리할 필요가 없습니다.

웹 검색의 경우 가능한 오류 코드는 다음과 같습니다:

• too_many_requests: 속도 제한 초과
• invalid_input: 잘못된 검색 쿼리 매개변수
• max_uses_exceeded: 최대 웹 검색 도구 사용 초과
• query_too_long: 쿼리가 최대 길이 초과
• unavailable: 내부 오류 발생

병렬 도구 호출이 작동하지 않음

Claude가 예상할 때 병렬 도구 호출을 하지 않는 경우 다음과 같은 일반적인 문제를 확인하세요:

1. 잘못된 도구 결과 형식

가장 일반적인 문제는 대화 기록에서 도구 결과를 잘못 형식화하는 것입니다. 이는 Claude에게 병렬 호출을 피하도록 “가르칩니다”.

특히 병렬 도구 사용의 경우:

• ❌ 잘못됨: 각 도구 결과에 대해 별도의 사용자 메시지 보내기
• ✅ 올바름: 모든 도구 결과가 단일 사용자 메시지에 있어야 함

// ❌ 이것은 병렬 도구 사용을 줄입니다
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // 별도 메시지
]

// ✅ 이것은 병렬 도구 사용을 유지합니다
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // 단일 메시지
]

다른 형식 규칙은 위의 일반 형식 요구사항을 참조하세요.

2. 약한 프롬프팅

기본 프롬프팅이 충분하지 않을 수 있습니다. 더 강한 언어를 사용하세요:

<use_parallel_tool_calls>
최대 효율성을 위해 여러 독립적인 작업을 수행할 때마다 
관련 도구를 순차적이 아닌 동시에 호출하세요. 
가능할 때마다 도구를 병렬로 호출하는 것을 우선시하세요.
</use_parallel_tool_calls>

3. 병렬 도구 사용 측정

병렬 도구 호출이 작동하는지 확인하려면:

# 도구 호출 메시지당 평균 도구 계산
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"]) 
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"메시지당 평균 도구: {avg_tools_per_message}")
# 병렬 호출이 작동하면 > 1.0이어야 함

4. 모델별 동작

• Claude Opus 4.1, Opus 4, Sonnet 4: 최소한의 프롬프팅으로 병렬 도구 사용에 뛰어남
• Claude Sonnet 3.7: 더 강한 프롬프팅이나 토큰 효율적인 도구 사용이 필요할 수 있음
• Claude Haiku: 명시적인 프롬프팅 없이는 병렬 도구를 사용할 가능성이 낮음