# Pourquoi les appels d’outils échouent-ils après le changement de modèle d’un agent de code ? > Les appels d’outils échouent souvent après un changement de modèle parce que le protocole, le schéma, la sérialisation des arguments, les événements de streaming ou l’état de conversation changent. Traitez la migration comme un changement de contrat, pas comme un simple changement de nom. Le premier test utile est plus petit qu’un benchmark de code : demandez au modèle remplaçant d’appeler une fonction en lecture seule avec deux arguments obligatoires. En cas d’échec, le problème se situe sous la couche de planification. En cas de réussite, ajoutez le streaming, plusieurs outils, l’état et les écritures un par un jusqu’à la première rupture du contrat. Un changement de modèle révèle les hypothèses cachées de l’intégration précédente. Un agent de code n’est pas seulement un prompt et un modèle : c’est une machine à états reliant la sortie, le parseur de flux, le registre d’outils, l’exécuteur et la boucle qui renvoie les résultats. Chaque frontière peut devenir incompatible même si le texte ordinaire semble correct. ## Séparez capacité et protocole Un modèle peut être excellent en programmation sans être disponible via le protocole utilisé par votre client. Un autre peut accepter la requête sans annoncer les outils sur cette route. Vérifiez les métadonnées de capacité avant de changer le nom du modèle. Le [guide des protocoles LLM d’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) répertorie OpenAI Chat Completions, Responses, Anthropic Messages, Google Gemini et d’autres formats accessibles depuis une même URL de base. Tous les modèles ne parlent pas tous les protocoles. Utilisez `supported_apis` et la capacité d’outils comme source de vérité. | Couche | Question de migration | Signal d’échec | |---|---|---| | Endpoint | Le modèle accepte-t-il ce protocole ? | Réponse 400 ou champs ignorés | | Capacité | Cette route annonce-t-elle les outils ? | Texte au lieu d’un appel | | Schéma | Les noms et JSON Schema sont-ils valides ? | Arguments absents ou incorrects | | Flux | Les deltas sont-ils assemblés correctement ? | JSON tronqué | | Boucle | Les résultats reviennent-ils avec le bon rôle ? | Appel répété ou tour bloqué | ## Réduisez le schéma à un seul contrat Commencez par une fonction au nom court, deux chaînes obligatoires, sans union ni imbrication facultative. Les schémas complexes mêlent comportement du modèle et validation, ce qui ralentit le diagnostic. ```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 } } } ``` Forcez cette fonction si le protocole le permet. Cela distingue l’incapacité d’appeler d’une décision de planification de ne pas appeler. ## Testez sans streaming avant de l’activer Une réponse sans streaming contient l’objet final dans un seul payload. Avec le streaming, le nom, l’ID et les arguments JSON peuvent arriver séparément. N’analysez les arguments qu’après l’événement final ou done du protocole. N’exécutez pas un outil parce qu’un tampon partiel est déjà un JSON valide : un delta ultérieur peut le prolonger. Conservez les tampons par ID, refusez une seconde finalisation et journalisez la séquence brute. | Invariant du flux | Comportement requis | |---|---| | Identité stable | Tous les deltas alimentent le même tampon | | Assemblage ordonné | Les fragments sont ajoutés dans l’ordre | | Fin explicite | L’exécution attend l’événement final | | Exécution unique | Un appel terminé s’exécute au plus une fois | ## Normalisez explicitement la boucle Ne dispersez pas les champs propres au fournisseur dans l’exécuteur. Convertissez chaque réponse en forme interne comme `assistant_text`, `tool_calls`, `usage` et `stop_reason`, puis renvoyez les résultats via un adaptateur de protocole. Traitez les IDs comme des valeurs opaques et conservez-les pour la corrélation. Validez les arguments avant exécution et renvoyez des erreurs structurées au lieu de corriger silencieusement un JSON invalide. ## Réinitialisez l’état lors de la première comparaison L’ancien historique peut contenir des blocs de raisonnement, des rôles de résultat, des identifiants d’état ou des messages refusés par la nouvelle route. Commencez une conversation neuve avec les mêmes instructions, puis rejouez un historique court et normalisé. Les raccourcis d’état dépendent du protocole. Un identifiant de réponse précédente ne garantit pas que les instructions de développement persistent. Faites-en un test explicite. ## Construisez une progression de migration Exécutez les mêmes cas dans cet ordre : * Réponse texte simple. * Un outil en lecture seule forcé, sans streaming. * Une sélection automatique, sans streaming. * Un outil forcé avec streaming. * Deux outils indépendants. * Une erreur d’outil et sa récupération. * Une courte tâche de code en plusieurs tours. Arrêtez-vous au premier échec et inspectez les données réseau. Ne passez pas d’un contrôle de santé à une modification autonome du dépôt. ## Décidez si un seul adaptateur suffit Un adaptateur commun convient si seuls les noms de champs ou d’événements changent. Des adaptateurs séparés sont plus sûrs lorsque les protocoles, historiques ou résultats ont des sémantiques différentes. Atlas Cloud simplifie les expériences : une clé et une URL donnent accès à plusieurs formats et à un [catalogue de modèles 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) évolutif. Cela ne supprime pas la vérification des capacités. Enregistrez ensemble modèle, protocole, version du schéma, mode de streaming et résultat. ## Conclusion Les appels échouent après un changement de modèle lorsqu’une migration de comportement et de protocole est traitée comme un remplacement de texte. Vérifiez la route, réduisez le schéma, validez un appel forcé sans streaming, contrôlez l’assemblage du flux et ajoutez l’état en dernier. Si deux modèles exigent des sémantiques différentes, conservez des adaptateurs séparés. ## FAQ ### Pourquoi le nouveau modèle répond-il en texte au lieu d’appeler un outil ? Il peut ne pas prendre en charge les outils sur le protocole choisi, exiger un autre réglage de sélection ou interpréter différemment la description. Vérifiez les métadonnées et forcez un appel de test. ### Deux modèles compatibles OpenAI peuvent-ils renvoyer des formats différents ? Oui. L’enveloppe de requête peut être compatible alors que les deltas, identifiants, fins d’arguments et raisons d’arrêt diffèrent. ### Faut-il réutiliser l’ancienne conversation après le changement ? Seulement après avoir confirmé que le nouveau modèle et le protocole acceptent les mêmes éléments d’historique. Il est plus sûr de repartir d’une conversation neuve. ### Quel est le test de diagnostic le plus rapide ? Forcez un outil déterministe en lecture seule avec un petit schéma JSON, exécutez-le sans streaming et journalisez la requête et la réponse brutes avant de tester la boucle complète. ### Atlas Cloud normalise-t-il tous les modèles dans une interface identique ? Non. Atlas Cloud prend en charge plusieurs protocoles et chaque modèle publie ses API et capacités. Le client doit choisir un protocole réellement pris en charge. ### Quand faut-il conserver deux adaptateurs séparés ? Lorsque leurs objets d’état, événements de streaming, messages de résultat ou sémantiques d’erreur ne peuvent pas être représentés sans risque par un contrat unique.