Comment tracer un agent IA sans exposer ses données

Tracer un agent IA consiste à enregistrer les étapes qui expliquent son comportement : appels au modèle, outils utilisés, transferts entre agents, garde-fous déclenchés, erreurs et résultat final. Une bonne trace permet de comprendre ce que l’agent a fait sans transformer les données de l’utilisateur en journal permanent.

Sans tracing, un agent peut annoncer « terminé » alors qu’un outil a échoué, répéter une action coûteuse ou envoyer une donnée au mauvais système. Avec trop de tracing, il peut stocker des prompts, documents et réponses sensibles dont personne n’avait besoin.

Le bon système conserve la preuve minimale qui permet de reproduire et diagnostiquer une exécution.

Trace, log et mémoire : les séparer

Ces trois mécanismes répondent à des questions différentes.

Le log

Un log décrit un événement technique :

• service démarré ;

• requête reçue ;

• erreur réseau ;

• temps de réponse ;

• code de statut.

Il aide à exploiter l’application.

La trace

Une trace relie les étapes d’une même exécution. Elle montre le chemin complet entre la demande et le résultat :

• instructions initiales ;

• appel au modèle ;

• outil choisi ;

• paramètres envoyés ;

• sortie reçue ;

• garde-fou ;

• décision suivante ;

• réponse finale.

Chaque étape est généralement représentée par un span. Les spans appartiennent à une trace et peuvent être imbriqués.

La mémoire

La mémoire conserve ce qui doit survivre à l’exécution : préférence, décision, état ou preuve durable. Elle ne devrait pas recopier chaque span.

Notre guide sur la mémoire d’un agent IA explique cette séparation. La trace sert au diagnostic. La mémoire sert à continuer.

Ce qu’il faut pouvoir répondre

Avant de choisir un outil d’observabilité, définis les questions concrètes.

Pour une exécution donnée :

1. Quelle demande a déclenché l’agent ?

2. Quelle version des instructions et du modèle a été utilisée ?

3. Quels outils ont été appelés ?

4. Dans quel ordre ?

5. Quelles actions ont modifié un système externe ?

6. Quels contrôles ont été passés ou bloqués ?

7. Où le temps et le coût ont-ils été consommés ?

8. Quelle preuve soutient le statut final ?

Si ton tableau de bord ne permet pas de répondre à ces questions, il affiche de l’activité sans créer de contrôle.

La structure minimale d’une trace

Une trace utile contient quelques champs stables.

Identité

• identifiant unique ;

• date et heure ;

• nom du workflow ;

• environnement ;

• version de l’agent ;

• identifiant de session pseudonymisé.

Le nom du workflow évite de mélanger une veille, une publication et une réponse support.

Entrée

Conserve le type de demande et les métadonnées nécessaires. Le texte intégral n’est pas toujours requis.

Pour une recherche documentaire, tu peux garder :

• longueur de la requête ;

• langue ;

• collection consultée ;

• politique d’accès appliquée ;

• empreinte de la requête.

Le contenu brut ne doit être enregistré que s’il est indispensable au diagnostic et couvert par une politique claire.

Étapes

Chaque span devrait préciser :

• type d’étape ;

• début et fin ;

• statut ;

• modèle ou outil ;

• identifiant parent ;

• erreur structurée ;

• coût ou jetons si disponibles.

Pour une architecture avec plusieurs agents, les handoffs doivent conserver le lien parent-enfant. Sinon, tu vois plusieurs exécutions sans comprendre pourquoi elles se sont déclenchées.

Sortie et preuve

Ne limite pas la sortie à success: true.

Une action de publication peut conserver :

• identifiant de l’item créé ;

• statut brouillon ou publié ;

• version déployée ;

• URL ;

• contrôle HTTP ;

• contrôle de contenu ;

• contrôle visuel.

Le principe rejoint celui d’un agent qui contrôle un ordinateur : une action acceptée ne prouve pas que l’interface finale reflète le résultat.

Tracing avec l’OpenAI Agents SDK

L’OpenAI Agents SDK intègre le tracing par défaut. Il capture notamment :

• générations du modèle ;

• appels d’outils ;

• handoffs ;

• garde-fous ;

• événements personnalisés.

