LangGraph: guía de grafos, memoria y despliegue

LangGraph es una biblioteca de orquestación que representa un proceso mediante un estado compartido, nodos de procesamiento y transiciones explícitas. Permite combinar reglas deterministas, llamadas a modelos, herramientas y aprobación humana en una aplicación que conserva el avance de la ejecución. Su fiabilidad depende, sin embargo, del almacenamiento, las condiciones de parada y las protecciones que usted implemente para las acciones externas.

¿Para qué sirve LangGraph en una aplicación de agentes?

LangGraph interviene cuando necesita decidir qué paso ejecutar, con qué datos y en qué condiciones reanudar un proceso. Esta orquestación de agentes no sustituye al modelo de lenguaje ni a los servicios del negocio: organiza la interacción entre ellos.

Imagine un asistente que gestiona solicitudes de clientes. Identifica la petición, consulta un pedido, prepara una propuesta, espera una aprobación cuando corresponde y ejecuta después una acción autorizada. El grafo hace visibles estos pasos y permite distinguir las decisiones del modelo de las reglas que impone su aplicación.

LangChain ofrece, entre otras cosas, abstracciones para modelos, mensajes y herramientas; LangGraph permite controlar las transiciones de forma más directa. Para comparar este enfoque con otras soluciones, consulte nuestro directorio de agentes y frameworks y el artículo sobre frameworks de agentes de IA.

La elección debe partir del control que necesita:

Criterio	Funciones secuenciales	Bucle de agente	Grafo explícito
Ruta de ejecución	Definida en el código	Elegida en parte por el modelo	Transiciones definidas y decisiones sujetas a reglas
Estado intermedio	Debe organizarse	Suele centrarse en los mensajes	Esquema compartido entre pasos
Aprobación humana	Debe desarrollarse	Depende de la implementación	Puede formar parte del recorrido
Complejidad de diseño	Limitada en procesos cortos	Aumenta con las excepciones	Requiere diseñar el estado y las transiciones

Un grafo no garantiza por sí mismo que una respuesta sea correcta. Su utilidad consiste en hacer que las decisiones se puedan controlar y que los fallos se puedan interpretar.

Entender el estado, los nodos y las transiciones

El estado contiene la información necesaria para continuar el proceso: solicitud inicial, documentos recuperados, resultados verificados, propuesta y situación de la aprobación. Un nodo recibe ese estado y devuelve una actualización. Las aristas definen los pasos siguientes, que pueden depender de una condición. La documentación de Graph API describe estos componentes y la compilación del grafo.

Separe los hechos de las interpretaciones. Una referencia de pedido obtenida del sistema de gestión no tiene el mismo valor que una categoría estimada por un modelo. Conserve la procedencia de ambos datos para poder explicar una decisión y corregir una interpretación sin perder la información original.

Cada campo tiene una regla de actualización, denominada reducer. De forma predeterminada, el valor nuevo sustituye al anterior; una regla personalizada puede combinar las distintas aportaciones. Esta diferencia resulta esencial cuando varias ramas generan resultados destinados al mismo campo.

Utilice campos estructurados en lugar de acumular todo en un texto largo. Un estado explícito como validation_requise se comprueba con más facilidad que una frase en la que el modelo recomienda una revisión. Mantenga también las conexiones y los secretos fuera del estado de negocio que se almacena.

Por último, defina las salidas antes de diseñar los bucles. En cada paso, identifique qué ocurre si hay éxito, un error recuperable, una cancelación o una necesidad de intervención. Un recorrido cuyo final no pueda explicar todavía necesita una definición más precisa.

Requisitos previos y paso 1: instalar los componentes básicos

La parte práctica utiliza Python y comienza sin llamadas a modelos. Debe saber definir una función, manejar un diccionario, interpretar una excepción y gestionar las dependencias de un proyecto. Para el servidor local que se presenta más adelante, la documentación consultada el 24 de octubre de 2026 exige Python 3.11 o posterior.

Prepare un entorno aislado con su gestor habitual. La documentación oficial de instalación proporciona este comando, reproducido sin cambios:

pip install -U langgraph

Este comando instala o actualiza el paquete disponible; no fija las versiones para reproducir el entorno. Una vez validada la aplicación, registre las versiones utilizadas en su gestor de dependencias y conserve el archivo de bloqueo correspondiente.

El siguiente ejemplo no necesita ninguna clave de proveedor. Cuando añada un modelo, instale su integración siguiendo la documentación y proporcione los secretos al proceso mediante un mecanismo adecuado para su entorno. Evite copiarlos en los ejemplos, los registros o los checkpoints.

