Gérer les erreurs d'outils et les résultats partiels dans une boucle d'agent

Ce que c'est

Trois résultats appellent trois réponses différentes. Une erreur de protocole (outil inconnu, arguments invalides, serveur inaccessible) est un échec de l'appel lui-même ; le Model Context Protocol rapporte ces cas sous forme d'erreurs JSON-RPC. Une erreur d'exécution d'outil (l'API en amont a renvoyé 500, le fichier n'existe pas, la requête a expiré) est un résultat valide qui indique que l'opération a échoué ; MCP la renvoie dans le résultat avec isError: true, et la documentation sur l'usage d'outils du fournisseur décrit l'indicateur équivalent is_error: true sur un bloc tool_result, après quoi le modèle intègre l'erreur à sa prochaine étape. Un résultat partiel (7 fichiers traités sur 10, la première page d'une recherche, un lot avec deux lignes rejetées) est un succès dont le contenu doit préciser ce qui manque.

Pourquoi c'est important

Un agent agit en fonction de ce que dit le résultat de l'outil. Une exception qui n'atteint jamais le modèle produit une réponse assurée construite sur rien. Une erreur sans détail produit des nouvelles tentatives aveugles du même appel. Un résultat partiel signalé comme complet produit une tâche marquée comme terminée alors que des lignes ont été perdues en silence.

Comment l'appliquer

• Ne jamais laisser une exception s'échapper de l'outil ; la capturer et renvoyer un résultat d'erreur avec un type d'erreur stable, le message et, si c'est connu, si une nouvelle tentative peut aider (non pour une 404, oui pour un délai dépassé).
• Pour les résultats partiels, renvoyer la partie réussie ainsi qu'une liste explicite de ce qui a échoué et pourquoi, et un curseur ou un identifiant pour poursuivre.
• Garder le texte d'erreur court et factuel ; pas de traces de pile ni de sortie amont susceptible de porter des instructions injectées.
• Imposer des limites de nouvelles tentatives dans la boucle, pas par instruction : le même outil avec les mêmes arguments après une erreur n'est autorisé qu'un nombre fixe de fois, après quoi la boucle rend la main avec un résumé.
• Rendre les outils d'écriture idempotents ou leur donner une clé d'idempotence, afin qu'une nouvelle tentative après un échec ambigu ne duplique pas l'effet.
• Distinguer « aucun résultat » d'« erreur » : une recherche vide est un résultat valide et complet.
• Journaliser chaque résultat d'erreur avec l'identifiant d'exécution ; la répartition des erreurs constitue le rapport d'utilisabilité de l'outil.

Pièges

Renvoyer null ou une chaîne vide en cas d'échec. Faire correspondre chaque échec à un seul message générique. Laisser le modèle décider du nombre de nouvelles tentatives. Lever une erreur de protocole pour une condition métier (« commande introuvable » est un résultat, pas un appel malformé). Ne faire apparaître les résultats partiels que dans un journal que le modèle ne voit jamais.