Le SDK regroupe les spans dans une trace. Tu peux nommer le workflow et associer plusieurs traces grâce à un identifiant de groupe, utile pour suivre une même conversation ou un même dossier.

Cette instrumentation native évite de reconstruire manuellement chaque lien. Elle ne dispense pas de décider quelles données peuvent sortir de ton système.

Exclure les données sensibles

La configuration trace_include_sensitive_data=False permet de garder les spans sans inclure le contenu sensible des entrées et sorties.

C’est un meilleur point de départ pour la production que d’enregistrer tous les prompts. Tu conserves la structure, les durées, les statuts et les relations, puis tu ajoutes uniquement les champs nécessaires à certains workflows.

Les organisations en mode Zero Data Retention ne disposent pas du tracing hébergé. Elles doivent prévoir leur propre chaîne d’observabilité compatible avec leurs engagements de conservation.

Forcer l’export

Dans un processus court, les traces peuvent ne pas avoir le temps d’être envoyées avant l’arrêt. La fonction flush_traces() force leur export.

Dans un worker long, utilise-la après un lot important ou avant une fermeture contrôlée. Ne la déclenche pas après chaque span si cela ralentit le système sans bénéfice.

Les garde-fous ne remplacent pas la trace

Un garde-fou décide si une entrée, une sortie ou un appel d’outil est autorisé. La trace explique ce qui s’est passé.

Les deux doivent travailler ensemble.

Garde-fou d’entrée

Il peut bloquer une demande avant qu’elle n’atteigne un outil dangereux. Dans l’OpenAI Agents SDK, un garde-fou d’entrée exécuté en mode bloquant peut empêcher l’exécution et ses effets de bord.

En mode parallèle, le modèle ou un outil peut commencer à travailler avant la fin du contrôle. Ce mode réduit la latence, mais convient mal lorsqu’une action irréversible doit être empêchée avant tout début d’exécution.

Garde-fou d’outil

Il inspecte les paramètres et la sortie de chaque fonction personnalisée. C’est l’endroit naturel pour vérifier :

• domaine autorisé ;

• destinataire ;

• chemin de fichier ;

• volume ;

• présence d’un secret ;

• niveau de permission ;

• résultat attendu.

Les outils hébergés et certains outils d’exécution intégrés ne passent pas automatiquement par la même chaîne de garde-fous que les fonctions personnalisées. Cette limite doit apparaître dans ton modèle de menace.

Garde-fou de sortie

Il contrôle la réponse finale. Il peut repérer une donnée personnelle, une affirmation interdite ou un format invalide.

Il ne voit pas forcément chaque sortie intermédiaire. Une fuite envoyée à un outil externe ne sera pas réparée par un contrôle final.

Pour concevoir les permissions avant l’observabilité, lis aussi comment sécuriser Claude Code.

Une politique de données en cinq niveaux

Le tracing devient plus simple lorsqu’une classification existe.

Niveau 0 : métadonnées techniques

Durées, statuts, identifiants pseudonymisés, versions et coûts. Conservation longue possible avec peu de risque.

Niveau 1 : paramètres non sensibles

Nom public d’un outil, catégorie de tâche, nombre de résultats, domaine cible. Conservation limitée selon l’usage.

Niveau 2 : contenu métier

Prompts, documents internes, réponses détaillées. Chiffrement, contrôle d’accès et durée courte.

Niveau 3 : données personnelles ou confidentielles

Identité, coordonnées, contrats, données RH ou commerciales sensibles. Collecte par exception, masquage et accès nominatif.

Niveau 4 : secrets

Clés API, mots de passe, jetons, informations de paiement. Ne jamais les écrire dans une trace.

Chaque champ collecté doit avoir une durée de conservation et un motif.

Redaction, hachage et échantillonnage

Trois techniques réduisent le risque.

Redaction

Supprime ou masque les motifs sensibles avant l’export :

• emails ;

• numéros de téléphone ;

• clés ;

• tokens ;

• identifiants de paiement ;

• chemins privés ;

• pièces jointes.

Le masquage doit intervenir dans le processus qui produit la trace, pas après l’envoi vers un service externe.

Hachage

Un hachage stable permet de savoir que deux exécutions concernent la même entrée sans conserver cette entrée.

