Checklist de mise en production d'un agent IA : logs, monitoring, alertes, rollback et canary release

Vendredi après-midi, vous vous apprêtez à ouvrir votre agent de support client à 5 % des utilisateurs. Les paramètres de canary sont prêts : part de trafic, fenêtre d’observation, seuils d’alerte. Au dernier contrôle, trois problèmes apparaissent :

1. Il n’y a pas de feature flag ; pour couper l’agent, il faut redéployer.
2. Personne ne sait comment basculer vers l’ancienne version les tâches déjà présentes dans la file d’approbation humaine.
3. Il n’est pas clair si les e-mails déjà envoyés comptent comme effets de bord d’outil, ni s’il faut les annuler lors du rollback.

Ces trois problèmes ne se voient ni dans un HTTP 500 ni dans un temps de réponse. La mise en production d’un agent exige huit dimensions de plus qu’un service web : trace, tool calls, guardrails, HITL, eval, cost, secrets, checkpoint. La checklist ci-dessous les organise en quatre groupes : portes avant release, observation du canary, monitoring post-release et rollback d’incident.

1. Portes avant release : dix contrôles à faire passer

1.1 Vérifier la complétude des traces

Avant la release, il faut confirmer qu’une trace peut reconstruire un Agent run complet. Sinon, impossible de rejouer proprement l’incident. OpenAI Agents SDK intègre le tracing et enregistre LLM generations, tool calls, handoffs, guardrails et custom events. Mais la conservation complète de ces informations en production doit être vérifiée point par point.

Checklist :

• run ID, trace ID et span ID sont correctement associés, et un log d’erreur permet de remonter à une requête précise.
• model call, tool call et guardrail result sont enregistrés complètement, sans champ manquant.
• les champs de durée, d’usage token et de code d’erreur sont disponibles, afin de calculer les baselines de coût et de performance.
• la politique de conservation et les règles de masquage des traces sont explicites, pour éviter les suppressions silencieuses liées au coût de stockage ou au risque conformité.
• le comportement d’export des traces est cohérent entre développement et production.

Si la trace ne contient que le LLM call, sans tool call ni guardrail result, un canary peut afficher HTTP 200 alors que les paramètres d’outil sont faux ou que les permissions débordent.

1.2 Politique de masquage des données sensibles

Les traces de production peuvent contenir des PII, des secrets et des données client. Avant le lancement, décidez ce qui est capturé et comment c’est masqué. OpenAI Agents SDK fournit trace_include_sensitive_data, qui contrôle l’enregistrement des entrées et sorties complètes des LLM et tool calls.

Checklist :

• l’emplacement et la valeur par défaut de trace_include_sensitive_data sont clairs.
• la détection et le masquage des PII couvrent les champs courants : nom, e-mail, téléphone.
• l’isolation des secrets est en place, afin que les API key et mots de passe de base de données n’apparaissent pas dans les traces ou les logs.
• les données client sont classées public/interne/confidentiel, avec des règles de masquage différentes selon le niveau.
• les traces masquées restent utiles pour le debugging.

En production, combinez détection automatique des PII et masquage par niveau. On couvre ainsi la conformité sans perdre la capacité de diagnostic.

1.3 Porte de monitoring des guardrails

Les guardrails valident les entrées utilisateur et les sorties de l’agent, et peuvent utiliser un modèle plus rapide ou moins cher pour bloquer les requêtes non conformes. Le tool input guardrail d’OpenAI Agents SDK s’exécute avant l’appel d’un function tool. Mais les guardrails ne sont pas une défense absolue. Avant release, vérifiez qu’ils sont observables, alertables et intégrés au rollback.

Checklist :

• la baseline du taux de blocage de l’input guardrail a été mesurée.
• les taux de faux positifs et de faux négatifs de l’output guardrail sont connus.
• le tool input guardrail s’exécute avant l’appel d’outil.
• les seuils d’alerte de guardrail trip sont configurés.
• un chemin de feedback rapide existe pour les faux positifs.

La porte guardrails tient en une phrase : le taux de blocage a une baseline, les faux positifs ont un feedback, les alertes ont des seuils.

1.4 Observabilité des Tool Calls

