MessagesAlat

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 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 menentukan 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 bersifat read-only 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 untuknya 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."
}

Menguji panggilan alat paralel

Gunakan Tool Runner untuk sebagian besar aplikasi: Tool Runner SDK menangani respons dengan beberapa panggilan alat dan memformat hasilnya untuk Anda, sehingga Anda tidak perlu menulis penanganan ini sendiri. Gunakan pola manual di halaman ini ketika Anda membutuhkan kontrol langsung atas cara panggilan dijalankan, seperti batching kustom, pengurutan, atau penanganan kesalahan.

Skrip berikut mengirimkan 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 environment 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 panggilan 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-4-8", max_tokens=1024, messages=messages, tools=tools
)

# Periksa panggilan 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-4-8", 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 menegaskan 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 melakukan panggilan alat paralel secara default ketika sebuah permintaan mendapat manfaat dari beberapa alat. Untuk semua model, Anda dapat meningkatkan kemungkinan panggilan alat paralel dengan prompting yang ditargetkan:

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-4-8",
    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. Contoh berikut menggunakan any. Field yang sama juga berfungsi dengan tool:

client = Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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 saat diharapkan, periksa masalah umum berikut:

1. Pemformatan hasil alat yang salah

Masalah paling umum adalah memformat hasil alat secara tidak benar 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 cukup. 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 berfungsi

4. Panggilan dalam satu batch tampak saling bergantung

Urutan eksekusi adalah pilihan Anda. Jika alat Anda memiliki dependensi urutan, menjalankan batch secara berurutan dan berhenti pada kegagalan pertama adalah strategi yang valid: 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 kesalahan yang wajar. Claude akan mengeluarkan kembali 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

Tool Runner (SDK)

Gunakan abstraksi Tool Runner SDK untuk menangani loop agentik, pembungkusan kesalahan, dan type safety secara otomatis.

Menangani panggilan alat

Parse blok tool_use, format respons tool_result, dan tangani kesalahan dengan is_error.

Mendefinisikan alat

Tentukan skema alat, tulis deskripsi yang efektif, dan kontrol kapan Claude memanggil alat Anda.

Was this page helpful?

MessagesAlat

Penggunaan alat paralel

Aktifkan, format, dan nonaktifkan panggilan alat paralel, dengan panduan riwayat pesan dan pemecahan masalah.

Semantik eksekusi

{
  "type": "tool_result",
  "tool_use_id": "toolu_02",
  "is_error": true,
  "content": "Not executed: the preceding write_file call failed."
}

Menguji panggilan alat paralel

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 panggilan 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-4-8", max_tokens=1024, messages=messages, tools=tools
)

# Periksa panggilan 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-4-8", 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")

Memaksimalkan penggunaan alat paralel

Menonaktifkan penggunaan alat paralel

Paling banyak satu panggilan alat

client = Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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

client = Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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 saat diharapkan, periksa masalah umum berikut:

1. Pemformatan hasil alat yang salah

Masalah paling umum adalah memformat hasil alat secara tidak benar 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 cukup. 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 berfungsi

4. Panggilan dalam satu batch tampak saling bergantung

Langkah selanjutnya

Tool Runner (SDK)

Gunakan abstraksi Tool Runner SDK untuk menangani loop agentik, pembungkusan kesalahan, dan type safety secara otomatis.

Menangani panggilan alat

Parse blok tool_use, format respons tool_result, dan tangani kesalahan dengan is_error.

Mendefinisikan alat

Tentukan skema alat, tulis deskripsi yang efektif, dan kontrol kapan Claude memanggil alat Anda.

Was this page helpful?

Semantik eksekusi

Menguji panggilan alat paralel

Memaksimalkan penggunaan alat paralel

Prompt sistem untuk penggunaan alat paralel

Prompting pesan pengguna

Menonaktifkan penggunaan alat paralel

Paling banyak satu panggilan alat

Tepat satu panggilan alat

Pemecahan masalah

Langkah selanjutnya

Semantik eksekusi

Menguji panggilan alat paralel

Memaksimalkan penggunaan alat paralel

Prompt sistem untuk penggunaan alat paralel

Prompting pesan pengguna

Menonaktifkan penggunaan alat paralel

Paling banyak satu panggilan alat

Tepat satu panggilan alat

Pemecahan masalah

Langkah selanjutnya

Semantik eksekusi

Menguji panggilan alat paralel

Memaksimalkan penggunaan alat paralel

Menonaktifkan penggunaan alat paralel

Paling banyak satu panggilan alat

Tepat satu panggilan alat

Pemecahan masalah

Langkah selanjutnya

Semantik eksekusi

Menguji panggilan alat paralel

Memaksimalkan penggunaan alat paralel

Menonaktifkan penggunaan alat paralel

Paling banyak satu panggilan alat

Tepat satu panggilan alat

Pemecahan masalah

Langkah selanjutnya