Phase 14 - Lesson 13

LangGraph: Grafos con Estado y Ejecución Durable

LangGraph es la referencia de 2026 para la orquestación con estado de bajo nivel. El agente es una máquina de estados; los nodos son funciones; las aristas son transiciones; el estado es inmutable y se guarda en un punto de control (checkpoint) después de cada paso. Reanuda desde cualquier falla exactamente donde se quedó.

Tipo: Aprender + Construir Idiomas: Python (stdlib) Prerrequisitos: Phase 14 · 01 (Agent Loop), Phase 14 · 12 (Workflow Patterns) Tiempo: ~75 minutos

Objetivos de Aprendizaje

• Describir el modelo central de LangGraph: máquina de estados con estado inmutable, nodos de función, aristas condicionales y puntos de control (checkpoints) posteriores a cada paso.
• Nombrar las cuatro capacidades que destacan los documentos: ejecución durable, streaming, human-in-the-loop (humano en el bucle) y memoria integral.
• Explicar las tres topologías de orquestación que admite LangGraph: supervisor, peer-to-peer (swarm) y jerárquica (subgrafos anidados).
• Implementar un grafo de estado de stdlib con estado inmutable, aristas condicionales y un ciclo de checkpoint/resume.

El Problema

Los agentes y los flujos de trabajo comparten un problema: cuando una ejecución de 40 pasos falla en el paso 38, deseas reanudar desde el paso 38, no comenzar de nuevo. Los modelos de estado de segunda clase obligan a los operadores a improvisar reintentos alrededor de una biblioteca que asume ejecuciones limpias.

La respuesta de diseño de LangGraph: el estado es un objeto tipado de primera clase, las mutaciones son explícitas y los puntos de control persisten después de cada nodo. La reanudación es una llamada a load_state(session_id).

El Concepto

El grafo

Un grafo está definido por:

• State type (Tipo de estado). Un diccionario tipado (o modelo Pydantic) que cada nodo lee y muta.
• Nodes (Nodos). Funciones puras (state) -> state_update. Las actualizaciones se fusionan en el estado después del retorno.
• Edges (Aristas). Transiciones condicionales o directas entre nodos.
• Entry and exit (Entrada y salida). Los nodos centinela START y END marcan el límite.

Ejemplo: un agente con nodos classify, refund, bug, sales, done — un flujo de trabajo de enrutamiento como un grafo.

Ejecución durable

Después de que cada nodo retorna, el runtime serializa el estado y lo escribe en un checkpointer (SQLite, Postgres, Redis, personalizado). En caso de falla en el paso N, el runtime puede hacer resume(session_id) y continuar desde el paso N+1 con el estado exacto.

La documentación de LangGraph destaca explícitamente a usuarios en producción donde esto importa: Klarna, Uber, J.P. Morgan. La afirmación no es la forma del grafo; es que la forma del grafo más el checkpointing abarata la recuperación.

Streaming

Cada nodo puede generar una salida parcial. El grafo transmite eventos delta por nodo al llamador para que las interfaces de usuario (UIs) se actualicen a medida que se ejecuta el grafo.

Human-in-the-loop (Humano en el bucle)

Inspeccionar y modificar el estado entre nodos. Implementaciones: pausar antes de un nodo crítico, mostrar el estado a un humano, aceptar modificaciones, reanudar. El checkpointer facilita esto porque el estado ya está serializado.

Memoria

A corto plazo (dentro de una ejecución: historial de conversación en el estado) y a largo plazo (entre ejecuciones: persistentemente a través del checkpointer más un almacenamiento externo de largo plazo independiente). LangGraph se integra con sistemas de memoria externa (Mem0, personalizado) a través de herramientas.

Tres topologías

1. Supervisor. El LLM enrutador central delega a subagentes especialistas. create_supervisor() en langgraph-supervisor (aunque el equipo de LangChain en 2026 recomienda hacer esto directamente a través de llamadas de herramientas para un mayor control del contexto).
2. Swarm / peer-to-peer. Los agentes se transfieren el control directamente a través de una superficie de herramientas compartida. Sin enrutador central.
3. Jerárquica. Supervisores que gestionan subsupervisores, implementados como subgrafos anidados.

Dónde falla este patrón

• Puntos de control demasiado pequeños. Guardar puntos de control únicamente de los turnos de conversación deja el estado de las herramientas y las escrituras de memoria de forma irrecuperable al reanudar. Todo el estado debe serializarse.
• Nodos no deterministas. La reanudación asume que las entradas del nodo producen la misma actualización de estado. Se deben capturar semillas aleatorias, reloj de pared y APIs externas.
• Uso excesivo de aristas condicionales. Un grafo con todas las aristas condicionales es una máquina de estados sobre la cual no se puede razonar. Es preferible usar cadenas lineales con bifurcaciones ocasionales.

Constrúyelo

code/main.py implementa un grafo con estado usando stdlib:

• State — un diccionario tipado con messages, step, route, output, human_approval.
• Node — un invocable que recibe el estado y devuelve un diccionario de actualización.
• StateGraph — nodos + aristas + aristas condicionales + run (ejecución) + resume (reanudación).
• SQLiteCheckpointer (simulación en memoria) — serializa el estado después de cada nodo; load(session_id) restaura.
• Un grafo de demostración: classify -> branch(refund / bug / sales) -> human gate -> send.

Ejecútalo:

python3 code/main.py

El trace (rastreo) muestra la primera ejecución fallando en la compuerta humana, la persistencia y luego la reanudación produciendo la salida final.

Úsalo

• LangGraph: la referencia lista para producción. Utiliza create_react_agent, create_supervisor o construye tu propio grafo.
• AutoGen v0.4 (Lesson 14): alternativa de modelo de actores para escenarios de alta concurrencia.
• Claude Agent SDK (Lesson 17): entorno administrado con almacenamiento de sesión integrado.
• Personalizado: cuando necesites control exacto sobre la estructura de estado o el backend del checkpointer.

Envíalo a Producción

outputs/skill-state-graph.md genera un grafo de estado con la forma de LangGraph en cualquier runtime de destino, con el checkpointing y la reanudación integrados.

Ejercicios

1. Agrega una arista condicional desde classify a end cuando la confianza de la clasificación esté por debajo de un umbral. Reanuda la ejecución después de que un humano establezca route manualmente.
2. Intercambia la simulación tipo SQLite por un checkpointer SQLite real. Mide la sobrecarga de serialización por paso.
3. Implementa aristas paralelas: dos nodos se ejecutan concurrentemente, se fusionan mediante un reducer personalizado. ¿Qué ventaja ofrece el estado inmutable aquí?
4. Lee la referencia de langgraph-supervisor. Migra el ejemplo simple a create_supervisor. Compara las formas de los traces.
5. Agrega streaming: cada nodo genera un estado parcial mientras se ejecuta. Imprime los deltas a medida que llegan.

Términos Clave

Lecturas Adicionales

• LangGraph overview — documentos de referencia
• langgraph-supervisor reference — API del patrón supervisor
• AutoGen v0.4, Microsoft Research — alternativa de modelo de actores
• Claude Agent SDK overview — almacenamiento de sesión y subagentes