Defina también un escenario de comprobación antes de empezar a programar. En este caso, una solicitud generará un borrador, esperará una decisión y terminará con un estado. Los resultados esperados son sencillos: la aprobación completa el recorrido, el rechazo impide que continúe y no se realiza ninguna acción externa.

Esta secuencia permite distinguir los errores de orquestación de los fallos del modelo o de la red.

Paso 2: construir un grafo con aprobación humana

El siguiente ejemplo didáctico adapta los componentes oficiales. Genera un borrador determinista para que pueda examinar el mecanismo de pausa sin depender de una respuesta generada por un modelo.

from typing import TypedDict

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command, interrupt


class Etat(TypedDict, total=False):
    demande: str
    brouillon: str
    approuve: bool
    statut: str


def preparer(etat: Etat):
    return {
        "brouillon": "Proposition à examiner : " + etat["demande"],
        "statut": "en_attente",
    }


def valider(etat: Etat):
    decision = interrupt({
        "action": "examiner_brouillon",
        "brouillon": etat["brouillon"],
    })
    return {"approuve": decision is True}


def orienter(etat: Etat):
    return "terminer" if etat["approuve"] else "refuser"


def terminer(etat: Etat):
    return {"statut": "approuve_sans_envoi"}


def refuser(etat: Etat):
    return {"statut": "refuse"}


builder = StateGraph(Etat)
builder.add_node("preparer", preparer)
builder.add_node("valider", valider)
builder.add_node("terminer", terminer)
builder.add_node("refuser", refuser)

builder.add_edge(START, "preparer")
builder.add_edge("preparer", "valider")
builder.add_conditional_edges("valider", orienter)
builder.add_edge("terminer", END)
builder.add_edge("refuser", END)

graph = builder.compile(checkpointer=InMemorySaver())

config = {"configurable": {"thread_id": "demande-demo"}}

pause = graph.invoke(
    {"demande": "Préparer une réponse au client"},
    config=config,
)
print(pause)

# Llamar después de obtener una decisión explícita en su aplicación.
resultat = graph.invoke(Command(resume=True), config=config)
print(resultat["statut"])

La llamada a interrupt suspende el recorrido; al reanudarlo, se transmite un valor mediante Command. La documentación sobre interrupciones exige, entre otras cosas, un checkpointer, un identificador de hilo y datos serializables en la interrupción.

En este ejemplo, el valor True representa una aprobación que ya se ha obtenido. Una interfaz real debe autenticar a la persona, mostrarle el borrador exacto y transmitir su decisión. El hilo identifica el recorrido; no demuestra que el usuario tenga derecho a consultarlo.

Compruebe el rechazo por separado, utilizando otro hilo y reanudándolo con False. Así dispondrá de una primera comprobación de las rutas de ejecución sin haber autorizado todavía ningún envío.

Paso 3: organizar la memoria y la persistencia

LangGraph distingue dos mecanismos complementarios: el checkpointer conserva el estado de un hilo, mientras que un store guarda datos de la aplicación que pueden utilizarse entre distintos hilos. La documentación sobre persistencia explica esta diferencia.

Criterio	Checkpointer	Store
Datos conservados	Instantáneas del estado del grafo	Información definida por la aplicación
Ámbito lógico	Un hilo concreto	Varios hilos, según su organización
Uso habitual	Continuidad y reanudación de un proceso	Preferencias o conocimientos duraderos
Pregunta de diseño	¿Dónde debe reanudarse el recorrido?	¿Qué información debe recuperarse más adelante?

InMemorySaver sirve para una demostración dentro del mismo proceso. No debe presentarse como una copia que sobreviva a un reinicio. Para una aplicación que deba conservar los datos, elija un almacenamiento persistente compatible con sus requisitos operativos.

La memoria de un agente también necesita criterios editoriales y técnicos. Una información propuesta por el modelo no debería convertirse en un hecho duradero sin verificación. Registre su fuente, su alcance y, cuando sea relevante, su periodo de validez.

Conservar el historial y enviarlo completo al modelo son decisiones distintas. Puede guardar eventos para auditoría y preparar al mismo tiempo un contexto reducido para cada llamada. El artículo sobre la memoria de los agentes de IA desarrolla esta diferencia.

Defina también cómo se eliminan los datos: borrar una preferencia del store puede dejar copias en estados anteriores, trazas o respaldos. Identifique todos esos lugares antes de afirmar que un dato se ha eliminado.

