Claude Platform Docs
PesanAlat

Menangani panggilan alat

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

Ketika respons Claude berisi blok tool_use, kode Anda menjalankan setiap alat dan mengirim kembali blok tool_result, termasuk error apa pun. Tulis kode ini sendiri ketika Anda memerlukan kontrol kustom atas eksekusi alat. Jika tidak, gunakan tool runner SDK, yang menjalankan alat dan mengirimkan hasilnya untuk Anda.

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

Menangani hasil dari alat klien

Respons memiliki stop_reason bernilai tool_use dan satu atau lebih blok konten tool_use yang mencakup:

  • id: Pengidentifikasi unik untuk blok penggunaan alat ini. Ini 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.

Blok tool_use untuk anggota dari toolset penggunaan komputer atau penggunaan browser juga membawa field toolset_name ("computer" atau "browser"). name-nya adalah alat anggota yang dipanggil Claude, seperti screenshot atau navigate, jadi lakukan dispatch blok-blok tersebut berdasarkan kedua field.

Ketika Anda menerima respons penggunaan alat untuk alat klien, ikuti langkah-langkah berikut:

  1. Untuk setiap blok tool_use, jalankan alat yang disebutkan oleh blok tersebut, dengan meneruskan input-nya.
  2. Dalam permintaan baru, pertahankan pesan-pesan sebelumnya dan tambahkan content dari respons tanpa diubah sebagai pesan assistant.
  3. Tambahkan pesan user dengan satu blok tool_result untuk setiap blok tool_use dalam konten tersebut, bahkan jika alat gagal.
  4. Kirim permintaan dengan tools yang sama seperti permintaan pertama. Claude menggunakan hasil alat untuk melanjutkan responsnya.
  5. Jika stop_reason pada respons berikutnya juga tool_use, ulangi langkah-langkah ini. Untuk nilai lainnya, lihat referensi cepat alasan berhenti.

Untuk langkah-langkah ini sebagai program lengkap, lihat Tutorial: Membangun agen yang menggunakan alat.

Setiap blok tool_result memiliki type yang diatur ke tool_result, ditambah field-field berikut:

  • tool_use_id: id dari blok tool_use yang dijawab oleh hasil ini.
  • content (opsional): Hasil dari alat sebagai string atau daftar blok konten. Blok konten ini dapat menggunakan tipe text, image, document, atau search_result.
  • is_error (opsional): Atur ke true jika alat gagal atau panggilan tidak valid.

Misalnya, hasil alat yang berhasil terlihat seperti ini:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

tool_result yang menjawab blok anggota penggunaan komputer atau penggunaan browser juga harus menggemakan nilai toolset_name yang sama dengan blok tool_use; hasil anggota yang menghilangkannya akan ditolak. content-nya juga lebih sempit: hasil anggota hanya boleh berisi blok text dan image, dan hasil penggunaan browser dapat menambahkan satu blok browser_state (anggota manajemen tab hanya mengembalikan blok tersebut).

Menangani hasil dari alat server

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

Menangani error dengan is_error

Ketika alat klien gagal atau panggilan tidak valid, kirim blok tool_result dengan is_error diatur ke true. Claude kemudian mungkin memanggil alat lagi dengan blok tool_use baru, jadi batasi berapa banyak percobaan ulang yang diizinkan oleh loop Anda.

Langkah selanjutnya

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

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

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

Apakah halaman ini membantu?