도구 사용을 구현하는 방법

매개변수	설명
`name`	도구의 이름입니다. 정규식 `^[a-zA-Z0-9_-]{1,64}$`와 일치해야 합니다.
`description`	도구가 무엇을 하는지, 언제 사용해야 하는지, 어떻게 작동하는지에 대한 자세한 일반 텍스트 설명입니다.
`input_schema`	도구의 예상 매개변수를 정의하는 JSON Schema 객체입니다.
`input_examples`	(선택사항, 베타) Claude가 도구를 사용하는 방법을 이해하도록 돕기 위한 예제 입력 객체의 배열입니다. 도구 사용 예제 제공을 참조하세요.

매개변수	설명
`name`	도구의 이름입니다. 정규식 `^[a-zA-Z0-9_-]{1,64}$`와 일치해야 합니다.
`description`	도구가 무엇을 하는지, 언제 사용해야 하는지, 어떻게 작동하는지에 대한 자세한 일반 텍스트 설명입니다.
`input_schema`	도구의 예상 매개변수를 정의하는 JSON Schema 객체입니다.
`input_examples`	(선택사항, 베타) Claude가 도구를 사용하는 방법을 이해하도록 돕기 위한 예제 입력 객체의 배열입니다. 도구 사용 예제 제공을 참조하세요.

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 API, Microsoft Foundry	`advanced-tool-use-2025-11-20`	모든 모델
Vertex AI, Amazon Bedrock	`tool-examples-2025-10-29`	Claude Opus 4.5만

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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?"}
    ]
)

JSON

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

중요한 형식 요구 사항:

도구 결과 블록은 메시지 히스토리에서 해당 도구 사용 블록 바로 뒤에 와야 합니다. 어시스턴트의 도구 사용 메시지와 사용자의 도구 결과 메시지 사이에 메시지를 포함할 수 없습니다.
도구 결과를 포함하는 사용자 메시지에서 tool_result 블록은 콘텐츠 배열의 FIRST에 와야 합니다. 모든 텍스트는 모든 도구 결과 AFTER에 와야 합니다.

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

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Text before 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?"}  // ✅ Text after tool_result
]}

"tool_use ids were found without tool_result blocks immediately after"와 같은 오류를 받으면 도구 결과가 올바르게 포맷되었는지 확인하세요.

# 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-sonnet-4-5",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools
        )

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)

도구 사용을 구현하는 방법

모델 선택

클라이언트 도구 지정

도구 사용을 구현하는 방법

모델 선택

클라이언트 도구 지정

도구 사용 시스템 프롬프트

도구 정의의 모범 사례

도구 사용 예제 제공

기본 사용법

요구사항 및 제한사항

도구 실행기(베타)

Claude의 출력 제어

도구 사용 강제

JSON 출력

도구를 사용한 모델 응답

병렬 도구 사용

병렬 도구 사용 최대화

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

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

서버 도구의 결과 처리

`max_tokens` 중지 이유 처리

`pause_turn` 중지 이유 처리

오류 문제 해결

모델 선택

클라이언트 도구 지정

간단한 도구 정의 예제

모델 선택

클라이언트 도구 지정

간단한 도구 정의 예제

도구 사용 시스템 프롬프트

도구 정의의 모범 사례

좋은 도구 설명의 예

좋지 않은 도구 설명의 예

도구 사용 예제 제공

기본 사용법

요구사항 및 제한사항

도구 실행기(베타)

Claude의 출력 제어

도구 사용 강제

JSON 출력

도구를 사용한 모델 응답

병렬 도구 사용

완전한 병렬 도구 사용 예제

병렬 도구에 대한 완전한 테스트 스크립트

병렬 도구 사용 최대화

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

사용자 메시지 프롬프팅

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

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

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

성공적인 도구 결과의 예

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

빈 도구 결과의 예

문서가 있는 도구 결과의 예

서버 도구의 결과 처리

max_tokens 중지 이유 처리

pause_turn 중지 이유 처리

오류 문제 해결

도구 실행 오류

잘못된 도구 이름

\<search_quality_reflection> 태그

서버 도구 오류

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

`max_tokens` 중지 이유 처리

`pause_turn` 중지 이유 처리