Un workflow linéaire se débugge avec deux logs. Un agent qui décide lui-même quel tool appeler, parfois sur 12 tours, est ingérable sans traçage structuré. Quand un utilisateur dit « ça a répondu n'importe quoi », tu dois pouvoir rejouer la session.

Ce qu'il faut tracer

Requête Tour LLM+ décision tool Tool exécutéargs + résultat Tour LLMboucle ou fin
Chaque tour : prompt envoyé, décision, tool + args + résultat, tokens, latence. Une trace par session, corrélée par un run_id.

Le minimum à logger par tour

  • run_id commun à toute la session + numéro de tour
  • Prompt exact envoyé (ou son hash + version, cf. Prompt versioning en prod)
  • Décision du modèle : quel tool, quels arguments
  • Résultat du tool (tronqué si volumineux)
  • Tokens in/out et latence par tour (pas seulement le total)
  • Condition d'arrêt : réponse finale, max tours atteint, erreur

Pourquoi par tour et pas global

Le coût et la latence d'un agent explosent par accumulation de tours. Sans granularité par tour, tu vois « 14 s et 0,18 € » sans savoir que le tour 7 a rebouclé trois fois sur un tool qui échoue. La trace par tour transforme une boîte noire en quelque chose d'optimisable — souvent, réduire le nombre de tours est le plus gros levier de coût.

FAQ

Pourquoi les logs classiques ne suffisent-ils pas pour un agent ?

Un agent peut enchaîner une dizaine de tours de décision ; sans trace structurée par tour, il est impossible de rejouer ce qui s'est passé.

Que faut-il logger à chaque tour ?

Le prompt envoyé, la décision prise, le tool appelé avec ses arguments et son résultat, les tokens et la latence.

Pourquoi tracer par tour plutôt que juste au niveau de la session ?

Parce que la dérive se produit souvent à un tour précis — un log global ne permet pas de l'isoler.