Observability pour agents IA : monitoring des systèmes agentiques

Idée en 30 secondes

L'observability pour les agents IA montre ce qui se passe pendant un run.

Un agent peut faire des dizaines d'étapes : reasoning, tool calls, appels LLM répétés.

L'observability rend ces étapes visibles via tracing, logs et métriques.

Problème principal

Dans un backend classique, une requête HTTP exécute un code prévisible :

request → handler → database → response

Le nombre d'étapes est connu à l'avance, et le comportement est facile à suivre avec des logs standards.

Dans les systèmes avec agents IA, c'est différent : une requête peut devenir un run avec plusieurs étapes de reasoning, des tool calls et des itérations répétées.

Un agent peut faire 2 étapes ou 20. Il peut appeler plusieurs tools, répéter le reasoning et consommer plus de tokens que prévu.

Sans observability, il devient difficile de répondre même à des questions de base :

• Pourquoi la requête est-elle lente ?
• Pourquoi les coûts en tokens ont-ils augmenté brusquement ?
• Pourquoi l'agent appelle-t-il un tool des dizaines de fois ?
• À quelle étape l'erreur est-elle apparue ?

Pour ces systèmes, les logs classiques ne suffisent pas. L'observability est nécessaire pour voir le chemin d'exécution complet et trouver rapidement les étapes problématiques pendant le debugging.

Comment ça fonctionne

L'observability pour agents IA repose sur trois types de signaux : traces, logs et métriques. Ensemble, ils permettent de voir les requêtes individuelles et l'état global du système.

Il existe des outils spécialisés d'observability pour agents (par exemple LangSmith, Langfuse, Arize Phoenix), mais les principes de base sont les mêmes quel que soit l'outil.

Tracing

Le tracing montre le chemin d'exécution complet d'un run d'agent. Chaque étape est enregistrée comme événement : reasoning du modèle, appel d'outil ou résultat. Un trace est composé de spans (spans). Le trace est le chemin complet d'exécution (run), et un span est une étape à l'intérieur, par exemple un tool call ou du reasoning.

run_id: 9fd2

step 1 — search_docs       420ms
step 2 — summarize         110ms
step 3 — generate_answer   890ms

Le tracing montre quels tools ont été appelés et combien d'étapes l'agent a faites. Il montre aussi où un retard ou une erreur est apparu.

À quoi ressemble un trace d'agent

Le plus simple pour comprendre le tracing est de regarder une requête réelle.

Exemple de trace pour une requête :

run_id: 9fd2
user_query: "Find recent research about battery recycling"

step 1  llm_reasoning        320ms
        thought: need to search research papers

step 2  tool_call: search    410ms
        query: battery recycling research 2024

step 3  llm_reasoning        180ms
        thought: summarize the most relevant papers

step 4  tool_call: fetch     260ms
        source: arxiv

step 5  llm_generate         720ms
        output: final answer

Ce trace permet de comprendre rapidement :

• quelles étapes l'agent a exécutées
• quels tools ont été appelés
• combien de temps chaque étape a pris
• où le retard ou l'erreur est apparu

Dans les systèmes de production, un trace contient souvent des informations supplémentaires :

• run_id et trace_id pour corréler les événements
• latency de chaque étape
• token usage du LLM
• stop reason (completed, max_steps, tool_error)

Les traces ne servent pas seulement au debugging. Ils sont aussi nécessaires pour les evaluations. Sans étapes intermédiaires, il est difficile de vérifier automatiquement si l'agent a bien agi pendant le run, et pas seulement s'il a donné une bonne réponse finale.

Logging

Les logs enregistrent les événements pendant l'exécution de l'agent :

• début et fin du run
• appels d'outils avec paramètres
• erreurs et exceptions
• raison d'arrêt de l'agent (stop reason)

Les logs répondent à la question « que s'est-il passé ». Le tracing répond « comment exactement cela s'est passé ».

Métriques

Les métriques montrent l'état global du système, pas une requête unique. Métriques de production typiques pour agents :

Les métriques sont nécessaires pour le monitoring et les alertes en production. Elles permettent de détecter vite les anomalies : hausse soudaine de token usage, latency ou nombre de tool calls.

La plupart des fournisseurs LLM (OpenAI, Anthropic) renvoient le token usage dans la réponse. Il n'est donc généralement pas nécessaire de le calculer à la main, il suffit de logger ces champs.

Quand l'utiliser

L'observability n'est pas toujours nécessaire.

Pour des scénarios simples, un logging de base suffit généralement. Par exemple, un seul appel LLM sans tools et sans boucle d'exécution.

Mais dès qu'il y a un run multi-étapes — reasoning, tool calls, itérations répétées — il devient difficile de déboguer, contrôler les coûts et expliquer le comportement sans observability.

Exemple d'implémentation

Ci-dessous, un exemple simplifié d'instrumentation dans un runtime d'agent. Dans les systèmes réels, ces événements sont généralement envoyés vers un système de tracing ou une plateforme d'observability. Dans la plupart des runtime, chaque unité d'exécution est représentée comme un step : cela peut être du reasoning modèle ou un appel d'outil. Cette boucle (agent.iter) est utilisée dans des frameworks comme LangGraph, CrewAI et des runtime maison.

