LangGraph: cómo crear agentes Python con estado, checkpoints y revisión humana

LangGraph no es otra capa bonita para llamar a un LLM. Su valor aparece cuando un agente necesita estado duradero, rutas explícitas, checkpoints, interrupciones humanas y una forma razonable de depurar ejecuciones largas.

LangGraph es un framework de orquestación para agentes con estado. La idea central no es escribir prompts más largos, sino declarar un grafo de ejecución donde cada nodo lee y devuelve estado, las aristas deciden el siguiente paso y un checkpointer permite pausar, reanudar y auditar runs.

Plan de despliegue

Resumen práctico

La keyword principal es LangGraph agentes Python. La intención de búsqueda en español es práctica: entender qué es LangGraph, cuándo usarlo frente a una llamada directa al modelo o un SDK de agentes, y cómo montarlo sin convertir producción en una demo imposible de depurar.

Mi postura: LangGraph merece la pena cuando el workflow tiene estado, bifurcaciones, herramientas, aprobación humana o duración larga. Para un chatbot simple o una única llamada con structured output, probablemente es demasiada maquinaria.

Checklist

Qué problema resuelve LangGraph

Un agente real no falla solo porque el modelo responda mal. Falla porque pierde estado entre pasos, llama tools en orden incorrecto, no se sabe qué decidió antes de actuar, reintenta sin criterio o necesita una persona justo cuando la ejecución ya está a medias.

LangGraph ataca ese problema bajando el agente a una estructura explícita: StateGraph, nodos, edges, estado tipado, checkpointers, streaming e interrupciones humanas. Eso no hace que el modelo sea más listo; hace que el sistema sea más observable y recuperable.

La diferencia importante frente a un script lineal es que el grafo conserva intención. Puedes decir: primero clasifica, luego busca, después decide si llama una tool o pide revisión humana, y finalmente responde o ejecuta. Esa forma se puede razonar, probar y explicar en revisión.

Briefing

Conceptos que debes entender antes de copiar código

State: contrato compartido de la run. Normalmente contiene mensajes, datos recuperados, decisiones, errores, contadores y cualquier campo que necesites para decidir el siguiente paso.

Node: función que recibe estado y devuelve un parche de estado. Un nodo debería tener una responsabilidad concreta: recuperar contexto, decidir tool, validar salida, pedir aprobación o sintetizar respuesta.

Edge: transición entre nodos. Puede ser fija o condicional. Las aristas condicionales son donde aparece la lógica de workflow: si hay tool call, ejecuta tool; si hay riesgo, pausa; si la respuesta está completa, termina.

Checkpointer: capa que guarda snapshots por thread_id. Sin esto, human-in-the-loop y durable execution son frágiles. En desarrollo puedes usar memoria; en producción necesitas almacenamiento externo.

Interrupt: mecanismo para pausar la ejecución y esperar input humano. Es útil para aprobar queries, cambios en repos, emails salientes, acciones sobre infraestructura o cualquier operación que no quieras delegar ciegamente.

La frontera sana: el LLM decide dentro de un grafo, pero el equipo controla estado, persistencia, revisión humana y runtime observable.

Código mínimo con StateGraph

from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver

class AgentState(TypedDict):
    task: str
    draft: str
    needs_review: bool

def plan(state: AgentState) -> dict:
    return {"draft": "Plan para: " + state["task"], "needs_review": True}

def human_gate(state: AgentState) -> dict:
    # En produccion, aqui usarias interrupt() o una cola de aprobacion.
    return state

def route_after_plan(state: AgentState) -> str:
    return "human_gate" if state["needs_review"] else END

builder = StateGraph(AgentState)
builder.add_node("plan", plan)
builder.add_node("human_gate", human_gate)
builder.add_edge(START, "plan")
builder.add_conditional_edges("plan", route_after_plan)
builder.add_edge("human_gate", END)

graph = builder.compile(checkpointer=InMemorySaver())
result = graph.invoke(
    {"task": "preparar un PR de documentacion", "draft": "", "needs_review": False},
    {"configurable": {"thread_id": "demo-1"}},
)

Este ejemplo no pretende ser producción. Sirve para ver la forma mental: estado explícito, nodos pequeños, routing condicional y un thread_id que permite asociar checkpoints a una ejecución. La parte seria empieza cuando sustituyes memoria local por un checkpointer persistente y defines qué acciones requieren aprobación.

Dónde está la decisión de arquitectura

