LangGraph en la práctica: cómo estructurar grafos cíclicos y checkpoints para agentes

Si ya construiste un agente que repite la misma llamada sin progreso o que pierde el contexto al encontrar un error, LangGraph ataca ese problema. Trata al agente como una máquina de estados, con checkpoints que permiten pausar, inspeccionar y reanudar.

El repositorio langchain-ai/langgraph tiene más de 44 mil estrellas, licencia MIT y recibió actualización el 8 de noviembre de 2026. Forma parte del ecosistema LangChain, pero puede usarse de forma independiente.

En este artículo verás:

• Qué es un grafo de estado y por qué ayuda a los agentes
• Cómo instalar y crear un grafo simple
• Cómo usar checkpoints para recuperar estado
• Cuándo usar LangGraph y cuándo basta una cadena lineal
• Límites y buenas prácticas

Qué es LangGraph y cómo funciona el grafo de estado

Un agente basado en cadena lineal ejecuta pasos en orden fijo. Si un paso falla, la cadena se rompe. Si el agente necesita volver y intentar de nuevo, debes reimplementar la lógica de reintento manualmente.

LangGraph modela al agente como un grafo. Cada nodo es una función que recibe el estado actual y retorna una actualización. Las aristas definen el orden de ejecución, incluyendo condiciones. Un nodo puede llevar de vuelta a un nodo anterior, creando un ciclo controlado.

El estado es un objeto compartido, generalmente un TypedDict o una clase Pydantic. Cada nodo lee y escribe campos de ese estado. Esto hace que el flujo sea explícito e inspeccionable.

Este enfoque es útil para agentes que necesitan planificar, ejecutar, verificar y replantear. El ciclo planificar ejecutar verificar es natural en un grafo, pero incómodo en una cadena lineal.

Cómo instalar LangGraph y crear un grafo simple

La instalación es directa. El paquete principal es langgraph.

$ pip install langgraph

Después, define el estado y los nodos.

from typing import TypedDict
from langgraph.graph import StateGraph, END

class Estado(TypedDict):
    entrada: str
    saida: str

def processar(estado: Estado) -> Estado:
    return {"saida": estado["entrada"].upper()}

grafo = StateGraph(Estado)
grafo.add_node("processar", processar)
grafo.set_entry_point("processar")
grafo.add_edge("processar", END)

app = grafo.compile()
resultado = app.invoke({"entrada": "olá"})
print(resultado)

El método compile genera una aplicación ejecutable. El método invoke ejecuta el grafo con el estado inicial. Puedes usar stream para seguir cada paso, lo que ayuda en la depuración.

Si ya usas LangChain, puedes reutilizar modelos y herramientas. LangGraph no obliga el uso de LangChain, pero la integración es natural.

Cómo usar checkpoints para recuperar estado

Los checkpoints son el diferencial de LangGraph. En cada paso, el framework puede guardar el estado en un almacenamiento, como SQLite o PostgreSQL. Si el proceso cae, reanudas desde el último checkpoint en lugar de empezar de cero.

Esto es esencial para agentes de larga duración, como los que procesan documentos grandes o ejecutan tareas en segundo plano. También facilita la auditoría, porque puedes inspeccionar el estado en cualquier punto.

Para activar checkpoints, pasa un checkpointer al compilar el grafo.

from langgraph.checkpoint.sqlite import SqliteSaver

memoria = SqliteSaver.from_conn_string("checkpoints.db")
app = grafo.compile(checkpointer=memoria)
config = {"configurable": {"thread_id": "1"}}
resultado = app.invoke({"entrada": "olá"}, config=config)

El thread_id identifica la ejecución. Con él, puedes reanudar después o inspeccionar el historial de estados.

Cuándo usar LangGraph y cuándo basta una cadena lineal

No todo agente necesita grafo. Si la tarea es una secuencia fija de llamadas, como resumir un texto y luego traducirlo, una cadena lineal es más simple y más rápida de implementar.

Usa LangGraph cuando el agente necesita iterar, decidir caminos diferentes o recuperarse de fallas. Casos típicos incluyen agentes de investigación que refinan la búsqueda, agentes de código que prueban y corrigen, y flujos con aprobación humana en el medio.

Si necesitas memoria persistente entre ejecuciones, combina LangGraph con una capa de memoria. Ve Mem0: cómo dar memoria persistente a agentes de IA. Si la tarea involucra navegador, ve browser-use: cómo conectar agentes de IA al navegador.

Límites y buenas prácticas

Los grafos añaden complejidad. Un grafo mal diseñado puede entrar en un bucle infinito o generar estados inconsistentes. Define límites de iteración y valida el estado en cada nodo.

Otro punto es la depuración. Los grafos son más difíciles de depurar que las cadenas lineales. Usa stream y logging para seguir cada transición. La documentación oficial incluye herramientas de visualización que ayudan.

Buenas prácticas que valen para cualquier agente basado en grafo:

• Mantén el estado pequeño y enfocado
• Valida entradas y salidas en cada nodo
• Define un límite máximo de iteraciones
• Usa checkpoints en producción, no solo en desarrollo
• Prueba cada nodo de forma aislada antes de componer el grafo

Si coordinas varios agentes, cada uno puede ser un subgrafo con su propio estado. En bridgecode montas ese squad y acompañas cada etapa, desde la planificación hasta la entrega.

Preguntas frecuentes sobre LangGraph

¿Es LangGraph gratuito?

Sí. Es open source con licencia MIT. El costo proviene del proveedor del modelo y de la infraestructura de checkpoint.

¿Necesito usar LangChain para usar LangGraph?

No. LangGraph puede usarse de forma independiente. La integración con LangChain es opcional y facilita la reutilización de modelos y herramientas.

¿LangGraph reemplaza a LangChain?

No. Se complementan. LangChain ofrece componentes e integraciones. LangGraph ofrece la orquestación basada en grafo. Puedes usar ambos juntos.

¿Cómo evitar bucles infinitos en un grafo?

Define un límite de iteraciones en el estado y verifícalo en cada nodo. LangGraph también permite configurar límites de recursión al invocar el grafo.

¿Funciona con modelos locales?

Sí, siempre que uses un modelo compatible. Ollama y vLLM funcionan cuando se integran vía LangChain o directamente.