---
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.
---

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](https://platform.claude.com/docs/id/agents-and-tools/tool-use/tool-runner) SDK, yang menjalankan alat dan mengirimkan hasilnya untuk Anda.

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 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](https://platform.claude.com/docs/id/agents-and-tools/tool-use/computer-use-tool) atau [penggunaan browser](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.

<Accordion title="Contoh respons API dengan blok konten `tool_use`">
  ```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" }
      }
    ]
  }
  ```
</Accordion>

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](https://platform.claude.com/docs/id/build-with-claude/handling-stop-reasons#quick-reference).

Untuk langkah-langkah ini sebagai program lengkap, lihat [Tutorial: Membangun agen yang menggunakan alat](https://platform.claude.com/docs/id/agents-and-tools/tool-use/build-a-tool-using-agent).

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`](https://platform.claude.com/docs/id/build-with-claude/search-results).
* `is_error` (opsional): Atur ke `true` jika alat gagal atau panggilan tidak valid.

Misalnya, hasil alat yang berhasil terlihat seperti ini:

```json 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`](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).

<Note>
  **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 PERTAMA dalam array konten. 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).

  Jika Anda menerima kesalahan seperti “tool\_use ids were found without tool\_result blocks immediately after”, periksa apakah hasil alat Anda diformat dengan benar.
</Note>

<Warning>
  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 (injeksi prompt tidak langsung). Simpan konten tidak tepercaya di dalam blok `tool_result` alih-alih prompt `system` atau blok `text` pengguna biasa, dan lihat [Mitigasi jailbreak dan injeksi prompt](https://platform.claude.com/docs/id/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) untuk pengamanan lebih lanjut.
</Warning>

<AccordionGroup>
  <Accordion title="Contoh hasil alat dengan gambar">
    ```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..."
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Contoh hasil alat kosong">
    ```json JSON
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Contoh hasil alat dengan dokumen">
    ```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"
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Contoh teks sebelum dan sesudah hasil alat">
    Misalnya, ini menyebabkan kesalahan 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
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Menangani hasil dari alat server

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

<Note>
  Sebuah respons dapat berisi blok `tool_use` klien sekaligus blok `server_tool_use` yang belum memiliki blok hasil. Panggilan alat server tersebut belum selesai, dan blok hasilnya akan 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 langsung oleh Claude, 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).
</Note>

<Tip>
  **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`.
</Tip>

## 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.

<AccordionGroup>
  <Accordion title="Error eksekusi alat">
    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 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.”

    <Tip>
      Tulis pesan kesalahan yang instruktif. Alih-alih kesalahan 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 dibutuhkan untuk pulih atau beradaptasi tanpa menebak.
    </Tip>
  </Accordion>

  <Accordion title="Panggilan alat tidak valid">
    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:

    ```json JSON
    {
      "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.

    <Tip>
      Untuk menghilangkan panggilan alat yang tidak valid sepenuhnya, gunakan [penggunaan alat strict](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 selalu sama persis dengan skema Anda, mencegah parameter yang hilang dan ketidakcocokan tipe.
    </Tip>
  </Accordion>

  <Accordion title="Error alat server">
    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](https://platform.claude.com/docs/id/agents-and-tools/tool-use/web-search-tool#errors).
  </Accordion>
</AccordionGroup>

## Langkah selanjutnya

<CardGroup cols={3}>
  <Card title="Penggunaan alat paralel" icon="grid" href="https://platform.claude.com/docs/id/agents-and-tools/tool-use/parallel-tool-use">
    Tangani respons di mana Claude memanggil beberapa alat dalam satu giliran.
  </Card>

  <Card title="Tool runner (SDK)" icon="wrench" href="https://platform.claude.com/docs/id/agents-and-tools/tool-use/tool-runner">
    Biarkan SDK mengelola loop `tool_use`, pemformatan hasil, dan percobaan ulang untuk Anda.
  </Card>

  <Card title="Mendefinisikan alat" icon="hammer" href="https://platform.claude.com/docs/id/agents-and-tools/tool-use/define-tools">
    Tulis skema dan deskripsi yang mengarahkan Claude ke alat yang tepat.
  </Card>
</CardGroup>