L’échec d’appel d’outil est l’un des modes de panne les plus fréquents pour un agent. L’API HTTP peut retourner 200 alors que les paramètres d’outil sont faux, que les permissions débordent ou qu’un service externe timeout. Le monitoring classique ne voit pas ces erreurs ; elles apparaissent dans les traces.

Checklist :

• la baseline de succès et d’échec est mesurée pour chaque outil.
• la distribution de latence des appels d’outils (P50/P95/P99) est connue.
• les frontières de permission sont explicites, avec allowlist ou denylist des ressources accessibles par outil.
• les modes d’échec sont classés : timeout, permission, erreur de paramètre, panne de service externe, avec des traitements différents.
• la stratégie de retry et les seuils de circuit breaker sont configurés.

L’observabilité des outils demande une baseline de succès par outil, une classification des échecs et un circuit breaker pour les timeouts.

1.5 Préparer le monitoring de la file HITL

L’accumulation dans une file Human-in-the-Loop (HITL) est un risque facile à manquer pendant un canary. Les checkpointers LangGraph sauvegardent le graph state à chaque super-step et prennent en charge HITL, time travel et fault tolerance. Mais la longueur de file et les timeouts d’approbation doivent être monitorés séparément.

Checklist :

• les seuils d’alerte de longueur de file HITL sont configurés.
• la stratégie automatique en cas de timeout d’approbation est claire : rejet, passage à un humain ou dégradation.
• le chemin de resume après interruption a été vérifié.
• la façon de traiter les tâches déjà en file lors d’un changement de version est définie.

La file HITL doit avoir un seuil, une stratégie de timeout et une reprise validée après interruption.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

1.6 Eval Regression Suite

Avant la release, exécutez votre propre regression suite pour éviter les régressions de capacité. Elle doit contenir de vraies tâches, pas seulement des synthetic examples. Si le taux de réussite tombe sous la baseline, la nouvelle version est probablement risquée.

Checklist :

• la regression suite contient assez de tâches réelles.
• la baseline de taux de réussite est explicite (recommandé : ≥95 %).
• les cas échoués sont clairement classés.
• le temps d’exécution de la suite est maîtrisé (recommandé : ≤15 minutes).
• le mécanisme de réinjection des échantillons échoués du canary est prêt.

La regression suite est la dernière porte. Si le taux de réussite est sous 95 %, mieux vaut corriger avant de lancer.

1.7 Cost Budget et Rate Limit

Les limites de coût et de débit au niveau plateforme sont la dernière barrière. OpenAI recommande usage tracking, billing limits, notification threshold et project-level spend/rate limits. Ne vous reposez pas seulement sur la logique budgétaire dans le code métier.

Checklist :

• les project-level spend limits sont configurés.
• les usage notification thresholds sont réglés (recommandé : 70 %/90 %).
• les rate limits sont segmentés par utilisateur ou tenant.
• les alertes de hausse soudaine des coûts sont configurées, par exemple en comparaison horaire.
• la stratégie de dégradation est claire : désactiver les outils coûteux, changer de modèle ou limiter les utilisateurs en cas de dépassement.

Le budget de coût doit avoir une limite, les alertes doivent avoir des seuils, et le dépassement doit avoir un chemin de dégradation.

1.8 Isolation des Secrets et audit

La fuite de secrets est l’un des incidents les plus graves pour un agent. Un agent peut accéder à des bases de données, API tierces et services internes via des tool calls. Chaque appel doit être auditable. Les quatre champs actor/subject/tool/resource doivent être complets.

Checklist :

• les champs actor/subject/tool/resource sont tous enregistrés.
• le stockage des secrets est isolé ; API key et mots de passe de base de données n’apparaissent pas dans les variables d’environnement ou fichiers de configuration.
• la validation des secrets s’exécute avant l’appel d’outil.
• la durée de conservation des journaux d’audit est explicite (recommandé : 1 an).
• un plan de rotation des clés existe.

Les journaux d’audit sont essentiels pour la revue d’incident.

1.9 Valider la reprise par Checkpoint

Un agent long doit pouvoir revenir au bon état après un échec. Les checkpointers LangGraph sauvegardent le graph state à chaque super-step et prennent en charge time travel debugging et fault-tolerant execution. Le chemin de reprise doit néanmoins être testé séparément.

