Voir ce que fait
votre agent.

1. Pourquoi l'observabilité change tout

Un agent IA en production fait potentiellement des centaines à des milliers d'actions par jour. Chaque action déclenche un appel LLM (avec un coût), peut appeler des outils, peut produire des résultats variables.

Sans observabilité, vous êtes aveugle :

• Vous ne savez pas combien ça vous coûte vraiment par jour ou par cas d'usage
• Vous ne détectez pas les régressions (un changement de prompt qui a baissé la qualité)
• Vous ne pouvez pas débugger quand un client se plaint d'une mauvaise réponse
• Vous ne savez pas quels outils sont les plus utilisés et lesquels jamais
• Vous ne pouvez pas optimiser ce que vous ne mesurez pas

Mettre en place l'observabilité dès le début vous fait gagner des semaines à long terme. C'est l'équivalent de mettre des compteurs dans une voiture : sans eux, vous roulez à l'aveuglette.

2. Les 3 piliers de l'observabilité

Pilier 1 : Logs (les détails)

Les logs sont le journal exhaustif de chaque action de l'agent. Pour chaque exécution, vous capturez :

• Input : ce que l'agent a reçu (question utilisateur, données d'entrée)
• Prompt complet : ce qui a été envoyé au LLM (system prompt + contexte + question)
• Réponse LLM : texte brut généré, avec tokens consommés
• Outils appelés : nom, paramètres, résultats
• Output final : ce qui a été produit/envoyé/stocké
• Métadonnées : timestamp, durée totale, coût estimé, modèle utilisé

Les logs servent surtout au debugging : quand un cas spécifique pose problème, on retrouve l'historique complet et on comprend.

Pilier 2 : Traces (l'arbre d'exécution)

Une trace est la représentation visuelle d'une exécution, montrant l'enchaînement des appels. Particulièrement utile en multi-agents ou agents avec planification.

Une trace ressemble à un arbre :

Les traces servent à identifier les goulots d'étranglement : quel appel LLM est le plus long ? Lequel coûte le plus ? Quel outil échoue le plus souvent ?

Pilier 3 : Métriques (les agrégats)

Les métriques sont des chiffres agrégés sur des périodes (heure, jour, mois). Ce qu'on suit typiquement :

• Coût : par jour, par agent, par cas d'usage
• Volume : nombre d'exécutions par jour
• Latence : temps moyen et p95 par exécution
• Taux d'erreur : exécutions qui échouent / total
• Taux de succès métier : exécutions qui atteignent l'objectif (à définir par cas)
• Taux d'escalade HITL : combien d'actions remontent à l'humain
• Tokens consommés : input et output, par modèle

Les métriques servent au pilotage : vous voyez les tendances, détectez les anomalies, optimisez ce qui doit l'être.

3. Outils d'observabilité spécialisés

Outil 1 : Langfuse (open-source)

Langfuse est l'outil open-source de référence en 2026. Il capture automatiquement traces, logs, métriques pour vos agents IA.

Avantages :

• Gratuit et open-source (auto-hébergeable)
• Intégrations natives avec OpenAI, Anthropic, LangChain, LlamaIndex
• Interface web complète : explorer traces, comparer prompts, A/B testing
• Capture du coût en temps réel
• Cloud managé disponible (free tier puis 50 €/mois)

Recommandation AzenFlow : auto-hébergé sur le même VPS Hostinger France que n8n. Tout reste souverain.

Outil 2 : Helicone (cloud)

Helicone est un proxy entre votre application et l'API LLM. Tous les appels passent par Helicone qui logge automatiquement.

Avantages :

• Setup ultra rapide (changer l'URL de l'API)
• Gratuit jusqu'à 100 000 requêtes/mois
• Cache LLM intégré (économie réelle)
• Alertes sur dépassement de seuils

Limites : proxy externe (US), donc moins souverain que Langfuse self-hosted.

Outil 3 : LangSmith (LangChain)

LangSmith est l'outil officiel de LangChain. Si vous codez vos agents en Python avec LangChain, c'est très intégré.

Avantages :

• Très bonne intégration LangChain
• Dataset management (créer des jeux de tests)
• Évaluation automatique de qualité

Limites : plus pertinent pour les développeurs Python que pour les déploiements no-code n8n. Coût significatif au-delà du free tier (à partir de 39 $/mois).

Outil 4 : Dashboards n8n (gratuit, intégré)

n8n a un système d'exécutions logguées en interne. Pour chaque workflow, vous voyez :

• Toutes les exécutions (succès, erreurs)
• Données d'entrée et de sortie de chaque nœud
• Durée par étape
• Possibilité de "replay" une exécution

Pour démarrer, c'est largement suffisant. Vous pouvez ajouter Langfuse plus tard pour des analyses plus avancées sur les coûts et la qualité LLM.

4. Architecture observabilité PME

Pour une PME française qui démarre, voici l'architecture recommandée par AzenFlow :

5. Patterns de debugging

Quand un agent ne fait pas ce qu'il faut, voici la démarche systématique pour identifier le problème.

Étape 1 : Reproduire

Avant tout : reproduire le cas problématique. Récupérer l'input exact qui a posé problème (depuis les logs ou les retours utilisateur) et relancer l'agent dans le même contexte. Si vous ne reproduisez pas, vous corrigez à l'aveugle.

Astuce n8n : utilisez "Execute previous run" pour rejouer une exécution précise.

Étape 2 : Isoler la couche défaillante

Le problème vient d'où ? Trois couches possibles :

