Cara mengimplementasikan penggunaan tool

Memilih model

Secara umum, gunakan Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 atau Claude Opus 3 untuk tool yang kompleks dan query yang ambigu; mereka menangani multiple tool dengan lebih baik dan mencari klarifikasi ketika diperlukan.

Gunakan Claude Haiku 3.5 atau Claude Haiku 3 untuk tool yang sederhana, tetapi perhatikan bahwa mereka mungkin menyimpulkan parameter yang hilang.

Jika menggunakan Claude Sonnet 3.7 dengan penggunaan tool dan extended thinking, lihat panduan kami di sini untuk informasi lebih lanjut.

Menentukan client tools

Client tools (baik yang didefinisikan Anthropic maupun yang didefinisikan pengguna) ditentukan dalam parameter tingkat atas tools dari permintaan API. Setiap definisi tool mencakup:

Parameter	Deskripsi
`name`	Nama tool. Harus sesuai dengan regex `^[a-zA-Z0-9_-]{1,64}$`.
`description`	Deskripsi plaintext yang detail tentang apa yang dilakukan tool, kapan harus digunakan, dan bagaimana perilakunya.
`input_schema`	Objek JSON Schema yang mendefinisikan parameter yang diharapkan untuk tool.

Contoh definisi tool sederhana

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

Tool ini, bernama get_weather, mengharapkan objek input dengan string location yang wajib dan string unit opsional yang harus berupa “celsius” atau “fahrenheit”.

System prompt penggunaan tool

Ketika Anda memanggil Anthropic API dengan parameter tools, kami membangun system prompt khusus dari definisi tool, konfigurasi tool, dan system prompt yang ditentukan pengguna. Prompt yang dibangun dirancang untuk menginstruksikan model menggunakan tool yang ditentukan dan memberikan konteks yang diperlukan agar tool dapat beroperasi dengan benar:

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 }}

Best practices untuk definisi tool

Untuk mendapatkan performa terbaik dari Claude ketika menggunakan tool, ikuti panduan berikut:

Berikan deskripsi yang sangat detail. Ini adalah faktor terpenting dalam performa tool. Deskripsi Anda harus menjelaskan setiap detail tentang tool, termasuk:
- Apa yang dilakukan tool
- Kapan harus digunakan (dan kapan tidak boleh)
- Apa arti setiap parameter dan bagaimana pengaruhnya terhadap perilaku tool
- Peringatan atau batasan penting, seperti informasi apa yang tidak dikembalikan tool jika nama tool tidak jelas. Semakin banyak konteks yang dapat Anda berikan kepada Claude tentang tool Anda, semakin baik Claude dalam memutuskan kapan dan bagaimana menggunakannya. Targetkan setidaknya 3-4 kalimat per deskripsi tool, lebih banyak jika tool kompleks.
Prioritaskan deskripsi daripada contoh. Meskipun Anda dapat menyertakan contoh cara menggunakan tool dalam deskripsinya atau dalam prompt yang menyertainya, ini kurang penting daripada memiliki penjelasan yang jelas dan komprehensif tentang tujuan dan parameter tool. Hanya tambahkan contoh setelah Anda sepenuhnya mengembangkan deskripsi.

Contoh deskripsi tool yang baik

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

Contoh deskripsi tool yang buruk

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

Deskripsi yang baik dengan jelas menjelaskan apa yang dilakukan tool, kapan menggunakannya, data apa yang dikembalikan, dan apa arti parameter ticker. Deskripsi yang buruk terlalu singkat dan meninggalkan Claude dengan banyak pertanyaan terbuka tentang perilaku dan penggunaan tool.

Mengontrol output Claude

Memaksa penggunaan tool

Dalam beberapa kasus, Anda mungkin ingin Claude menggunakan tool tertentu untuk menjawab pertanyaan pengguna, bahkan jika Claude berpikir dapat memberikan jawaban tanpa menggunakan tool. Anda dapat melakukan ini dengan menentukan tool dalam field tool_choice seperti ini:

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

Ketika bekerja dengan parameter tool_choice, kami memiliki empat opsi yang mungkin:

auto memungkinkan Claude memutuskan apakah akan memanggil tool yang disediakan atau tidak. Ini adalah nilai default ketika tools disediakan.
any memberi tahu Claude bahwa ia harus menggunakan salah satu tool yang disediakan, tetapi tidak memaksa tool tertentu.
tool memungkinkan kita memaksa Claude untuk selalu menggunakan tool tertentu.
none mencegah Claude menggunakan tool apa pun. Ini adalah nilai default ketika tidak ada tools yang disediakan.

