Memilih model

Kami merekomendasikan menggunakan model Claude Sonnet (4.5) atau Claude Opus (4.1) terbaru untuk alat yang kompleks dan kueri yang ambigu; mereka menangani beberapa alat dengan lebih baik dan mencari klarifikasi saat diperlukan. Gunakan model Claude Haiku untuk alat yang sederhana, tetapi perhatikan bahwa mereka mungkin menyimpulkan parameter yang hilang.
Jika menggunakan Claude dengan penggunaan alat dan pemikiran yang diperluas, lihat panduan kami di sini untuk informasi lebih lanjut.

Menentukan alat klien

Alat klien (baik yang ditentukan Anthropic maupun yang ditentukan pengguna) ditentukan dalam parameter tingkat atas tools dari permintaan API. Setiap definisi alat mencakup:
ParameterDeskripsi
nameNama alat. Harus cocok dengan regex ^[a-zA-Z0-9_-]{1,64}$.
descriptionDeskripsi plaintext terperinci tentang apa yang dilakukan alat, kapan harus digunakan, dan bagaimana perilakunya.
input_schemaObjek JSON Schema yang mendefinisikan parameter yang diharapkan untuk alat.
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"]
  }
}
Alat ini, bernama get_weather, mengharapkan objek input dengan string location yang diperlukan dan string unit opsional yang harus berupa “celsius” atau “fahrenheit”.

Prompt sistem penggunaan alat

Ketika Anda memanggil API Claude dengan parameter tools, kami membuat prompt sistem khusus dari definisi alat, konfigurasi alat, dan prompt sistem yang ditentukan pengguna. Prompt yang dibangun dirancang untuk menginstruksikan model untuk menggunakan alat yang ditentukan dan memberikan konteks yang diperlukan agar alat 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 }}

Praktik terbaik untuk definisi alat

Untuk mendapatkan kinerja terbaik dari Claude saat menggunakan alat, ikuti panduan ini:
  • Berikan deskripsi yang sangat terperinci. Ini adalah faktor paling penting dalam kinerja alat. Deskripsi Anda harus menjelaskan setiap detail tentang alat, termasuk:
    • Apa yang dilakukan alat
    • Kapan harus digunakan (dan kapan tidak boleh digunakan)
    • Apa arti setiap parameter dan bagaimana pengaruhnya terhadap perilaku alat
    • Peringatan atau batasan penting, seperti informasi apa yang tidak dikembalikan alat jika nama alat tidak jelas. Semakin banyak konteks yang dapat Anda berikan kepada Claude tentang alat Anda, semakin baik dalam memutuskan kapan dan bagaimana menggunakannya. Targetkan setidaknya 3-4 kalimat per deskripsi alat, lebih banyak jika alat tersebut kompleks.
  • Prioritaskan deskripsi daripada contoh. Meskipun Anda dapat menyertakan contoh cara menggunakan alat dalam deskripsinya atau dalam prompt yang menyertainya, ini kurang penting daripada memiliki penjelasan yang jelas dan komprehensif tentang tujuan dan parameter alat. Hanya tambahkan contoh setelah Anda telah sepenuhnya mengembangkan deskripsi.
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"]
  }
}
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 alat, 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 alat.

Pelari alat (beta)

Pelari alat menyediakan solusi siap pakai untuk menjalankan alat dengan Claude. Alih-alih menangani panggilan alat, hasil alat, dan manajemen percakapan secara manual, pelari alat secara otomatis:
  • Menjalankan alat ketika Claude memanggilnya
  • Menangani siklus permintaan/respons
  • Mengelola status percakapan
  • Menyediakan keamanan tipe dan validasi
Kami merekomendasikan agar Anda menggunakan pelari alat untuk sebagian besar implementasi penggunaan alat.
Pelari alat saat ini dalam beta dan hanya tersedia di SDK Python dan TypeScript.

Penggunaan dasar

Gunakan dekorator @beta_tool untuk mendefinisikan alat dan client.beta.messages.tool_runner() untuk menjalankannya.
Jika Anda menggunakan klien async, ganti @beta_tool dengan @beta_async_tool dan tentukan fungsi dengan async def.
import anthropic
import json
from anthropic import beta_tool

