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.Menentukan alat klien
Alat klien (baik yang ditentukan Anthropic maupun yang ditentukan pengguna) ditentukan dalam parameter tingkat atastools dari permintaan API. Setiap definisi alat mencakup:
| Parameter | Deskripsi |
|---|---|
name | Nama alat. Harus cocok dengan regex ^[a-zA-Z0-9_-]{1,64}$. |
description | Deskripsi plaintext terperinci tentang apa yang dilakukan alat, kapan harus digunakan, dan bagaimana perilakunya. |
input_schema | Objek JSON Schema yang mendefinisikan parameter yang diharapkan untuk alat. |
Contoh definisi alat sederhana
Contoh definisi alat sederhana
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 parametertools, 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:
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.
Contoh deskripsi alat yang baik
Contoh deskripsi alat yang baik
Contoh deskripsi alat yang buruk
Contoh deskripsi alat yang buruk
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
Penggunaan dasar
@beta_tool untuk mendefinisikan alat dan client.beta.messages.tool_runner() untuk menjalankannya.@beta_tool dengan @beta_async_tool dan tentukan fungsi dengan async def.@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: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 bidangtool_choice seperti ini:
automemungkinkan Claude memutuskan apakah akan memanggil alat yang disediakan atau tidak. Ini adalah nilai default ketikatoolsdisediakan.anymemberitahu Claude bahwa itu harus menggunakan salah satu alat yang disediakan, tetapi tidak memaksa alat tertentu.toolmemungkinkan kami memaksa Claude untuk selalu menggunakan alat tertentu.nonemencegah Claude menggunakan alat apa pun. Ini adalah nilai default ketika tidak adatoolsyang disediakan.
tool_choice akan membatalkan blok pesan yang di-cache. Definisi alat dan prompt sistem tetap di-cache, tetapi konten pesan harus diproses ulang.
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.
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.{"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 alatrecord_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:<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=trueketika tipe tool_choice adalahauto, yang memastikan bahwa Claude menggunakan paling banyak satu alat - Mengatur
disable_parallel_tool_use=trueketika tipe tool_choice adalahanyatautool, yang memastikan bahwa Claude menggunakan tepat satu alat
Contoh penggunaan alat paralel lengkap
Contoh penggunaan alat paralel lengkap
Skrip pengujian lengkap untuk alat paralel
Skrip pengujian lengkap untuk alat paralel
- 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)
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:Prompt sistem untuk penggunaan alat paralel
Prompt sistem untuk penggunaan alat paralel
Prompting pesan pengguna
Prompting pesan pengguna
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
Menangani hasil dari alat klien
Respons akan memilikistop_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 denganinput_schemaalat.
Contoh respons API dengan blok konten `tool_use`
Contoh respons API dengan blok konten `tool_use`
- Ekstrak
name,id, daninputdari bloktool_use. - Jalankan alat aktual dalam codebase Anda yang sesuai dengan nama alat itu, meneruskan
inputalat. - Lanjutkan percakapan dengan mengirim pesan baru dengan
roledariuser, dan blokcontentyang berisi tipetool_resultdan informasi berikut:tool_use_id:iddari 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 tipetext,image, ataudocument.is_error(opsional): Atur ketruejika eksekusi alat menghasilkan kesalahan.
- 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.
Contoh hasil alat yang berhasil
Contoh hasil alat yang berhasil
Contoh hasil alat dengan gambar
Contoh hasil alat dengan gambar
Contoh hasil alat kosong
Contoh hasil alat kosong
Contoh hasil alat dengan dokumen
Contoh hasil alat dengan dokumen
Menangani hasil dari alat server
Claude menjalankan alat secara internal dan menggabungkan hasil langsung ke dalam responsnya tanpa memerlukan interaksi pengguna tambahan.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.
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:
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
Kesalahan eksekusi alat
Kesalahan eksekusi alat
content bersama dengan "is_error": true:Nama alat tidak valid
Nama alat tidak valid
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:Tag <search_quality_reflection>
Tag <search_quality_reflection>
Kesalahan alat server
Kesalahan alat server
is_error untuk alat server.Untuk pencarian web khususnya, kode kesalahan yang mungkin termasuk:too_many_requests: Batas laju terlampauiinvalid_input: Parameter kueri pencarian tidak validmax_uses_exceeded: Penggunaan alat pencarian web maksimum terlampauiquery_too_long: Kueri melebihi panjang maksimumunavailable: Kesalahan internal terjadi
Panggilan alat paralel tidak berfungsi
Panggilan alat paralel tidak berfungsi
- ❌ Salah: Mengirim pesan pengguna terpisah untuk setiap hasil alat
- ✅ Benar: Semua hasil alat harus dalam satu pesan pengguna
- 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