Cara mengimplementasikan penggunaan alat

Memilih model

Kami merekomendasikan menggunakan model Claude Opus terbaru (4.6) untuk alat kompleks dan kueri yang ambigu; model ini 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.

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:

Prompt sistem penggunaan alat

Ketika Anda memanggil Claude API 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 beroperasi dengan baik:

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 pedoman berikut:

• 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)
  • 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 kompleks.
• Prioritaskan deskripsi, tetapi pertimbangkan menggunakan input_examples untuk alat kompleks. Deskripsi yang jelas paling penting, tetapi untuk alat dengan input kompleks, objek bersarang, atau parameter sensitif format, Anda dapat menggunakan bidang input_examples (beta) untuk memberikan contoh yang divalidasi skema. Lihat Memberikan contoh penggunaan alat untuk detail.

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.

Memberikan contoh penggunaan alat

Anda dapat memberikan contoh konkret dari input alat yang valid untuk membantu Claude memahami cara menggunakan alat Anda dengan lebih efektif. Ini sangat berguna untuk alat kompleks dengan objek bersarang, parameter opsional, atau input sensitif format.

Penggunaan dasar

Tambahkan bidang input_examples opsional ke definisi alat Anda dengan larik objek input contoh. Setiap contoh harus valid sesuai dengan input_schema alat:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    betas=["advanced-tool-use-2025-11-20"],
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature"
                    }
                },
                "required": ["location"]
            },
            "input_examples": [
                {
                    "location": "San Francisco, CA",
                    "unit": "fahrenheit"
                },
                {
                    "location": "Tokyo, Japan",
                    "unit": "celsius"
                },
                {
                    "location": "New York, NY"  # 'unit' is optional
                }
            ]
        }
    ],
    messages=[
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
)

Contoh disertakan dalam prompt bersama skema alat Anda, menunjukkan kepada Claude pola konkret untuk panggilan alat yang terbentuk dengan baik. Ini membantu Claude memahami kapan harus menyertakan parameter opsional, format apa yang digunakan, dan cara menyusun input kompleks.

Persyaratan dan batasan

• Validasi skema - Setiap contoh harus valid sesuai dengan input_schema alat. Contoh yang tidak valid mengembalikan kesalahan 400
• Tidak didukung untuk alat sisi server - Hanya alat yang ditentukan pengguna yang dapat memiliki contoh input
• Biaya token - Contoh menambah token prompt: ~20-50 token untuk contoh sederhana, ~100-200 token untuk objek bersarang kompleks

Tool runner (beta)

Tool runner menyediakan solusi siap pakai untuk menjalankan alat dengan Claude. Alih-alih menangani panggilan alat, hasil alat, dan manajemen percakapan secara manual, tool runner secara otomatis:

• Menjalankan alat ketika Claude memanggilnya
• Menangani siklus permintaan/respons
• Mengelola status percakapan
• Menyediakan keamanan tipe dan validasi

Kami merekomendasikan agar Anda menggunakan tool runner untuk sebagian besar implementasi penggunaan alat.

Penggunaan dasar

Tentukan alat menggunakan pembantu SDK, kemudian gunakan tool runner untuk menjalankannya.

Fungsi alat harus mengembalikan blok konten atau larik blok konten, termasuk teks, gambar, atau blok dokumen. Ini memungkinkan alat untuk mengembalikan respons multimodal yang kaya. 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.

Iterasi di atas tool runner

Tool runner adalah iterable yang menghasilkan pesan dari Claude. Ini sering disebut sebagai "tool call loop". Setiap iterasi, runner memeriksa apakah Claude meminta penggunaan alat. Jika demikian, ia memanggil alat dan mengirim hasilnya kembali ke Claude secara otomatis, kemudian menghasilkan pesan berikutnya dari Claude untuk melanjutkan loop Anda.

Anda dapat mengakhiri loop di iterasi mana pun dengan pernyataan break. Runner akan loop sampai Claude mengembalikan pesan tanpa penggunaan alat.

