LangGraph: agentes con estado como grafo dirigido

LangGraph es un framework de orquestación de bajo nivel de LangChain Inc. para construir agentes de IA con estado y de larga duración. No modela un agente como un script lineal, sino como un grafo dirigido de nodos y aristas con un objeto de estado compartido, checkpointing persistente, puntos de human-in-the-loop y streaming. Desde octubre de 2025, LangGraph está disponible en la versión principal estable 1.x, con licencia MIT, y admite Python y JavaScript/TypeScript.

Si quieres llevar agentes a producción más allá de simples llamadas a la API de un LLM, necesitas una orquestación controlada con un estado fiable. LangGraph está construido precisamente para eso: bajo nivel de abstracción, control explícito y durable execution.

Respuestas rápidas

• Qué es: una capa de orquestación que describe los workflows de agentes como un grafo de nodos (lógica) y aristas (flujo de control) sobre un estado compartido.
• Para qué sirve: workflows multipaso complejos, controlados y de larga duración, sobre todo con estado, aprobaciones y obligación de auditoría.
• Diferencia: LangGraph no es el sucesor de LangChain, sino la orquestación con estado que se sitúa por encima. LangChain aporta modelos y herramientas; LangGraph, el flujo.

El modelo central: Nodes, Edges, State, Reducer

LangGraph describe un agente como un State Graph. El modelo se apoya en tres componentes:

• State: un objeto tipado y compartido que recorre todo el grafo. Cada paso lee del state y vuelve a escribir en él. El state es la única fuente de verdad sobre el progreso de una ejecución.
• Nodes (nodos): funciones que hacen el trabajo, como llamar a un LLM, ejecutar una herramienta o validar un resultado. Un nodo recibe el state actual y devuelve una actualización del state.
• Edges (aristas): determinan qué nodo se ejecuta a continuación. Las aristas condicionales (conditional edges) permiten ramificaciones en función del state, lo que hace posibles bucles, reintentos y rutas dinámicas que un pipeline lineal no puede representar.

Un concepto clave es el reducer. Cuando varios nodos escriben en el mismo campo del state, como una lista de mensajes, el reducer define cómo se combinan las actualizaciones, por ejemplo añadiendo en lugar de sobrescribir. Así, los pasos paralelos o iterativos no entran en conflicto. Esa es la diferencia entre un bucle de agente frágil hecho a mano y una máquina de estados controlada.

Persistencia y checkpointing: durable execution

La característica más importante de LangGraph para producción es la durable execution mediante checkpointing. Tras cada paso, el state se guarda de forma persistente en un backend. De ahí se derivan tres capacidades prácticas:

• Pausar y reanudar: una ejecución puede detenerse y retomarse más tarde exactamente en el mismo punto, sin perder el progreso.
• Tolerancia a fallos: si un workflow de larga duración falla, no empieza de cero, sino desde el último checkpoint.
• Viaje en el tiempo: se puede inspeccionar un state anterior y bifurcar la ejecución desde un punto concreto, lo que facilita mucho la depuración y la auditabilidad.

Desde la versión 1.2, los timeouts por nodo limitan el tiempo de ejecución de cada nodo. Una parada controlada (graceful drain) detiene la ejecución tras el paso actual y guarda un checkpoint desde el que se puede reanudar. En los hilos largos, el DeltaChannel guarda en cada paso solo el cambio en lugar del valor completo, aunque por ahora está marcado como beta.

Human-in-the-loop, streaming y subgrafos

Human-in-the-loop (HITL): como el state es persistente, un grafo puede detenerse en un punto definido y esperar una decisión humana, por ejemplo una aprobación antes de una acción que genere costes o sea irreversible. El workflow solo continúa tras la confirmación. Es justo lo que necesitan los sectores regulados con requisitos de supervisión humana (human oversight).

Streaming: LangGraph transmite en streaming resultados intermedios, tokens y el progreso de cada paso. Hay disponible una vía de streaming type-safe (v2) y un streaming por bloques de contenido (v3), para que las interfaces muestren en directo el progreso del agente.

Subgrafos: un grafo puede integrarse como nodo dentro de otro más grande. Así se pueden encapsular módulos de agentes reutilizables y componer de forma limpia arquitecturas multiagente complejas, como los patrones supervisor o swarm, en lugar de meterlo todo en un flujo monolítico.

Pseudocódigo: un grafo sencillo

El siguiente ejemplo en pseudocódigo muestra un bucle de agente mínimo: un nodo de modelo decide, un nodo de herramientas ejecuta y una arista condicional cierra el bucle.

