Agents LangChain/LangGraph : construire un agent et tracer chacune de ses étapes

Construisez des agents LangChain/LangGraph sur un modèle local, puis tracez chaque nœud, appel au LLM et token avec OpenTelemetry jusqu’à Dynatrace.
Agents LangGraph et LangChain : construire un agent et tracer chacune de ses étapes

Construire des agents LangGraph est devenu l’une des façons les plus courantes d’orchestrer des LLM en Python : on décrit les étapes d’un raisonnement sous forme de graphe, avec un état partagé, des boucles et des appels d’outils. Dans le duo LangChain/LangGraph, LangChain fournit les briques de base (modèles, prompts, outils, intégrations), LangGraph l’orchestration. Les deux projets figurent parmi les plus suivis sur GitHub dans l’écosystème des agents IA.

Le problème arrive avec la mise en production. Un agent n’est pas une fonction qui renvoie une réponse : c’est une suite de décisions, d’appels au modèle et d’appels d’outils dont le nombre varie d’une exécution à l’autre. Quand une réponse est fausse, lente ou coûteuse, il faut savoir quelle étape en est responsable. Sans traces, on devine.

Dans cet article, nous construisons un petit agent avec LangGraph branché sur un modèle local, puis nous le traçons avec OpenTelemetry pour voir chaque nœud, chaque appel au LLM et chaque consommation de tokens dans un backend comme Dynatrace.

LangChain/LangGraph : qui fait quoi ?

  • LangChain standardise l’accès aux modèles de chat (OpenAI, Anthropic, Mistral, Ollama, serveurs compatibles OpenAI…), aux outils, aux documents et aux bases vectorielles. Les intégrations sont publiées dans des paquets séparés, comme langchain-openai ou langchain-ollama.
  • LangGraph modélise une application comme un graphe d’états : des nœuds (fonctions) lisent et modifient un état typé, des arêtes, éventuellement conditionnelles, décident de la suite. Il gère aussi la persistance de l’état, l’interruption pour validation humaine et le streaming des étapes.

Des fonctions prêtes à l’emploi créent un agent de type ReAct (le modèle choisit un outil, observe le résultat, recommence) en une ligne. Leur nom et leur module ont changé entre les versions : référez-vous à la documentation officielle de LangChain et LangGraph. Le graphe explicite, que nous utilisons ici, reste le moyen le plus lisible de comprendre ce qui se passe.

En pratique : un agent LangGraph sur un modèle local

Étape 1 — Installer les paquets

python3 -m venv .venv && source .venv/bin/activate
pip install langgraph langchain-openai

Nous utilisons le client compatible OpenAI pour pouvoir viser indifféremment Ollama, vLLM ou llama.cpp. Pour Ollama, notre guide Ollama en local décrit l’installation ; son API compatible OpenAI est servie sous /v1.

Étape 2 — Décrire l’état et les nœuds

L’agent reçoit un symptôme d’incident, établit un plan de diagnostic, puis rédige une réponse courte :

from typing import TypedDict
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END

llm = ChatOpenAI(model="llama3.2",
                 base_url="http://localhost:11434/v1",
                 api_key="non-utilise")

class Etat(TypedDict):
    symptome: str
    plan: str
    reponse: str

def planifier(etat: Etat) -> dict:
    msg = llm.invoke(f"Liste 3 vérifications pour : {etat['symptome']}")
    return {"plan": msg.content}

def repondre(etat: Etat) -> dict:
    msg = llm.invoke(f"Symptôme : {etat['symptome']}\n"
                     f"Plan : {etat['plan']}\nRésume en 5 lignes.")
    return {"reponse": msg.content}

Étape 3 — Assembler et exécuter le graphe

graphe = StateGraph(Etat)
graphe.add_node("planifier", planifier)
graphe.add_node("repondre", repondre)
graphe.add_edge(START, "planifier")
graphe.add_edge("planifier", "repondre")
graphe.add_edge("repondre", END)
agent = graphe.compile()

for etape in agent.stream({"symptome": "latence p95 en hausse sur le service paiement"},
                          stream_mode="updates"):
    print(etape)

Le mode updates affiche la mise à jour de l’état produite par chaque nœud. C’est une première forme d’observabilité, utile en développement, mais limitée à la console.

Étape 4 — Ajouter des outils

Un vrai agent appelle des outils : requête à une API de supervision, lecture d’un runbook, recherche dans une base documentaire. On lie les outils au modèle et on ajoute une arête conditionnelle qui boucle tant que le modèle demande un outil. Cette boucle est précisément ce qui rend le comportement imprévisible, et donc ce qu’il faut tracer. Les outils peuvent aussi venir de serveurs MCP, comme expliqué dans observer des agents MCP avec OpenTelemetry.

