Je dépanne mes flux de travail Agentic : Voici comment

Salut tout le monde, Leo ici de agntdev.com. J’espère que vous passez tous une semaine productive !

Aujourd’hui, je veux explorer quelque chose qui me préoccupe beaucoup ces derniers temps, surtout depuis que j’ai bidouillé quelques projets personnels qui impliquent des workflows agentiels plus complexes et multi-étapes. Nous parlons beaucoup de la construction d’agents, des LLM eux-mêmes, et des choses cool qu’ils peuvent faire. Mais qu’en est-il de l’aspect moins glamour, mais absolument crucial, de s’assurer que nos agents fonctionnent réellement de manière fiable et efficace au fil du temps ?

Plus précisément, je parle de l’observabilité des agents. Ce n’est pas seulement une question de journalisation ; il s’agit de vraiment comprendre ce que fait votre agent, pourquoi il le fait, et de détecter les problèmes avant qu’ils ne deviennent ingérables. Dans un monde où les agents interagissent avec des API externes, prennent des décisions basées sur des entrées dynamiques, et peuvent potentiellement fonctionner pendant de longues périodes, naviguer à l’aveugle est une recette pour le désastre. J’ai appris cela à mes dépens, comme je vais l’expliquer.

Le « Bug Mystérieux » Qui M’a Tout Appris

Il y a quelques mois, je développais un agent d’assistant personnel. Appelons-le « Projet Chronos. » Son rôle était de surveiller mon calendrier, mes fils d’actualités, et des canaux Slack spécifiques, puis de proposer de manière proactive des heures de réunion, de résumer les mises à jour clés, ou même de rédiger des réponses initiales à des questions courantes. Un fonctionnement assez standard en surface.

Je l’ai construit, testé avec quelques scénarios, et il semblait fonctionner correctement. Je l’ai configuré pour fonctionner pendant la nuit, pensant que je me réveillerais avec un résumé parfaitement organisé. Au lieu de cela, je me suis réveillé avec… rien. Ou plutôt, un résumé partiel qui s’est terminé abruptement, suivi d’un message d’erreur cryptique dans mes journaux système disant essentiellement « quelque chose a échoué. »

Déboguer cela a été un cauchemar. Chronos était censé faire plusieurs choses : récupérer des événements de calendrier, interroger une API d’actualités, toucher une API Slack, traiter les données, puis générer un résumé. Quelle étape a échoué ? Pourquoi ? A-t-il même tenté toutes les étapes ? Était-ce une limite de taux d’API ? Un prompt malformé ? Un délai d’attente ? Je n’en avais aucune idée.

Ma journalisation initiale était basique : « Étape X démarrée, » « Étape Y terminée, » et ensuite la sortie finale ou une erreur. Cela n’était pas suffisant. C’était comme essayer de diagnostiquer un problème de voiture en juste sachant qu’elle a démarré puis s’est arrêtée, sans aucune information sur la température du moteur, la pression de carburant, ou les défauts électriques.

Cette expérience a souligné un point : si vous êtes sérieux au sujet du développement d’agents, vous avez besoin d’une bonne observabilité dès le premier jour. Ce n’est pas une réflexion après coup ; c’est un composant fondamental.

Au-delà de la Journalisation Basique : Que Signifie l’« Observabilité » pour les Agents ?

Pour moi, l’observabilité des agents se décompose en quelques domaines clés, chacun offrant une perspective différente sur le fonctionnement de votre agent :

1. Suivi d’Exécution Étape par Étape

C’est le plus critique. Vous devez savoir exactement ce que fait votre agent à chaque étape de son exécution. Pensez-y comme un fil d’Ariane détaillé. Pour le Projet Chronos, j’avais besoin de voir :

• Quand il a commencé à récupérer les événements de calendrier.
• Les paramètres qu’il a utilisés pour l’appel API du calendrier (par exemple, la plage de dates).
• La réponse brute de l’API du calendrier.
• Comment il a traité cette réponse.
• Le prompt exact qu’il a envoyé au LLM pour résumer les informations du calendrier.
• La réponse du LLM.
• Tous les outils appelés, avec leurs entrées et sorties.
• Les messages d’erreur, pas seulement « quelque chose a échoué », mais une erreur spécifique avec contexte (par exemple, « L’API du calendrier a retourné 401 Unauthorized pour l’utilisateur X »).

