# Claude API Tool Use di Produksi: Panduan Dunia Nyata > Semua yang saya pelajari dari mengirimkan tool use Claude (function calling) di produksi — desain schema, penanganan error, streaming, dan manajemen biaya. URL: https://www.matthewswong.com/id/blog/claude-api-tool-use-production/ - Author: Matthews Wong (https://www.matthewswong.com/id/about/) - Published: 2025-06-10 - Updated: 2025-06-10 - Category: AI Saya telah menggunakan tool use Claude (yang disebut OpenAI sebagai function calling) di produksi untuk aplikasi fitness AI Gymbro selama beberapa bulan. Dokumentasi Anthropic bagus, tetapi ada kesenjangan antara contoh tutorial dan kekacauan produksi nyata. Posting ini mencakup apa yang saya harapkan seseorang memberitahu saya ketika saya mulai. ## Desain Schema Alat: Detail yang Penting Tool use Claude bekerja dengan memberikan model schema JSON yang mendeskripsikan alat yang tersedia. Kualitas deskripsi alat Anda adalah faktor terpenting dalam akurasi pemanggilan alat. Deskripsi yang tidak jelas seperti 'mencatat latihan' menyebabkan model menebak nilai argumen. ### Praktik Terbaik Schema Parameter Gunakan tipe enum sebisa mungkin untuk membatasi pilihan model. Jika field hanya bisa 'sets', 'reps', atau 'weight', definisikan sebagai enum. Tambahkan contoh di field deskripsi — model menggunakan contoh ini untuk mengoreksi diri saat tidak yakin dengan format yang benar. ### Parameter tool_choice API Claude mendukung parameter tool_choice yang memungkinkan Anda mengontrol apakah model harus menggunakan alat (tool_choice: 'any' atau menentukan nama alat) atau boleh menggunakan alat secara opsional. Menggunakan tool_choice: '{ type: ''tool'', name: ''log_workout'' }' memaksa model untuk selalu mengembalikan panggilan alat log_workout. > Untuk alur kerja multi-alat yang kompleks di API Claude, saya mendefinisikan alat 'done' yang dipanggil agent saat selesai. Alat ini mengambil parameter 'summary' yang mendeskripsikan apa yang telah dicapai. Pola ini memecahkan masalah 'bagaimana saya tahu kapan agent selesai' dengan bersih. ## Penanganan Error untuk Pemanggilan Alat Pemanggilan alat gagal karena dua alasan: model memanggil alat dengan argumen tidak valid (validasi schema Anda menangkap ini), atau eksekusi alat itu sendiri gagal. Kedua kasus memerlukan pengembalian hasil ke model dengan informasi error — ini dilakukan dengan mengembalikan tool_result dengan is_error: true. ### Streaming dengan Tool Use API streaming Claude mengirim peristiwa tool use saat dibuat, tetapi argumen pemanggilan alat tiba dalam fragmen. Membangun parser streaming untuk pemanggilan alat memerlukan buffering stream argumen dan hanya memicu eksekusi alat setelah peristiwa stop_reason: 'tool_use' tiba. > **Pemanggilan Alat Paralel Dapat Menyebabkan Race Condition** > Claude terkadang mengembalikan beberapa pemanggilan alat dalam satu respons. Jika implementasi alat Anda memiliki efek samping atau membaca dari state bersama, eksekusi paralel dapat menyebabkan race condition. Saya belajar hal ini dengan cara yang sulit ketika dua panggilan log_workout paralel membuat catatan latihan duplikat. ## Biaya Token dari Tool Use Definisi alat berkontribusi pada jumlah token input Anda. Alat tipikal dengan schema dan deskripsi rinci biaya 100-300 token per definisi alat. Saya mengimplementasikan pemilih alat yang sadar konteks yang mengurangi 60% overhead alat. ## Menguji Aplikasi yang Banyak Menggunakan Alat Menguji aplikasi LLM yang bergantung pada pemanggilan alat memerlukan pendekatan berbeda dari pengujian unit tradisional. Saya menggunakan strategi pengujian dua lapisan: mock test yang menstub LLM, dan integration test yang menggunakan panggilan LLM nyata terhadap set percakapan uji. ## Metrik Produksi Nyata dari AI Gymbro Setelah enam bulan tool use Claude di produksi: tingkat keberhasilan pemanggilan alat 94,2% pada percobaan pertama, 98,8% setelah satu retry. Rata-rata token per definisi alat: 180. Rata-rata pemanggilan alat per sesi pengguna: 4,3. Mode kegagalan paling umum: model memanggil alat dengan argumen yang secara semantik salah. ## Sumber & Bacaan Lanjutan - Anthropic — Dokumentasi Tool Use — https://docs.anthropic.com/en/docs/build-with-claude/tool-use - Anthropic — Contoh Tool Use — https://docs.anthropic.com/en/docs/build-with-claude/tool-use/tool-use-examples - Anthropic — Ikhtisar Streaming — https://docs.anthropic.com/en/docs/build-with-claude/streaming ## Source links - https://docs.anthropic.com/en/docs/build-with-claude/tool-use - https://docs.anthropic.com/en/docs/build-with-claude/tool-use/tool-use-examples - https://docs.anthropic.com/en/docs/build-with-claude/streaming ## FAQ ### Mengapa kualitas deskripsi alat sangat berpengaruh pada akurasi pemanggilan alat Claude? Claude mengandalkan deskripsi alat dan schema parameter untuk memutuskan kapan dan bagaimana memanggil alat. Deskripsi yang tidak jelas membuat model menebak nilai argumen sehingga menurunkan akurasi. Menambahkan tipe enum, batasan array, dan contoh konkret di field deskripsi membantu model mengoreksi diri sendiri dan meningkatkan tingkat keberhasilan pemanggilan alat secara signifikan. ### Apa itu pola alat 'done' dan mengapa berguna dalam alur kerja multi-alat? Alat 'done' adalah alat sentinel yang dipanggil agent saat selesai dengan tugas, mengambil parameter 'summary' yang mendeskripsikan apa yang telah dicapai. Pola ini memecahkan masalah 'bagaimana saya tahu kapan agent selesai' tanpa mengandalkan model mengembalikan respons teks bebas. Pola ini direkomendasikan khususnya untuk alur kerja multi-alat yang kompleks di API Claude. ### Bagaimana cara mengembalikan error dari eksekusi alat ke Claude? Baik error argumen tidak valid (tertangkap oleh validasi schema) maupun kegagalan eksekusi alat harus dikembalikan ke model sebagai pesan tool_result dengan is_error diset true. Ini memungkinkan Claude memahami apa yang salah dan mencoba pemanggilan alat yang diperbaiki atau memberikan respons yang berguna kepada pengguna. ### Apakah pemanggilan alat paralel bisa menimbulkan masalah, dan bagaimana cara menghindarinya? Ya — Claude terkadang mengembalikan beberapa pemanggilan alat dalam satu respons, dan eksekusi paralel bisa menyebabkan race condition saat alat berbagi state atau memiliki efek samping. Di AI Gymbro, dua panggilan log_workout paralel membuat catatan latihan duplikat karena keduanya membaca state yang sama sebelum salah satunya menulis. Solusinya adalah menegakkan eksekusi sekuensial atau mendesain alat agar idempoten. ### Berapa biaya token dari definisi alat, dan bagaimana cara mengurangi overhead tersebut? Setiap definisi alat dengan schema dan deskripsi rinci biayanya sekitar 100–300 token, yang bisa menjadi ribuan token overhead per request ketika banyak alat didefinisikan. Rata-rata token per definisi alat di AI Gymbro adalah 180 token. Mengimplementasikan pemilih alat yang sadar konteks yang hanya menyertakan alat relevan untuk setiap request berhasil mengurangi overhead ini sebesar 60%. --- - HTML version: https://www.matthewswong.com/id/blog/claude-api-tool-use-production/ - English: https://www.matthewswong.com/en/blog/claude-api-tool-use-production/ - Site index for agents: https://www.matthewswong.com/llms.txt - Sitemap: https://www.matthewswong.com/sitemap.xml - API description (OpenAPI): https://www.matthewswong.com/openapi.json