# Initialize client
client = anthropic.Anthropic()

# Define tools using the decorator
@beta_tool
def get_weather(location: str, unit: str = "fahrenheit") -> str:
    """Get the current weather in a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA
        unit: Temperature unit, either 'celsius' or 'fahrenheit'
    """
    # In a full implementation, you'd call a weather API here
    return json.dumps({"temperature": "20°C", "condition": "Sunny"})

@beta_tool
def calculate_sum(a: int, b: int) -> str:
    """Add two numbers together.

    Args:
        a: First number
        b: Second number
    """
    return str(a + b)

# Use the tool runner
with client.beta.messages.tool_runner(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[get_weather, calculate_sum],
    messages=[
        {"role": "user", "content": "What's the weather like in Paris? Also, what's 15 + 27?"}
    ]
) as runner:
    for message in runner:
        print(message.content[0].text)
Fungsi yang didekorasi harus mengembalikan blok konten atau array blok konten, termasuk teks, gambar, atau blok dokumen. Ini memungkinkan alat untuk mengembalikan respons kaya dan multimodal. String yang dikembalikan akan dikonversi ke blok konten teks. Jika Anda ingin mengembalikan objek JSON terstruktur ke Claude, enkode ke string JSON sebelum mengembalikannya. Angka, boolean, atau primitif non-string lainnya juga harus dikonversi ke string.Dekorator @beta_tool akan memeriksa argumen fungsi dan docstring untuk mengekstrak representasi json schema dari fungsi yang diberikan, dalam contoh di atas calculate_sum akan diubah menjadi:
{
  "name": "calculate_sum",
  "description": "Adds two integers together.",
  "input_schema": {
    "additionalProperties": false,
    "properties": {
      "left": {
        "description": "The first integer to add.",
        "title": "Left",
        "type": "integer"
      },
      "right": {
        "description": "The second integer to add.",
        "title": "Right",
        "type": "integer"
      }
    },
    "required": ["left", "right"],
    "type": "object"
  }
}
Pelari alat SDK dalam beta. Sisa dokumen ini mencakup implementasi alat manual.

Mengontrol output Claude

Memaksa penggunaan alat

Dalam beberapa kasus, Anda mungkin ingin Claude menggunakan alat tertentu untuk menjawab pertanyaan pengguna, bahkan jika Claude berpikir dapat memberikan jawaban tanpa menggunakan alat. Anda dapat melakukan ini dengan menentukan alat di bidang tool_choice seperti ini:
tool_choice = {"type": "tool", "name": "get_weather"}
Saat bekerja dengan parameter tool_choice, kami memiliki empat opsi yang mungkin:
  • auto memungkinkan Claude memutuskan apakah akan memanggil alat yang disediakan atau tidak. Ini adalah nilai default ketika tools disediakan.
  • any memberitahu Claude bahwa itu harus menggunakan salah satu alat yang disediakan, tetapi tidak memaksa alat tertentu.
  • tool memungkinkan kami memaksa Claude untuk selalu menggunakan alat tertentu.
  • none mencegah Claude menggunakan alat apa pun. Ini adalah nilai default ketika tidak ada tools yang disediakan.
Saat menggunakan prompt caching, perubahan pada parameter tool_choice akan membatalkan blok pesan yang di-cache. Definisi alat dan prompt sistem tetap di-cache, tetapi konten pesan harus diproses ulang.
Diagram ini mengilustrasikan cara kerja setiap opsi:
Perhatikan bahwa ketika Anda memiliki tool_choice sebagai any atau tool, kami akan mengisi pesan asisten sebelumnya untuk memaksa alat digunakan. Ini berarti bahwa model tidak akan memancarkan respons bahasa alami atau penjelasan sebelum blok konten tool_use, bahkan jika secara eksplisit diminta untuk melakukannya.
Saat menggunakan pemikiran yang diperluas dengan penggunaan alat, tool_choice: {"type": "any"} dan tool_choice: {"type": "tool", "name": "..."} tidak didukung dan akan menghasilkan kesalahan. Hanya tool_choice: {"type": "auto"} (default) dan tool_choice: {"type": "none"} yang kompatibel dengan pemikiran yang diperluas.
Pengujian kami menunjukkan bahwa ini tidak boleh mengurangi kinerja. Jika Anda ingin model memberikan konteks bahasa alami atau penjelasan sambil tetap meminta model menggunakan alat 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