Ketika menggunakan prompt caching, perubahan pada parameter tool_choice akan membatalkan blok pesan yang di-cache. Definisi tool dan system prompt tetap di-cache, tetapi konten pesan harus diproses ulang.

Diagram ini mengilustrasikan bagaimana setiap opsi bekerja:

Perhatikan bahwa ketika Anda memiliki tool_choice sebagai any atau tool, kami akan mengisi pesan asisten untuk memaksa tool digunakan. Ini berarti bahwa model tidak akan mengeluarkan blok konten text chain-of-thought sebelum blok konten tool_use, bahkan jika diminta secara eksplisit untuk melakukannya.

Ketika menggunakan extended thinking dengan penggunaan tool, tool_choice: {"type": "any"} dan tool_choice: {"type": "tool", "name": "..."} tidak didukung dan akan menghasilkan error. Hanya tool_choice: {"type": "auto"} (default) dan tool_choice: {"type": "none"} yang kompatibel dengan extended thinking.

Pengujian kami telah menunjukkan bahwa ini seharusnya tidak mengurangi performa. Jika Anda ingin mempertahankan chain-of-thought (terutama dengan Opus) sambil tetap meminta model menggunakan tool tertentu, Anda dapat menggunakan {"type": "auto"} untuk tool_choice (default) dan menambahkan instruksi eksplisit dalam pesan user. Misalnya: What's the weather like in London? Use the get_weather tool in your response.

Output JSON

Tool tidak harus berupa fungsi klien — Anda dapat menggunakan tool kapan saja Anda ingin model mengembalikan output JSON yang mengikuti skema yang disediakan. Misalnya, Anda mungkin menggunakan tool record_summary dengan skema tertentu. Lihat Tool use with Claude untuk contoh kerja lengkap.

Chain of thought

Ketika menggunakan tool, Claude akan sering menunjukkan “chain of thought”-nya, yaitu penalaran langkah demi langkah yang digunakan untuk memecah masalah dan memutuskan tool mana yang akan digunakan. Model Claude Opus 3 akan melakukan ini jika tool_choice diatur ke auto (ini adalah nilai default, lihat Memaksa penggunaan tool), dan Sonnet dan Haiku dapat diprompt untuk melakukannya.

Misalnya, diberikan prompt “What’s the weather like in San Francisco right now, and what time is it there?”, Claude mungkin merespons dengan:

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Chain of thought ini memberikan wawasan tentang proses penalaran Claude dan dapat membantu Anda men-debug perilaku yang tidak terduga.

Dengan model Claude Sonnet 3, chain of thought kurang umum secara default, tetapi Anda dapat meminta Claude untuk menunjukkan penalarannya dengan menambahkan sesuatu seperti "Before answering, explain your reasoning step-by-step in tags." ke pesan pengguna atau system prompt.

Penting untuk dicatat bahwa meskipun tag <thinking> adalah konvensi umum yang digunakan Claude untuk menunjukkan chain of thought-nya, format yang tepat (seperti nama tag XML ini) mungkin berubah seiring waktu. Kode Anda harus memperlakukan chain of thought seperti teks yang dihasilkan asisten lainnya, dan tidak bergantung pada keberadaan atau format khusus tag <thinking>.

Penggunaan tool paralel

Secara default, Claude dapat menggunakan multiple tool untuk menjawab query pengguna. Anda dapat menonaktifkan perilaku ini dengan:

Mengatur disable_parallel_tool_use=true ketika tipe tool_choice adalah auto, yang memastikan bahwa Claude menggunakan paling banyak satu tool
Mengatur disable_parallel_tool_use=true ketika tipe tool_choice adalah any atau tool, yang memastikan bahwa Claude menggunakan tepat satu tool

Contoh lengkap penggunaan tool paralel

Berikut adalah contoh lengkap yang menunjukkan cara memformat panggilan tool paralel dengan benar dalam riwayat pesan:

import anthropic

client = anthropic.Anthropic()

# Define tools
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"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Initial request
response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "What's the weather in SF and NYC, and what time is it there?"
        }
    ]
)

# Claude's response with parallel tool calls
print("Claude wants to use tools:", response.stop_reason == "tool_use")
print("Number of tool calls:", len([c for c in response.content if c.type == "tool_use"]))

# Build the conversation with tool results
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?"
    },
    {
        "role": "assistant",
        "content": response.content  # Contains multiple tool_use blocks
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # Must match the ID from tool_use
                "content": "San Francisco: 68°F, partly cloudy"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "New York: 45°F, clear skies"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "San Francisco time: 2:30 PM PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "New York time: 5:30 PM EST"
            }
        ]
    }
]

