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 ini secara otomatis, lihat Tool Runner.

Respons Claude berbeda tergantung pada apakah ia menggunakan alat klien atau alat 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 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 dalam 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 menjadi hasil 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 assistant dan pesan hasil alat dari user.
Dalam pesan user yang berisi hasil alat, blok tool_result harus berada PERTAMA dalam array content. Teks apa pun harus berada SETELAH semua hasil alat.
Jika giliran assistant juga memanggil alat server yang belum memiliki blok hasil, pesan user hanya boleh berisi blok tool_result. Teks setelah hasil mengakhiri giliran lebih awal; untuk alat server yang dipanggil Claude secara langsung, permintaan kemudian gagal dengan kesalahan 400 yang menyebutkan alat server yang belum terselesaikan. Lihat Stop reason 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 assistant 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 user asli.

Menangani hasil dari alat server

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

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.

Definisikan alat

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

Was this page helpful?

MessagesAlat

Menangani panggilan alat

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

Respons Claude berbeda tergantung pada apakah ia menggunakan alat klien atau alat 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 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 dalam 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 menjadi hasil 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 assistant dan pesan hasil alat dari user.
Dalam pesan user yang berisi hasil alat, blok tool_result harus berada PERTAMA dalam array content. Teks apa pun harus berada SETELAH semua hasil alat.
Jika giliran assistant juga memanggil alat server yang belum memiliki blok hasil, pesan user hanya boleh berisi blok tool_result. Teks setelah hasil mengakhiri giliran lebih awal; untuk alat server yang dipanggil Claude secara langsung, permintaan kemudian gagal dengan kesalahan 400 yang menyebutkan alat server yang belum terselesaikan. Lihat Stop reason 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 assistant 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 user asli.

Menangani hasil dari alat server

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

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.

Definisikan alat

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

Was this page helpful?

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