Ce niveau de détail est inestimable pour recréer des problèmes et comprendre les points de décision. Mes journaux initiaux disaient juste « Récupération des données du calendrier… » puis « Résumé des données du calendrier… » sans rien entre les deux. Pas utile quand la récupération des données elle-même a échoué silencieusement.

2. Suivi des Prompts et Réponses

Le LLM est le cerveau de votre agent. Si vous ne savez pas quels prompts il reçoit et quelles réponses il donne, vous naviguez à l’aveugle. Cela inclut :

• Le prompt complet envoyé au LLM (système, utilisateur, et toutes les descriptions des appels de fonction).
• La température, top_p, et d’autres paramètres de génération.
• La réponse brute du LLM, y compris tous les appels d’outils qu’il a décidé de faire.
• Utilisation des tokens (entrée, sortie, total) pour le suivi des coûts et l’analyse des performances.

Ceci est crucial pour l’ingénierie des prompts. Si un agent donne des réponses sans sens, voir le prompt exact qu’il a reçu vous aide à déboguer si le contexte d’entrée était incorrect ou si le prompt lui-même était mal structuré.

3. Suivi des Appels d’Outils

Les agents interagissent souvent avec des outils externes ou des API. Chaque interaction représente un point de défaillance potentiel ou un comportement inattendu. Vous devez enregistrer :

• Quel outil a été appelé.
• Les arguments exacts passés à l’outil.
• La sortie brute de l’outil.
• Toutes les erreurs retournées par l’outil ou pendant son exécution.

Pour Chronos, s’il essayait d’appeler l’API Slack pour poster un résumé, j’avais besoin de savoir le canal ciblé, le contenu du message, et si l’API revenait par exemple une erreur 403 Forbidden. Ma configuration précédente se contentait de me dire « Tentative de poster sur Slack. »

4. Captures d’État

De nombreux agents maintiennent un état interne – un bloc-notes, une mémoire, une liste de faits qu’ils ont rassemblés. Capturer régulièrement cet état peut être incroyablement utile pour le débogage. Si un agent se retrouve coincé dans une boucle ou prend une mauvaise décision, voir ses « pensées » internes à divers moments peut révéler où sa compréhension a déraillé.

Ceci concerne moins la journalisation de chaque changement de variable et plus la capture des états clés de prise de décision. Pour Chronos, cela pourrait être « Compréhension actuelle de l’emploi du temps de l’utilisateur, » ou « Points clés des fils d’actualités jusqu’à présent. »

Approches Pratiques : Intégrer l’Observabilité

D’accord, comment mettons-nous cela en œuvre sans nous noyer dans les journaux ? Voici quelques stratégies pratiques et extraits de code.

Stratégie 1 : Journalisation Structurée avec Contexte

Oubliez les déclarations `print()`. Utilisez une bibliothèque de journalisation appropriée (comme le module `logging` de Python). Il est crucial d’augmenter vos messages de journalisation avec des données structurées (JSON, dictionnaires) plutôt qu’avec de simples chaînes de caractères. Cela rend les journaux analysables, recherchables, et beaucoup plus utiles.

Voici un exemple simplifié en Python :

import logging
import json
import uuid
from datetime import datetime