Alat tidak harus berupa fungsi klien — Anda dapat menggunakan alat kapan pun Anda ingin model mengembalikan output JSON yang mengikuti skema yang disediakan. Misalnya, Anda mungkin menggunakan alat record_summary dengan skema tertentu. Lihat Penggunaan alat dengan Claude untuk contoh kerja lengkap.

Respons model dengan alat

Saat menggunakan alat, Claude sering kali akan berkomentar tentang apa yang dilakukannya atau merespons secara alami kepada pengguna sebelum memanggil alat. 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": "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"}
    }
  ]
}
Gaya respons alami ini membantu pengguna memahami apa yang dilakukan Claude dan menciptakan interaksi yang lebih percakapan. Anda dapat memandu gaya dan konten respons ini melalui prompt sistem Anda dan dengan menyediakan <examples> dalam prompt Anda. Penting untuk dicatat bahwa Claude dapat menggunakan berbagai frasa dan pendekatan saat menjelaskan tindakannya. Kode Anda harus memperlakukan respons ini seperti teks yang dihasilkan asisten lainnya, dan tidak mengandalkan konvensi pemformatan tertentu.

Penggunaan alat paralel

Secara default, Claude dapat menggunakan beberapa alat untuk menjawab kueri 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 alat
  • Mengatur disable_parallel_tool_use=true ketika tipe tool_choice adalah any atau tool, yang memastikan bahwa Claude menggunakan tepat satu alat
Lebih sederhana dengan Tool runner: Contoh di bawah ini menunjukkan penanganan alat paralel manual. Untuk sebagian besar kasus penggunaan, tool runner secara otomatis menangani eksekusi alat paralel dengan kode yang jauh lebih sedikit.
Berikut adalah contoh lengkap yang menunjukkan cara memformat dengan benar panggilan alat paralel 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-sonnet-4-5",
    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-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)