Comment tracer des agents LangGraph avec OpenTelemetry ?

Deux familles de solutions existent. LangSmith, la plateforme de l’éditeur de LangChain, s’active par variables d’environnement et offre une vue très détaillée ; c’est un service commercial, avec une offre auto-hébergée réservée à certaines formules. L’alternative ouverte est OpenTelemetry, qui envoie les traces vers le backend de votre choix.

L’instrumentation OpenLLMetry pour LangChain

Le projet OpenLLMetry publie une instrumentation OpenTelemetry pour LangChain, qui couvre aussi LangGraph puisque ce dernier s’appuie sur le système de callbacks de LangChain. Chaque exécution du graphe devient une trace, chaque nœud un span enfant, chaque appel au modèle un span portant le modèle, les tokens en entrée et en sortie et la durée.

pip install opentelemetry-sdk opentelemetry-exporter-otlp \
  opentelemetry-instrumentation-langchain
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.langchain import LangchainInstrumentor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)
LangchainInstrumentor().instrument()
# ... puis construire et invoquer le graphe comme plus haut

Le SDK traceloop-sdk du même projet regroupe cette configuration en un appel d’initialisation. Vérifiez les noms de paquets et de classes dans le dépôt OpenLLMetry ; nous comparons cette approche avec Langfuse dans Langfuse et OpenLLMetry.

Ajouter le contexte métier

Les spans automatiques disent ce que fait l’agent, pas pour qui. Ajoutez des attributs sur le span courant : identifiant de conversation, équipe, type de demande. Évitez d’y placer le texte complet des prompts si ceux-ci contiennent des données personnelles ; certaines instrumentations proposent une option pour désactiver la capture du contenu.

Visualiser les étapes de l’agent dans Dynatrace

L’exportateur OTLP se configure par les variables standard (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_SERVICE_NAME), soit vers un Collector OpenTelemetry, soit directement vers l’endpoint OTLP de Dynatrace avec un jeton d’API autorisé à ingérer des traces. Dans la vue des traces distribuées, une exécution de l’agent apparaît comme un arbre : nœud planifier, appel au LLM, nœud repondre, nouvel appel. On repère immédiatement l’étape la plus lente, une boucle d’outils qui s’emballe ou un appel qui consomme trop de tokens.

À partir de ces spans, on dérive des indicateurs : nombre d’étapes par exécution, tokens par exécution, taux d’erreurs des outils, latence de bout en bout. Si le serveur de modèles est lui-même tracé, la propagation W3C prolonge la trace jusqu’à l’inférence, selon les principes de notre article OpenTelemetry de bout en bout.

Bonnes pratiques

  • Fixez une limite au nombre d’itérations du graphe pour éviter les boucles infinies et les factures surprises.
  • Nommez les nœuds de façon explicite : ce sont eux qui apparaîtront dans les traces.
  • Épinglez les versions de langchain, langgraph et des instrumentations, qui évoluent vite.
  • Tracez dès le développement : comparer les traces avant et après un changement de prompt est très instructif.
  • Masquez ou désactivez la capture du contenu des prompts lorsqu’il est sensible.

Questions fréquentes

Faut-il LangChain pour utiliser LangGraph ?

LangGraph peut orchestrer n’importe quel code Python, mais il s’intègre naturellement aux modèles et outils de LangChain, et les deux sont généralement installés ensemble.

LangSmith est-il obligatoire pour tracer un agent ?

Non. Une instrumentation OpenTelemetry comme celle d’OpenLLMetry envoie les traces vers n’importe quel backend compatible OTLP.

Peut-on utiliser un modèle local avec LangGraph ?

Oui, via l’intégration Ollama ou un client compatible OpenAI pointé vers Ollama, vLLM ou llama.cpp.

Conclusion

LangGraph rend les agents explicites, OpenTelemetry les rend observables. Ensemble, ils transforment un comportement opaque en arbre d’étapes mesurables, que l’on peut suivre et alerter dans Dynatrace comme n’importe quel service. Pour choisir le reste de la pile, consultez notre comparatif des stacks IA open source auto-hébergées.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC ni aux projets cités. Les marques citées appartiennent à leurs propriétaires. Les outils évoluent vite : vérifiez les commandes et options dans leur documentation officielle.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
Open WebUI auto-hébergé : un ChatGPT interne devant Ollama ou une API compatible OpenAI

Open WebUI auto-hébergé : un ChatGPT interne devant Ollama ou une API compatible OpenAI

Next Post
LlamaIndex RAG : un assistant sur votre documentation interne, et comment mesurer sa qualité

LlamaIndex RAG : un assistant sur votre documentation interne, et comment mesurer sa qualité

Related Posts