Construir agentes con LangChain y LangGraph se ha convertido en una de las formas más habituales de orquestar LLM en Python: se describen los pasos de un razonamiento como un grafo, con un estado compartido, bucles y llamadas a herramientas. En el dúo LangChain LangGraph, LangChain aporta las piezas básicas (modelos, prompts, herramientas, integraciones) y LangGraph la orquestación. Ambos proyectos figuran entre los más seguidos en GitHub dentro del ecosistema de los agentes de IA.
El problema llega con la puesta en producción. Un agente no es una función que devuelve una respuesta: es una sucesión de decisiones, de llamadas al modelo y de llamadas a herramientas cuyo número varía de una ejecución a otra. Cuando una respuesta es errónea, lenta o cara, hay que saber qué paso es el responsable. Sin trazas, se adivina.
En este artículo construimos un pequeño agente con LangGraph conectado a un modelo local y lo trazamos después con OpenTelemetry para ver cada nodo, cada llamada al LLM y cada consumo de tokens en un backend como Dynatrace.
LangChain LangGraph: ¿quién hace qué?
- LangChain estandariza el acceso a los modelos de chat (OpenAI, Anthropic, Mistral, Ollama, servidores compatibles con OpenAI…), a las herramientas, a los documentos y a las bases vectoriales. Las integraciones se publican en paquetes separados, como
langchain-openaiolangchain-ollama. - LangGraph modela una aplicación como un grafo de estados: unos nodos (funciones) leen y modifican un estado tipado, y unas aristas, a veces condicionales, deciden el paso siguiente. También gestiona la persistencia del estado, la interrupción para validación humana y el streaming de los pasos.
Hay funciones ya preparadas que crean un agente de tipo ReAct (el modelo elige una herramienta, observa el resultado y vuelve a empezar) en una sola línea. Su nombre y su módulo han cambiado entre versiones: consulta la documentación oficial de LangChain y LangGraph. El grafo explícito, que usamos aquí, sigue siendo la forma más legible de entender lo que ocurre.
En la práctica: un agente LangGraph sobre un modelo local
Paso 1: instalar los paquetes
python3 -m venv .venv && source .venv/bin/activate
pip install langgraph langchain-openai
Usamos el cliente compatible con OpenAI para poder apuntar indistintamente a Ollama, vLLM o llama.cpp. Para Ollama, nuestra guía de Ollama en local describe la instalación; su API compatible con OpenAI se sirve bajo /v1.
Paso 2: describir el estado y los nodos
El agente recibe el síntoma de un incidente, establece un plan de diagnóstico y redacta después una respuesta corta:
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}
Paso 3: ensamblar y ejecutar el grafo
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)
El modo updates muestra la actualización del estado que produce cada nodo. Es una primera forma de observabilidad, útil en desarrollo, pero limitada a la consola.
Paso 4: añadir herramientas
Un agente de verdad llama a herramientas: consulta a una API de monitorización, lectura de un runbook, búsqueda en una base documental. Se enlazan las herramientas al modelo y se añade una arista condicional que hace un bucle mientras el modelo pida una herramienta. Ese bucle es precisamente lo que hace imprevisible el comportamiento y, por tanto, lo que hay que trazar. Las herramientas también pueden venir de servidores MCP, como se explica en observar agentes MCP con OpenTelemetry.
¿Cómo trazar agentes de LangGraph con OpenTelemetry?
Existen dos familias de soluciones. LangSmith, la plataforma del editor de LangChain, se activa con variables de entorno y ofrece una vista muy detallada; es un servicio comercial, con una oferta autoalojada reservada a ciertos planes. La alternativa abierta es OpenTelemetry, que envía las trazas al backend que elijas.
La instrumentación OpenLLMetry para LangChain
El proyecto OpenLLMetry publica una instrumentación de OpenTelemetry para LangChain, que cubre también LangGraph, ya que este se apoya en el sistema de callbacks de LangChain. Cada ejecución del grafo se convierte en una traza, cada nodo en un span hijo y cada llamada al modelo en un span con el modelo, los tokens de entrada y de salida y la duración.
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
El SDK traceloop-sdk del mismo proyecto reúne esta configuración en una llamada de inicialización. Comprueba los nombres de paquetes y de clases en el repositorio de OpenLLMetry; comparamos este enfoque con Langfuse en Langfuse y OpenLLMetry.
Añadir el contexto de negocio
Los spans automáticos dicen lo que hace el agente, no para quién. Añade atributos al span actual: identificador de conversación, equipo, tipo de petición. Evita poner en ellos el texto completo de los prompts si contienen datos personales; algunas instrumentaciones ofrecen una opción para desactivar la captura del contenido.
Visualizar los pasos del agente en Dynatrace
El exportador OTLP se configura con las variables estándar (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_SERVICE_NAME), ya sea hacia un OpenTelemetry Collector o directamente hacia el endpoint OTLP de Dynatrace con un token de API autorizado a ingerir trazas. En la vista de trazas distribuidas, una ejecución del agente aparece como un árbol: nodo planifier, llamada al LLM, nodo repondre, nueva llamada. Se localiza de inmediato el paso más lento, un bucle de herramientas que se desboca o una llamada que consume demasiados tokens.
A partir de estos spans se derivan indicadores: número de pasos por ejecución, tokens por ejecución, tasa de errores de las herramientas y latencia de extremo a extremo. Si el servidor de modelos también está trazado, la propagación W3C prolonga la traza hasta la inferencia, según los principios de nuestro artículo OpenTelemetry de extremo a extremo.
Buenas prácticas
- Fija un límite al número de iteraciones del grafo para evitar bucles infinitos y facturas sorpresa.
- Nombra los nodos de forma explícita: son los que aparecerán en las trazas.
- Fija las versiones de
langchain,langgraphy de las instrumentaciones, que evolucionan rápido. - Traza desde el desarrollo: comparar las trazas antes y después de un cambio de prompt es muy instructivo.
- Enmascara o desactiva la captura del contenido de los prompts cuando sea sensible.
Preguntas frecuentes
¿Hace falta LangChain para usar LangGraph?
LangGraph puede orquestar cualquier código Python, pero se integra de forma natural con los modelos y herramientas de LangChain, y ambos se instalan normalmente juntos.
¿Es obligatorio LangSmith para trazar un agente?
No. Una instrumentación de OpenTelemetry como la de OpenLLMetry envía las trazas a cualquier backend compatible con OTLP.
¿Se puede usar un modelo local con LangGraph?
Sí, mediante la integración de Ollama o un cliente compatible con OpenAI apuntado a Ollama, vLLM o llama.cpp.
Conclusión
LangGraph hace explícitos los agentes y OpenTelemetry los hace observables. Juntos convierten un comportamiento opaco en un árbol de pasos medibles, que se puede seguir y sobre el que se puede alertar en Dynatrace como en cualquier servicio. Para elegir el resto de la pila, consulta nuestra comparativa de pilas de IA de código abierto autoalojadas.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a los proyectos citados. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba los comandos y opciones en su documentación oficial.