# Perché le chiamate agli strumenti falliscono dopo aver cambiato il modello di un coding agent? > Le chiamate agli strumenti spesso falliscono dopo un cambio di modello perché cambiano protocollo, aspettative dello schema, serializzazione degli argomenti, eventi di streaming o gestione dello stato. Tratta la migrazione come un cambio di contratto, non come la sostituzione di un nome. Il primo test utile è più piccolo di un benchmark di programmazione: chiedi al modello sostitutivo di chiamare una funzione in sola lettura con due argomenti obbligatori. Se fallisce, il problema è sotto il livello di pianificazione. Se riesce, aggiungi streaming, più strumenti, stato e scritture uno alla volta fino alla prima rottura del contratto. Il cambio di modello espone ipotesi nascoste nell’integrazione precedente. Un coding agent non è solo prompt e modello: è una macchina a stati che collega output, parser del flusso, registro degli strumenti, esecutore e loop che restituisce i risultati. Ogni confine può diventare incompatibile anche se il testo normale sembra corretto. ## Separa capacità e protocollo Un modello può essere ottimo nel codice ma non disponibile tramite il protocollo usato dal client. Un altro può accettare la richiesta senza offrire strumenti su quella rotta. Controlla i metadati delle capacità prima di cambiare il nome del modello. La [guida ai protocolli LLM di 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) elenca OpenAI Chat Completions, Responses, Anthropic Messages, Google Gemini e altri formati su un unico URL di base. Non tutti i modelli parlano tutti i protocolli. Usa `supported_apis` e la capacità strumenti come fonte autorevole. | Livello | Domanda di migrazione | Segnale di errore | |---|---|---| | Endpoint | Il modello accetta questo protocollo? | Risposta 400 o campi ignorati | | Capacità | La rotta dichiara il supporto agli strumenti? | Testo invece di chiamata | | Schema | Nomi e JSON Schema sono validi? | Argomenti mancanti o errati | | Stream | I delta sono ricomposti correttamente? | JSON troncato | | Loop | I risultati tornano con il ruolo previsto? | Chiamata ripetuta o turno bloccato | ## Riduci lo schema a un solo contratto Inizia con un nome breve, due stringhe obbligatorie, senza union né annidamenti opzionali. Gli schemi complessi mescolano il comportamento del modello a quello del validatore e rallentano la diagnosi. ```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 } } } ``` Forza questa funzione se il protocollo lo consente. Così distingui l’incapacità di chiamare da una scelta di pianificazione. ## Prova senza streaming prima di abilitarlo Senza streaming, l’oggetto finale arriva in un solo payload. Con lo streaming, nome, ID e argomenti JSON possono arrivare separatamente. Analizza gli argomenti solo dopo l’evento final o done previsto dal protocollo. Non eseguire perché un buffer parziale è già JSON valido: un delta successivo può estenderlo. Conserva i buffer per ID, rifiuta una seconda finalizzazione e registra la sequenza grezza. | Invariante del flusso | Comportamento richiesto | |---|---| | Identità stabile | Tutti i delta vanno nello stesso buffer | | Assemblaggio ordinato | I frammenti vengono aggiunti in ordine | | Completamento esplicito | L’esecuzione attende l’evento finale | | Esecuzione singola | Una chiamata completa viene eseguita al massimo una volta | ## Normalizza esplicitamente il loop Non distribuire campi specifici del provider nell’esecutore. Converti ogni risposta in una forma interna come `assistant_text`, `tool_calls`, `usage` e `stop_reason`, quindi restituisci i risultati tramite un adattatore. Tratta gli ID come valori opachi e conservali per la correlazione. Valida gli argomenti prima dell’esecuzione e restituisci errori strutturati invece di correggere silenziosamente JSON non valido. ## Reimposta lo stato nel primo confronto La cronologia precedente può contenere blocchi di ragionamento, ruoli dei risultati, identificatori di stato o messaggi rifiutati dalla nuova rotta. Inizia una conversazione nuova con le stesse istruzioni, poi riproduci una cronologia breve e normalizzata. Le scorciatoie di stato dipendono dal protocollo. Un ID della risposta precedente non garantisce che le istruzioni di sviluppo persistano. Trasforma la persistenza in un test esplicito. ## Costruisci una scala di migrazione Esegui gli stessi casi in questo ordine: * Risposta testuale semplice. * Uno strumento in sola lettura forzato, senza streaming. * Una selezione automatica, senza streaming. * Uno strumento forzato con streaming. * Due strumenti indipendenti. * Un errore di strumento e recupero. * Una breve attività di codice in più turni. Fermati al primo errore e ispeziona i dati di rete. Non saltare da un controllo di salute a una modifica autonoma del repository. ## Decidi se basta un adattatore Un adattatore comune va bene quando cambiano solo nomi di campi o eventi. Adattatori separati sono più sicuri quando servono protocolli, cronologie o semantiche dei risultati differenti. Atlas Cloud semplifica gli esperimenti perché una chiave e un URL di base danno accesso a più formati e a un [catalogo di modelli 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) in evoluzione. Questo non elimina la verifica delle capacità. Registra insieme modello, protocollo, versione dello schema, modalità streaming e risultato. ## Conclusione Le chiamate falliscono dopo un cambio di modello quando una migrazione di comportamento e protocollo viene trattata come sostituzione di testo. Verifica la rotta, riduci lo schema, supera una chiamata forzata senza streaming, convalida l’assemblaggio del flusso e aggiungi lo stato per ultimo. Se le semantiche differiscono, mantieni adattatori separati. ## FAQ ### Perché il nuovo modello risponde con testo invece di chiamare uno strumento? Potrebbe non supportare gli strumenti sul protocollo scelto, richiedere un’altra impostazione di selezione o interpretare diversamente la descrizione. Controlla i metadati e forza una chiamata di prova. ### Due modelli compatibili con OpenAI possono restituire formati diversi? Sì. L’involucro della richiesta può essere compatibile mentre delta, ID, completamento degli argomenti e motivi di arresto rimangono differenti. ### Devo riutilizzare la vecchia conversazione dopo il cambio? Solo dopo aver verificato che il nuovo modello e protocollo accettino gli stessi elementi di cronologia. È più sicuro iniziare una conversazione nuova e aggiungere lo stato in modo deliberato. ### Qual è il test diagnostico più rapido? Forza uno strumento deterministico in sola lettura con un piccolo schema JSON, eseguilo senza streaming e registra richiesta e risposta grezze prima di provare il loop completo. ### Atlas Cloud normalizza tutti i modelli in un’interfaccia identica? No. Atlas Cloud supporta più protocolli e ogni modello pubblica API e capacità compatibili. Il client deve scegliere un protocollo realmente supportato. ### Quando conviene mantenere adattatori separati? Quando oggetti di stato, eventi di streaming, messaggi di risultato o semantica degli errori non possono essere rappresentati in sicurezza da un solo contratto normalizzato.