Menangani panggilan alat

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.

Respons Claude berbeda tergantung pada apakah Claude 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.

Blok tool_use untuk anggota dari toolset computer use atau browser use 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, 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.
   • 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 (anggota manajemen tab hanya mengembalikan blok tersebut).

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

{
  "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"
          }
        }
      ]
    }
  ]
}

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.

Menangani error dengan is_error

Ada beberapa jenis error berbeda yang dapat terjadi saat menggunakan alat dengan Claude:

{
  "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
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

Langkah selanjutnya