La decisión no es LangGraph sí o no. La decisión real es cuánto control necesitas sobre la trayectoria del agente. Si tu flujo solo genera una respuesta tipada, Pydantic AI u OpenAI Agents SDK pueden bastar. Si necesitas bucles, pausa humana, recuperación tras error y una ruta auditable, LangGraph empieza a justificar su complejidad.

Puntos a revisar

Lo que conviene comprobar

Tampoco usaría LangGraph para esconder lógica de negocio dentro de prompts. Justo al revés: lo usaría para sacar decisiones del prompt y convertirlas en nodos, edges, validadores y checkpoints que el equipo pueda revisar.

Un buen diseño de LangGraph se parece más a un workflow de software que a un chat: entradas claras, estado versionable, pasos nombrados, errores manejables y criterios de salida. Si el grafo solo llama al modelo cinco veces sin contratos, no has ganado arquitectura; has ganado una forma más larga de tener una demo.

Checklist

Checkpoints: desarrollo no es producción

El error normal es quedarse con InMemorySaver porque el tutorial funciona. En memoria está bien para notebooks, tests y ejemplos locales. En producción, si el proceso muere, pierdes la run; si necesitas escalar workers, no compartes estado; si debes auditar, no tienes una historia fiable.

Para producción necesitas un checkpointer externo: Postgres, Redis, DynamoDB u otra capa que encaje con tu infraestructura. Lo importante no es el proveedor, sino las propiedades: persistencia, concurrencia, retención, cifrado, backups y capacidad de buscar por thread o usuario.

AWS publicó un patrón de checkpointing con DynamoDB precisamente porque el checkpointer pasa a ser infraestructura. Esa es la lectura correcta: en agentes duraderos, el estado ya no es un detalle interno del código; es parte de la superficie operativa.

Checklist

Human-in-the-loop sin teatro

Human-in-the-loop no significa que una persona lea todo. Significa que el sistema sabe cuándo debe detenerse. Una aprobación humana útil aparece antes de acciones irreversibles: enviar un email externo, ejecutar una query destructiva, abrir un PR grande, tocar infraestructura, gastar presupuesto o publicar contenido.

La mala versión es pedir aprobación para cada paso y convertir al agente en un formulario lento. La buena versión es clasificar riesgo: lectura sin aprobación, escritura reversible con logs, escritura sensible con interrupción y acciones críticas fuera del alcance del agente.

En LangGraph, interrupt() tiene sentido cuando el estado ya contiene suficiente contexto para que la persona decida. Si el humano tiene que reconstruir toda la run, el grafo no está explicando su propio trabajo.

Briefing

Observabilidad y evals

Para evaluar un agente LangGraph, no midas solo la respuesta final. Mide trayectoria: nodos visitados, tools llamadas, argumentos, reintentos, interrupciones, duración, coste, errores y cambios entre versiones de prompt o modelo.

Una batería mínima debería incluir casos felices, inputs ambiguos, datos hostiles, fallo de tool, timeout, salida inválida, aprobación humana y reanudación desde checkpoint. Si solo pruebas el happy path, justo estás ignorando la razón por la que LangGraph existe.

El logging debe conservar thread_id, versión del grafo, versión de prompts, modelo, tools disponibles y resultado de cada nodo. Sin esa evidencia, depurar un agente duradero se convierte en leer una novela escrita por un modelo con mala memoria.

Lectura práctica

Plan de adopción en cinco días

Día 1: elige un caso con estado real, como triage de tickets, revisión de PRs, generación de reportes o asistente interno con tools.

Día 2: define el State antes de escribir prompts. Si no sabes qué estado existe, no sabes qué estás orquestando.

Día 3: crea un grafo con tres o cuatro nodos y un checkpointer local. Añade logging por nodo desde el principio.

Día 4: cambia a checkpointer persistente y añade un punto de interrupción humana para la acción más sensible.

Día 5: crea evals de trayectoria y prueba reanudación tras fallo. Si no puedes explicar una run fallida, todavía no lo despliegues.

Errores que veo venir

• Meter toda la lógica en un nodo gigante llamado agent. Si todo ocurre dentro de un prompt, LangGraph no te está ayudando a operar el sistema.
• Persistir estado sin política de retención. Los checkpoints pueden contener datos sensibles, prompts, resultados de tools y decisiones intermedias.
• Confundir memory del agente con memoria de usuario. El estado de ejecución no es necesariamente una preferencia duradera del usuario.
• Abrir todas las tools desde el primer día. Empieza con lectura, observa trayectorias y añade mutaciones con aprobación.
• Desplegar sin versionar prompts y grafo. Cambiar el routing o el prompt principal sin evals hace que los checkpoints antiguos sean más difíciles de interpretar.