# Get final response
final_response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)

Pesan asisten dengan panggilan tool paralel akan terlihat seperti ini:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the weather and time for both San Francisco and New York City."
    },
    {
      "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"}
    }
  ]
}

Script tes lengkap untuk tool paralel

Berikut adalah script lengkap yang dapat dijalankan untuk menguji dan memverifikasi bahwa panggilan tool paralel bekerja dengan benar:

#!/usr/bin/env python3
"""Test script to verify parallel tool calls with the Anthropic API"""

import os
from anthropic import Anthropic

# Initialize client
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Define tools
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"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Test conversation with parallel tool calls
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?"
    }
]

# Make initial request
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# Check for parallel tool calls
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude made {len(tool_uses)} tool calls")

if len(tool_uses) > 1:
    print("✓ Parallel tool calls detected!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ No parallel tool calls detected")

# Simulate tool execution and format results correctly
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, partly cloudy"
        else:
            result = "New York: 45°F, clear skies"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# Continue conversation with tool results
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # All results in one message!
])

# Get final response
print("\nG etting final response...")
final_response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nClaude's response:\n{final_response.content[0].text}")

# Verify formatting
print("\n--- Verification ---")
print(f"✓ Tool results sent in single user message: {len(tool_results)} results")
print("✓ No text before tool results in content array")
print("✓ Conversation formatted correctly for future parallel tool use")

Script ini mendemonstrasikan:

Cara memformat panggilan tool paralel dan hasil dengan benar
Cara memverifikasi bahwa panggilan paralel sedang dibuat
Struktur pesan yang benar yang mendorong penggunaan tool paralel di masa depan
Kesalahan umum yang harus dihindari (seperti teks sebelum hasil tool)

Jalankan script ini untuk menguji implementasi Anda dan memastikan Claude membuat panggilan tool paralel secara efektif.

Memaksimalkan penggunaan tool paralel

Meskipun model Claude 4 memiliki kemampuan penggunaan tool paralel yang sangat baik secara default, Anda dapat meningkatkan kemungkinan eksekusi tool paralel di semua model dengan prompting yang terarah:

System prompt untuk penggunaan tool paralel

Untuk model Claude 4 (Opus 4 dan Sonnet 4), tambahkan ini ke system prompt Anda:

For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.

Untuk penggunaan tool paralel yang lebih kuat (direkomendasikan jika default tidak cukup), gunakan:

<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like `ls` or `list_dir`, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially.
</use_parallel_tool_calls>

Prompting pesan pengguna

Anda juga dapat mendorong penggunaan tool paralel dalam pesan pengguna tertentu:

# Alih-alih:
"What's the weather in Paris? Also check London."

# Gunakan:
"Check the weather in Paris and London simultaneously."

# Atau eksplisit:
"Please use parallel tool calls to get the weather for Paris, London, and Tokyo at the same time."

Penggunaan tool paralel dengan Claude Sonnet 3.7

Claude Sonnet 3.7 mungkin kurang cenderung membuat panggilan tool paralel dalam respons, bahkan ketika Anda tidak mengatur disable_parallel_tool_use. Untuk mengatasi ini, kami merekomendasikan mengaktifkan token-efficient tool use, yang membantu mendorong Claude untuk menggunakan tool paralel. Fitur beta ini juga mengurangi latensi dan menghemat rata-rata 14% token output.

Jika Anda lebih memilih untuk tidak menggunakan beta token-efficient tool use, Anda juga dapat memperkenalkan “batch tool” yang dapat bertindak sebagai meta-tool untuk membungkus pemanggilan tool lain secara bersamaan. Kami menemukan bahwa jika tool ini ada, model akan menggunakannya untuk secara bersamaan memanggil multiple tool secara paralel untuk Anda.

Lihat contoh ini dalam cookbook kami untuk cara menggunakan solusi ini.

Menangani blok konten tool use dan tool result

Respons Claude berbeda berdasarkan apakah ia menggunakan client atau server tool.

Menangani hasil dari client tools

Respons akan memiliki stop_reason berupa tool_use dan satu atau lebih blok konten tool_use yang mencakup:

id: Pengenal unik untuk blok penggunaan tool tertentu ini. Ini akan digunakan untuk mencocokkan hasil tool nanti.
name: Nama tool yang digunakan.
input: Objek yang berisi input yang diteruskan ke tool, sesuai dengan input_schema tool.

Contoh respons API dengan blok konten `tool_use`

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to use the get_weather, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Ketika Anda menerima respons penggunaan tool untuk client tool, Anda harus:

Ekstrak name, id, dan input dari blok tool_use.
Jalankan tool aktual dalam codebase Anda yang sesuai dengan nama tool tersebut, dengan memasukkan input tool.
Lanjutkan percakapan dengan mengirim pesan baru dengan role berupa user, dan blok content yang berisi tipe tool_result dan informasi berikut:
- tool_use_id: id dari permintaan penggunaan tool yang ini adalah hasilnya.
- content: Hasil tool, sebagai string (misalnya "content": "15 degrees") atau daftar blok konten bersarang (misalnya "content": [{"type": "text", "text": "15 degrees"}]). Blok konten ini dapat menggunakan tipe text atau image.
- is_error (opsional): Atur ke true jika eksekusi tool menghasilkan error.

Persyaratan format penting:

Blok hasil tool harus segera mengikuti blok penggunaan tool yang sesuai dalam riwayat pesan. Anda tidak dapat menyertakan pesan apa pun antara pesan penggunaan tool asisten dan pesan hasil tool pengguna.
Dalam pesan pengguna yang berisi hasil tool, blok tool_result harus datang PERTAMA dalam array konten. Teks apa pun harus datang SETELAH semua hasil tool.

Misalnya, ini akan menyebabkan error 400:

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Teks sebelum tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Ini benar:

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "What should I do next?"}  // ✅ Teks setelah tool_result
]}

Jika Anda menerima error seperti “tool_use ids were found without tool_result blocks immediately after”, periksa bahwa hasil tool Anda diformat dengan benar.

Contoh hasil tool yang berhasil

Contoh hasil tool dengan gambar

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

Contoh hasil tool kosong

Setelah menerima hasil tool, Claude akan menggunakan informasi tersebut untuk melanjutkan menghasilkan respons terhadap prompt pengguna asli.

Menangani hasil dari server tools

Claude mengeksekusi tool secara internal dan menggabungkan hasil langsung ke dalam responsnya tanpa memerlukan interaksi pengguna tambahan.

Perbedaan dari API lain

Tidak seperti API yang memisahkan penggunaan tool atau menggunakan peran khusus seperti tool atau function, API Anthropic mengintegrasikan tool langsung ke dalam struktur pesan user dan assistant.

Pesan berisi array blok text, image, tool_use, dan tool_result. Pesan user mencakup konten klien dan tool_result, sedangkan pesan assistant berisi konten yang dihasilkan AI dan tool_use.

Menangani stop reason `max_tokens`

Jika respons Claude terpotong karena mencapai batas max_tokens, dan respons yang terpotong berisi blok penggunaan tool yang tidak lengkap, Anda perlu mencoba ulang permintaan dengan nilai max_tokens yang lebih tinggi untuk mendapatkan penggunaan tool yang lengkap.

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

Menangani stop reason `pause_turn`

Ketika menggunakan server tools seperti web search, API mungkin mengembalikan stop reason pause_turn, yang menunjukkan bahwa API telah menjeda turn yang berjalan lama.

Berikut cara menangani stop reason 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)

Ketika menangani pause_turn:

Lanjutkan percakapan: Teruskan respons yang dijeda kembali apa adanya dalam permintaan berikutnya untuk membiarkan Claude melanjutkan turn-nya
Modifikasi jika diperlukan: Anda dapat secara opsional memodifikasi konten sebelum melanjutkan jika Anda ingin mengganggu atau mengarahkan ulang percakapan
Pertahankan state tool: Sertakan tool yang sama dalam permintaan lanjutan untuk mempertahankan fungsionalitas

Troubleshooting error

Ada beberapa jenis error yang dapat terjadi ketika menggunakan tool dengan Claude:

Error eksekusi tool

Jika tool itu sendiri mengeluarkan error selama eksekusi (misalnya error jaringan ketika mengambil data cuaca), Anda dapat mengembalikan pesan error dalam content bersama dengan "is_error": true:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

Claude kemudian akan menggabungkan error ini ke dalam responsnya kepada pengguna, misalnya “I’m sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later.”

Nama tool tidak valid

Jika upaya Claude untuk menggunakan tool tidak valid (misalnya parameter yang diperlukan hilang), biasanya berarti bahwa tidak ada informasi yang cukup bagi Claude untuk menggunakan tool dengan benar. Taruhan terbaik Anda selama pengembangan adalah mencoba permintaan lagi dengan nilai description yang lebih detail dalam definisi tool Anda.

Namun, Anda juga dapat melanjutkan percakapan dengan tool_result yang menunjukkan error, dan Claude akan mencoba menggunakan tool lagi dengan informasi yang hilang diisi:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