Paso 4: añadir un modelo y herramientas controladas

Cuando haya comprendido el recorrido determinista, sustituya la preparación del borrador por una llamada al modelo. Mantenga la aprobación y las reglas del negocio en el código. Pedir al modelo que respete un límite no sustituye a un mecanismo que lo haga cumplir.

La guía oficial de inicio rápido presenta un bucle en el que el modelo propone llamadas a herramientas, un nodo las ejecuta y los resultados vuelven al modelo. Utilice esta estructura como punto de partida y añada los controles que necesita su aplicación.

Para cada herramienta, defina:

los argumentos admitidos y su validación;
los permisos necesarios y el alcance de los datos accesibles;
el tiempo máximo de espera y los errores recuperables;
los efectos externos y las condiciones de aprobación;
el resultado estructurado que necesitan los siguientes pasos del grafo.

Una herramienta de lectura y otra de escritura deberían tener permisos distintos. Si el asistente solo debe preparar una respuesta, su acceso al servicio de correo no debería permitirle enviarla.

La inyección de prompts sigue siendo posible a través de los documentos y los resultados de las herramientas. Trate esos contenidos como datos: no pueden ampliar los permisos ni anular una aprobación prevista. Las protecciones deben seguir activas aunque el modelo obedezca una instrucción maliciosa.

Cuando un servicio devuelva un resultado incompleto, evite presentarlo como un éxito. Devuelva un estado que la aplicación pueda procesar: sin resultados, acceso denegado, tiempo de espera agotado o datos no válidos. Así el grafo podrá elegir de forma explícita cómo continuar.

Paso 5: hacer que las acciones admitan reanudaciones

Los checkpointers guardan instantáneas en los límites entre superpasos y permiten, entre otras cosas, inspeccionar el historial. Sin embargo, un checkpoint no constituye una transacción compartida con su correo, su software contable o su servicio de pagos.

Suponga que un envío se completa y después se produce un fallo antes de guardar la confirmación. Al reanudar el proceso, la aplicación puede desconocer si el envío llegó a realizarse. Debe poder recuperar esa información en lugar de repetir la acción sin comprobarlo.

Para las operaciones sensibles, utilice una clave de idempotencia que reconozca el servicio de destino o un registro de operaciones que permita verificar el resultado. Conserve una referencia estable de la operación, independiente de las reformulaciones que pueda generar el modelo.

El código situado antes de una interrupción dentro de un nodo puede volver a ejecutarse durante la reanudación. Por ello, sitúe los efectos externos después de la decisión necesaria y diséñelos para admitir ejecuciones repetidas. Evite un nodo demasiado amplio que mezcle búsqueda, aprobación y envío.

Aplique también una política de reintentos distinta según el error. Un fallo temporal de red puede justificar otro intento; una denegación de permisos suele requerir una decisión diferente. Una entrada no válida debe corregirse antes de volver a llamar al servicio.

Documente el comportamiento esperado si se interrumpe la ejecución en cada punto sensible. Este análisis suele revelar más defectos que una prueba en la que todos los servicios responden con normalidad.

Paso 6: iniciar el servidor local y preparar el despliegue

Para explorar una aplicación como servicio, el procedimiento oficial del servidor local, consultado el 24 de octubre de 2026, proporciona los siguientes comandos:

pip install -U "langgraph-cli[inmem]"
langgraph new path/to/your/app --template new-langgraph-project-python
cd path/to/your/app
pip install -e .

La ruta propuesta es un ejemplo que debe adaptar. La plantilla generada contiene la estructura inicial; deberá integrar en ella su grafo y comprobar cómo está declarado en la configuración de la aplicación.

El procedimiento también pide crear un archivo .env a partir de la plantilla incluida e introducir una clave de LangSmith. Mantenga este archivo fuera del repositorio y ejecute después:

langgraph dev

Este comando inicia un entorno de desarrollo. Utilice las direcciones que aparezcan para inspeccionar la aplicación y comprobar los recorridos en Studio. Que funcione en local todavía no valida la persistencia, el aislamiento ni la capacidad del servicio en producción.

La documentación de despliegue presenta LangSmith Cloud y distintas opciones híbridas y de alojamiento en infraestructura propia. Integrar la biblioteca en su propio servicio también es una decisión de arquitectura y conlleva responsabilidades operativas que deberá prever.