Checklist :

• la fréquence de sauvegarde des checkpoints est claire, à chaque super-step ou à chaque nœud important.
• le test de reprise après échec a été exécuté.
• la correction de l’état après reprise a été vérifiée.
• la stratégie de nettoyage des tâches à moitié terminées est claire.

La reprise par checkpoint est une capacité de base pour les agents longs.

1.10 Feature Flag et Kill Switch

Vous devez pouvoir désactiver l’agent sans redéploiement. OpenFeature fournit un modèle standard de feature flag, avec ciblage par tenant, utilisateur, type de tâche et rollout en pourcentage.

Checklist :

• le feature flag est segmenté par tenant, utilisateur ou type de tâche.
• le kill switch prend effet en moins d’une minute.
• le rollout en pourcentage est pris en charge et utilisable pour le canary release.
• le monitoring et l’audit de l’état des flags sont configurés.

Le contrôle Feature Flag exige un contrôle segmenté, un effet rapide et un audit d’état.

2. Observation du canary : quoi regarder pendant les 10-30 premières minutes

Des portes avant release réussies ne garantissent pas un canary sans problème. Un canary d’agent doit suivre deux couches de métriques : les métriques service (taux d’erreur HTTP, temps de réponse) et les métriques agent (tool failure rate, guardrail trip rate, cost per run, HITL queue).

2.1 Part de trafic et fenêtre d’observation

Un canary ne se pilote pas au ressenti. Kubernetes et AWS recommandent de commencer avec peu de trafic, de définir une période d’évaluation suffisante, de surveiller les métriques, puis d’élargir progressivement. Les paramètres de trafic et de durée doivent être définis.

Checklist :

• la part initiale de trafic est claire (recommandé : 5-10 %).
• la fenêtre minimale d’observation est définie (recommandé : 10-30 minutes).
• le nombre minimal de requêtes dans la fenêtre est configuré.
• les conditions d’élargissement progressif du trafic sont définies.

La part de trafic et la fenêtre d’observation sont les paramètres de base du canary. Si 5 % de trafic déclenchent une alerte en 10 minutes, la nouvelle version a un problème sérieux et doit être rollbackée immédiatement.

2.2 Monitoring des métriques de service

Le taux d’erreur HTTP, le temps de réponse et le débit sont la première couche d’un canary, comme pour un service classique. Mais si vous ne regardez que cette couche, vous pouvez manquer les pannes propres aux agents.

Checklist :

• le seuil de taux d’erreur HTTP 5xx est configuré (recommandé : ≤1 %).
• le seuil de temps de réponse P95 est clair.
• l’évolution du débit par rapport à la baseline est monitorée.
• l’utilisation CPU/mémoire est monitorée.
• le taux d’erreur réseau est monitoré.

Les métriques de service sont la première ligne de défense, pas toute l’image. Un agent peut répondre HTTP 200 tout en ratant ses tool calls, en contournant les guardrails ou en faisant exploser les coûts.

2.3 Monitoring des métriques Agent

Les métriques propres aux agents forment la deuxième couche du canary. Le monitoring de service classique ne les couvre pas. Elles vivent dans les traces, pas dans les logs HTTP.

Checklist :

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

• tool failure rate est monitoré par outil.
• guardrail trip rate est monitoré par type.
• cost per run est monitoré par rapport à la baseline précédente.
• la longueur de la file HITL est monitorée en temps réel.
• eval drift est monitoré si disponible.

Les métriques agent doivent être classées par outil et par type, pas noyées dans une moyenne.

2.4 Conditions d’alerte et rollback automatique

Un canary doit pouvoir rollbacker automatiquement. Il ne peut pas dépendre d’une personne qui surveille un écran. La documentation AWS recommande des CloudWatch alarms pour déclencher le rollback automatique, avec conditions et chemins explicites.

Checklist :

• les conditions de déclenchement du rollback automatique sont définies.
• le chemin de bascule du trafic après rollback est clair.
• la fenêtre d’observation après rollback est définie.
• le processus de confirmation humaine et d’escalade est défini.

Le rollback automatique exige des déclencheurs clairs, un chemin de rollback clair et une confirmation humaine quand elle est nécessaire.

