Halaman ini membahas siklus hidup panggilan alat: membaca blok tool_use dari respons Haijun, memformat blok tool_result dalam balasan Anda, dan memberi sinyal error. Untuk abstraksi SDK yang menangani hal ini secara otomatis, lihat Tool Runner.

Note: Lebih sederhana dengan Tool Runner: Penanganan alat manual yang dijelaskan di halaman ini dikelola secara otomatis oleh Tool Runner. Gunakan halaman ini ketika Anda memerlukan kontrol kustom atas eksekusi alat.

Respons Haijun berbeda tergantung pada apakah Haijun 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 Haijun, seperti screenshot atau navigate, jadi lakukan dispatch blok-blok tersebut berdasarkan kedua field.

#Contoh respons API dengan blok konten tool_use

  {
    "id": "msg_01Aq9w938a90dw8q",
    "model": "haijun-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.

1. Menjalankan alat yang sebenarnya di codebase Anda yang sesuai dengan nama alat tersebut, dengan meneruskan input alat.

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

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 di urutan PERTAMA dalam array content. Teks apa pun harus berada SETELAH semua hasil alat. * Jika giliran asisten juga memanggil alat server 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 Haijun secara langsung, permintaan kemudian gagal dengan error 400 yang menyebutkan alat server yang belum terselesaikan. Lihat Alasan berhenti dan fallback. 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.

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 Haijun ("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 untuk penguatan lebih lanjut.

#### Contoh hasil alat yang berhasil

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

#### Contoh hasil alat dengan gambar

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

#### Contoh hasil alat kosong

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

#### Contoh hasil alat dengan dokumen

    {
      "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, Haijun akan menggunakan informasi tersebut untuk melanjutkan menghasilkan respons terhadap prompt pengguna yang asli.

#Menangani hasil dari alat server

Haijun mengeksekusi alat secara internal dan menggabungkan hasilnya langsung ke dalam responsnya tanpa memerlukan interaksi pengguna tambahan.

Note: 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 Haijun secara langsung, API menjalankannya pada permintaan tersebut dan respons berikutnya dimulai dengan blok hasilnya. Lihat Alasan berhenti dan fallback.

Tip: Perbedaan dari API lain Tidak seperti API yang memisahkan penggunaan alat atau menggunakan role khusus seperti tool atau function, Haijun 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 Haijun:

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

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

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

> Tip: Tulis pesan error yang instruktif. Alih-alih error generik seperti "failed", sertakan apa yang salah dan apa yang harus dicoba Haijun selanjutnya (misalnya, "Rate limit exceeded. Retry after 60 seconds."). Ini memberi Haijun konteks yang dibutuhkannya untuk pulih atau beradaptasi tanpa menebak-nebak.

#### Nama alat tidak valid

Jika upaya Haijun menggunakan alat tidak valid (misalnya, parameter wajib tidak ada), biasanya itu berarti tidak ada cukup informasi bagi Haijun 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 Haijun akan mencoba menggunakan alat lagi dengan informasi yang hilang telah diisi:

    {
      "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, Haijun akan mencoba ulang 2-3 kali dengan koreksi sebelum meminta maaf kepada pengguna.

> Tip: Untuk menghilangkan panggilan alat yang tidak valid sepenuhnya, gunakan penggunaan alat ketat 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.

#### Error alat server

Ketika alat server mengalami error (misalnya, masalah jaringan dengan Web Search), Haijun 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 Haijun 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 Haijun ke alat yang tepat.