La mayoría del código de agente comienza de forma sencilla y luego colapsa bajo sus propios reintentos. Conectas un LLM, le das algunas herramientas, y en el momento en que el flujo de trabajo necesita hacer un bucle, bifurcarse o pausar para un humano, el script lineal se desmorona. LangGraph es el framework construido precisamente para ese desorden: modela un agente como un grafo con estado compartido, de modo que los bucles y las bifurcaciones se convierten en una estructura de primera clase en lugar de enredadas declaraciones if. Esta guía explica qué es LangGraph, el problema que resuelve y dónde encaja la prueba de API cuando tu agente llama a servicios reales.
Qué es LangGraph
LangGraph es un framework de orquestación de bajo nivel y un entorno de ejecución para construir agentes de larga duración y con estado. Es construido por LangChain Inc, el equipo detrás de LangChain, pero es una biblioteca separada con su propio enfoque. Se instala de forma independiente con pip install -U langgraph, y puedes usarlo sin el resto del ecosistema de LangChain.
La idea central es sencilla. Describes tu agente como un grafo. Los nodos realizan el trabajo (llaman a un modelo, ejecutan una herramienta, transforman datos). Las aristas deciden qué se ejecuta a continuación. Un objeto de estado compartido fluye a través de cada nodo, y cada nodo puede leerlo y escribir en él. Dado que las aristas pueden apuntar hacia atrás, el grafo puede ciclar. Esa es la parte que una cadena simple no puede hacer bien.
Si has utilizado la abstracción Chain anterior de LangChain, la diferencia es la forma del flujo de control. Una cadena es una tubería: paso uno, paso dos, paso tres, listo. Un grafo permite que un nodo inspeccione el estado actual, luego salte a una rama diferente, retroceda para reintentar, o se ramifique a varios nodos que se ejecutan en paralelo y fusionan sus resultados. Los agentes reales necesitan eso, porque "razonar, actuar, observar, razonar de nuevo" es un bucle, no una línea.
El problema que resuelve LangGraph
Los flujos de trabajo de los agentes son cíclicos por naturaleza. Un agente llama a una herramienta, mira el resultado, decide si ha terminado y, si no, lo intenta de nuevo. Modelar eso con condicionales anidados se vuelve ilegible rápidamente, y empeora una vez que se añaden las cosas que los agentes de producción realmente necesitan:
- Bucles con una condición de parada. Seguir llamando a herramientas hasta que la tarea se complete, sin girar infinitamente.
- Bifurcación según el estado. Enrutar a un nodo diferente dependiendo de lo que el modelo devolvió.
- Persistencia. Sobrevivir a un fallo, un tiempo de espera o un reinicio y reanudar desde el último punto bueno.
- Humano en el bucle. Pausar, permitir que una persona inspeccione o edite el estado, y luego continuar.
- Streaming. Emitir tokens y pasos intermedios a medida que ocurren, no solo al final.
LangGraph convierte cada uno de estos en una capacidad incorporada en lugar de algo que tienes que crear manualmente. Obtienes una máquina de estados con ejecución duradera, para que un agente pueda funcionar durante minutos u horas y retomar el trabajo donde lo dejó.
Conceptos clave: grafo, estado, nodos, aristas
Cuatro primitivas soportan la mayor parte del framework. Así es como encajan.
El Estado es un objeto tipado compartido en toda la ejecución. Defines su forma con un esquema, a menudo un TypedDict, y LangGraph fusiona las actualizaciones de cada nodo en él. Un punto de partida común es MessagesState, un esquema predefinido que contiene una lista en ejecución de mensajes de chat.
Los Nodos son funciones. Cada uno toma el estado actual y devuelve una actualización parcial. Los registras con add_node().
Las Aristas conectan nodos. Una arista normal con add_edge() siempre va de A a B. Una arista condicional con add_conditional_edges() ejecuta una función de enrutamiento que lee el estado y devuelve el nombre del siguiente nodo, que es como expresas "si el modelo pidió una herramienta, ejecútala; de lo contrario, termina".
START y END son marcadores especiales para donde comienza y se detiene la ejecución.
Aquí está la forma de un grafo mínimo. Es a nivel de pseudo-código, pero los nombres de la API son reales.
from langgraph.graph import StateGraph, START, END, MessagesState
def call_model(state: MessagesState):
response = model.invoke(state["messages"])
return {"messages": [response]}
def should_continue(state: MessagesState) -> str:
last = state["messages"][-1]
return "tools" if last.tool_calls else END
builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", tool_node)
builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model") # loop back
graph = builder.compile()
La línea add_edge("tools", "model") es el ciclo. Después de que se ejecutan las herramientas, el control vuelve al modelo, que puede llamar a más herramientas o detenerse. Ese bucle es la razón de ser de LangGraph.
Persistencia y humano en el bucle
Compila un grafo con un "checkpointer" y guardará una instantánea del estado después de cada paso. Pasa un thread_id en la configuración, y LangGraph restaurará el último punto de control para ese hilo en la siguiente llamada. Tus nodos no cambian; el entorno de ejecución se encarga de guardar y restaurar.
from langgraph.checkpoint.memory import InMemorySaver
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [user_message]}, config)
InMemorySaver está bien para el desarrollo. Para algo que sobreviva a los reinicios, LangGraph incluye "savers" respaldados por bases de datos (SQLite para un solo servidor, Postgres para escalar a múltiples instancias). Dado que el estado es duradero, también obtienes "humano en el bucle" casi de forma gratuita. Puedes interrumpir el grafo en un punto elegido, mostrar el estado actual para que una persona lo inspeccione o edite, y luego reanudar desde ese punto de control exacto. Las puertas de aprobación, las correcciones manuales y los pasos de "estás seguro?" se basan en esto.
El streaming lo completa. LangGraph puede transmitir tokens del modelo y actualizaciones a nivel de nodo a medida que avanza la ejecución, de modo que una interfaz de usuario puede mostrar al agente pensando en lugar de quedarse mirando un "spinner".
Cómo se relaciona LangGraph con LangChain
Esto confunde a la gente, así que seamos directos. LangChain es el conjunto de herramientas más amplio: envoltorios de modelos, plantillas de prompts, recuperadores, cargadores de documentos e integraciones con cientos de proveedores. LangGraph es la capa de orquestación subyacente a las partes de agente de ese conjunto de herramientas.
No necesitas LangChain para usar LangGraph. Puedes definir tu estado, nodos y aristas, y llamar a cualquier cliente de modelo que desees dentro de un nodo. Muchos equipos combinan ambos, porque las abstracciones de modelos y herramientas de LangChain son convenientes, y el asistente preconstruido create_react_agent de LangGraph (en langgraph.prebuilt) te proporciona un agente que llama a herramientas en unas pocas líneas cuando no necesitas un grafo personalizado.
| LangChain | LangGraph | |
|---|---|---|
| Rol | Componentes e integraciones | Orquestación y entorno de ejecución |
| Flujo de control | Cadenas lineales | Grafos con ciclos y bifurcaciones |
| Estado incorporado | Limitado | Compartido, tipado, duradero |
| Persistencia / reanudación | No es el foco | Checkpointers + IDs de hilos |
| Mejor para | Componer llamadas a modelos y herramientas | Agentes con estado y de múltiples pasos |
Una nota para los usuarios actuales: la línea LangGraph v1.0 (estable desde finales de 2025) ha estado moviendo el asistente de agente preconstruido hacia langchain.agents.create_agent, así que verifica tu versión instalada y la referencia oficial para la ruta de importación exacta antes de copiar fragmentos antiguos. Construir agentes personalizados desde cero también es una habilidad útil aquí; consulta nuestro tutorial sobre cómo construir un agente de IA personalizado para una visión más amplia.
Plataforma y Studio de LangGraph
La biblioteca de código abierto es el núcleo, pero dos productos adyacentes importan una vez que se lanza.
LangGraph Studio es un IDE visual de agentes. Renderiza tu grafo, te permite ejecutarlo y muestra el estado en cada nodo para que puedas observar la ejecución paso a paso a través de tus nodos y aristas. Para cualquier cosa con ciclos y enrutamiento condicional, ver la ruta que realmente tomó el agente es mucho mejor que leer líneas de registro.
LangGraph Platform es el lado de despliegue gestionado: puntos finales de API para tus agentes, persistencia integrada para ejecuciones de larga duración y opciones de alojamiento que van desde autoalojadas hasta totalmente gestionadas en la nube. No lo necesitas para usar la biblioteca; está ahí cuando quieres infraestructura para agentes en producción en lugar de ejecutarlos tú mismo.
Cuándo usar LangGraph
Recurre a LangGraph cuando tu agente tenga un flujo de control real. Buenas señales:
- El trabajo es un bucle, no una secuencia (llamar herramientas, verificar, repetir).
- Necesitas bifurcar según lo que decidió el modelo.
- Una ejecución puede ser larga y quieres que sobreviva a un fallo y se reanude.
- Un humano debe aprobar o editar algo a mitad de la ejecución.
- Estás coordinando múltiples actores o sub-agentes que comparten estado.
Evítalo cuando una sola llamada al modelo o una cadena lineal corta hagan el trabajo. Un grafo es una sobrecarga que no necesitas para "resumir este texto". Guarda la estructura para flujos de trabajo que realmente se bifurcan y hacen bucles.
Dónde encajan las pruebas y simulaciones de API
Aquí es donde los equipos encuentran problemas en el desarrollo. Un agente de LangGraph es tan fiable como las APIs a las que llama, y llama a muchas de ellas: el punto final del LLM, más cada API de herramienta (búsqueda, un CRM, tu propio backend). LangGraph orquesta esas llamadas; no las prueba. Ese es un trabajo aparte, y ahí es donde Apidog entra en juego.
Dos problemas surgen rápidamente. Primero, llamar a APIs en vivo en cada ejecución de prueba consume tokens y alcanza los límites de tasa. Puedes simular la API de la que depende un agente para que un punto final de herramienta devuelva una respuesta determinista e instantánea mientras iteras en la lógica del grafo. Simula el punto final del LLM de la misma manera y dejarás de pagar por tokens solo para probar el enrutamiento.
Segundo, tus nodos asumen una forma de respuesta. Si la API de una herramienta cambia silenciosamente el nombre de un campo, tu arista condicional lee la información incorrecta y el agente entra en un bucle o se detiene. Fijar esos contratos con aserciones de API detecta el desvío antes de que llegue a tu grafo. Y como los agentes manejan claves entre entornos de staging y producción, gestionarlas en entornos mantiene los secretos fuera de tu código de nodo. Si quieres el flujo de trabajo completo centrado en el agente, el arnés de prueba de Apidog para agentes de IA lo explica de principio a fin. Para ser claros, nada de esto orquesta el agente; Apidog prueba y simula las APIs subyacentes.
Preguntas frecuentes
¿Es LangGraph un reemplazo de LangChain? No. LangGraph es el entorno de ejecución de orquestación; LangChain es el conjunto más amplio de componentes e integraciones. Son bibliotecas separadas del mismo equipo, y puedes ejecutar LangGraph sin LangChain o usarlos juntos. LangGraph maneja el flujo de control con estado y cíclico con el que las cadenas simples tienen dificultades.
¿Necesito saber LangChain para empezar con LangGraph? No. Puedes definir un StateGraph, añadir nodos y aristas, y llamar a cualquier cliente de modelo dentro de un nodo. Los envoltorios de modelos de LangChain son convenientes, pero son opcionales. Empieza con las primitivas de grafo centrales y añade el resto solo cuando lo necesites.
¿Cómo recuerda LangGraph las cosas entre llamadas? A través de los "checkpointers". Compila tu grafo con un "checkpointer" y pasa un thread_id, y LangGraph guardará una instantánea del estado después de cada paso, luego la restaurará en la siguiente llamada para ese hilo. Así es como obtienes memoria conversacional y recuperación de fallos sin cambiar la lógica de tu nodo.
¿Cómo pruebo las APIs a las que llama mi agente? Pruébalas y simúlalas por separado del grafo. Simula los puntos finales de LLM y de herramientas para que las ejecuciones sean rápidas y gratuitas durante el desarrollo, y verifica las formas de respuesta para que un campo cambiado no rompa un nodo. Nuestra guía sobre cómo probar la API de ChatGPT cubre la autenticación, el streaming y las llamadas a herramientas, que son las superficies exactas de las que depende un agente.
Conclusión
LangGraph te proporciona la estructura que faltaba para agentes que hacen bucles, se ramifican, persisten y pausan para un humano. Modela el flujo de trabajo como un grafo con estado compartido, apóyate en los "checkpointers" para la memoria y la recuperación, y usa Studio y la Plataforma cuando estés listo para depurar y desplegar. El framework maneja la orquestación. Las APIs a las que llama tu agente aún necesitan su propia red de seguridad, así que simúlalas y pruébalas en Apidog para mantener el desarrollo económico y tus contratos de herramientas honestos. Descarga Apidog para simular un punto final y verificar sus respuestas antes de que tu agente lo utilice de verdad.