• Couche LLM : la réponse du modèle est mauvaise (invente, contredit, hors scope)
• Couche outils : un outil retourne des données fausses ou mal formatées
• Couche orchestration : la logique du workflow est buggée (mauvaise condition, étape manquante)

Regardez la trace pas-à-pas : où le résultat commence à diverger de l'attendu ?

Étape 3 : Tester en isolation

Une fois la couche identifiée :

• Si LLM : refaire l'appel LLM seul (sans le reste du workflow) avec exactement le même prompt. Si l'erreur revient, c'est le prompt à corriger. Si elle ne revient pas, le contexte est en cause.
• Si outil : appeler l'outil seul avec les paramètres exacts. Voir s'il retourne ce qu'on attend.
• Si orchestration : vérifier les conditions, les variables, les enchaînements dans le workflow.

Étape 4 : Corriger et tester

Appliquer le fix, retester sur le cas problématique, ET sur 5-10 autres cas similaires pour ne pas créer de régression. Documenter le fix dans un journal d'incidents.

6. Erreurs typiques et leur diagnostic

Symptôme : "L'agent invente des informations"

Diagnostic : hallucination du LLM. Causes possibles : prompt système flou, pas de contexte fourni, modèle trop "creative" (temperature trop haute). Fixes : renforcer le system prompt avec "Si tu ne sais pas, dis 'je ne sais pas'", baisser la temperature à 0.1, fournir plus de contexte via RAG.

Symptôme : "L'agent boucle sur la même action"

Diagnostic : mauvaise interprétation du résultat de l'outil par le LLM. Causes : le résultat de l'outil n'est pas clair (format ambigu), la limite d'itérations n'est pas configurée. Fixes : améliorer le format de retour des outils (JSON structuré clair), configurer maxIterations.

Symptôme : "Coût exploite soudain"

Diagnostic : souvent un workflow en boucle ou un cas où le contexte grossit anormalement. Investigation : regardez les exécutions les plus chères du jour, identifiez le pattern. Fixes : tronquer les inputs trop gros avant LLM, ajouter limite de coût par exécution, vérifier les conditions de sortie de boucle.

Symptôme : "Latence anormalement élevée"

Diagnostic : trace l'identifie : appel LLM lent ? Outil externe lent ? Trop d'appels en série ?Fixes : paralléliser quand possible, utiliser modèle plus rapide pour étapes simples, mettre en cache les résultats répétés.

Symptôme : "Qualité varie d'un jour à l'autre"

Diagnostic : le modèle a peut-être été mis à jour côté fournisseur (les modèles évoluent). Investigation : comparez les outputs sur les mêmes inputs avant/après. Fixes : "épingler" un modèle précis (claude-sonnet-4-20250514 au lieu de claude-sonnet-4), créer un set de tests de régression à rejouer après chaque update.

7. Optimisation continue : la boucle d'amélioration

L'observabilité ne sert pas qu'à débugger les problèmes. Elle sert aussi à améliorer continuellement votre agent.

Cycle hebdomadaire d'optimisation

Optimisation des coûts spécifiquement

5 leviers principaux :

1. Modèle plus économique : Si Sonnet 4 peut être remplacé par Haiku sans perte de qualité, économies x10 immédiates.
2. Tronquer les inputs longs : si vous envoyez régulièrement 50 000 tokens en contexte, voyez si on peut réduire à 10 000.
3. Cache LLM : pour les requêtes répétées (FAQ standard), mettre en cache les réponses. Helicone ou Anthropic le font automatiquement.
4. Réduction du nombre d'itérations : si l'agent fait souvent 8 itérations alors que 4 suffisent, ajustez le prompt pour qu'il aille plus directement.
5. Désactiver les agents inutilisés : audit régulier, certains agents tournent sans servir.

8. Conformité et observabilité

L'observabilité a aussi une dimension légale importante.

Pour le RGPD

Si vos agents traitent des données personnelles, vous devez pouvoir tracer qui a fait quoi avec quelles données. Les logs sont votre meilleure défense en cas de plainte.

Attention : les logs eux-mêmes contiennent souvent des données personnelles (emails, noms). Appliquez les principes RGPD aux logs : durée de conservation limitée (90 à 365 jours), accès restreint, suppression sur demande.

Pour l'IA Act

Le règlement IA Act exige conservation des logs pour les systèmes haut risque pendant au moins 6 mois. Les logs doivent permettre de retracer chaque décision et la supervision humaine appliquée.

Pour les agents en risque limité (Article 50), pas d'obligation formelle, mais c'est fortement recommandé en cas de plainte ou contrôle.

9. À retenir avant le chapitre suivant

• 3 piliers de l'observabilité : logs (détails), traces (arbre), métriques (agrégats)
• 4 outils principaux : Langfuse (open-source recommandé), Helicone (cloud rapide), LangSmith (LangChain), n8n natif (suffit pour démarrer)
• Architecture PME : n8n + Langfuse auto-hébergé sur Hostinger France = ~5 €/mois en plus
• Démarche debugging en 4 étapes : reproduire → isoler la couche → tester en isolation → corriger et tester
• 5 erreurs typiques avec leurs diagnostics : hallucinations, boucles, coût explosé, latence, qualité variable
• Routine hebdo 30 min pour optimisation continue
• Conformité : logs sont essentiels pour RGPD et IA Act (haut risque)

Au chapitre 8 (le dernier !), on passe à la pratique : construction guidée de votre premier agent avec n8n + Claude. Étape par étape, captures d'écran, prompts, configurations. Vous repartez avec un agent fonctionnel.