LangGraph

Resumen

LangGraph es un framework y runtime de bajo nivel para construir agentes y workflows de IA con estado. Modela una ejecución como un grafo: el estado viaja entre nodos, los nodos hacen trabajo, y los edges deciden qué nodo corre después.

Importa porque muchos agentes no son una cadena lineal. Pueden necesitar ciclos, rutas condicionales, llamadas a herramientas, checkpoints, reintentos, streaming o pausas para aprobación humana. LangGraph hace explícito ese control de flujo, en vez de esconderlo dentro de un prompt largo o un loop improvisado.

Alcance y supuestos

Este paquete cubre LangGraph a nivel conceptual: estado del grafo, nodos, edges, routing condicional, ejecución durable e interrupciones human-in-the-loop. Lo presenta como herramienta para orquestar agentes IA y workflows complejos.

No cubre una guía completa del SDK, deployment, LangSmith, observabilidad avanzada ni la referencia exacta de Python o JavaScript. Asume que entiendes prompts, tools, workflows, agentes IA y el problema de mantener estado entre pasos.

Modelo mental

Piensa en un tablero de operaciones con tarjetas que avanzan entre estaciones. Una estación investiga, otra llama una API, otra decide si falta información y otra pide aprobación humana. La tarjeta lleva su historial: qué se intentó, qué datos aparecieron y qué falta resolver.

LangGraph convierte esa idea en código. El estado es la tarjeta compartida. Los nodos son estaciones de trabajo. Los edges son las reglas de tránsito. Un edge normal dice "después de A viene B". Un edge condicional dice "si falta evidencia, vuelve a buscar; si está listo, responde; si hay riesgo, pausa y pide aprobación".

La diferencia con una cadena simple es el control explícito. Una chain suele avanzar en línea recta. Un grafo puede bifurcarse, repetir pasos, pausar y retomar. Esa estructura es útil cuando el comportamiento del agente depende de lo que descubre durante la ejecución.

Uso práctico

Usa LangGraph cuando el flujo de IA necesita estado y decisiones de control:

• ✅ Un agente de soporte puede buscar información, decidir si necesita más datos, escalar casos riesgosos y luego redactar respuesta.
• ✅ Un flujo de investigación puede iterar entre búsqueda, lectura y síntesis hasta cumplir un criterio de evidencia.
• ❌ Si solo haces un prompt con una respuesta final, LangGraph probablemente agrega complejidad innecesaria.
• ❌ Si el proceso es un pipeline fijo sin ramas ni estado relevante, un workflow tradicional puede ser más simple.

Ejemplo trabajado: modelar un agente de soporte con grafo de estado

Supón que quieres automatizar triage de tickets. El agente debe buscar el pedido, revisar política, decidir si puede responder o si necesita aprobación humana.

Primero defines el estado que viajará por el grafo:

type SupportState = {
  ticket: string;
  orderStatus?: string;
  policy?: string;
  risk: "unknown" | "low" | "high";
  answer?: string;
};

Luego defines nodos como pasos pequeños. Cada nodo lee estado y devuelve una actualización:

type Node = (state: SupportState) => Promise<Partial<SupportState>>;

const fetchOrder: Node = async () => ({
  orderStatus: "delivered",
});

const fetchPolicy: Node = async () => ({
  policy: "Si el cliente disputa entrega, abrir investigación antes de reembolsar.",
});

const assessRisk: Node = async (state) => ({
  risk: state.orderStatus === "delivered" ? "high" : "low",
});

const draftAnswer: Node = async (state) => ({
  answer: `Abriremos investigación con courier. Política aplicada: ${state.policy}`,
});

La parte importante no son los nombres, sino la separación entre trabajo y routing. Los nodos hacen trabajo; los edges deciden el siguiente paso.

function routeAfterRisk(state: SupportState) {
  if (state.risk === "high") return "humanApproval";
  return "draftAnswer";
}

En LangGraph, esa ruta condicional permite expresar ciclos y pausas con intención clara. Si el riesgo es alto, el grafo puede interrumpirse para aprobación humana. Si el riesgo es bajo, continúa automáticamente.

El diseño final se puede pensar así:

START
  -> fetchOrder
  -> fetchPolicy
  -> assessRisk
  -> humanApproval si risk = high
  -> draftAnswer si risk = low o aprobación OK
  -> END

Esto evita dos extremos comunes: un prompt gigante que intenta decidir todo sin estructura, o un workflow rígido que no puede adaptarse a lo que encuentra. LangGraph sirve cuando necesitas autonomía acotada y trazable.

Antes de usarlo, revisa cinco decisiones:

1. ¿Qué forma tiene el estado compartido?
2. ¿Qué nodos son pasos atómicos y testeables?
3. ¿Qué edges son fijos y cuáles son condicionales?
4. ¿Dónde debe pausar el sistema para aprobación humana?
5. ¿Qué datos deben persistirse para reanudar o auditar la ejecución?

Si no puedes responder esas preguntas, el problema probablemente no está listo para un grafo. Si sí puedes, LangGraph ayuda a convertir un agente difuso en una máquina de estados explícita.

Evidencia

• LangGraph documentation, Overview define LangGraph como framework y runtime de bajo nivel para construir, gestionar y desplegar agentes stateful de larga duración.
• LangGraph documentation, Graph API overview describe nodos y edges como piezas centrales: los nodos hacen trabajo y los edges determinan qué ejecutar después según el estado.
• LangGraph documentation, Interrupts explica cómo pausar la ejecución y esperar input externo, habilitando patrones human-in-the-loop.