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 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.
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.
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.
¿Te está sirviendo? Hay una dosis cada semana
Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.
Suscribirme gratisCódigo mínimo con StateGraph
<pre><code class="language-python">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"}}, )</code></pre>
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.
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.
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
- Definir el estado. Escribe el contrato de `State` con mensajes, contexto, decisiones, errores y metadatos mínimos antes de crear nodos.
- Separar nodos. Divide planificación, recuperación, decisión, tool calls, validación y síntesis en nodos pequeños y observables.
- Persistir checkpoints. Sustituye memoria local por un checkpointer externo con retención, cifrado, backups y búsqueda por thread.
- Añadir revisión humana. Usa interrupciones solo para acciones sensibles y entrega al humano un estado suficiente para decidir rápido.
- Evaluar trayectorias. Crea casos que verifiquen nodos recorridos, tools llamadas, errores, reintentos y reanudación tras fallo.
- Desplegar con límites. Publica el runtime con logging, límites de coste, timeouts, versionado de prompts y rollback claro.
Fuentes y referencias
También te puede interesar
Pydantic AI: agentes Python tipadosGoogle ADK: agentes Python con tools y evalsOpenAI Agents SDK: MCP, guardrails y tracingMétricas para agentes de códigoRecibe una lectura semanal de herramientas IA para devs
Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.
Suscribirme gratis
