Tool Runner (SDK)

"Tool runner" (penjalan alat) menangani loop agentik, pembungkusan error, dan keamanan tipe sehingga Anda tidak perlu melakukannya sendiri. Ketika Anda membutuhkan persetujuan human-in-the-loop, logging kustom, atau eksekusi bersyarat, gunakan loop manual sebagai gantinya.

Alih-alih menangani panggilan alat, hasil alat, dan manajemen percakapan secara manual, tool runner secara otomatis:

• Menjalankan alat ketika Claude memanggilnya
• Menangani siklus permintaan/respons
• Mengelola state percakapan
• Menyediakan keamanan tipe dan validasi



Penggunaan dasar

Definisikan alat menggunakan helper SDK, lalu gunakan tool runner untuk menjalankannya.

Tergantung pada signature alat di SDK, sebuah alat mengembalikan hasilnya sebagai string atau sebagai blok konten (blok teks, gambar, atau dokumen), sehingga alat dapat mengembalikan hasil multimodal. String yang dikembalikan menjadi satu blok konten teks. Untuk mengembalikan data terstruktur, seperti objek JSON atau angka, encode terlebih dahulu sebagai string.



Melakukan iterasi pada tool runner

Tool runner adalah iterable yang menghasilkan pesan dari Claude. Pada setiap iterasi, runner memeriksa apakah Claude meminta penggunaan alat. Jika ya, runner menjalankan alat tersebut dan mengirimkan hasilnya kembali ke Claude secara otomatis, lalu menghasilkan pesan berikutnya dari Claude untuk melanjutkan loop Anda.

Anda dapat mengakhiri loop pada iterasi mana pun dengan pernyataan break. Runner melakukan loop hingga Claude mengembalikan pesan tanpa penggunaan alat, atau hingga mencapai max_iterations jika Anda menetapkannya.

Jika Anda tidak membutuhkan pesan perantara, Anda dapat langsung mendapatkan pesan akhir:



Penggunaan lanjutan

Di dalam loop, Anda dapat membaca setiap pesan respons dan memodifikasi state runner sebelum panggilan API berikutnya. Setiap iterasi mengikuti siklus hidup berikut:

1. Runner mengirim permintaan ke Messages API dengan state-nya saat ini.
2. Runner menghasilkan pesan respons ke body loop Anda.
3. Body loop Anda dijalankan. Anda dapat membaca pesan dan secara opsional memodifikasi state runner.
4. Ketika body loop Anda selesai, runner memeriksa apakah Anda memodifikasi riwayat pesannya.
   • Jika Anda tidak memodifikasi riwayat pesan: Runner menambahkan pesan asisten ke state-nya. Jika pesan berisi panggilan alat, runner menjalankannya dan menambahkan hasilnya. Jika tidak ada panggilan alat, loop keluar.
   • Jika Anda memodifikasi riwayat pesan: Runner melewati penambahan otomatisnya dan menggunakan state Anda tanpa perubahan. Lihat Mengambil alih riwayat pesan.



Mengambil alih riwayat pesan

Secara default, runner mengelola state percakapan untuk Anda: setelah setiap giliran, runner menambahkan pesan asisten dan hasil alat apa pun ke riwayat pesannya sendiri. Anda mengambil alih riwayat pesan ketika Anda ingin mencoba ulang sebuah giliran (membuang respons dan mengirim ulang), menyisipkan pesan tindak lanjut, atau membangun hasil alat sendiri.

Anda mengambil alih dengan memodifikasi pesan runner dari dalam body loop. Metode persisnya tergantung pada SDK. Lihat tab per bahasa berikut.

Ketika Anda mengambil alih untuk sebuah iterasi, runner tidak menambahkan pesan asisten atau hasil alat dari giliran tersebut. Anda bertanggung jawab untuk menjaga percakapan tetap valid: tambahkan sendiri pesan asisten dan hasil alat (jika Anda ingin giliran tersebut dihitung), modifikasi state secara kondisional agar loop tetap dapat keluar ketika tidak ada panggilan alat, dan berikan max_iterations untuk membatasi loop. Ketujuh SDK mendukung max_iterations.



Manajemen konteks otomatis

Untuk tugas agentik yang berjalan lama, tool runner Python, TypeScript, dan Ruby mendukung compaction (pemadatan) otomatis, yang menghasilkan ringkasan ketika penggunaan token melebihi ambang batas sehingga percakapan dapat berlanjut melampaui batas jendela konteks. Ketiga SDK tersebut telah menandai opsi sisi klien ini sebagai deprecated dan menggantinya dengan context editing sisi server, yang tersedia di setiap SDK. Tool runner Go, Java, C#, dan PHP tidak menyertakan compaction sisi klien.



Melakukan debug eksekusi alat

Ketika sebuah alat melempar exception, tool runner menangkapnya dan mengembalikan error ke Claude sebagai hasil alat dengan is_error: true. Hasil alat membawa pesan exception (di Python, tipe dan pesannya), bukan stack trace lengkap.

Apa yang dicatat SDK bersifat spesifik per bahasa. Python SDK mencatat exception lengkap, termasuk stack trace-nya, melalui modul logging standar setiap kali sebuah alat melempar exception yang tidak tertangani. Python, TypeScript, dan Java SDK membaca variabel lingkungan ANTHROPIC_LOG untuk mengaktifkan logging SDK, yang mencakup detail permintaan dan respons:

# Log pada level info
export ANTHROPIC_LOG=info

# Log pada level debug untuk output yang lebih detail
export ANTHROPIC_LOG=debug

Go, Ruby, C#, dan PHP SDK tidak membaca ANTHROPIC_LOG. Di luar Python, tidak ada SDK yang mencatat alat yang gagal: untuk melihat mengapa sebuah alat gagal, tangkap dan catat exception di dalam fungsi alat sebelum mengembalikan atau melemparnya kembali.



Mencegat error alat

Secara default, error alat diteruskan kembali ke Claude, yang kemudian dapat merespons dengan tepat. Namun, Anda mungkin ingin mendeteksi error dan menanganinya secara berbeda, misalnya, untuk menghentikan eksekusi lebih awal atau mengimplementasikan penanganan error kustom.

Di Python dan TypeScript SDK, gunakan metode respons alat (generate_tool_call_response() di Python, generateToolResponse() di TypeScript) untuk mencegat hasil alat dan memeriksa error sebelum dikirim ke Claude. SDK lainnya tidak mengekspos hook tersebut. Tab masing-masing menjelaskan alternatif terdekat:



Memodifikasi hasil alat

Anda dapat memodifikasi hasil alat sebelum dikirim kembali ke Claude. Ini berguna untuk menambahkan metadata seperti cache_control untuk mengaktifkan caching prompt pada hasil alat, atau untuk mentransformasi output alat.

Di Python dan TypeScript SDK, gunakan metode respons alat untuk mendapatkan hasil alat, lalu modifikasi sebelum runner melanjutkan. Apakah Anda secara eksplisit menambahkan hasil yang dimodifikasi atau memutasinya secara langsung tergantung pada SDK. Lihat komentar kode di setiap tab.



Streaming

Aktifkan streaming untuk memproses respons setiap giliran secara inkremental. Setiap iterasi menghasilkan objek stream yang dapat Anda iterasi untuk mendapatkan event.



Langkah selanjutnya