# Mengapa Tool Call Gagal Setelah Coding Agent Beralih ke Model Lain? > Tool call biasanya gagal setelah pergantian model karena model pengganti mengubah protokol, ekspektasi skema, serialisasi argumen, event streaming, atau perilaku state percakapan. Perlakukan migrasi sebagai perubahan kontrak, bukan sekadar perubahan nama model. Tes pertama yang berguna lebih kecil daripada benchmark coding: minta model pengganti memanggil satu fungsi read-only dengan dua argumen wajib. Jika gagal, masalah berada di bawah lapisan perencanaan. Jika berhasil, tambahkan streaming, beberapa tool, state, dan aksi tulis satu per satu sampai batas kontrak pertama terlihat. Pergantian model membongkar asumsi yang tersembunyi dalam integrasi lama. Coding agent bukan hanya prompt dan model. Ia adalah state machine yang menghubungkan output model, parser stream, registry tool, executor, dan loop yang mengembalikan hasil tool. ## Pisahkan kemampuan dari protokol Sebuah model bisa sangat baik dalam coding tetapi tidak tersedia melalui protokol yang dikirim klien. Model lain mungkin menerima request namun tidak menawarkan tool pada route tersebut. Periksa metadata kemampuan sebelum mengganti nama model. [Panduan protokol LLM Atlas Cloud](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=why-tool-calls-fail-after-switching-coding-agent-models) mencakup OpenAI Chat Completions, Responses, Anthropic Messages, Google Gemini, dan format lain pada satu base URL. Tidak semua model mendukung semua protokol. Gunakan `supported_apis` dan kemampuan tool tiap model sebagai sumber kebenaran. | Lapisan | Pertanyaan migrasi | Sinyal kegagalan | |---|---|---| | Endpoint | Apakah model menerima protokol ini? | Respons 400 atau field diabaikan | | Kemampuan | Apakah route menawarkan tool? | Jawaban teks, bukan panggilan | | Skema | Apakah nama dan JSON Schema valid? | Argumen hilang atau rusak | | Stream | Apakah delta argumen dirakit benar? | JSON terpotong | | Loop | Apakah hasil tool dikembalikan dengan role yang benar? | Panggilan berulang atau turn macet | ## Sederhanakan skema tool menjadi satu kontrak Mulailah dengan fungsi bernama pendek, dua string wajib, tanpa union, dan tanpa nested optional. Skema rumit mencampurkan perilaku model dengan validator sehingga diagnosis melambat. ```json { "type": "function", "function": { "name": "read_file", "description": "Read a UTF-8 text file from the workspace.", "parameters": { "type": "object", "properties": { "path": {"type": "string"}, "max_chars": {"type": "integer", "minimum": 1} }, "required": ["path", "max_chars"], "additionalProperties": false } } } ``` Paksa fungsi ini jika protokol mendukung forced tool choice. Panggilan paksa membedakan ketidakmampuan memanggil tool dari keputusan perencanaan untuk tidak memanggilnya. ## Uji tanpa streaming terlebih dahulu Respons non-streaming menampilkan objek tool final dalam satu payload. Streaming dapat mengirim nama, ID panggilan, dan argumen JSON melalui event terpisah. Parse argumen hanya setelah event final atau done milik protokol. Jangan menjalankan tool hanya karena buffer parsial kebetulan valid sebagai JSON. Delta berikutnya masih dapat memperpanjangnya. Simpan buffer berdasarkan ID panggilan, tolak finalisasi ganda, dan rekam urutan event mentah. | Invarian stream | Perilaku wajib | |---|---| | Identitas panggilan stabil | Semua delta masuk ke satu buffer | | Perakitan berurutan | Fragmen ditambahkan sesuai urutan event | | Penyelesaian eksplisit | Eksekusi menunggu event final | | Eksekusi tunggal | Panggilan selesai dijalankan maksimal sekali | ## Normalisasikan loop agent secara eksplisit Jangan sebarkan field khusus provider ke executor. Konversikan setiap respons ke bentuk internal seperti `assistant_text`, `tool_calls`, `usage`, dan `stop_reason`, lalu konversikan hasil tool kembali melalui adapter protokol. Perlakukan call ID sebagai nilai opaque dan pertahankan persis ketika protokol memerlukannya. Validasi argumen sebelum eksekusi dan kembalikan error terstruktur, bukan diam-diam memperbaiki JSON yang salah. ## Reset state pada perbandingan pertama Item percakapan lama dapat memuat reasoning block, role hasil tool, state handle, atau pesan assistant yang tidak diterima route baru. Mulailah dengan percakapan baru dan instruksi sistem yang sama, lalu replay riwayat pendek yang sudah dinormalisasi. Shortcut state bersifat khusus protokol. Uji persistensi instruksi secara eksplisit, jangan menganggap handle respons sebelumnya membawanya. ## Bangun tangga migrasi Jalankan fixture yang sama dalam urutan berikut: * Respons teks biasa. * Satu tool read-only paksa tanpa streaming. * Satu automatic tool choice tanpa streaming. * Satu tool paksa dengan streaming. * Dua tool independen. * Satu error tool dan pemulihan. * Tugas coding multi-turn pendek. Berhenti pada kegagalan pertama dan periksa data wire. Jangan melompat dari health check ke pengeditan repository otonom. ## Tentukan apakah satu adapter cukup Adapter bersama berguna bila perbedaannya hanya nama field atau event. Adapter terpisah lebih aman bila model memerlukan protokol, representasi riwayat, atau semantik hasil tool yang berbeda. Atlas Cloud memudahkan eksperimen model karena satu key dan base URL membuka beberapa format serta [katalog model LLM](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=why-tool-calls-fail-after-switching-coding-agent-models) yang terus berubah. Namun kemudahan itu tidak menggantikan pemeriksaan kemampuan. Catat model, protokol, versi skema, mode streaming, dan hasil pengujian bersama-sama. ## Kesimpulan Tool call gagal setelah pergantian model ketika integrasi memperlakukan migrasi perilaku dan protokol sebagai penggantian string. Verifikasi route, sederhanakan skema, loloskan tes forced call non-streaming, validasi perakitan stream, lalu tambahkan state percakapan terakhir. Jika dua model memerlukan semantik pesan atau event berbeda, gunakan adapter terpisah. ## FAQ ### Mengapa model baru menjawab dengan teks alih-alih memanggil tool? Model mungkin tidak mendukung tool pada protokol yang dipilih, membutuhkan pengaturan tool choice lain, atau menafsirkan deskripsi tool secara berbeda. Verifikasi metadata kemampuan dan uji satu panggilan paksa. ### Bisakah dua model yang kompatibel dengan OpenAI mengembalikan bentuk tool call berbeda? Ya. Format request luar dapat kompatibel, tetapi delta streaming, ID panggilan, penyelesaian argumen, dan finish reason masih dapat berbeda. ### Haruskah percakapan lama digunakan kembali setelah mengganti model? Hanya setelah memastikan model dan protokol baru menerima item riwayat yang sama. Pengujian lebih aman dimulai dari percakapan baru lalu menambahkan state secara bertahap. ### Apa tes diagnostik tercepat? Paksa satu tool read-only deterministik dengan skema JSON kecil, jalankan tanpa streaming, lalu catat request dan response mentah sebelum menguji loop agent lengkap. ### Apakah Atlas Cloud menormalkan semua model menjadi satu antarmuka tool yang identik? Tidak. Atlas Cloud mendukung beberapa protokol dan setiap model menerbitkan API serta kemampuan yang didukung. Klien harus memilih protokol yang benar-benar didukung model. ### Kapan dua model perlu adapter terpisah? Pertahankan adapter terpisah bila objek state, event streaming, pesan hasil tool, atau semantik error tidak dapat diwakili dengan aman oleh satu kontrak normalisasi.