# Configuration de base du logger (dans une vraie application, vous le configureriez plus solidement)
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
formatter = logging.Formatter('%(levelname)s: %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)

def log_agent_step(agent_id: str, step_name: str, status: str, details: dict = None):
 log_data = {
 "timestamp": datetime.now().isoformat(),
 "agent_id": agent_id,
 "step_name": step_name,
 "status": status, # par exemple, "started", "completed", "failed"
 "details": details if details is not None else {}
 }
 logger.info(json.dumps(log_data))

class MyAgent:
 def __init__(self, agent_id: str = None):
 self.agent_id = agent_id if agent_id else str(uuid.uuid4())
 self.memory = [] # Mémoire interne simple

 def _fetch_calendar_events(self, user_id: str, date_range: str):
 log_agent_step(self.agent_id, "fetch_calendar_events", "started", 
 {"user_id": user_id, "date_range": date_range})
 try:
 # Simuler un appel API
 if "error" in date_range:
 raise ValueError("Erreur simulée de l'API calendrier")
 
 events = [
 {"title": "Réunion d'équipe", "time": "10:00 AM"},
 {"title": "Réunion client", "time": "02:00 PM"}
 ]
 log_agent_step(self.agent_id, "fetch_calendar_events", "completed", 
 {"num_events": len(events), "data_preview": events[0]})
 self.memory.append(f"Événements du calendrier : {events}")
 return events
 except Exception as e:
 log_agent_step(self.agent_id, "fetch_calendar_events", "failed", 
 {"error": str(e), "traceback": "..."}) # Dans la vie réelle, capturer la trace
 raise

 def _summarize_with_llm(self, prompt_text: str):
 log_agent_step(self.agent_id, "summarize_with_llm", "started", 
 {"prompt_length": len(prompt_text), "prompt_preview": prompt_text[:100]})
 try:
 # Simuler un appel LLM
 if "fail_llm" in prompt_text:
 raise RuntimeError("Erreur simulée de l'API LLM")
 
 response = f"Résumé LLM de : {prompt_text[:50]}..."
 token_usage = {"input": len(prompt_text) // 4, "output": len(response) // 4}
 log_agent_step(self.agent_id, "summarize_with_llm", "completed", 
 {"response_length": len(response), "token_usage": token_usage, 
 "llm_response_preview": response[:100]})
 self.memory.append(f"Résumé produit par LLM : {response}")
 return response
 except Exception as e:
 log_agent_step(self.agent_id, "summarize_with_llm", "failed", 
 {"error": str(e), "traceback": "..."})
 raise

 def run_daily_briefing(self, user_id: str):
 log_agent_step(self.agent_id, "run_daily_briefing", "started", {"user_id": user_id})
 try:
 calendar_data = self._fetch_calendar_events(user_id, "today")
 news_summary = self._summarize_with_llm("Résumer les principales nouvelles d'aujourd'hui...")
 
 final_briefing_prompt = (
 f"Créer un briefing quotidien basé sur :\n"
 f"Calendrier : {json.dumps(calendar_data)}\n"
 f"Nouvelles : {news_summary}"
 )
 final_briefing = self._summarize_with_llm(final_briefing_prompt)
 
 log_agent_step(self.agent_id, "run_daily_briefing", "completed", 
 {"final_briefing_length": len(final_briefing)})
 return final_briefing
 except Exception as e:
 log_agent_step(self.agent_id, "run_daily_briefing", "failed", 
 {"error": str(e), "current_memory": self.memory}) # Capturer la mémoire en cas d'échec
 raise

# Exemple d'utilisation
if __name__ == "__main__":
 agent = MyAgent()
 print(f"\n--- Exécution de l'agent {agent.agent_id} (Cas de succès) ---")
 try:
 briefing = agent.run_daily_briefing("leo_g")
 print(f"Briefing : {briefing[:100]}...")
 except Exception as e:
 print(f"L'exécution de l'agent a échoué : {e}")

 agent_fail = MyAgent()
 print(f"\n--- Exécution de l'agent {agent_fail.agent_id} (Cas d'échec du calendrier) ---")
 try:
 # Simuler un échec du calendrier en passant "error" dans date_range
 agent_fail._fetch_calendar_events("leo_g", "error_today") 
 except Exception as e:
 print(f"L'exécution de l'agent a échoué comme prévu : {e}")

 agent_llm_fail = MyAgent()
 print(f"\n--- Exécution de l'agent {agent_llm_fail.agent_id} (Cas d'échec LLM) ---")
 try:
 # Simuler un échec LLM
 agent_llm_fail._summarize_with_llm("fail_llm_please")
 except Exception as e:
 print(f"L'exécution de l'agent a échoué comme prévu : {e}")

Remarquez comment `log_agent_step` capture l’ID de l’agent, le nom de l’étape, le statut et un dictionnaire de détails pertinents. Cela facilite le filtrage des journaux par ID d’agent, le suivi d’une exécution unique ou la recherche de toutes les étapes “échouées”.

Stratégie 2 : Observabilité centralisée avec une bibliothèque/service dédié

Pour des agents plus complexes ou des environnements de production, vous dépasserez rapidement le simple journalage de fichiers. C’est là que des outils spécialisés brillent. Des bibliothèques comme `LangSmith` de LangChain (ou similaires pour d’autres frameworks) fournissent un traçage intégré, de la visualisation et du débogage pour les applications LLM.

Même si vous n’utilisez pas LangChain, le concept est transférable. Vous pouvez créer votre propre wrapper autour de l’exécution de votre agent qui envoie des événements structurés à un service de journalisation (Datadog, Splunk, pile ELK, ou même un simple bucket S3 avec traitement Lambda). L’essentiel est de standardiser le schéma des événements.

Mon projet Chronos amélioré utilise maintenant une classe `TraceManager` personnalisée qui enveloppe les opérations critiques. Ce gestionnaire envoie des événements structurés à une base de données locale pour le développement et à un service de journalisation dans le cloud en production. Cela me permet de voir un “trace” complet de chaque exécution d’agent, avec des étapes imbriquées et toutes les données associées (invite, réponses, entrées/sorties d’outils, erreurs).

Stratégie 3 : Interception des appels LLM et des outils

De nombreux SDK LLM vous permettent de configurer des rappels ou des interceptors pour les appels API. Utilisez-les ! Au lieu de journaliser manuellement avant et après chaque invite LLM, vous pouvez avoir un seul interceptor qui journalise automatiquement :

• L’endpoint API exact utilisé.
• Les en-têtes et le corps de la requête (en particulier l’invite).
• Les en-têtes et le corps de la réponse (la complétion).
• La latence.
• Toutes les exceptions.

De même, encapsulez vos appels d’outils. Si vous avez un outil `search_web`, le wrapper doit journaliser la requête de recherche, le moteur de recherche utilisé et les N meilleurs résultats retournés, ainsi que toutes les erreurs.

Conseils Actionnables pour Votre Prochain Projet d’Agent

1. Concevez d’abord pour l’Observabilité : Ne le considérez pas comme une réflexion après coup. Pensez à ce dont vous auriez besoin pour déboguer avant même d’écrire votre première étape d’agent.
2. Adoptez le Journalage Structuré : Abandonnez `print()` et `console.log()` pour le code de production. Utilisez une bibliothèque de journalisation appropriée et sortez des données structurées (JSON) pour chaque événement significatif.
3. Tracez Tout ce qui est Important : Journalisez le début et la fin de chaque étape majeure, toutes les invites et réponses LLM (y compris les paramètres et les comptes de tokens), et chaque appel d’outil avec ses entrées et sorties.
4. Capturer l’État en Cas d’Échec : Lorsqu’un agent échoue, journalisez son état interne ou sa mémoire à ce moment-là. Cela fournit un contexte crucial pour comprendre pourquoi il a échoué.
5. Utilisez des IDs Spécifiques à l’Agent : Assignez un ID unique à chaque exécution d’agent (par exemple, un UUID). Cela vous permet de filtrer et de suivre facilement un chemin d’exécution unique à travers vos journaux.
6. Visualisez Vos Traces : Si possible, utilisez ou créez un outil qui peut visualiser ces journaux structurés comme une séquence d’événements. Voir le flux rend le débogage infiniment plus facile que de traiter du texte brut. LangSmith le fait magnifiquement, mais même un script personnalisé peut rendre une simple chronologie HTML.
7. Surveillez les Coûts : L’utilisation des tokens LLM représente un coût direct. Journalisez-le. Cela vous aide à comprendre où va votre argent et à optimiser vos invites.

Construire des agents est excitant, mais construire des agents fiables est là où se trouve le véritable travail (et la véritable valeur). Et la fiabilité commence par savoir ce qui se passe en coulisse. Mon expérience douloureuse avec le projet Chronos m’a bien enseigné cette leçon. N’attendez pas votre propre “bogue mystérieux” pour vous convaincre. Commencez à journaliser intelligemment dès aujourd’hui.

Quelles sont vos stratégies d’observabilité préférées pour les agents ? Écrivez-moi dans les commentaires ou sur les réseaux sociaux. Je suis toujours intéressé de savoir comment les autres relèvent ces défis !

🕒 Published: March 26, 2026