Créer un agent IA qui enquête avec des outils et vérifier qu’il ne devine pas

## Séparer le moteur d’enquête des plugins propres à chaque service Organisez le système en couches explicites : points d’entrée destinés aux utilisateurs, chargement de la configuration, moteur d’investigation, gestionnaire d’outils, ainsi que sources, ensembles d’outils, prompts et destinations interchangeables. Les points d’entrée doivent acheminer les requêtes et mettre en place la journalisation ; la configuration doit valider les paramètres et construire les intégrations ; le moteur doit sélectionner les outils, recueillir les preuves, analyser les résultats et, si nécessaire, renvoyer les constats vers une destination autorisée. Placez le comportement propre à chaque fournisseur derrière des plugins afin que la boucle centrale puisse raisonner à partir d’un contrat d’outil stable. Chargez dynamiquement les intégrations depuis une configuration validée et maintenez séparées l’ingestion des sources, l’investigation et les écritures vers les destinations afin qu’un diagnostic en lecture seule ne devienne pas discrètement une modification externe. ## Faire de chaque outil une fine enveloppe qui explique précisément ses échecs Préférez une enveloppe légère autour d’un seul point de terminaison ou d’une seule opération externe. Fournissez à chaque intégration un petit objet de configuration validé, un prérequis explicite ou un contrôle de bon fonctionnement, ainsi qu’une fonction d’outil dont les paramètres correspondent directement à la requête sous-jacente. Évitez les abstractions client lourdes lorsqu’un appel de transport transparent facilite l’examen du comportement et des erreurs. Renvoyez suffisamment de contexte sur l’échec pour que l’appelant puisse se corriger : requête ou commande exacte, plage temporelle, filtres, paramètres pertinents, état de la réponse et message d’erreur sous-jacent. Un résultat sans données doit indiquer ce qui a été recherché et où. Préservez les contrôles d’accès, validez les commandes exécutables, maintenez les outils en lecture seule par défaut et n’exposez ni ne consignez jamais de secrets dans le contrôle de versions. ## Limiter la quantité de données renvoyée par un outil avant que l’IA la lise N’exposez jamais une collection sans limites par l’intermédiaire d’un outil. Exigez des filtres côté serveur pour les points de terminaison susceptibles de renvoyer de grands ensembles de résultats et concevez le schéma de façon que les appelants ne puissent pas omettre le paramètre de périmètre le plus important. Un dépassement de la capacité en jetons ou en mémoire causé par une opération de liste sans restriction constitue un défaut du contrat d’outil, pas un problème de prompt. Lorsque le service distant ne peut pas filtrer correctement, ajoutez des contrôles explicites côté client, tels qu’une profondeur maximale, des limites de résultats, une sélection de champs ou une expression de requête structurée. Signalez la troncature et les limites appliquées. Maintenez la réponse par défaut compacte tout en autorisant une extension ciblée lorsque l’investigation nécessite davantage de preuves. ## Garder valides les anciens noms de configuration et placer le comportement commun au bon niveau de classe Lorsque vous renommez un champ de configuration, acceptez les noms obsolètes comme entrée supplémentaire, associez-les au champ actuel et émettez un avertissement d’obsolescence. Ne conservez que les noms actuels dans le schéma public et la sortie sérialisée, afin que la compatibilité ne pollue ni la configuration générée ni la logique en aval. Avant d’ajouter un champ, une méthode, un délai d’attente ou une politique de nouvelle tentative à une intégration nommée, examinez sa hiérarchie de classes et les implémentations similaires. Placez le comportement partagé au niveau le plus général qui en a réellement besoin. Utilisez un mécanisme éprouvé de nouvelles tentatives assorti de politiques explicites de tentatives et de délais ; n’écrivez une boucle personnalisée que lorsque le mécanisme standard ne peut pas exprimer l’exigence, et documentez cette raison. ## Tester en trois couches, des tests unitaires à l’évaluation complète de l’agent Utilisez trois couches complémentaires. Les tests unitaires isolent le comportement local, les tests d’intégration exercent les limites entre outils et services, et les évaluations des agents vérifient le comportement d’investigation de bout en bout avec des prompts et des données de test réalistes. Tout nouveau comportement local nécessite une couverture unitaire, toute nouvelle intégration une couverture des limites, et toute investigation complexe des cas d’évaluation. Maintenez la structure des sources et celle des tests alignées. Utilisez des simulacres HTTP au niveau du transport pour tester le comportement des requêtes afin d’exercer les en-têtes, les URL, les paramètres et les adaptateurs plutôt que de remplacer une fonction de haut niveau. Exécutez des outils réels uniquement dans un environnement configuré à dessein et distinguez les tests déterministes ordinaires des évaluations qui nécessitent des identifiants d’accès au modèle ou des services externes. ## Concevoir des évaluations qui repèrent les réponses inventées (hallucinations) Faites demander à chaque prompt les faits exacts contrôlés par l’évaluation. Préférez des valeurs attendues qui ne peuvent être découvertes que par une requête, comme un identifiant unique inséré, un décompte exact, un titre ou un code d’erreur. La réponse attendue doit rester invisible pour l’agent. Si la réponse est trop générique pour prouver la découverte, exigez la preuve que l’outil approprié a été appelé. Testez la découverte plutôt que la reconnaissance. Utilisez des noms de ressources neutres, des scénarios réalistes et des prompts qui ne révèlent ni l’implémentation ni la solution probable. Évitez les assertions génériques qu’un modèle pourrait deviner grâce à sa connaissance du domaine. N’utilisez que des étiquettes de test enregistrées, des noms de ressources uniques, des versions figées de dépendances ou d’images et des terminaisons explicites en échec lorsque la préparation ne peut pas prouver que le service fonctionne. ## Permettre à plusieurs exécutions de test de partager des ressources cloud sans se gêner Partez du principe que les évaluations adossées au cloud de plusieurs branches peuvent se chevaucher sur un même compte. La préparation doit être idempotente : créez ou réutilisez les ressources sans échouer lorsqu’elles existent déjà. Le nettoyage ne doit jamais supprimer une ressource partagée statique qu’une autre exécution utilise peut-être encore ; omettez le nettoyage ou limitez-le à un identifiant unique dans le périmètre de l’exécution. Vérifiez le fonctionnement au moyen d’une véritable réponse de l’API, et non du seul état de disponibilité. Interrogez le service avec un nombre limité de nouvelles tentatives pour gérer les conditions de concurrence lors de la création, échouez rapidement si le contenu attendu n’apparaît jamais et recueillez les diagnostics en cas d’expiration du délai. Réutilisez une infrastructure partagée normalisée lorsque plusieurs tests nécessitent le même service, mais maintenez les données et les identifiants de chaque test isolés. ## Trouver la cause des défauts d’affichage du terminal et des baisses d’évaluation à partir de traces réelles Pour les défauts des terminaux interactifs, reproduisez le problème au moyen d’un pseudo-terminal et capturez les séquences d’échappement brutes. Comparez le déplacement du curseur et les opérations d’effacement à la hauteur du cadre rendu, puis testez le moteur de rendu avec un flux en mémoire forcé à se comporter comme un terminal. Corrigez le contrat de cadre ou d’actualisation qui provoque le décalage ; ne modifiez pas aveuglément le déplacement du curseur lorsque le comportement diffère au bas du terminal. Pour les régressions des évaluations d’agents, comparez une trace de référence et une trace actuelle pour le même test et le même modèle avant de vous fier aux différences du code source ou aux statistiques agrégées. Examinez les prompts rendus, l’ordre des appels d’outils, les mesures par appel et les preuves renvoyées. Un gabarit peut s’allonger dans le code source tout en se raccourcissant à l’exécution, et la variance agrégée peut masquer un changement déterministe propre à chaque exécution. Lisez l’ensemble complet des modifications d’une révision suspecte avant de rétablir uniquement le fichier le plus visible. ## Formater et vérifier seulement les fichiers concernés et ne pas pousser sans autorisation Respectez les règles propres au dépôt en matière de style, de typage, de tests et de gestion de versions, mais n’exécutez pas de corrections automatiques étendues, de formatage ou de contrôles à l’échelle du dépôt lorsqu’ils sont connus pour modifier des fichiers sans rapport, sauf demande explicite de l’utilisateur ou du flux de travail applicable. Limitez le formatage automatique et l’analyse statique aux fichiers inclus dans le périmètre, et maintenez les revues concentrées avec les tests correspondants. Placez les imports et les utilitaires partagés selon les conventions du projet, préservez un historique réversible et évitez toute réécriture forcée de l’historique sans autorisation explicite. Une tâche locale n’autorise pas à elle seule à effectuer des commits, des pushs, des publications ni des modifications d’état externe. Indiquez quelles vérifications ont été exécutées et quels contrôles ont été délibérément exclus. ## Mettre à jour toutes les références quand une page ou un titre de la documentation change Utilisez la documentation du dépôt comme source principale du comportement du projet avant de consulter le site web public. Lorsqu’une page est déplacée, qu’un nom de fichier change ou que l’ancre d’un titre est modifiée, recherchez l’ancien chemin et l’ancienne ancre dans l’ensemble du dépôt, y compris la documentation, les chaînes du code source, les guides de premier niveau et les commentaires, puis mettez à jour toutes les références concernées. Mettez à jour la véritable source de navigation du système de documentation plutôt qu’une configuration inactive au nom similaire. Préservez la structure propre au moteur de rendu, notamment les lignes vides obligatoires et une hiérarchie de titres valide. Évitez les listes de fonctionnalités obsolètes et le remplissage de sécurité répétitif ; préférez des exemples concis et des blocs consolidés de résolution des problèmes. Lorsqu’une intégration est ajoutée, mettez à jour ensemble sa présentation, son index, sa page dédiée, son entrée de navigation et sa ressource visuelle.