3. Monitoring après release : la production ne s’arrête pas au lancement

Un canary réussi n’est pas une garantie de production readiness. Après la release, il faut continuer à surveiller la qualité des traces, l’usage des coûts, l’effet des guardrails et l’eval regression, afin d’éviter la dérive de capacité ou les hausses de coût.

3.1 Monitoring de la qualité des traces

Après la release, des traces peuvent disparaître, arriver en retard ou perdre des champs. Cela gêne le debugging et la revue d’incident. Le monitoring de qualité des traces doit être séparé des métriques de service.

Checklist :

• la complétude des traces est monitorée ; une corrélation run ID sous la baseline déclenche une alerte.
• la latence des traces est monitorée ; un délai trop long avant requêtage déclenche une alerte.
• le taux d’échantillonnage des traces est configuré ; le downsampling réduit les coûts de stockage en cas de fort trafic.
• le coût de stockage des traces est monitoré.

La qualité trace exige une baseline de complétude, un seuil de latence et un budget de coût.

3.2 Monitoring continu de Cost et Usage

La hausse soudaine des coûts est l’un des incidents de production les plus fréquents pour un agent. Usage token anormal, mauvais choix de modèle ou hausse de fréquence des tool calls peuvent faire exploser la facture. OpenAI recommande usage tracking et notification threshold.

Checklist :

• les tendances quotidiennes de cost sont monitorées, avec comparaison jour sur jour et semaine sur semaine.
• l’usage token est monitoré par modèle et par utilisateur.
• les outils coûteux sont identifiés.
• la vitesse de consommation du budget est monitorée.
• un circuit breaker automatique est configuré en cas de dépassement.

Le monitoring des coûts demande des comparaisons de tendance, une classification par modèle et un circuit breaker budgétaire.

3.3 Monitoring continu des Guardrails

Une variation du taux de blocage des guardrails peut signaler une attaque ou un faux positif. Une hausse du taux de blocage input guardrail peut indiquer plus de prompts malveillants. Une hausse du false positive rate output guardrail peut signifier que la règle est trop stricte.

Checklist :

• la tendance du taux de blocage input guardrail est monitorée.
• le false positive rate output guardrail est monitoré.
• la collecte de feedback guardrail false positive/negative est complète.
• les règles de guardrails sont évaluées régulièrement.

Le monitoring guardrails demande une tendance de blocage, un feedback sur les faux positifs et des règles mises à jour.

3.4 Eval regression continue

Après release, continuez à vérifier que la capacité ne régresse pas. Exécutez la regression suite chaque jour ou chaque semaine, alertez sur les cas échoués et ajoutez les nouveaux échecs à la suite.

Checklist :

• les exécutions quotidiennes ou hebdomadaires de la regression suite sont automatisées.
• les cas échoués déclenchent des alertes automatiquement.
• les nouveaux cas échoués sont ajoutés à la suite.
• la gestion de version de la regression suite est en place.

Eval regression signifie exécution régulière, alerte sur échec et réinjection des cas.

4. Rollback d’incident : le plus difficile, ce sont les effets de bord des outils

Le rollback d’un agent est plus complexe que celui d’un service classique. Un service classique peut souvent revenir à une version de code. Un agent doit aussi traiter les effets de bord d’outils déjà exécutés, les workflows à moitié terminés et les tâches dans les files d’approbation humaine.

4.1 Rollback du code

Le rollback du code est le chemin le plus simple. Kubernetes Deployment prend en charge rolling update et rollback, mais la fenêtre de rollback doit rester sous 5 minutes.

Checklist :

• le chemin de rollback de version de code est clair.
• la bascule de trafic après rollback a été vérifiée.
• la validation après rollback, comme un smoke test, est exécutée.
• la fenêtre de rollback est définie (recommandé : ≤5 minutes).

Le rollback de code exige un chemin clair, une bascule vérifiée et une fenêtre limitée.

4.2 Rollback des effets de bord d’outils

Le plus difficile dans un rollback d’agent, ce sont les effets de bord déjà produits par les outils. Envoyer un e-mail, créer une commande, appeler une API externe : ces actions ne disparaissent pas parce que le code revient en arrière. Il faut distinguer opérations idempotentes et non idempotentes, puis définir des actions de compensation.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Checklist :

