Penggunaan alat paralel
Aktifkan, format, dan nonaktifkan panggilan alat paralel, dengan panduan riwayat pesan dan pemecahan masalah.
Secara default, Claude dapat memanggil beberapa alat dalam satu respons. Halaman ini membahas cara menjalankan panggilan tersebut, cara memformat riwayat pesan agar paralelisme tetap berfungsi, dan cara menonaktifkan "parallel tool use" (penggunaan alat paralel) saat Anda membutuhkannya. Untuk alur panggilan tunggal, lihat Menangani panggilan alat.
Semantik eksekusi
Ketika Claude memanggil alat, respons memiliki stop_reason berupa tool_use dan dapat berisi beberapa blok tool_use dalam satu giliran asisten. Cara Anda menjalankan panggilan tersebut adalah keputusan Anda. API tidak menetapkan urutan eksekusi: Anda dapat menjalankan panggilan secara bersamaan (Promise.all, asyncio.gather), secara berurutan sesuai urutan kemunculannya, atau dalam kombinasi apa pun yang sesuai dengan alat Anda.
Pilih strategi berdasarkan apa yang dilakukan alat Anda. Operasi independen yang hanya membaca biasanya aman dijalankan secara paralel untuk "latency" (latensi) yang lebih rendah. Alat dengan efek samping, state bersama, atau persyaratan urutan mungkin lebih baik dijalankan secara berurutan.
Strategi apa pun yang Anda gunakan, kembalikan satu tool_result untuk setiap blok tool_use, semuanya bersama-sama dalam pesan pengguna berikutnya. Cocokkan setiap hasil dengan panggilannya menggunakan tool_use_id, dan letakkan setiap blok tool_result sebelum konten teks apa pun dalam pesan tersebut. Lihat Menangani panggilan alat untuk aturan pemformatan lengkap. Jika Anda memilih untuk tidak menjalankan panggilan tertentu (misalnya, karena Anda menjalankan batch secara berurutan dan panggilan sebelumnya gagal), tetap kembalikan tool_result untuk panggilan tersebut dengan is_error: true dan penjelasan singkat.
{
"type": "tool_result",
"tool_use_id": "toolu_02",
"is_error": true,
"content": "Not executed: the preceding write_file call failed."
}Alat computer use dan alat browser use lebih ketat. Ketika Claude mengembalikan beberapa panggilan alat anggotanya dalam satu giliran (aksi batch), jalankan secara berurutan sesuai urutan kemunculannya dan berhenti pada kegagalan pertama; setiap alat mendefinisikan teks persis yang harus dikembalikan untuk panggilan yang Anda lewati.
Menguji panggilan alat paralel
Skrip berikut mengirim permintaan yang seharusnya memicu panggilan alat paralel, memverifikasi bahwa respons berisi panggilan tersebut, dan memformat hasil alat agar paralelisme tetap berfungsi. Jalankan dengan ANTHROPIC_API_KEY yang telah diatur di lingkungan Anda:
client = Anthropic()
# Definisikan alat
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"],
},
},
]
# Uji percakapan dengan pemanggilan alat paralel
messages = [
{
"role": "user",
"content": "What's the weather in SF and NYC, and what time is it there?",
}
]
# Buat permintaan awal
print("Requesting parallel tool calls...")
response = client.messages.create(
model="claude-opus-5", max_tokens=1024, messages=messages, tools=tools
)
# Periksa pemanggilan alat paralel
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")
# Simulasikan eksekusi alat dan format hasilnya dengan benar
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}
)
# Lanjutkan percakapan dengan hasil alat
messages.extend(
[
{"role": "assistant", "content": response.content},
{"role": "user", "content": tool_results}, # All results in one message!
]
)
# Dapatkan respons akhir
print("\nGetting final response...")
final_response = client.messages.create(
model="claude-opus-5", max_tokens=1024, messages=messages, tools=tools
)
final_text = next(
block.text for block in final_response.content if block.type == "text"
)
print(f"\nClaude's response:\n{final_text}")
# Verifikasi pemformatan
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")Baris ringkasan di bagian akhir menyatakan kembali dua aturan pemformatan yang menjaga paralelisme tetap berfungsi: setiap hasil alat dikembalikan dalam satu pesan pengguna, dan tidak ada konten teks yang muncul sebelum hasil alat dalam pesan tersebut.
Memaksimalkan penggunaan alat paralel
Model Claude 4 dan yang lebih baru melakukan panggilan alat paralel secara default ketika permintaan mendapat manfaat dari beberapa alat. Untuk semua model, Anda dapat meningkatkan kemungkinan panggilan alat paralel dengan prompting yang terarah:
Untuk model Claude 4 dan yang lebih baru, tambahkan ini ke prompt sistem Anda:
For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.Untuk penggunaan alat paralel yang lebih kuat lagi (direkomendasikan jika default tidak mencukupi), 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>Anda juga dapat mendorong penggunaan alat paralel dalam pesan pengguna tertentu:
Instead of:
"What's the weather in Paris? Also check London."
Use:
"Check the weather in Paris and London simultaneously."
Or be explicit:
"Please use parallel tool calls to get the weather for Paris, London, and Tokyo at the same time."Menonaktifkan penggunaan alat paralel
Penggunaan alat paralel aktif secara default. Untuk menonaktifkannya, atur disable_parallel_tool_use: true di dalam objek tool_choice. Ini bukan parameter permintaan tingkat atas. Efeknya bergantung pada tipe tool_choice.
Paling banyak satu panggilan alat
Ketika tipe tool_choice adalah auto (default), mengatur disable_parallel_tool_use: true berarti Claude memanggil paling banyak satu alat per respons. Claude masih dapat menjawab dalam teks biasa tanpa memanggil alat apa pun. Baris yang disorot adalah satu-satunya perubahan dari permintaan penggunaan alat standar:
client = Anthropic()
response = client.messages.create(
model="claude-opus-5",
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",
}
},
"required": ["location"],
},
}
],
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=[
{
"role": "user",
"content": "What is the weather in San Francisco and New York?",
}
],
)
print(response.content)Tepat satu panggilan alat
Ketika tipe tool_choice adalah any atau tool, mengatur disable_parallel_tool_use: true berarti Claude memanggil tepat satu alat. Claude Fable 5.1 dan Claude Mythos 5.1 tidak mendukung tipe tool_choice ini (lihat Memaksa penggunaan alat). Contoh berikut menggunakan any. Field yang sama berfungsi dengan tool:
client = Anthropic()
response = client.messages.create(
model="claude-opus-5",
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",
}
},
"required": ["location"],
},
}
],
tool_choice={"type": "any", "disable_parallel_tool_use": True},
messages=[
{
"role": "user",
"content": "What is the weather in San Francisco and New York?",
}
],
)
print(response.content)Pemecahan masalah
Jika Claude tidak melakukan panggilan alat paralel ketika diharapkan, periksa masalah umum berikut:
1. Pemformatan hasil alat yang salah
Masalah yang paling umum adalah memformat hasil alat secara salah dalam riwayat percakapan. Ini "mengajarkan" Claude untuk menghindari panggilan paralel.
Khusus untuk penggunaan alat paralel:
- Salah: pesan pengguna terpisah untuk setiap hasil alat
- Benar: semua hasil alat bersama-sama dalam satu pesan pengguna
// Wrong: separate user messages reduce parallel tool use
[
{"role": "assistant", "content": [tool_use_1, tool_use_2]},
{"role": "user", "content": [tool_result_1]},
{"role": "user", "content": [tool_result_2]} // Separate message
]
// Correct: one user message with all results maintains parallel tool use
[
{"role": "assistant", "content": [tool_use_1, tool_use_2]},
{"role": "user", "content": [tool_result_1, tool_result_2]} // Single message
]Lihat Menangani panggilan alat untuk aturan pemformatan lainnya.
2. Prompting yang lemah
Prompting default mungkin tidak mencukupi. Gunakan prompt sistem yang lebih kuat dari Memaksimalkan penggunaan alat paralel.
3. Mengukur penggunaan alat paralel
Untuk memverifikasi bahwa panggilan alat paralel berfungsi:
messages = [] # Message objects returned by client.messages.create across your run
tool_call_messages = [
msg for msg in messages if any(block.type == "tool_use" for block in msg.content)
]
total_tool_calls = sum(
len([block for block in msg.content if block.type == "tool_use"])
for msg in tool_call_messages
)
avg_tools_per_message = (
total_tool_calls / len(tool_call_messages) if tool_call_messages else 0.0
)
print(f"Average tools per message: {avg_tools_per_message}")
# Seharusnya > 1,0 jika panggilan paralel berfungsi4. Panggilan dalam satu batch tampak saling bergantung
Urutan eksekusi adalah pilihan Anda. Jika alat Anda memiliki ketergantungan urutan, menjalankan batch secara berurutan dan berhenti pada kegagalan pertama adalah strategi yang valid (dan merupakan strategi yang diwajibkan untuk alat computer use dan browser use): kembalikan is_error: true untuk setiap panggilan yang tidak Anda jalankan. Jika Anda menjalankan secara paralel dan sebuah panggilan gagal karena prasyaratnya belum selesai, kembalikan is_error: true dengan pesan error yang wajar. Claude akan mengeluarkan ulang panggilan tersebut pada giliran berikutnya. Untuk mengurangi panggilan yang saling bergantung muncul bersamaan, tambahkan ini ke prompt sistem Anda: "Only batch tool calls that are independent of each other."
Langkah selanjutnya
Gunakan abstraksi Tool Runner SDK untuk menangani loop agentik, pembungkusan error, dan keamanan tipe secara otomatis.
Parse blok tool_use, format respons tool_result, dan tangani error dengan is_error.
Tentukan skema alat, tulis deskripsi yang efektif, dan kendalikan kapan Claude memanggil alat Anda.
Was this page helpful?