---
title: Menangani panggilan alat
url: https://platform.claude.com/docs/id/agents-and-tools/tool-use/handle-tool-calls
description: Mengurai blok tool_use, memformat respons tool_result, dan menangani error 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 error. Untuk abstraksi SDK yang menangani hal ini secara otomatis, lihat [Tool Runner](https://platform.claude.com/docs/id/agents-and-tools/tool-use/tool-runner).
**Lebih sederhana dengan Tool Runner:** Penanganan alat manual yang dijelaskan di halaman ini dikelola secara otomatis oleh [Tool Runner](https://platform.claude.com/docs/id/agents-and-tools/tool-use/tool-runner). Gunakan halaman ini ketika Anda memerlukan kontrol kustom atas eksekusi alat.
Respons Claude berbeda tergantung pada apakah Claude menggunakan [alat klien atau alat server](https://platform.claude.com/docs/id/agents-and-tools/tool-use/overview#how-tool-use-works).
## 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.
Blok `tool_use` untuk anggota dari toolset [computer use](https://platform.claude.com/docs/id/agents-and-tools/tool-use/computer-use-tool) atau [browser use](https://platform.claude.com/docs/id/agents-and-tools/tool-use/browser-use-tool) 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.
```json JSON
{
"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, Anda harus:
1. Mengekstrak `name`, `id`, dan `input` dari blok `tool_use`.
2. Menjalankan alat yang sebenarnya di codebase Anda yang sesuai dengan nama alat tersebut, dengan meneruskan `input` alat.
3. 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 tujuan 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`](https://platform.claude.com/docs/id/build-with-claude/search-results).
* `is_error` (opsional): Atur ke `true` jika eksekusi alat menghasilkan error.
`tool_result` yang menjawab blok anggota computer use atau browser use 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 browser use dapat menambahkan satu blok [`browser_state`](https://platform.claude.com/docs/id/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) ([anggota manajemen tab](https://platform.claude.com/docs/id/agents-and-tools/tool-use/browser-use-tool#tab-management-results) hanya mengembalikan blok tersebut).
**Persyaratan pemformatan penting:**
* Blok hasil alat harus langsung mengikuti blok penggunaan alat yang bersesuaian 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 di urutan PERTAMA dalam array content. Teks apa pun harus berada SETELAH semua hasil alat.
* Jika giliran asisten juga memanggil [alat server](https://platform.claude.com/docs/id/agents-and-tools/tool-use/server-tools) 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 error 400 yang menyebutkan alat server yang belum terselesaikan. Lihat [Alasan berhenti dan fallback](https://platform.claude.com/docs/id/build-with-claude/handling-stop-reasons#tool-use).
Misalnya, ini akan menyebabkan error 400:
```json
{
"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:
```json
{
"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 error seperti "tool\_use ids were found without tool\_result blocks immediately after", periksa apakah hasil alat Anda diformat dengan benar.
Hasil alat sering 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 menyisipkan instruksi yang mencoba mengalihkan Claude ("indirect prompt injection" atau injeksi prompt tidak langsung). Simpan konten tidak tepercaya di dalam blok `tool_result` alih-alih prompt `system` atau blok `text` pengguna biasa, dan lihat [Memitigasi jailbreak dan injeksi prompt](https://platform.claude.com/docs/id/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) untuk penguatan lebih lanjut.
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}
```
```json JSON
{
"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..."
}
}
]
}
]
}
```
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}
```
```json JSON
{
"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"
}
}
]
}
]
}
```
Setelah menerima hasil alat, Claude akan menggunakan informasi tersebut untuk melanjutkan menghasilkan respons terhadap prompt pengguna yang asli.
## Menangani hasil dari alat server
Claude mengeksekusi alat secara internal dan menggabungkan hasilnya langsung ke dalam responsnya tanpa memerlukan interaksi pengguna tambahan.
Sebuah respons dapat berisi blok `tool_use` klien dan blok `server_tool_use` yang tidak 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](https://platform.claude.com/docs/id/build-with-claude/handling-stop-reasons#tool-use).
**Perbedaan dari API lain**
Tidak seperti API yang memisahkan penggunaan alat atau menggunakan role khusus seperti `tool` atau `function`, Claude API 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 error dengan is\_error
Ada beberapa jenis error berbeda yang dapat terjadi saat menggunakan alat dengan Claude:
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`:
```json JSON
{
"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 akan menggabungkan error ini ke dalam responsnya kepada pengguna. Misalnya: "Maaf, saya tidak dapat mengambil cuaca saat ini karena API layanan cuaca tidak tersedia. Silakan coba lagi nanti."
Tulis pesan error yang instruktif. Alih-alih error generik seperti `"failed"`, sertakan apa yang salah dan apa yang harus dicoba Claude selanjutnya (misalnya, `"Rate limit exceeded. Retry after 60 seconds."`). Ini memberi Claude konteks yang dibutuhkannya untuk pulih atau beradaptasi tanpa menebak-nebak.
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. Pilihan terbaik Anda selama pengembangan adalah mencoba permintaan lagi dengan nilai `description` yang lebih detail dalam definisi alat Anda.
Namun, Anda juga dapat melanjutkan percakapan dengan `tool_result` yang menunjukkan error tersebut, dan Claude akan mencoba menggunakan alat lagi dengan informasi yang hilang telah diisi:
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}
```
Jika permintaan alat tidak valid atau parameternya tidak ada, Claude akan mencoba ulang 2-3 kali dengan koreksi sebelum meminta maaf kepada pengguna.
Untuk menghilangkan panggilan alat yang tidak valid sepenuhnya, gunakan [penggunaan alat ketat](https://platform.claude.com/docs/id/agents-and-tools/tool-use/strict-tool-use) dengan `strict: true` pada definisi alat Anda. Ini menjamin bahwa input alat akan selalu cocok dengan skema Anda secara tepat, mencegah parameter yang hilang dan ketidakcocokan tipe.
Ketika alat server mengalami error (misalnya, masalah jaringan dengan Web Search), Claude akan menangani error ini secara transparan dan berupaya memberikan respons alternatif atau penjelasan kepada pengguna. Tidak seperti alat klien, Anda tidak perlu menangani hasil `is_error` untuk alat server.
Khusus untuk pencarian web, kode error yang mungkin muncul meliputi:
* `too_many_requests`: Batas laju terlampaui
* `invalid_input`: Parameter kueri pencarian tidak valid
* `max_uses_exceeded`: Jumlah maksimum penggunaan alat pencarian web terlampaui
* `query_too_long`: Kueri melebihi panjang maksimum
* `unavailable`: Terjadi error internal
## 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.