La denominación actual es LangSmith Deployment; el nombre anterior, LangGraph Platform, puede seguir apareciendo en recursos antiguos. Revise las condiciones de la oferta elegida: la disponibilidad de la biblioteca no implica que todos los servicios asociados tengan las mismas condiciones.

Operar el grafo: permisos, presupuesto y evaluación

Antes de abrir la aplicación a los usuarios, vincule cada hilo con una identidad y un ámbito de acceso autorizado. El servidor debe controlar el acceso a los estados, las reanudaciones y los documentos. Separar las instrucciones en el prompt no basta para aislar los datos de distintos clientes.

En las aprobaciones, vincule la decisión con la versión exacta de la acción. Aprobar un borrador no debería autorizar un destinatario o un importe que se modifiquen después. Establezca también un plazo de validez y defina qué ocurre cuando la solicitud queda sin respuesta.

Mida el costo por tarea completada. Las llamadas al modelo, los resultados voluminosos de las herramientas, las reanudaciones y los procesos abandonados también consumen presupuesto. La calculadora de precios de LLM ayuda a estimar la parte correspondiente a los tokens; añada por separado el almacenamiento y la operación del servicio.

Prepare un conjunto de escenarios que incluya éxito, rechazo, datos ausentes, herramientas no disponibles e intentos de eludir los controles. Compruebe las transiciones y las acciones realizadas, además de la redacción de la respuesta final. La guía para evaluar un agente de IA propone un método de seguimiento.

Las trazas deben permitir localizar un error sin acumular datos privados innecesarios. Registre los identificadores de ejecución, los estados y las duraciones útiles; oculte los secretos y controle los accesos. La guía para proteger un agente de IA amplía estas medidas.

Problemas frecuentes

El recorrido vuelve a empezar sin recuperar el historial. Revise el checkpointer, su disponibilidad y el identificador del hilo. Un identificador nuevo corresponde a otro recorrido; un almacenamiento únicamente en memoria desaparece al terminar el proceso.

Desaparecen datos anteriores. Examine las reglas de actualización del campo afectado. Sustituir un valor puede ser correcto para un estado, pero inadecuado para una colección de resultados que deben acumularse.

La reanudación repite una acción. Busque efectos externos antes de una interrupción o dentro de una operación que pueda volver a ejecutarse. Compruebe después la idempotencia y la posibilidad de consultar el resultado en el servicio de destino.

El bucle continúa sin avanzar. Añada una condición de parada vinculada al proceso de negocio, un presupuesto y un mecanismo que detecte los intentos repetitivos. Aumentar únicamente el límite técnico aplaza el problema.

El modelo anuncia un éxito que no aparece en el sistema de gestión. Haga que el estado final dependa de una confirmación estructurada del servicio. Una respuesta generada no demuestra que la acción se haya ejecutado.

El prototipo funciona, pero los usuarios se bloquean entre sí. Examine los accesos concurrentes al mismo hilo y a los mismos recursos del negocio. Defina una política de coordinación antes de aceptar varias operaciones simultáneas.

Lista de comprobación antes de la puesta en servicio

Páginas relacionadas

Preguntas frecuentes

¿Es necesario usar LangChain para trabajar con LangGraph?

No. Puede llamar a sus modelos y servicios desde funciones convencionales. Las abstracciones de LangChain resultan útiles si desea utilizar interfaces comunes para los mensajes, los modelos y las herramientas.

¿Puede funcionar LangGraph sin un modelo de lenguaje?

Sí: un grafo puede coordinar únicamente funciones deterministas. Esto permite comprobar las rutas de ejecución, las interrupciones y las actualizaciones del estado antes de incorporar llamadas al modelo.

¿Un checkpoint evita que una herramienta se ejecute dos veces?

Por sí solo, no garantiza ese comportamiento en un sistema externo. Para una operación sensible, utilice una clave de idempotencia y un mecanismo que permita comprobar si la acción ya se ha realizado.

¿Se puede alojar una aplicación LangGraph en infraestructura propia?

Sí, pero integrar la biblioteca en su propio servicio y desplegar Agent Server son decisiones distintas. Revise las condiciones y las dependencias de la modalidad de despliegue elegida antes de calcular los recursos que necesitará.

¿Cuándo añade LangGraph demasiada complejidad?

Si el proceso sigue un recorrido corto, sin reanudaciones ni aprobaciones intermedias, unas funciones convencionales pueden ser suficientes. El grafo resulta útil cuando su estado y sus transiciones permiten controlar mejor los errores.

LangGraph, guía de referencia: grafos de estado, memoria, herramientas y despliegue