import logging
import time
import uuid

logger = logging.getLogger("agent")

def run_agent(agent, task):
    run_id = str(uuid.uuid4())

    logger.info("agent_run_started", extra={
        "run_id": run_id,
        "task": task,
    })

    steps = []

    for step in agent.iter(task):  # step: reasoning ou tool execution
        step_start = time.time()
        result = step.execute()
        latency = time.time() - step_start

        step_event = {
            "run_id": run_id,
            "step_type": step.type,  # reasoning | tool_call | llm_generate
            "tool": getattr(step, "tool_name", None),
            "latency": latency,
        }

        logger.info("agent_step", extra=step_event)
        steps.append(step_event)

        if result.is_final:
            break

    logger.info("agent_run_finished", extra={
        "run_id": run_id,
        "steps": len(steps),
    })

On peut envelopper les tools dans un wrapper pour logger les appels réussis et les erreurs :

def traced_tool(tool_fn):
    def wrapper(*args, **kwargs):
        start = time.time()

        try:
            result = tool_fn(*args, **kwargs)
            logger.info(
                "tool_call",
                extra={
                    "tool": tool_fn.__name__,
                    "latency": time.time() - start,
                    "status": "ok",
                },
            )
            return result
        except Exception as error:
            logger.error(
                "tool_call_failed",
                extra={
                    "tool": tool_fn.__name__,
                    "latency": time.time() - start,
                    "error": str(error),
                },
            )
            raise

    return wrapper

L'exemple ci-dessus montre la logique de base d'instrumentation. En production, on l'étend généralement avec plusieurs pratiques :

• trace_id pour chaque run
• logs structurés (JSON)
• métriques de latency et token usage
• intégration avec des systèmes de monitoring

Par exemple, un log structuré peut ressembler à ceci :

{
  "timestamp": "2026-03-21T15:17:00Z",
  "level": "INFO",
  "event": "tool_call",
  "run_id": "9fd2...",
  "tool": "search_docs",
  "latency_ms": 410,
  "status": "ok"
}

Dans les systèmes réels, run_id et trace_id doivent être propagés dans toute la chaîne d'appels. En Python, on utilise souvent contextvars pour éviter de passer l'identifiant comme argument dans chaque fonction.

Cela aide à voir le chemin complet d'exécution et à trouver rapidement les étapes problématiques.

Erreurs typiques

Même quand l'observability est déjà en place, les systèmes agentiques restent souvent difficiles à diagnostiquer. Le plus souvent à cause des erreurs ci-dessous.

Logger uniquement la réponse finale

Si le système enregistre seulement le résultat final, il est impossible de comprendre comment l'agent y est arrivé. Il faut donc logger les étapes de reasoning, les tool calls et la stop reason. Sans cela, même des incidents simples après release sont difficiles à analyser.

Absence de traces pour les appels d'outils

Les outils sont souvent la partie la plus lente du système. Si les appels d'outils ne sont pas dans le tracing, il est difficile de comprendre :

• quel tool ajoute de la latence
• où exactement l'erreur se produit
• si l'agent appelle le même tool en boucle

En production, cela masque souvent le spam d'outils ou une phase précoce de pannes en cascade.

Absence de métriques de coût

Les agents peuvent augmenter les coûts de façon invisible via des boucles de reasoning longues, des appels LLM répétés ou des tool calls inutiles. Sans métriques de coût, on le remarque souvent seulement après une hausse notable de facture. Le système peut alors basculer rapidement dans un mode coûteux et instable.

Logger les prompts bruts

Les prompts peuvent contenir des données personnelles, des secrets ou des informations internes. Avant de les écrire dans les logs, il faut les rediger ou les anonymiser. Sinon, des données sensibles peuvent se retrouver dans les logs d'incident.

Auto-vérification

Ci-dessous, une checklist courte de base pour l'observability en production.

FAQ

Q : Quelle différence entre tracing, logs et métriques ?
R : Le tracing montre le chemin d'un run étape par étape. Les logs enregistrent les événements et erreurs. Les métriques montrent la vue globale sur une période (latency, error rate, token usage).

Q : Que mettre en place en premier s'il n'y a pas encore d'observability ?
R : Commencez par le minimum : run_id, logs structurés et latency de chaque étape. Ensuite ajoutez le tracing des tool calls et les métriques clés (token usage, tool calls per run, error rate).

Q : Quels champs sont les plus importants pour debugger un run problématique ?
R : Minimum : run_id/trace_id, type d'étape, tool appelé, latency de l'étape, stop reason, erreur (si présente). C'est suffisant pour reconstruire la chaîne d'événements.

Q : Faut-il absolument utiliser des outils externes d'observability dès le départ ?
R : Non. Vous pouvez démarrer avec votre propre instrumentation et des logs structurés. Les plateformes spécialisées deviennent utiles quand le volume de runs, le nombre d'équipes et le besoin d'analyse centralisée augmentent.

Pages liées

Suite du sujet :

• Tracing d'agent — comment suivre l'exécution d'un run.
• Tracing distribué d'agents — tracing entre plusieurs agents.
• Métriques d'agents — quels indicateurs mesurer.