• les opérations d’outil déjà exécutées sont identifiées, et tous les tool calls exécutés sont retrouvables dans les traces.
• les opérations idempotentes peuvent être rejouées en sécurité.
• les opérations non idempotentes ont des actions de compensation : envoyer un e-mail correctif, annuler une commande, appeler une API d’annulation.
• la stratégie de nettoyage des tâches à moitié terminées est claire.
• le processus de secours humain est défini.

Le rollback des effets de bord demande d’identifier les opérations exécutées, d’évaluer l’idempotence et de concevoir les compensations.

4.3 Nettoyer la file HITL

Lors d’un rollback, la file d’approbation humaine peut contenir des tâches à moitié terminées. La nouvelle version de l’agent peut avoir escaladé des tâches en HITL, alors que l’ancienne version n’exige pas d’approbation humaine. Les tâches en file doivent être réassignées ou remises en arrière.

Checklist :

• les tâches de la file sont identifiées par label de version.
• la stratégie de réassignation est claire.
• le traitement du timeout d’approbation est défini.
• le flux de confirmation humaine est complet.

Le nettoyage de file HITL exige une identification par version, une stratégie de réassignation et un traitement des timeouts.

4.4 Conservation des traces et journaux d’audit

Une revue d’incident demande des traces et journaux d’audit complets. OpenTelemetry traite les logs comme l’un des telemetry signals et peut les intégrer aux logging frameworks existants.

Checklist :

• la durée de conservation des traces est claire (recommandé : 30-90 jours).
• la durée de conservation des journaux d’audit est claire (recommandé : 1 an).
• les règles de masquage des données sensibles sont complètes.
• les exigences de conformité du secteur sont respectées.

La conservation trace et audit exige une durée adaptée, des règles de masquage complètes et une couverture conformité.

4.5 Réinjecter les échantillons échoués dans l’Eval Suite

Après un incident, les échantillons échoués doivent rejoindre la regression suite pour éviter la répétition. L’extraction part des traces pour trouver les failed cases, puis un humain étiquette la cause d’échec et le comportement attendu.

Checklist :

• un outil ou script d’extraction des échantillons échoués existe.
• l’étiquetage des échantillons est confirmé par un humain.
• un processus existe pour ajouter les échantillons à la regression suite.
• un mécanisme empêche la répétition du même type d’incident.

La réinjection des échecs demande extraction, étiquetage humain, ajout à la suite et validation du correctif.

Conclusion

La mise en production d’un agent exige huit dimensions de plus qu’un service web : trace, tool calls, guardrails, HITL, eval, cost, secrets, checkpoint. Ces huit dimensions se regroupent en quatre checklists :

Portes avant release (10 contrôles) : complétude des traces, masquage des données sensibles, monitoring des guardrails, observabilité des Tool Calls, préparation de la file HITL, Eval Regression Suite, Cost Budget et Rate Limit, isolation des Secrets et audit, validation de reprise par Checkpoint, Feature Flag et Kill Switch. Vérifiez-les une par une avant release ; ce qui échoue doit bloquer le lancement.

Observation du canary (4 contrôles) : part de trafic et fenêtre d’observation, monitoring des métriques de service, monitoring des métriques agent, conditions d’alerte et rollback automatique. Un canary ne regarde pas seulement le taux d’erreur HTTP ; il surveille aussi tool failure rate, guardrail trip rate, cost per run et HITL queue length.

Monitoring après release (4 contrôles) : qualité des traces, Cost et Usage, guardrails continus, eval regression continue. Un canary propre ne suffit pas ; le monitoring continu évite la dérive de capacité et l’explosion de coûts.

Rollback d’incident (5 contrôles) : rollback du code, rollback des effets de bord d’outils, nettoyage de file HITL, conservation trace et audit, réinjection des échantillons échoués dans l’Eval Suite. Rollbacker ne consiste pas seulement à revenir à une version de code. Il faut aussi traiter les effets de bord d’outils déjà exécutés, les workflows à moitié terminés et les files d’approbation humaine.

Conservez ces quatre checklists comme modèle et parcourez-les avant chaque release. Si un contrôle échoue, corrigez-le avant la mise en ligne au lieu d’emmener un problème connu dans le canary.