Pesan asisten dengan panggilan alat 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"}
    }
  ]
}
Berikut adalah skrip lengkap yang dapat dijalankan untuk menguji dan memverifikasi panggilan alat paralel berfungsi dengan benar:
#!/usr/bin/env python3
"""Test script to verify parallel tool calls with the Claude 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-sonnet-4-5",
    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("\nGetting final response...")
final_response = client.messages.create(
    model="claude-sonnet-4-5",
    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")
Skrip ini mendemonstrasikan:
  • Cara memformat dengan benar panggilan alat paralel dan hasil
  • Cara memverifikasi bahwa panggilan paralel sedang dilakukan
  • Struktur pesan yang benar yang mendorong penggunaan alat paralel di masa depan
  • Kesalahan umum yang harus dihindari (seperti teks sebelum hasil alat)
Jalankan skrip ini untuk menguji implementasi Anda dan memastikan Claude membuat panggilan alat paralel secara efektif.

Memaksimalkan penggunaan alat paralel

Meskipun model Claude 4 memiliki kemampuan penggunaan alat paralel yang sangat baik secara default, Anda dapat meningkatkan kemungkinan eksekusi alat paralel di semua model dengan prompting yang ditargetkan:
Untuk model Claude 4 (Opus 4.1, Opus 4, dan Sonnet 4), 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 (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>
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."
Penggunaan alat paralel dengan Claude Sonnet 3.7Claude Sonnet 3.7 mungkin kurang mungkin membuat panggilan alat paralel dalam respons, bahkan ketika Anda belum mengatur disable_parallel_tool_use. Untuk mengatasi ini, kami merekomendasikan mengaktifkan penggunaan alat yang efisien token, yang membantu mendorong Claude untuk menggunakan alat paralel. Fitur beta ini juga mengurangi latensi dan menghemat rata-rata 14% dalam token output.Jika Anda lebih suka tidak memilih fitur penggunaan alat yang efisien token, Anda juga dapat memperkenalkan “alat batch” yang dapat bertindak sebagai meta-alat untuk membungkus invokasi ke alat lain secara bersamaan. Kami menemukan bahwa jika alat ini ada, model akan menggunakannya untuk secara bersamaan memanggil beberapa alat secara paralel untuk Anda.Lihat contoh ini dalam cookbook kami untuk cara menggunakan solusi ini.

Menangani blok konten penggunaan alat dan hasil alat

Lebih sederhana dengan Tool runner: Penanganan alat manual yang dijelaskan di bagian ini secara otomatis dikelola oleh tool runner. Gunakan bagian ini ketika Anda memerlukan kontrol khusus atas eksekusi alat.
Respons Claude berbeda berdasarkan apakah menggunakan alat klien atau server.

Menangani hasil dari alat klien

Respons akan memiliki stop_reason dari tool_use dan satu atau lebih blok konten tool_use yang mencakup:
  • id: Pengidentifikasi unik untuk blok penggunaan alat tertentu ini. Ini akan digunakan untuk mencocokkan hasil alat nanti.
  • name: Nama alat yang digunakan.
  • input: Objek yang berisi input yang diteruskan ke alat, sesuai dengan input_schema alat.
JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-sonnet-4-5",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the current weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}
Ketika Anda menerima respons penggunaan alat untuk alat klien, Anda harus:
  1. Ekstrak name, id, dan input dari blok tool_use.
  2. Jalankan alat aktual dalam codebase Anda yang sesuai dengan nama alat itu, meneruskan input alat.
  3. Lanjutkan percakapan dengan mengirim pesan baru dengan role dari user, dan blok content yang berisi tipe tool_result dan informasi berikut:
    • tool_use_id: id dari permintaan penggunaan alat ini adalah hasil untuk.
    • content: Hasil alat, sebagai string (misalnya "content": "15 degrees"), daftar blok konten bersarang (misalnya "content": [{"type": "text", "text": "15 degrees"}]), atau daftar blok dokumen (misalnya "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}]). Blok konten ini dapat menggunakan tipe text, image, atau document.
    • is_error (opsional): Atur ke true jika eksekusi alat menghasilkan kesalahan.
Persyaratan pemformatan penting:
  • Blok hasil alat harus segera mengikuti blok penggunaan alat yang sesuai dalam riwayat pesan. Anda tidak dapat menyertakan pesan apa pun antara pesan penggunaan alat asisten dan pesan hasil alat pengguna.
  • Dalam pesan pengguna yang berisi hasil alat, blok tool_result harus datang PERTAMA dalam array konten. Teks apa pun harus datang SETELAH semua hasil alat.
Misalnya, ini akan menyebabkan kesalahan 400:
{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Text before 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?"}  // ✅ Text after tool_result
]}
Jika Anda menerima kesalahan seperti “tool_use ids were found without tool_result blocks immediately after”, periksa bahwa hasil alat Anda diformat dengan benar.
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}
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...",
          }
        }
      ]
    }
  ]
}
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": "The weather is"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 degrees"
          }
        }
      ]
    }
  ]
}
Setelah menerima hasil alat, Claude akan menggunakan informasi itu untuk terus menghasilkan respons terhadap prompt pengguna asli.

Menangani hasil dari alat server

Claude menjalankan alat secara internal dan menggabungkan hasil langsung ke dalam responsnya tanpa memerlukan interaksi pengguna tambahan.
Perbedaan dari API lainTidak seperti API yang memisahkan penggunaan alat atau menggunakan peran khusus seperti tool atau function, API Claude mengintegrasikan alat 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, sementara pesan assistant berisi konten yang dihasilkan AI dan tool_use.

Menangani alasan penghentian max_tokens

Jika respons Claude terpotong karena mencapai batas max_tokens, dan respons yang terpotong berisi blok penggunaan alat yang tidak lengkap, Anda perlu mencoba ulang permintaan dengan nilai max_tokens yang lebih tinggi untuk mendapatkan penggunaan alat 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-sonnet-4-5",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools
        )

Menangani alasan penghentian pause_turn

Saat menggunakan alat server seperti pencarian web, API dapat mengembalikan alasan penghentian pause_turn, menunjukkan bahwa API telah menjeda giliran yang berjalan lama. Berikut adalah cara menangani alasan penghentian 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)
Saat menangani pause_turn:
  • Lanjutkan percakapan: Teruskan respons yang dijeda apa adanya dalam permintaan berikutnya untuk membiarkan Claude melanjutkan gilirannya
  • Modifikasi jika diperlukan: Anda dapat secara opsional memodifikasi konten sebelum melanjutkan jika Anda ingin mengganggu atau mengalihkan percakapan
  • Pertahankan status alat: Sertakan alat yang sama dalam permintaan lanjutan untuk mempertahankan fungsionalitas

Pemecahan masalah kesalahan

Penanganan Kesalahan Bawaan: Tool runner menyediakan penanganan kesalahan otomatis untuk sebagian besar skenario umum. Bagian ini mencakup penanganan kesalahan manual untuk kasus penggunaan lanjutan.
Ada beberapa jenis kesalahan berbeda yang dapat terjadi saat menggunakan alat dengan Claude:
Jika alat itu sendiri melempar kesalahan selama eksekusi (misalnya kesalahan jaringan saat mengambil data cuaca), Anda dapat mengembalikan pesan kesalahan 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 kesalahan 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.”
Jika upaya Claude menggunakan alat tidak valid (misalnya parameter yang diperlukan hilang), biasanya berarti tidak ada cukup informasi bagi Claude untuk menggunakan alat dengan benar. Taruhan terbaik Anda selama pengembangan adalah mencoba permintaan lagi dengan nilai description yang lebih terperinci dalam definisi alat Anda.Namun, Anda juga dapat melanjutkan percakapan ke depan dengan tool_result yang menunjukkan kesalahan, dan Claude akan mencoba menggunakan alat 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 alat tidak valid atau parameter hilang, Claude akan mencoba ulang 2-3 kali dengan koreksi sebelum meminta maaf kepada pengguna.
Untuk mencegah Claude merefleksikan kualitas hasil pencarian dengan tag <search_quality_reflection>, tambahkan “Do not reflect on the quality of the returned search results in your response” ke prompt Anda.
Ketika alat server mengalami kesalahan (misalnya masalah jaringan dengan Pencarian Web), Claude akan menangani kesalahan ini secara transparan dan mencoba memberikan respons alternatif atau penjelasan kepada pengguna. Tidak seperti alat klien, Anda tidak perlu menangani hasil is_error untuk alat server.Untuk pencarian web khususnya, kode kesalahan yang mungkin termasuk:
  • too_many_requests: Batas laju terlampaui
  • invalid_input: Parameter kueri pencarian tidak valid
  • max_uses_exceeded: Penggunaan alat pencarian web maksimum terlampaui
  • query_too_long: Kueri melebihi panjang maksimum
  • unavailable: Kesalahan internal terjadi
Jika Claude tidak membuat panggilan alat paralel saat diharapkan, periksa masalah umum ini:1. Pemformatan hasil alat yang tidak benarMasalah paling umum adalah memformat hasil alat secara tidak benar dalam riwayat percakapan. Ini “mengajarkan” Claude untuk menghindari panggilan paralel.Secara khusus untuk penggunaan alat paralel:
  • Salah: Mengirim pesan pengguna terpisah untuk setiap hasil alat
  • Benar: Semua hasil alat harus dalam satu pesan pengguna
// ❌ This reduces 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
]

// ✅ This 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 persyaratan pemformatan umum di atas untuk aturan pemformatan lainnya.2. Prompting yang lemahPrompting 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 alat paralelUntuk memverifikasi panggilan alat paralel berfungsi:
# 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.1, Opus 4, dan Sonnet 4: Unggul dalam penggunaan alat paralel dengan prompting minimal
  • Claude Sonnet 3.7: Mungkin memerlukan prompting yang lebih kuat atau penggunaan alat yang efisien token
  • Claude Haiku: Kurang mungkin menggunakan alat paralel tanpa prompting eksplisit