Tool Runner (SDK)

Tool Runner menangani loop agentic, pembungkus error, dan keamanan tipe sehingga Anda tidak perlu melakukannya. Gunakan loop manual hanya ketika Anda memerlukan persetujuan manusia-dalam-loop, logging khusus, atau eksekusi bersyarat. Tersedia di Python, TypeScript, dan Ruby SDKs.

Tool runner menyediakan solusi siap pakai untuk menjalankan tools dengan Claude. Alih-alih menangani tool calls, hasil tool, dan manajemen percakapan secara manual, tool runner secara otomatis:

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

Gunakan tool runner untuk sebagian besar implementasi tool use.

Penggunaan dasar

Tentukan tools menggunakan helper SDK, kemudian gunakan tool runner untuk menjalankannya.

Fungsi tool harus mengembalikan blok konten atau array blok konten, termasuk teks, gambar, atau blok dokumen. Ini memungkinkan tools untuk mengembalikan respons kaya dan multimodal. String yang dikembalikan akan dikonversi ke blok konten teks. Jika Anda ingin mengembalikan objek JSON terstruktur ke Claude, enkode ke string JSON sebelum mengembalikannya. Angka, boolean, atau primitif non-string lainnya juga harus dikonversi ke string.

Iterasi di atas tool runner

Tool runner adalah iterable yang menghasilkan pesan dari Claude. Ini sering disebut sebagai "tool call loop". Setiap iterasi, runner memeriksa apakah Claude meminta penggunaan tool. Jika ya, ia memanggil tool dan mengirim hasilnya kembali ke Claude secara otomatis, kemudian menghasilkan pesan berikutnya dari Claude untuk melanjutkan loop Anda.

Anda dapat mengakhiri loop di iterasi mana pun dengan pernyataan break. Runner akan loop sampai Claude mengembalikan pesan tanpa penggunaan tool.

Jika Anda tidak memerlukan pesan perantara, Anda dapat mendapatkan pesan final secara langsung:

Penggunaan lanjutan

Dalam loop, Anda dapat sepenuhnya menyesuaikan permintaan berikutnya tool runner ke Messages API. Runner secara otomatis menambahkan hasil tool ke riwayat pesan, jadi Anda tidak perlu mengelolanya secara manual. Anda dapat secara opsional memeriksa hasil tool untuk logging atau debugging, dan memodifikasi parameter permintaan sebelum panggilan API berikutnya.

Debugging eksekusi tool

Ketika tool melempar pengecualian, tool runner menangkapnya dan mengembalikan error ke Claude sebagai hasil tool dengan is_error: true. Secara default, hanya pesan pengecualian yang disertakan, bukan stack trace lengkap.

Untuk melihat stack trace lengkap dan informasi debug, atur variabel lingkungan ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Ketika diaktifkan, SDK mencatat detail pengecualian lengkap (menggunakan modul logging Python, konsol di TypeScript, atau logger Ruby), termasuk stack trace lengkap ketika tool gagal.

Mengintersepsi error tool

Secara default, error tool 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 menerapkan penanganan error khusus.

Gunakan metode respons tool untuk mengintersepsi hasil tool dan memeriksa error sebelum dikirim ke Claude:

Memodifikasi hasil tool

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

Gunakan metode respons tool untuk mendapatkan hasil tool, kemudian modifikasi sebelum runner melanjutkan. Apakah Anda secara eksplisit menambahkan hasil yang dimodifikasi atau memutasinya di tempat tergantung pada SDK; lihat komentar kode di setiap tab.

Streaming

Aktifkan streaming untuk menerima event saat tiba. Setiap iterasi menghasilkan objek stream yang dapat Anda iterasi untuk event.

Langkah berikutnya

• Untuk kontrol manual atas loop tool-call, lihat Handle tool calls.
• Untuk menjalankan multiple tools secara bersamaan, lihat Parallel tool use.
• Untuk workflow tool-use lengkap, lihat Define tools.