LangGraph: grafos de agentes con estado que sí puedes depurar

La mayoría de los agentes empiezan como un bucle «while» alrededor de una llamada al modelo, y ese bucle funciona de maravilla hasta que necesitas que reintente cuando falla un control de calidad, que espere a que un humano apruebe un paso, o que le pase el trabajo a un sub-agente y vuelva. En ese punto, el control de flujo que estaba implícito en tu prompt, "sigue hasta que termines", se vuelve la parte más difícil de ver del sistema y la más fácil de romper. La apuesta de LangGraph es que escribas ese control de flujo como un grafo explícito y tipado en vez de enterrarlo en prosa, y a cambio te llevas checkpointing, corridas que se reanudan solas y corridas que de verdad puedes trazar. Aquí va qué es la herramienta, cuándo se gana su ceremonia, un quickstart que puedes copiar y pegar, y las concesiones que nadie pone en el README.

01 · Qué es en realidad

LangGraph modela un agente como un grafo dirigido sobre un único objeto de estado compartido. Declaras la forma de ese estado una sola vez, registras nodos (funciones normales que leen el estado y devuelven una actualización parcial) y los conectas con aristas. Las aristas pueden ser incondicionales ("después de planear, siempre actúa") o condicionales, una función de routing mira el estado actual y devuelve el nombre del siguiente nodo. Ese es todo el modelo mental: los nodos hacen el trabajo, las aristas deciden y el estado carga todo lo que va en medio.

Dos cosas lo vuelven algo más que un «if/else» con más adornos:

• El estado es tipado y compartido. Cada nodo ve el mismo objeto de estado y le aporta una actualización parcial. No estás pasando argumentos por una pila de llamadas; estás leyendo y escribiendo campos sobre una sola estructura que maneja el runtime.
• El grafo tiene checkpoints. Cuando compilas con un checkpointer, el runtime guarda el estado después de cada nodo. Una corrida identificada por un thread id puede detenerse, porque llegó a un interrupt, se cayó o mataste el proceso, y más tarde retomar justo donde se quedó, con el estado intacto.

Esa segunda propiedad es la verdadera razón para usarlo. Un bucle común sabe ramificar y reintentar; lo que no hace fácil es pausarse un día entero esperando a un humano, sobrevivir a un deploy y retomar a mitad de corrida sin rehacer todo.

02 · Cuándo usarlo (y cuándo no)

Usa LangGraph cuando tu agente necesita control de flujo de verdad, ese que de otro modo estarías armando a mano y te quedaría mal:

• Un bucle de investigación o generación que reintenta hasta pasar un control de calidad, genera, critica, decide "ya está bien o va otra vez", con un tope duro de iteraciones.
• Un paso con humano de por medio: el grafo llega a un nodo de aprobación, hace interrupt y espera, quizá minutos o días, hasta que un humano retoma el thread con una decisión.
• Un patrón de supervisor: un nodo reparte trabajo a sub-agentes especializados (buscar, programar, resumir) y junta sus resultados antes de decidir qué sigue.
• Cualquier cosa larga o interrumpible, donde aguantar un reinicio y retomar a media corrida es un requisito, no un lujo.

No lo uses cuando la tarea es mandar un prompt y recibir respuesta, o un bucle corto de uso de tools sin ninguna ramificación que te importe. Envolver una llamada de una sola pasada en un grafo te suma un esquema de estado, un paso de compile y un checkpointer a cambio de cero beneficio, eso es ceremonia, no arquitectura.

Cómo se compara

• vs. el SDK de Claude en un bucle: el SDK es el punto de partida correcto para agentes simples y no te da nada contra qué pelear. Das el salto a LangGraph cuando el bucle gana ramas, esperas y la necesidad de retomar.
• vs. un motor de workflows genérico (n8n, Temporal): esos orquestan sistemas y jobs durables; LangGraph orquesta los pasos de razonamiento de un agente, sobre un estado con forma de modelo. Otro nivel. Es común tener a n8n disparando una corrida de LangGraph, no reemplazándola.
• vs. armar tu propia máquina de estados: puedes, y para un grafo diminuto quizá deberías. LangGraph se gana su lugar cuando quieres checkpointing, depuración con viaje en el tiempo e interrupts con humano de por medio sin escribir tú mismo la capa de persistencia.

03 · Quickstart

Instálalo junto al SDK de modelo que ya estés usando:

pip install langgraph

La forma mínima es un tipo de estado, un par de nodos y una arista condicional que cierra un bucle. Aquí va un bucle plan/act que reintenta hasta que un router decide que ya terminó, con checkpointing activado para que la corrida se pueda reanudar:

from typing import Annotated, TypedDict
from operator import add
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver

class State(TypedDict):
    task: str
    # messages ACUMULA — fíjate en el reducer
    messages: Annotated[list, add]
    attempts: int

def plan(state: State) -> dict:
    return {"messages": [f"plan para: {state['task']}"]}

def act(state: State) -> dict:
    # ... aquí llamas a tu modelo ...
    return {"messages": ["hice la tarea"], "attempts": state.get("attempts", 0) + 1}

def route(state: State) -> str:
    return "done" if state["attempts"] >= 3 else "again"

g = StateGraph(State)
g.add_node("plan", plan)
g.add_node("act", act)
g.add_edge(START, "plan")
g.add_edge("plan", "act")
g.add_conditional_edges("act", route, {"again": "plan", "done": END})

app = g.compile(checkpointer=MemorySaver())

# El thread id es lo que vuelve reanudable una corrida.
config = {"configurable": {"thread_id": "run-1"}}
result = app.invoke({"task": "resumir el repo", "attempts": 0}, config)

Cambia MemorySaver por un checkpointer respaldado en base de datos (Postgres, por ejemplo) y el mismo grafo se vuelve durable aunque el proceso se reinicie, el thread id es lo único que necesitas para retomar.

04 · La trampa de los reducers

Esto es lo que muerde a todo el mundo, así que se gana su propia sección. Entre nodos, LangGraph fusiona las actualizaciones de estado campo por campo, no reemplaza el objeto entero. Para un campo escalar es intuitivo: devuelves un «attempts» nuevo y pisa al viejo. La trampa está en los campos que se supone que acumulan, como una lista de mensajes.

Si declaras «messages: list» y un nodo devuelve una lista parcial, la fusión reemplaza la lista anterior con la nueva, tu historial se esfumó, sin avisar y sin ningún error. El arreglo es anotar el campo con un reducer que le diga al runtime cómo combinar las actualizaciones. En el quickstart de arriba, «Annotated[list, add]» dice "agrega, no reemplaces", así que los mensajes de cada nodo se concatenan en vez de pisarse entre sí.

Un segundo detalle relacionado: los nodos deben devolver actualizaciones parciales, no el estado completo. Devolver el objeto de estado entero funciona, pero te tienta a pisar sin querer un campo con reducer al pasarle de vuelta su valor viejo. Devuelve solo las claves que el nodo de verdad cambió.

05 · Concesiones honestas

LangGraph es la herramienta correcta para toda una clase de problema, pero no sale gratis:

• Es una dependencia real con su curva de aprendizaje. Esquemas de estado, reducers, aristas condicionales y checkpointers son conceptos que tienes que llevar en la cabeza. Para un agente simple, eso es carga extra que vas a terminar odiando.
• La abstracción puede esconderte el costo. Un bucle que "reintenta hasta pasar calidad" es un bucle que puede llamar al modelo un montón de veces. Pon un tope duro de iteraciones en cada ciclo y vigila tu gasto de tokens. El grafo vuelve el bucle fácil de escribir y, justo igual, fácil de que se te descontrole.
• El estado con checkpoints es estado que ahora te toca administrar a ti. Los threads persistidos se van acumulando; necesitas un plan para expirarlos o limpiarlos, y para decidir qué es seguro guardar. Trata el almacenamiento de checkpoints como cualquier otra base de datos, incluida la parte de que puede terminar guardando datos intermedios sensibles.
• Que sea fácil de depurar es la recompensa, pero solo si la aprovechas. Toda la razón de pagar la ceremonia es que las aristas explícitas y el estado persistido vuelven trazable una corrida. Si no te apoyas en el tracing ni en el viaje en el tiempo, te quedaste con el costo y sin el beneficio.

Yo me apoyo mucho en el pensamiento de grafos en Agent Orchestra, hacer explícitas las aristas es justo lo que convierte una corrida multi-agente de "el modelo hizo algo" en algo que puedo recorrer paso a paso, repetir y entender. Ese es el trato: más estructura por adelantado, muchísimo menos misterio cuando una corrida se va de lado.

LangGraph rinde cuando el control de flujo es la parte difícil de tu agente y ya te cansaste de que sea invisible. Échale mano en cuanto tu bucle gane una espera o una rama real que te importe, mantén un tope de iteraciones en cada ciclo y respeta la regla del reducer desde el día uno. Sáltatelo para llamadas de una sola pasada. Ahí el SDK directo es la respuesta honesta, y meterle un grafo sería pura ceremonia.