Pemecahan masalah penggunaan alat
Perbaiki kesalahan penggunaan alat yang paling umum dengan tabel diagnostik gejala-ke-perbaikan.
Temukan gejala atau kesalahan yang Anda lihat, lalu terapkan perbaikan yang tercantum untuknya.
Claude memanggil alat yang salah
| Gejala | Kemungkinan penyebab | Perbaikan |
|---|---|---|
| Claude memanggil alat A padahal Anda menginginkan alat B | Deskripsi ambigu | Pertajam deskripsi. Bedakan alat berdasarkan KAPAN menggunakannya, bukan hanya APA yang dilakukannya. Lihat Mendefinisikan alat. |
| Claude tidak pernah memanggil alat Anda | Tabrakan nama alat atau skema yang terlalu generik | Periksa nama duplikat di seluruh daftar alat Anda. Tambahkan input_examples agar penggunaan yang dimaksud menjadi konkret. |
| Claude memanggil dengan tipe parameter yang salah | Skema ambigu | Tambahkan strict: true (jika skema Anda berada dalam subset yang didukung) atau tambahkan input_examples. |
Claude mengarang parameter alat
| Gejala | Kemungkinan penyebab | Perbaikan |
|---|---|---|
| Parameter yang tidak ada dalam skema Anda | Model menghasilkan berlebihan tanpa mode strict | Tambahkan strict: true jika skema Anda berada dalam subset yang didukung. |
| Nilai parameter di luar enum Anda | Mode strict tidak ada atau enum terlalu besar | Perkecil enum atau tambahkan input_examples yang menunjukkan pilihan yang valid. |
Pemanggilan alat paralel tidak berfungsi
| Gejala | Kemungkinan penyebab | Perbaikan |
|---|---|---|
| Claude memanggil alat secara berurutan padahal paralel akan lebih baik | Pemformatan riwayat pesan | Kirim beberapa blok tool_result dalam SATU pesan pengguna, bukan satu per giliran. Lihat Penggunaan alat paralel. |
disable_parallel_tool_use tampaknya diabaikan | Diatur terlalu lambat dalam percakapan | Atur pada permintaan yang mengembalikan tool_use. Mengaturnya pada permintaan selanjutnya tidak berpengaruh pada pemanggilan alat sebelumnya. |
Cache terus menjadi tidak valid
| Gejala | Kemungkinan penyebab | Perbaikan |
|---|---|---|
| Setiap permintaan adalah cache miss | tool_choice, konfigurasi thinking, atau output_config.effort bervariasi antar permintaan | Jaga tool_choice tetap stabil atau tempatkan breakpoint cache_control sebelum titik variasi; pertahankan konfigurasi thinking dan tingkat effort konstan selama masa hidup percakapan yang di-cache. Lihat Penggunaan alat dengan caching prompt dan Thinking dan caching prompt. |
| Menambahkan alat di tengah percakapan merusak cache | Alat ditambahkan di awal array tools | Deklarasikan alat dengan defer_loading: true sejak permintaan pertama dan biarkan pencarian alat memuatnya secara inline, alih-alih menambahkannya ke array di kemudian waktu. |
Kesalahan pada saat permintaan
Kolom Kesalahan menampilkan sebagian dari setiap pesan, dan ... mewakili teks yang bervariasi.
| Kesalahan | Penyebab | Perbaikan |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | tool_result tidak ada untuk beberapa ID tool_use, atau tool_result bukan blok konten pertama dalam pesan pengguna | Kembalikan satu tool_result untuk setiap blok tool_use dalam respons asisten. Letakkan blok tool_result sebelum teks apa pun. Lihat Menangani pemanggilan alat dan Penggunaan alat paralel. |
was found without a corresponding ... block | Permintaan lanjutan mencegah alat server yang sedang menunggu untuk dijalankan | Lihat Pemanggilan alat server tidak memiliki blok hasil. |
Unsupported regex feature in pattern field: ... | Sebuah pattern alat strict menggunakan fitur regex yang tidak dapat dikompilasi oleh mode strict, seperti backreference, batas kata, atau rentang {n,m} yang besar | Sederhanakan pola tersebut. Lihat Batasan JSON Schema. |
Invalid regex in pattern field: ... | Sebuah pattern alat strict memiliki lookahead, lookbehind, atau kesalahan sintaksis | Hapus lookahead atau lookbehind apa pun dan perbaiki kesalahan sintaksis apa pun. Lihat Batasan JSON Schema. |
All tools have defer_loading: true | Tidak ada alat yang terlihat oleh model | Setidaknya satu alat harus dimuat segera. Alat pencarian alat itu sendiri tidak boleh memiliki defer_loading: true. |
Pemanggilan alat server tidak memiliki blok hasil
Sebuah alat server masih menunggu untuk dijalankan ketika blok server_tool_use atau mcp_tool_use-nya tidak memiliki blok hasil. Kesalahan was found without a corresponding ... block berarti permintaan lanjutan mencegah alat yang sedang menunggu tersebut dijalankan. Pesan kesalahan dan stop_reason sebelumnya menunjukkan alasannya. Gunakan kasus pertama yang cocok:
- Pesan diakhiri dengan
but no `<name>` tool was providedatauis not available after the last message: Di sini,<name>adalah nama alat, sepertiweb_search. Permintaan tidak lagi mendefinisikan alat tersebut. Kirim arraytoolsyang sama seperti sebelumnya, danmcp_serversyang sama untuk alat MCP. stop_reasonsebelumnya adalahtool_use: Pesan pengguna Anda memiliki konten setelah bloktool_result. Kirim hanya bloktool_result, satu untuk setiap bloktool_useklien.stop_reasonsebelumnya adalahpause_turn: Anda menambahkan pesan pengguna. Hapus pesan tersebut agar permintaan diakhiri dengan respons yang dijeda sebagai pesanassistant.
Untuk langkah lengkapnya, lihat Ketika alat server masih menunggu dan alasan berhenti pause_turn.
Kesalahan: blok thinking tidak dapat dimodifikasi
Jika sebuah permintaan gagal dengan 400 invalid_request_error yang pesannya berisi `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified saat melanjutkan percakapan setelah pemanggilan alat, aplikasi Anda mengubah blok thinking asisten sebelum mengirimkannya kembali. Kirim seluruh pesan asisten kembali tanpa perubahan, lalu tambahkan tool_result Anda.
Lihat Blok thinking tidak dapat dimodifikasi untuk kesalahan lengkap dan langkah perbaikannya.
Claude menandai hasil alat sebagai injeksi prompt
| Gejala | Kemungkinan penyebab | Perbaikan |
|---|---|---|
| Claude menolak bertindak berdasarkan hasil alat, atau meminta pengguna mengonfirmasi instruksi yang berasal darinya | Instruksi Anda sendiri dikirimkan di dalam konten tool_result | Claude dilatih untuk memperlakukan instruksi di dalam hasil alat sebagai konten pihak ketiga yang berpotensi tidak tepercaya. Pindahkan instruksi Anda keluar dari hasil alat: kirimkan dalam giliran user setelah blok tool_result, atau, pada model yang didukung, dalam pesan sistem di tengah percakapan. Jaga agar hasil alat hanya berisi data. Lihat Memitigasi jailbreak dan prompt injection. |
Perbedaan escaping JSON antar versi model
| Gejala | Penyebab | Perbaikan |
|---|---|---|
| Perbandingan string pada input alat gagal dengan model yang lebih baru | Escaping Unicode dan garis miring berbeda antar versi model | Parse dengan json.loads() atau JSON.parse(). Jangan pernah melakukan pencocokan string mentah pada input yang diserialisasi. |
Langkah selanjutnya
Tulis skema dan deskripsi yang mengarahkan Claude ke alat yang tepat.
Jalankan alat dan kembalikan hasil dalam format pesan yang diperlukan.
Direktori lengkap alat yang disediakan Anthropic dan string versinya.
Apakah halaman ini membantu?