Aller au contenu
Cercle IA Tech · Agents Un site du réseau Cercle IA Tech

Guide

Erreurs d'un agent IA : outils en échec, reprise et arrêt

Outil en échec, limite de tours atteinte, session interrompue : is_error, nouvelles tentatives, sous-types d'arrêt et reprise de session.

Mis à jour le

Une stratégie en cinq lignes
  1. Classez ce que vos outils renvoient : erreur à réessayer, erreur à expliquer au modèle, erreur à montrer à une personne.
  2. Écrivez les messages d'erreur pour le modèle, pas pour un journal.
  3. Posez max_turns et un plafond de budget dès le premier test : voir l'architecture d'un agent.
  4. Traitez chaque sous-type d'arrêt, avec reprise de session quand la tâche est longue.
  5. Gardez la trace de chaque appel d'outil pour comprendre après coup : la méthode générale de reprise de flux, avec files d'échecs et alertes, est détaillée dans la gestion des erreurs d'un flux d'intégration.

Parmi les échecs à prévoir pour un agent : un outil qui plante, une limite atteinte (tours ou budget), une session interrompue. Chacune a un traitement précis dans la documentation d'Anthropic, relue le 16/11/2026. Anthropic prévient dans « Building effective agents » (19/12/2024) que l'autonomie d'un agent implique des coûts plus élevés et un risque d'erreurs qui s'accumulent, et conseille des essais poussés en environnement isolé avec des garde-fous.

Pour préparer l’intégration d’un assistant à une application, confrontez votre stratégie de reprise à un contrat concret, comme la documentation API d’ALMA. Vérifiez séparément les erreurs de requête, les événements reçus et les effets déjà produits avant de relancer une opération.

1. L'outil échoue

Quand votre fonction lève une erreur (par exemple un service injoignable), vous répondez au modèle avec un bloc tool_result marqué en erreur. Exemple cité tel quel par la documentation :

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
  "content": "ConnectionError: the weather service API is not available (HTTP 500)",
  "is_error": true
}

Le modèle intègre alors l'erreur à sa réponse. Le conseil de la page : écrire des messages d'erreur instructifs, qui disent ce qui s'est passé et ce qu'il peut essayer ensuite, plutôt qu'un « failed » (exemple : « Rate limit exceeded. Retry after 60 seconds. »).

2. Le modèle appelle mal l'outil

Un appel invalide (paramètre obligatoire manquant) signale en général une description d'outil insuffisante. Pendant la conception, la documentation conseille de la détailler. En exécution, vous pouvez renvoyer une erreur dans tool_result : la documentation décrit 2 à 3 tentatives de correction avant une réponse d’excuse. Ce comportement annoncé ne remplace pas une limite de tentatives imposée par votre application. Pour supprimer ces appels invalides, elle propose l'option strict: true sur la définition de l'outil, qui contraint les paramètres au schéma pris en charge. Cela ne vérifie ni les droits, ni l’existence d’un identifiant, ni la pertinence de l’action métier.

Deux règles de forme évitent des erreurs de l'API elle-même : un résultat d'outil doit suivre immédiatement l'appel correspondant, et les blocs tool_result passent avant tout texte dans le message.

3. L'outil est refusé

Si votre politique de droits refuse l'appel, la documentation du Claude Agent SDK indique que Claude reçoit un message de refus comme résultat d'outil et tente en général une autre approche ou signale qu'il ne peut pas continuer. Un point d'accroche (PreToolUse) qui rejette un appel produit le même effet. Voir les permissions.

4. La boucle atteint une limite

Le ResultMessage final de l'Agent SDK porte un sous-type :

Sous-type Signification Réponse finale
success boucle terminée normalement ; résultat métier à vérifier oui
error_max_turns limite de tours atteinte non
error_max_budget_usd limite de dépense atteinte non
error_during_execution une erreur a interrompu la boucle (requête annulée par exemple) non
error_max_structured_output_retries aucune sortie structurée valide dans la limite de tentatives non

Vérifiez toujours ce sous-type avant de lire le résultat. Les variantes de résultat exposent le coût, l’usage, le nombre de tours et l’identifiant de session ; en Python, certains champs de coût et d’usage peuvent être absents (None). Détail utile : la limite de budget est comparée à la dépense après chaque réponse, donc la dépense peut dépasser le seuil avec cette réponse et l’activité de sous-agents encore en cours ; laissez de la marge. Autre détail : un appel query() isolé lève une exception après avoir émis le résultat en erreur ; entourez la boucle d'un bloc d'interception si votre code doit continuer.

5. La session plante ou s'arrête

Lorsqu’un plantage de session donne lieu à un résultat final synthétisé par Claude Code, son type est error_during_execution et ses coûts peuvent être à zéro. Une panne de connexion ou du processus peut aussi ne produire aucun résultat : prévoyez ce chemin dans le traitement des exceptions. Pour reprendre, la documentation recommande de conserver l'identifiant de session : à la reprise, le contexte des tours précédents est restauré (fichiers lus, analyses, actions). La session peut aussi être dupliquée pour tenter une autre voie sans toucher à l'originale.

Ne pas doubler une action après une coupure

Supposons qu’un outil crée un ticket, mais que la connexion coupe avant le retour de son identifiant. L’absence de réponse ne signifie pas que la création a échoué. Avant de réessayer, recherchez le ticket avec une référence d’opération conservée par votre application, ou utilisez le mécanisme d’idempotence prévu par le service. S’il est impossible de savoir ce qui a été créé, remontez un état incertain à une personne.

Distinguez donc les erreurs transitoires, les arguments à corriger, les refus de droits et les effets inconnus. Un refus d’accès ne se résout pas en répétant la même demande. Une limite de débit peut justifier une attente bornée ; un secret invalide demande une correction de configuration. Fixez aussi un délai total : des tentatives individuellement limitées peuvent ensemble immobiliser la tâche trop longtemps.

Une stratégie en cinq lignes

  1. Classez ce que vos outils renvoient : erreur à réessayer, erreur à expliquer au modèle, erreur à montrer à une personne.
  2. Écrivez les messages d'erreur pour le modèle, pas pour un journal.
  3. Posez max_turns et un plafond de budget dès le premier test : voir l'architecture d'un agent.
  4. Traitez chaque sous-type d'arrêt, avec reprise de session quand la tâche est longue.
  5. Gardez la trace de chaque appel d'outil pour comprendre après coup : la méthode générale de reprise de flux, avec files d'échecs et alertes, est détaillée dans la gestion des erreurs d'un flux d'intégration.

Pour la façon dont le modèle demande et reçoit les outils, voir le function calling.

Questions fréquentes

Comment dire au modèle qu'un outil a échoué ?

Dans la documentation de l'API Claude, on renvoie un bloc tool_result avec is_error à true et un message d'erreur dans content. Le modèle l'intègre ensuite à sa réponse ou réessaie.

Combien de fois le modèle réessaie-t-il un appel invalide ?

La documentation indique que, pour une requête d'outil invalide ou sans paramètre requis, Claude réessaie 2 à 3 fois avec des corrections avant de s'excuser auprès de l'utilisateur.

Que faire quand l'agent atteint la limite de tours ?

Le résultat porte le sous-type error_max_turns, sans réponse finale. L'exemple de la documentation du Claude Agent SDK conserve l'identifiant de session et propose de la reprendre avec une limite plus haute.

Sources

Pages consultées pour écrire cet article :

  1. https://alma.iarche.fr/fr/api-docs
  2. https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls
  3. https://code.claude.com/docs/en/agent-sdk/agent-loop
  4. https://www.anthropic.com/engineering/building-effective-agents

À lire aussi