Jika Anda tidak memerlukan pesan perantara, Anda dapat mendapatkan pesan akhir secara langsung:

Penggunaan lanjutan

Dalam loop, Anda dapat sepenuhnya menyesuaikan permintaan berikutnya tool runner ke Messages API. Runner secara otomatis menambahkan hasil alat ke riwayat pesan, jadi Anda tidak perlu mengelolanya secara manual. Anda dapat secara opsional memeriksa hasil alat untuk logging atau debugging, dan memodifikasi parameter permintaan sebelum panggilan API berikutnya.

Debugging eksekusi alat

Ketika alat melempar pengecualian, tool runner menangkapnya dan mengembalikan kesalahan ke Claude sebagai hasil alat dengan is_error: true. Secara default, hanya pesan pengecualian yang disertakan, bukan stack trace lengkap.

Untuk melihat stack trace lengkap dan informasi debug, atur variabel lingkungan ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Ketika diaktifkan, SDK mencatat detail pengecualian lengkap (menggunakan modul logging Python, konsol di TypeScript, atau logger Ruby), termasuk stack trace lengkap ketika alat gagal.

Mengintersepsi kesalahan alat

Secara default, kesalahan alat diteruskan kembali ke Claude, yang kemudian dapat merespons dengan tepat. Namun, Anda mungkin ingin mendeteksi kesalahan dan menanganinya secara berbeda—misalnya, untuk menghentikan eksekusi lebih awal atau menerapkan penanganan kesalahan khusus.

Gunakan metode respons alat untuk mengintersepsi hasil alat dan memeriksa kesalahan sebelum dikirim ke Claude:

Memodifikasi hasil alat

Anda dapat memodifikasi hasil alat sebelum dikirim kembali ke Claude. Ini berguna untuk menambahkan metadata seperti cache_control untuk mengaktifkan prompt caching pada hasil alat, atau untuk mengubah output alat.

Gunakan metode respons alat untuk mendapatkan hasil alat, memodifikasinya, kemudian tambahkan versi yang dimodifikasi ke pesan:

Streaming

Aktifkan streaming untuk menerima acara saat tiba. Setiap iterasi menghasilkan objek stream yang dapat Anda iterasi untuk acara.

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 dalam 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 ia 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.

Diagram ini mengilustrasikan cara kerja setiap opsi:

Perhatikan bahwa ketika Anda memiliki tool_choice sebagai any atau tool, kami akan mengisi sebelumnya pesan asisten untuk memaksa alat digunakan. Ini berarti bahwa model tidak akan mengeluarkan respons bahasa alami atau penjelasan sebelum blok konten tool_use, bahkan jika secara eksplisit diminta untuk melakukannya.

Pengujian kami telah 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 saja Anda ingin model mengembalikan output JSON yang mengikuti skema yang disediakan. Misalnya, Anda mungkin menggunakan alat record_summary dengan skema tertentu. Lihat Tool use with Claude untuk contoh kerja lengkap.

Respons model dengan alat

Saat menggunakan alat, Claude sering kali akan mengomentari apa yang sedang 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:

{
  "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 pertanyaan pengguna. Anda dapat menonaktifkan perilaku ini dengan:

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

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:

Menangani blok konten penggunaan alat dan hasil 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: Pengenal 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.

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 yang merupakan hasil ini.
   • 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.

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

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

Setelah menerima hasil alat, Claude akan menggunakan informasi itu untuk melanjutkan 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.

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-opus-4-6",
            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 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 sesuai adanya dalam permintaan berikutnya untuk membiarkan Claude melanjutkan gilirannya
• Ubah jika diperlukan: Anda dapat secara opsional mengubah konten sebelum melanjutkan jika Anda ingin mengganggu atau mengarahkan ulang percakapan
• Pertahankan status alat: Sertakan alat yang sama dalam permintaan lanjutan untuk mempertahankan fungsionalitas

Mengatasi kesalahan

Ada beberapa jenis kesalahan berbeda yang dapat terjadi saat menggunakan alat dengan Claude: