MessagesAlat

Menangani panggilan alat

Mengurai blok tool_use, memformat respons tool_result, dan menangani kesalahan dengan is_error.

Halaman ini membahas siklus hidup panggilan alat: membaca blok tool_use dari respons Claude, memformat blok tool_result dalam balasan Anda, dan memberi sinyal kesalahan. Untuk abstraksi SDK yang menangani hal ini secara otomatis, lihat Tool Runner.

Lebih sederhana dengan Tool Runner: Penanganan alat secara manual yang dijelaskan di halaman ini dikelola secara otomatis oleh Tool Runner. Gunakan halaman ini ketika Anda memerlukan kontrol khusus atas eksekusi alat.

Respons Claude berbeda tergantung pada apakah ia menggunakan alat klien atau server.

Menangani hasil dari alat klien

Respons akan memiliki stop_reason berupa 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 nantinya.
name: Nama alat yang sedang digunakan.
input: Objek yang berisi input yang diteruskan ke alat, sesuai dengan input_schema alat tersebut.

Ketika Anda menerima respons penggunaan alat untuk alat klien, Anda harus:

Mengekstrak name, id, dan input dari blok tool_use.
Menjalankan alat yang sebenarnya di basis kode Anda yang sesuai dengan nama alat tersebut, dengan meneruskan input alat.
Melanjutkan percakapan dengan mengirim pesan baru dengan role berupa user, dan blok content yang berisi tipe tool_result serta informasi berikut:
- tool_use_id: id dari permintaan penggunaan alat yang hasilnya ini.
- content (opsional): Hasil dari 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, document, atau search_result.
- is_error (opsional): Atur ke true jika eksekusi alat menghasilkan kesalahan.

Persyaratan pemformatan penting:

Blok hasil alat harus langsung mengikuti blok penggunaan alat yang sesuai dalam riwayat pesan. Anda tidak dapat menyertakan pesan apa pun di antara pesan penggunaan alat dari asisten dan pesan hasil alat dari pengguna.
Dalam pesan pengguna yang berisi hasil alat, blok tool_result harus berada PERTAMA dalam array konten. Teks apa pun harus berada SETELAH semua hasil alat.
Jika giliran asisten juga memanggil alat server yang belum memiliki blok hasil, pesan pengguna harus hanya berisi blok tool_result. Teks setelah hasil akan mengakhiri giliran lebih awal; untuk alat server yang dipanggil Claude secara langsung, permintaan kemudian gagal dengan kesalahan 400 yang menyebutkan nama alat server yang belum terselesaikan. Lihat Alasan berhenti dan fallback.

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 ketika giliran asisten hanya memanggil alat klien:

{
  "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 apakah hasil alat Anda diformat dengan benar.

Hasil alat sering kali membawa konten dari sumber di luar kendali Anda: halaman web, email masuk, unggahan pengguna, API pihak ketiga. Perlakukan konten tersebut sebagai tidak tepercaya: penyerang yang dapat memengaruhinya mungkin menyematkan instruksi yang mencoba mengalihkan Claude (injeksi prompt tidak langsung). Simpan konten yang tidak tepercaya di dalam blok tool_result alih-alih prompt system atau blok text pengguna biasa, dan lihat Memitigasi jailbreak dan injeksi prompt untuk pengamanan lebih lanjut.

Setelah menerima hasil alat, Claude akan menggunakan informasi tersebut untuk melanjutkan menghasilkan respons terhadap prompt pengguna asli.

Menangani hasil dari alat server

Claude mengeksekusi alat secara internal dan memasukkan hasilnya langsung ke dalam responsnya tanpa memerlukan interaksi pengguna tambahan.

Sebuah respons dapat berisi blok tool_use klien dan blok server_tool_use yang belum memiliki blok hasil. Panggilan alat server tersebut belum selesai, dan blok hasilnya tiba dalam respons berikutnya. Balas dengan pesan pengguna yang hanya berisi blok tool_result untuk alat klien dan pertahankan array tools yang sama; untuk alat server yang dipanggil Claude secara langsung, API menjalankannya pada permintaan tersebut dan respons berikutnya dimulai dengan blok hasilnya. Lihat Alasan berhenti dan fallback.

Perbedaan dari API lain

Tidak 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, sedangkan pesan assistant berisi konten yang dihasilkan AI dan tool_use.

Menangani kesalahan dengan is_error

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

Langkah selanjutnya

Penggunaan alat paralel

Tangani respons di mana Claude memanggil beberapa alat dalam satu giliran.

Tool Runner (SDK)

Biarkan SDK mengelola loop tool_use, pemformatan hasil, dan percobaan ulang untuk Anda.

Mendefinisikan alat

Tulis skema dan deskripsi yang mengarahkan Claude ke alat yang tepat.

Was this page helpful?

Menangani hasil dari alat klien

Respons akan memiliki stop_reason berupa 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 nantinya.

name: Nama alat yang sedang digunakan.

input: Objek yang berisi input yang diteruskan ke alat, sesuai dengan input_schema alat tersebut.

Ketika Anda menerima respons penggunaan alat untuk alat klien, Anda harus:

Mengekstrak name, id, dan input dari blok tool_use.

Menjalankan alat yang sebenarnya di basis kode Anda yang sesuai dengan nama alat tersebut, dengan meneruskan input alat.

Melanjutkan percakapan dengan mengirim pesan baru dengan role berupa user, dan blok content yang berisi tipe tool_result serta informasi berikut:

tool_use_id: id dari permintaan penggunaan alat yang hasilnya ini.
content (opsional): Hasil dari 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, document, atau search_result.
is_error (opsional): Atur ke true jika eksekusi alat menghasilkan kesalahan.

Persyaratan pemformatan penting:

Blok hasil alat harus langsung mengikuti blok penggunaan alat yang sesuai dalam riwayat pesan. Anda tidak dapat menyertakan pesan apa pun di antara pesan penggunaan alat dari asisten dan pesan hasil alat dari pengguna.
Dalam pesan pengguna yang berisi hasil alat, blok tool_result harus berada PERTAMA dalam array konten. Teks apa pun harus berada SETELAH semua hasil alat.
Jika giliran asisten juga memanggil alat server yang belum memiliki blok hasil, pesan pengguna harus hanya berisi blok tool_result. Teks setelah hasil akan mengakhiri giliran lebih awal; untuk alat server yang dipanggil Claude secara langsung, permintaan kemudian gagal dengan kesalahan 400 yang menyebutkan nama alat server yang belum terselesaikan. Lihat Alasan berhenti dan fallback.

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 ketika giliran asisten hanya memanggil alat klien:

{
  "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 apakah hasil alat Anda diformat dengan benar.

Setelah menerima hasil alat, Claude akan menggunakan informasi tersebut untuk melanjutkan menghasilkan respons terhadap prompt pengguna asli.

Menangani hasil dari alat server

Claude mengeksekusi alat secara internal dan memasukkan hasilnya langsung ke dalam responsnya tanpa memerlukan interaksi pengguna tambahan.

Perbedaan dari API lain

Menangani hasil dari alat klien

Contoh respons API dengan blok konten `tool_use`

Contoh hasil alat yang berhasil

Contoh hasil alat dengan gambar

Contoh hasil alat kosong

Contoh hasil alat dengan dokumen

Menangani hasil dari alat server

Menangani kesalahan dengan is_error

Kesalahan eksekusi alat

Nama alat tidak valid

Kesalahan alat server

Langkah selanjutnya

Menangani hasil dari alat klien

Contoh respons API dengan blok konten `tool_use`

Contoh hasil alat yang berhasil

Contoh hasil alat dengan gambar

Contoh hasil alat kosong

Contoh hasil alat dengan dokumen

Menangani hasil dari alat server

Menangani kesalahan dengan is_error

Kesalahan eksekusi alat

Nama alat tidak valid

Kesalahan alat server

Langkah selanjutnya

Menangani hasil dari alat klien

Menangani hasil dari alat server

Menangani kesalahan dengan is_error

Langkah selanjutnya

Menangani hasil dari alat klien

Menangani hasil dari alat server

Menangani kesalahan dengan is_error

Langkah selanjutnya