Cuándo no usaría LangGraph

No lo usaría para un endpoint simple que recibe input, llama al modelo una vez y devuelve JSON validado. Ahí una llamada estructurada o un SDK más directo será más barato de mantener.

Puntos a revisar

Lo que conviene comprobar

No lo usaría si el equipo no tiene todavía tests, logs ni dueño técnico del workflow. Un framework de orquestación no arregla una operación inmadura; la hace más visible.

Tampoco lo usaría para simular autonomía donde en realidad quieres una automatización determinista. Si el proceso se puede escribir como reglas normales, escribe reglas normales y reserva el LLM para partes ambiguas.

Checklist

Conclusión

LangGraph es valioso cuando aceptas una premisa incómoda: un agente de producción es un sistema distribuido pequeño, no un prompt con marketing. Tiene estado, fallos parciales, decisiones intermedias, permisos, observabilidad y usuarios esperando una respuesta explicable.

Mi recomendación es empezar con un grafo pequeño, estado explícito, checkpointer persistente, una sola interrupción humana y evals de trayectoria. Si eso funciona, amplía. Si no funciona, el problema no era falta de nodos; era falta de diseño.

Preguntas frecuentes

¿Qué es LangGraph?

LangGraph es un framework para construir agentes y workflows con estado usando grafos: defines estado, nodos, edges, persistencia, streaming e interrupciones humanas.

¿LangGraph reemplaza a LangChain?

No. LangGraph forma parte del ecosistema LangChain, pero se centra en orquestación de agentes stateful y workflows duraderos.

¿Cuándo conviene usar LangGraph?

Conviene cuando el agente necesita varios pasos, routing condicional, tools, checkpoints, recuperación, human-in-the-loop u observabilidad de trayectoria.

¿InMemorySaver sirve para producción?

No como base seria. Es útil para desarrollo y pruebas, pero producción necesita un checkpointer persistente y operable.

¿LangGraph es mejor que Pydantic AI o Google ADK?

No universalmente. LangGraph destaca en control de workflow y estado; Pydantic AI destaca en contratos Python tipados; Google ADK encaja mejor si priorizas el stack Google.

¿Qué debo medir en un agente LangGraph?

Mide respuesta final, nodos visitados, tool calls, argumentos, reintentos, interrupciones humanas, latencia, coste y éxito de reanudación desde checkpoints.

Cómo llevar un agente LangGraph a producción

1. Definir el estado. Escribe el contrato de State con mensajes, contexto, decisiones, errores y metadatos mínimos antes de crear nodos.
2. Separar nodos. Divide planificación, recuperación, decisión, tool calls, validación y síntesis en nodos pequeños y observables.
3. Persistir checkpoints. Sustituye memoria local por un checkpointer externo con retención, cifrado, backups y búsqueda por thread.
4. Añadir revisión humana. Usa interrupciones solo para acciones sensibles y entrega al humano un estado suficiente para decidir rápido.
5. Evaluar trayectorias. Crea casos que verifiquen nodos recorridos, tools llamadas, errores, reintentos y reanudación tras fallo.
6. Desplegar con límites. Publica el runtime con logging, límites de coste, timeouts, versionado de prompts y rollback claro.

Cierre editorial

Regla operativa

Activa la automatización donde el comentario pueda cambiar una decisión técnica, no donde solo vaya a producir ruido revisable.

Fuentes y referencias

• LangGraph overview
• LangGraph thinking in LangGraph
• LangGraph checkpointers
• LangGraph human-in-the-loop
• LangGraph GitHub repository
• LangChain: LangGraph v1.0 alpha
• AWS: durable AI agents with LangGraph and DynamoDB
• AWS: serverless LangGraph multi-agent systems with AgentCore

También te puede interesar

• Pydantic AI: agentes Python tipados
• Google ADK: agentes Python con tools y evals
• OpenAI Agents SDK: MCP, guardrails y tracing
• Métricas para agentes de código

---

Cada semana resumo herramientas de IA para developers (agentes, MCP, seguridad, workflows) en un email corto en español. Suscríbete gratis.

Publicado originalmente en devaisemanal.com.