Votre agent a fonctionné dans la démo. Il a lu le ticket, appelé trois API et publié un résumé clair. Puis vous l'avez déployé. Une semaine plus tard, il a envoyé deux fois le même e-mail au même client, a épuisé le budget de jetons d'une journée dans une boucle de réessai, et a transmis à votre frontend une charge utile qu'il ne pouvait pas analyser.
Cet écart entre un prototype fonctionnel et un agent fiable est là où la plupart des équipes butent. Le modèle est rarement le coupable. Le problème réside dans la partie traitée comme de la plomberie : les appels API que l'agent effectue pour obtenir une réponse. Un agent est une boucle d'appels d'outils, et chaque appel d'outil est une requête HTTP qui peut échouer, être limitée, expirer ou renvoyer quelque chose que vous n'attendiez pas. Si vous ignorez le test de ces appels de la même manière que vous testez n'importe quelle API de production, votre agent est à une mauvaise réponse près d'un incident.
Voici la partie rassurante : la fiabilité d'un agent est testable. Vous n'avez pas à faire confiance au modèle pour qu'il se comporte bien. Vous exercez délibérément les chemins d'échec, avant que vos utilisateurs ne les découvrent. Ce guide classe les défaillances des agents en cinq modes et montre comment détecter chacun d'eux. Le travail se fait à la limite de l'API, vous avez donc besoin d'une plateforme que vous pouvez pointer vers les dépendances de l'agent pour concevoir le contrat, simuler les défaillances et vérifier ce qui revient. Apidog couvre ce travail et parcourt les exemples ci-dessous.
Les agents échouent à la limite de l'API, pas dans le prompt
Lorsqu'un agent se comporte mal en production, l'instinct est d'éditer le prompt. Parfois, cela aide. Plus souvent, l'échec n'a rien à voir avec le libellé. L'agent a demandé quelque chose à une API réelle, et la réponse était lente, mal formée, soumise à des limites de débit, ou d'une forme différente de ce que l'agent attendait. Le modèle a alors raisonné sur une mauvaise entrée et a fait quelque chose de confiant et de faux.
Voyez ce qu'implique une seule étape d'agent. Le modèle choisit un outil. Votre code transforme ce choix en une requête HTTP. Un service externe répond. Votre code renvoie le résultat au modèle. Quatre transferts, et trois d'entre eux sont de l'intégration API ordinaire, pas de l'apprentissage automatique. C'est une bonne nouvelle, car l'intégration API est un problème de test résolu. Vous savez déjà comment simuler un point de terminaison lent ou faire des assertions sur un schéma JSON. Les agents augmentent les enjeux, car le modèle agit sur tout ce qu'il reçoit au lieu de générer une exception propre.
Ainsi, la question de la fiabilité n'est pas « le modèle est-il assez intelligent ? ». C'est plutôt « ai-je testé toutes les façons dont les appels API de l'agent peuvent mal tourner ? ». Cinq modes couvrent la majeure partie de ce problème.
Mode de défaillance 1 : appels d'outils qui s'écartent du contrat
La défaillance d'agent la plus courante est un appel d'outil qui ne correspond pas à l'API qu'il appelle. Le modèle invente un paramètre, omet un champ requis, envoie une chaîne là où le schéma attend un entier, ou appelle le bon point de terminaison avec des arguments qui n'ont aucun sens. Supposons qu'un agent de réservation appelle POST /reservations avec guests: "two" au lieu de guests: 2. L'API renvoie un 400, ou pire, un 200 avec une erreur cachée dans le corps, et l'agent continue comme s'il avait réussi.
Vous détectez cela en testant l'appel d'outil comme un contrat. Définissez le schéma pour chaque outil que l'agent peut invoquer, puis affirmez que la requête sortante correspond : champs requis présents, types corrects, énumérations valides. Lorsque l'agent produit un appel qui rompt le contrat, vous voulez que cela échoue bruyamment dans un test, pas silencieusement en production. Notre guide détaillé sur le test des appels d'outils d'un agent IA approfondit ce sujet, et la méthode plus large pour tester les agents qui appellent vos API couvre la configuration de bout en bout.
La démarche pratique : capturez les schémas d'outils que votre agent utilise, chargez-les dans Apidog et exécutez les appels d'outils réels de l'agent par rapport à ces définitions. Les non-concordances apparaissent sous forme d'échecs de validation nommant le champ exact qui a posé problème.
Mode de défaillance 2 : erreurs en amont et limites de débit
Chaque appel externe effectué par l'agent peut renvoyer un 429, un 500, ou rien du tout avant un délai d'attente. Un agent bien conçu gère ces situations avec des réessais et un backoff. Un agent fragile abandonne à la première erreur ou, plus dangereusement, réessaie si intensément qu'il déclenche davantage de limitations et tourne en boucle, épuisant votre budget. La question la plus posée sur le forum de discussion du SDK Anthropic concerne littéralement les modèles de récupération d'erreur d'agent, ce qui indique à quel point cette douleur est courante.
Vous ne pouvez pas tester la récupération avec une API saine, car une API saine ne renvoie jamais les erreurs que vous devez gérer. C'est là que la simulation est utile. Mettez en place une simulation de la dépendance de l'agent et programmez une séquence : un 429 avec un en-tête Retry-After, puis un 500, puis un succès. Observez maintenant ce que fait votre agent. Se retire-t-il avec une gigue ? Respecte-t-il l'en-tête ? Abandonne-t-il gracieusement après un nombre raisonnable de tentatives, ou ouvre-t-il un disjoncteur pour cesser de bombarder un service manifestement en panne ? Et si une action retentée n'est pas idempotente, un повтор entraîne-t-il un double débit ou un double envoi ? Une clé d'idempotence est ce qui rend un réessai sûr à répéter.
Les limites de débit méritent leur propre répétition. Si vous n'avez pas vu comment votre agent se comporte lorsqu'un fournisseur le limite, lisez notre guide sur ce que signifie une réponse de dépassement de limite de débit et simulez-le ensuite. Le guide dédié à la récupération d'erreurs d'agent IA couvre en détail les modèles de réessai, de délai d'attente, de backoff et de disjoncteur.
Mode de défaillance 3 : sortie non déterministe
Même en réglant la température à zéro, vous n'obtiendrez toujours pas une sortie identique au bit près d'une exécution à l'autre. Les développeurs le redécouvrent constamment ; il existe un long fil de discussion vLLM sur le fait que les graines et la température ne suffisent pas pour la reproductibilité. Le matériel, le traitement par lots et les modifications côté fournisseur introduisent tous des variations. Si vos tests affirment des chaînes exactes, ils deviennent instables, et les tests instables sont ignorés, ce qui est pire que pas de tests du tout. Notre récapitulatif des causes des tests instables s'applique directement ici.
La solution consiste à affirmer la structure et le sens, et non le texte exact. Vérifiez que la réponse est valide par rapport à un schéma JSON. Vérifiez que l'appel de l'outil a la bonne forme et la bonne cible. Vérifiez qu'une réponse numérique se situe dans une plage raisonnable. Vérifiez que les clés requises existent et que les champs interdits sont absents. Un test qui dit « la réponse contient un total entre 0 et la valeur du panier » survit à la variation naturelle du modèle tout en détectant une véritable régression. Le guide sur le test des agents IA non déterministes expose l'ensemble complet des stratégies, et l'article sur le fonctionnement de la mémoire de l'agent montre pourquoi l'état rend cela plus difficile.
Mode de défaillance 4 : coût incontrôlé
Les agents tournent en boucle, et les boucles coûtent de l'argent. Un seul agent bloqué qui réessaie un appel défaillant quelques milliers de fois peut transformer une petite facture en une grande du jour au lendemain. Un rapport de terrain dans les discussions du SDK a décrit la réduction du coût d'un agent de 500 dollars par mois à 80 sans perte de qualité, ce qui montre à la fois la rapidité avec laquelle les coûts augmentent et la marge de manœuvre qui se cache habituellement dans la conception.
Le coût est un problème de fiabilité, pas seulement financier, car les bugs qui gaspillent de l'argent (boucles, appels redondants, contexte surdimensionné) rendent également l'agent lent et imprévisible. Suivez les jetons par exécution, plafonnez le budget par tâche et mettez en cache ce que vous pouvez. Pour le côté ligne de commande, notre guide sur la réduction des coûts de jetons d'agent propose des leviers concrets. Lorsque vous testez les chemins de récupération avec une simulation, surveillez également le nombre d'appels. Un agent qui réussit mais effectue quarante appels pour y parvenir est un incident de coût en attente.
Mode de défaillance 5 : garde-fous manquants
Les défaillances les plus douloureuses sont celles où l'agent fait exactement ce qu'on lui a dit et où le résultat est toujours mauvais. Il envoie l'e-mail, supprime l'enregistrement ou passe la commande, car rien ne se trouvait entre la décision du modèle et l'action réelle. Les forums du SDK contiennent un fil de discussion mémorable centré sur un agent qui a envoyé un e-mail à trois heures du matin au patron de quelqu'un. Drôle une fois, coûteux deux fois.
Les garde-fous sont la ceinture de sécurité. Mettez une liste blanche sur les actions qu'un agent peut effectuer sans approbation. Protégez les appels destructeurs ou irréversibles derrière une confirmation humaine. Donnez à l'agent un mode d'exécution à blanc qui décrit ce qu'il ferait sans le faire. Ensuite, testez que le garde-fou tient : simulez le point de terminaison à effets secondaires, exécutez l'agent et affirmez qu'il emprunte le chemin de confirmation plutôt que l'action réelle. Les directives de sécurité comme l' OWASP Top 10 pour les applications LLM sont une liste de contrôle solide pour ce qu'il faut protéger. Le guide sur les garde-fous des agents IA couvre en profondeur les portes d'approbation et le contrôle du rayon d'action.
Comment structurer un test d'agent
Les cinq modes partagent une forme de test, et vous pouvez la réutiliser :
- Capturez les schémas d'outils que votre agent peut appeler, afin d'avoir un contrat sur lequel faire des assertions.
- Simulez chaque dépendance afin de contrôler le timing, les codes d'état et les corps de réponse, et d'éviter les effets secondaires réels.
- Exécutez l'agent à travers le scénario, y compris les chemins d'échec qu'une API réelle ne produira pas à la demande.
- Affirmez ce que l'agent a envoyé et comment il a réagi : forme de la requête, comportement de récupération, nombre d'appels, et si les garde-fous se sont déclenchés.
Exécutez cette boucle pour un outil, puis ajoutez le suivant. La configuration est rentabilisée dès la première fois qu'elle détecte un appel d'outil cassé avant qu'un utilisateur ne le fasse.
La liste de contrôle de la fiabilité des agents
Avant qu'un agent ne passe en production, parcourez cette liste :
- Chaque appel d'outil est validé par rapport à un schéma, et les violations de contrat font échouer un test.
- Les réponses en amont 429, 500 et les délais d'attente sont simulés, et l'agent se rétablit avec un backoff.
- Les actions répétées sont idempotentes, de sorte qu'une répétition ne peut pas doubler la facturation ou l'envoi.
- Les tests affirment la structure et le sens, pas les chaînes exactes, de sorte que la variation normale ne provoque pas d'instabilité.
- L'utilisation des jetons par exécution est mesurée, et un plafond budgétaire arrête les boucles incontrôlées.
- Les actions destructrices sont derrière une liste blanche ou une porte d'approbation humaine.
- Le chemin du garde-fou est testé avec une simulation, et non supposé.
Cochez les sept points et vous aurez testé les façons dont les agents échouent en production.
Où Apidog s'intègre (et où il ne s'intègre pas)
Soyez clair sur le rôle de l'outil. Apidog n'est pas un framework d'agent, un hôte de modèle ou un harnais d'évaluation. Il ne construit ni n'exécute votre agent. Ce qu'il fait, c'est gérer la couche API dont dépend votre agent, et c'est précisément là que résident ces défaillances.
En pratique, cela signifie trois choses. Vous concevez et stockez les contrats pour les outils que votre agent appelle, afin de pouvoir valider les requêtes sortantes par rapport à eux. Vous simulez ces dépendances et programmez les réponses d'échec (429, 500, timeout, corps mal formé) qu'une API réelle ne produira pas à la demande, afin de pouvoir répéter la récupération. Et vous écrivez des assertions sur les réponses (schéma, forme, plages, clés requises) qui survivent à une sortie non déterministe. C'est l'ajustement honnête : Apidog teste les API que votre agent appelle, simule les échecs que vous devez gérer et vérifie ce qui est renvoyé. Notre aperçu des tests d'agents IA place cela dans le cadre plus large de l'assurance qualité.
Questions fréquemment posées
La fiabilité d'un agent est-elle un problème de modèle ou un problème d'ingénierie ? Principalement d'ingénierie. Le choix du modèle est important, mais les défaillances qui causent des incidents (mauvais appels d'outils, limites de débit non gérées, garde-fous manquants) sont des problèmes d'intégration et de test que vous pouvez résoudre sans changer le modèle.
Puis-je tester un agent sans appeler les API réelles qu'il utilise ? Oui, et vous devriez. Simulez les dépendances afin de pouvoir forcer les réponses d'erreur, contrôler le timing et éviter les effets secondaires. C'est le seul moyen fiable de tester les chemins de récupération et les garde-fous.
Comment écrire des tests lorsque la sortie change à chaque exécution ? Affirmez la structure et le sens au lieu du texte exact. Validez la réponse par rapport à un schéma, vérifiez la forme de l'appel d'outil et utilisez des plages pour les nombres. Le guide tester les agents IA non déterministes couvre cela en détail.
Que dois-je tester en premier ? Les garde-fous sur les actions destructrices, puis la récupération d'erreur. Ces deux éléments vous protègent des défaillances les plus coûteuses : un agent effectuant une action nuisible, ou un agent tournant en boucle et épuisant votre budget.
Commencer par un mode de défaillance
Vous n'avez pas besoin de tester les cinq modes à la fois. Choisissez celui qui vous effraie le plus, généralement les garde-fous ou la récupération d'erreur, et répétez-le cette semaine avec une simulation. Programmez la défaillance, exécutez l'agent et observez ce qu'il fait. La première fois que vous verrez votre agent gérer un 429 simulé avec un backoff propre au lieu d'une boucle épuisant le budget, vous lui ferez davantage confiance, et pour une meilleure raison qu'une démo réussie.
Téléchargez Apidog pour concevoir les contrats, simuler les défaillances et faire des assertions sur les réponses dont votre agent dépend.