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 denganinput_schemaalat 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.
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll check the current weather in San Francisco for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA", "unit": "celsius" }
}
]
}Ketika Anda menerima respons penggunaan alat untuk alat klien, ikuti langkah-langkah berikut:
- Untuk setiap blok
tool_use, jalankan alat yang disebutkan oleh blok tersebut, dengan meneruskaninput-nya. - Dalam permintaan baru, pertahankan pesan-pesan sebelumnya dan tambahkan
contentdari respons tanpa diubah sebagai pesanassistant. - Tambahkan pesan
userdengan satu bloktool_resultuntuk setiap bloktool_usedalam konten tersebut, bahkan jika alat gagal. - Kirim permintaan dengan
toolsyang sama seperti permintaan pertama. Claude menggunakan hasil alat untuk melanjutkan responsnya. - Jika
stop_reasonpada respons berikutnya jugatool_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:iddari bloktool_useyang dijawab oleh hasil ini.content(opsional): Hasil dari alat sebagai string atau daftar blok konten. Blok konten ini dapat menggunakan tipetext,image,document, atausearch_result.is_error(opsional): Atur ketruejika alat gagal atau panggilan tidak valid.
Misalnya, hasil alat yang berhasil terlihat seperti ini:
{
"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).
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "15 degrees" },
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "The weather is" },
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "15 degrees"
}
}
]
}
]
}Misalnya, ini 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
]
}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.
Jika alat itu sendiri melempar error selama eksekusi (misalnya, error jaringan saat mengambil data cuaca), Anda dapat mengembalikan pesan error dalam content bersama dengan "is_error": true:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}Claude kemudian dapat memanggil alat lagi atau memberi tahu pengguna apa yang terjadi. Misalnya, Claude mungkin mengatakan “Maaf, saya tidak dapat mengambil cuaca saat ini karena API layanan cuaca tidak tersedia. Silakan coba lagi nanti.”
Jika upaya Claude menggunakan alat tidak valid (misalnya, parameter wajib tidak ada), biasanya itu berarti tidak ada cukup informasi bagi Claude untuk menggunakan alat dengan benar. Pendekatan terbaik selama pengembangan adalah mencoba permintaan lagi dengan nilai description yang lebih rinci dalam definisi alat Anda.
Namun, Anda juga dapat melanjutkan percakapan dengan tool_result yang menunjukkan kesalahan:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}Claude kemudian dapat memanggil alat lagi dengan informasi yang hilang telah diisi.
Tidak seperti alat klien, Anda tidak mengirim hasil is_error untuk alat server. Ketika alat server mengalami error, seperti masalah jaringan selama pencarian web, API mengembalikan error tersebut di dalam blok hasil alat. Dalam sebagian besar kasus, Claude kemudian melanjutkan dengan pendekatan lain atau penjelasan untuk pengguna.
Untuk kode error pencarian web, lihat Error alat pencarian web.
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?