Utilise un secret de hachage et une rotation adaptée. Un simple hash d’un email courant peut être retrouvé par dictionnaire.

Échantillonnage

Il n’est pas nécessaire de stocker toutes les exécutions normales.

Tu peux conserver :

• 100 % des erreurs ;

• 100 % des actions externes ;

• 100 % des blocages de garde-fou ;

• un échantillon des succès ordinaires ;

• une fenêtre courte des contenus détaillés.

L’échantillonnage ne doit pas effacer les preuves d’une action à risque.

Le tableau de bord qui aide vraiment

Commence par quatre vues.

Fiabilité

• taux de succès ;

• erreurs par outil ;

• exécutions sans preuve finale ;

• retries ;

• timeouts ;

• sorties bloquées.

Performance

• latence totale ;

• latence par étape ;

• appels modèle ;

• appels outils ;

• coût estimé ;

• files d’attente.

Sécurité

• garde-fous déclenchés ;

• domaines refusés ;

• secrets masqués ;

• actions à permission élevée ;

• accès aux données sensibles.

Qualité métier

• résultat accepté ;

• correction humaine ;

• motif d’échec ;

• retour utilisateur ;

• conversion utile.

Un score technique vert ne dit pas si l’agent a produit la bonne chose. Relie la trace aux résultats métier sans transformer chaque résultat en vérité automatique.

Le workflow de diagnostic

Lorsqu’une exécution échoue :

1. ouvre la trace avec son identifiant ;

2. repère le dernier span réussi ;

3. distingue erreur du modèle, de l’outil ou du contrôle ;

4. vérifie les paramètres réellement envoyés ;

5. reproduis avec des données synthétiques ;

6. corrige la cause ;

7. rejoue le cas négatif ;

8. conserve le test de régression.

Si l’échec concerne une action externe, vérifie le système cible. Une trace peut dire que l’API a répondu 200 alors que le contenu visible reste vide.

Cette boucle est la même que pour automatiser son SEO avec l’IA : créer, lire le résultat public, puis fermer la tâche avec la preuve.

Les erreurs fréquentes

Tout enregistrer par défaut

C’est rapide à installer et pénible à sécuriser. La collecte maximale augmente le coût, l’exposition et le bruit.

Utiliser les traces comme base métier

Une trace peut être échantillonnée, expirer ou contenir un état intermédiaire. Les données qui pilotent le produit doivent vivre dans une source conçue pour cela.

Confondre absence d’erreur et succès

Un agent peut terminer sans exception et produire un résultat inutilisable. Ajoute une preuve métier.

Oublier les actions parallèles

Un garde-fou exécuté en parallèle peut arriver après le début d’une action. Les opérations sensibles exigent un contrôle bloquant.

Exposer le tracing aux utilisateurs

Les traces internes peuvent contenir des noms d’outils, des instructions et des erreurs qui n’ont rien à faire dans l’interface publique. Crée un résumé sûr au lieu d’afficher la trace brute.

Questions fréquentes

Faut-il conserver les prompts complets ?

Non par défaut. Commence avec les métadonnées et active une capture détaillée bornée pour les cas à diagnostiquer. Masque les données avant export.

Combien de temps garder les traces ?

La durée dépend du risque, du volume et des obligations contractuelles. Fixe une durée courte pour le contenu détaillé et plus longue pour les métadonnées agrégées.

Peut-on tracer un agent local ?

Oui. Le collecteur peut rester sur la machine ou le réseau privé. Le principe des traces et spans ne dépend pas d’un service hébergé.

Le tracing ralentit-il l’agent ?

Il ajoute un coût. L’export asynchrone, l’échantillonnage et une instrumentation ciblée limitent cet impact. Mesure la latence avant et après.

La preuve minimale gagne

Une trace utile ne raconte pas toute la vie de l’agent. Elle relie une demande, des décisions, des actions et une preuve finale.

Commence par tracer 100 % des erreurs, actions externes et blocages. Exclue les contenus sensibles par défaut. Ajoute ensuite les champs qui répondent à une question de diagnostic réelle.

Pour recevoir nos systèmes concrets sur les agents, l’automatisation et leur mise en production, abonne-toi à la newsletter Kryve.