Jika permintaan tool tidak valid atau parameter hilang, Claude akan mencoba ulang 2-3 kali dengan koreksi sebelum meminta maaf kepada pengguna.

Tag <search_quality_reflection>

Error server tool

Panggilan tool paralel tidak bekerja

Jika Claude tidak membuat panggilan tool paralel ketika diharapkan, periksa masalah umum berikut:

1. Format hasil tool yang salah

Masalah paling umum adalah memformat hasil tool secara salah dalam riwayat percakapan. Ini “mengajarkan” Claude untuk menghindari panggilan paralel.

Khusus untuk penggunaan tool paralel:

❌ Salah: Mengirim pesan pengguna terpisah untuk setiap hasil tool
✅ Benar: Semua hasil tool harus dalam satu pesan pengguna

// ❌ Ini mengurangi penggunaan tool paralel
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Pesan terpisah
]

// ✅ Ini mempertahankan penggunaan tool paralel
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Pesan tunggal
]

Lihat persyaratan format umum di atas untuk aturan format lainnya.

2. Prompting yang lemah

Prompting default mungkin tidak cukup. Gunakan bahasa yang lebih kuat:

<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations, 
invoke all relevant tools simultaneously rather than sequentially. 
Prioritize calling tools in parallel whenever possible.
</use_parallel_tool_calls>

3. Mengukur penggunaan tool paralel

Untuk memverifikasi panggilan tool paralel bekerja:

# Calculate average tools per tool-calling message
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"Average tools per message: {avg_tools_per_message}")
# Should be > 1.0 if parallel calls are working

4. Perilaku khusus model

Claude Opus 4 dan Sonnet 4: Unggul dalam penggunaan tool paralel dengan prompting minimal
Claude Sonnet 3.7: Mungkin memerlukan prompting yang lebih kuat atau token-efficient tool use
Claude Haiku: Kurang cenderung menggunakan tool paralel tanpa prompting eksplisit

Gambaran Umum Penggunaan alat yang efisien token (beta)

On this page

Memilih model
Menentukan client tools
System prompt penggunaan tool
Best practices untuk definisi tool
Mengontrol output Claude
Memaksa penggunaan tool
Output JSON
Chain of thought
Penggunaan tool paralel
Memaksimalkan penggunaan tool paralel
Menangani blok konten tool use dan tool result
Menangani hasil dari client tools
Menangani hasil dari server tools
Menangani stop reason max_tokens
Menangani stop reason pause_turn
Troubleshooting error

Langkah pertama

Model & harga

Pelajari tentang Claude

Kemampuan

Alat

Model Context Protocol (MCP)

Kasus penggunaan

Rekayasa prompt

Uji & evaluasi

Perkuat pagar pengaman

Pusat Hukum

Cara mengimplementasikan penggunaan tool

Memilih model

Menentukan client tools

System prompt penggunaan tool

Best practices untuk definisi tool

Mengontrol output Claude

Memaksa penggunaan tool

Output JSON

Chain of thought

Penggunaan tool paralel

Memaksimalkan penggunaan tool paralel

Menangani blok konten tool use dan tool result

Menangani hasil dari client tools

Menangani hasil dari server tools

Menangani stop reason `max_tokens`

Menangani stop reason `pause_turn`

Troubleshooting error

Langkah pertama

Model & harga

Pelajari tentang Claude

Kemampuan

Alat

Model Context Protocol (MCP)

Kasus penggunaan

Rekayasa prompt

Uji & evaluasi

Perkuat pagar pengaman

Pusat Hukum

​Memilih model

​Menentukan client tools

​System prompt penggunaan tool

​Best practices untuk definisi tool

​Mengontrol output Claude

​Memaksa penggunaan tool

​Output JSON

​Chain of thought

​Penggunaan tool paralel

​Memaksimalkan penggunaan tool paralel

​Menangani blok konten tool use dan tool result

​Menangani hasil dari client tools

​Menangani hasil dari server tools

​Menangani stop reason max_tokens

​Menangani stop reason pause_turn

​Troubleshooting error

Memilih model

Menentukan client tools

System prompt penggunaan tool

Best practices untuk definisi tool

Mengontrol output Claude

Memaksa penggunaan tool

Output JSON

Chain of thought

Penggunaan tool paralel

Memaksimalkan penggunaan tool paralel

Menangani blok konten tool use dan tool result

Menangani hasil dari client tools

Menangani hasil dari server tools

Menangani stop reason `max_tokens`

Menangani stop reason `pause_turn`

Troubleshooting error