```
State = {
messages: list # Reducer: añadir, no sobrescribir
}

def call_model(state):
respuesta = llm.invoke(state.messages)
return {"messages": [respuesta]}

def call_tools(state):
resultado = tools.run(state.messages[-1].tool_calls)
return {"messages": [resultado]}

def should_continue(state):
if state.messages[-1].tiene_tool_calls:
return "tools" # arista condicional -> ejecutar herramienta
return END # respuesta lista -> terminar

graph = StateGraph(State)
graph.add_node("model", call_model)
graph.add_node("tools", call_tools)
graph.set_entry_point("model")
graph.add_conditional_edges("model", should_continue)
graph.add_edge("tools", "model") # bucle de vuelta al modelo

app = graph.compile(checkpointer=Checkpointer())
app.invoke({"messages": [user_input]}, config={"thread_id": "cliente-42"})
```

El thread_id vincula la ejecución a una secuencia de checkpoints. Es precisamente este mecanismo el que permite continuar más tarde el mismo hilo de conversación o de proceso en lugar de empezar de nuevo cada vez.

LangGraph vs. LangChain: diferencias

Una confusión frecuente: LangGraph no es la siguiente versión de LangChain. Ambos proceden de LangChain Inc., pero cumplen funciones distintas. LangChain es la biblioteca para modelos, prompts e integraciones de herramientas (más de 750 herramientas en el ecosistema). LangGraph es la orquestación de bajo nivel que combina estos componentes en un flujo con estado y de larga duración. La migración del LangChain clásico a LangGraph es incremental y los componentes de LangChain existentes se pueden seguir utilizando.

El ecosistema tiene una estructura de capas clara: LangChain (biblioteca e integraciones) aporta los componentes, LangGraph (orquestación, durable) controla el flujo, LangSmith (evaluación y observabilidad) proporciona el tracing y LangSmith Deployment (antes LangGraph Platform) ofrece hosting gestionado.

Para los protocolos MCP y A2A ya existen vías oficiales. Las herramientas MCP las integras en Python mediante el módulo langchain.mcp, disponible desde langchain 1.4.0 a través del extra langchain[mcp] y marcado actualmente como beta. Sustituye al paquete langchain-mcp-adapters, cuyo repositorio está archivado. A la inversa, el Agent Server, en el que se basa LangSmith Deployment, expone tus agentes de forma nativa como endpoint MCP en /mcp y como endpoint A2A en /a2a/{assistant_id}.

Funciones y beneficios de un vistazo

Ejemplo concreto: proceso controlado con aprobación

Una agencia B2B desarrolla para un cliente asegurador un agente que preprocesa los partes de siniestro: leer documentos, extraer datos, cotejarlos con las pólizas, implicar a un tramitador para su aprobación cuando el importe supera los 5.000 euros y, después, abrir el expediente.

Con LangGraph, esto se convierte en un grafo de cuatro nodos y una arista condicional en el umbral. Si el importe supera el límite, el grafo se detiene en un punto HITL y guarda su state de forma persistente; tras la aprobación, continúa. Si el sistema cae entretanto, se reanuda desde el último checkpoint y ningún documento se procesa dos veces. Cada paso es trazable en LangSmith, lo que cumple el requisito de auditabilidad.

El precio de este control es la curva de aprendizaje. Análisis de terceros cifran el esfuerzo adicional en unas 120 líneas de código para un agente ReAct, frente a unas 40 en frameworks más ligeros. A cambio, el flujo se controla de forma determinista en lugar de depender de un bucle de caja negra difícil de depurar. Klarna, Replit, Uber, LinkedIn y Elastic, entre otras empresas, usan LangGraph en producción.

Para agencias y equipos B2B

LangGraph es la elección adecuada si necesitas agentes controlados, de larga duración y auditables, no el prototipo de demo más rápido. Para clientes en Europa con requisitos de RGPD y soberanía de datos, lo decisivo es esto: el framework es open source (MIT) y se puede autoalojar por completo, por ejemplo en STACKIT, IONOS u OVHcloud. La solución gestionada LangSmith también está disponible en una región de la UE con centro de datos de Google Cloud en los Países Bajos, al mismo precio en todos los planes. Pero la parte contratante sigue siendo la empresa estadounidense LangChain: según sus preguntas frecuentes sobre regiones, no existe una sociedad en la UE para los contratos con clientes. Por eso conviene revisar de antemano el contrato de encargo del tratamiento y la transferencia a terceros países (esto no es asesoramiento jurídico). En Blck Alpaca evaluamos contigo si LangGraph, un framework más ligero o una solución directa y sencilla encaja mejor con tu caso de uso, e implementamos la arquitectura conforme a los requisitos de soberanía. Contáctanos para una evaluación de frameworks.