¿Qué es LangGraph? Guía para crear agentes de IA con estado

La mayoría del código de agentes empieza simple y falla cuando aparecen reintentos, bucles, bifurcaciones o aprobaciones humanas. LangGraph resuelve ese problema modelando el agente como un grafo con estado compartido: cada nodo ejecuta una parte del trabajo, cada arista decide el siguiente paso y el flujo puede volver atrás, pausar o reanudarse. En esta guía verás qué es LangGraph, cómo implementarlo y dónde encajan las pruebas de API cuando tu agente llama a servicios reales.

Prueba Apidog hoy

Qué es LangGraph

LangGraph es un framework de orquestación de bajo nivel y un entorno de ejecución para construir agentes con estado y de larga duración. Lo mantiene LangChain Inc., el equipo detrás de LangChain, pero es una biblioteca separada con su propio enfoque.

Instálalo de forma independiente:

pip install -U langgraph

Puedes usarlo sin el resto del ecosistema de LangChain.

La idea central es práctica:

• Nodos: funciones que hacen trabajo, como llamar a un modelo, ejecutar una herramienta o transformar datos.
• Aristas: conexiones que deciden qué nodo se ejecuta después.
• Estado compartido: objeto que viaja por todo el grafo y que cada nodo puede leer o actualizar.
• Ciclos: aristas que pueden volver a nodos anteriores para repetir una acción.

Eso permite representar flujos como:

usuario -> modelo -> herramienta -> modelo -> respuesta final

o, si el modelo necesita otra herramienta:

usuario -> modelo -> herramienta -> modelo -> otra herramienta -> modelo -> respuesta final

Con una cadena lineal, ese flujo termina convirtiéndose en condicionales anidados. Con LangGraph, el bucle es parte del diseño.

El problema que resuelve LangGraph

Los agentes reales no suelen ser una secuencia fija. Normalmente siguen este patrón:

1. Reciben una instrucción.
2. Razonan sobre qué hacer.
3. Llaman a una herramienta.
4. Observan el resultado.
5. Deciden si terminar o continuar.

Ese patrón es un bucle. Implementarlo con scripts lineales funciona al principio, pero se complica cuando necesitas:

• Bucles con condición de parada: repetir hasta completar la tarea sin caer en un ciclo infinito.
• Bifurcación según el estado: elegir el siguiente nodo según la salida del modelo o de una API.
• Persistencia: reanudar después de un fallo, timeout o reinicio.
• Humano en el bucle: pausar, revisar o editar el estado y continuar.
• Streaming: emitir tokens y pasos intermedios mientras el agente trabaja.

LangGraph convierte esas necesidades en primitivas del framework. En lugar de crear tu propia máquina de estados con if, while y lógica de recuperación, defines un grafo ejecutable.

Conceptos clave: grafo, estado, nodos y aristas

La mayoría de implementaciones en LangGraph se construyen con cuatro piezas.

1. Estado

El estado es un objeto tipado compartido por toda la ejecución. Define qué datos necesita tu agente y qué datos pueden actualizar los nodos.

Un punto de partida común es MessagesState, un esquema predefinido que mantiene una lista de mensajes de chat.

from langgraph.graph import MessagesState

También puedes definir tu propio estado con TypedDict:

from typing import TypedDict, List

class AgentState(TypedDict):
    task: str
    steps: List[str]
    result: str | None

2. Nodos

Los nodos son funciones. Reciben el estado actual y devuelven una actualización parcial.

def call_model(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}

Cada nodo debe hacer una tarea concreta: llamar al modelo, ejecutar una herramienta, validar una respuesta, pedir aprobación, etc.

3. Aristas

Las aristas conectan nodos.

Una arista normal siempre mueve la ejecución de un nodo a otro:

builder.add_edge("tools", "model")

Una arista condicional decide el siguiente nodo en tiempo de ejecución:

builder.add_conditional_edges("model", should_continue)

4. START y END

START y END indican dónde inicia y termina la ejecución.

from langgraph.graph import START, END

Implementar un grafo mínimo con bucle de herramientas

Este ejemplo muestra la forma básica de un agente que:

1. Llama al modelo.
2. Revisa si el modelo pidió herramientas.
3. Ejecuta herramientas si es necesario.
4. Vuelve al modelo.
5. Termina si no hay más herramientas.

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")   # vuelve al modelo

graph = builder.compile()

La línea importante es esta:

builder.add_edge("tools", "model")

Ese es el ciclo. Después de ejecutar herramientas, el control vuelve al modelo. El modelo puede pedir más herramientas o finalizar.

Ejecutar el grafo se ve así:

result = graph.invoke({
    "messages": [
        {"role": "user", "content": "Busca el estado de mi pedido y resume el resultado."}
    ]
})

Persistencia y humano en el bucle

Para agentes de producción, no basta con ejecutar el grafo en memoria. Si el proceso falla o la tarea dura varios minutos, necesitas guardar el estado.

LangGraph lo hace con checkpointers. Compilas el grafo con un checkpointer y pasas un thread_id por configuración.

from langgraph.checkpoint.memory import InMemorySaver

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

config = {
    "configurable": {
        "thread_id": "user-42"
    }
}

graph.invoke(
    {"messages": [user_message]},
    config
)

InMemorySaver sirve para desarrollo. Para ejecuciones que deben sobrevivir reinicios, LangGraph incluye savers respaldados por bases de datos, como SQLite para un solo servidor y Postgres para múltiples instancias.

La persistencia también habilita patrones de humano en el bucle:

1. Ejecutas el grafo hasta un punto de interrupción.
2. Guardas el estado.
3. Muestras ese estado a una persona.
4. La persona aprueba, edita o rechaza.
5. Reanudas desde el mismo checkpoint.

Ese patrón es útil para:

• aprobaciones antes de enviar un correo;
• revisión de cambios antes de ejecutar una acción irreversible;
• corrección manual de datos ambiguos;
• validación de resultados sensibles.

El streaming completa la experiencia. LangGraph puede transmitir tokens del modelo y actualizaciones por nodo mientras el grafo avanza, para que una interfaz muestre progreso real en lugar de un spinner.

Cómo se relaciona LangGraph con LangChain

LangChain y LangGraph no son lo mismo.

LangChain es el conjunto amplio de componentes: envoltorios de modelos, prompts, recuperadores, cargadores de documentos e integraciones.

LangGraph es la capa de orquestación para flujos con estado, ciclos, ramas y ejecución duradera.

Puedes usar LangGraph sin LangChain. Dentro de un nodo puedes llamar al cliente de modelo que prefieras:

def call_model(state):
    response = my_llm_client.chat(state["messages"])
    return {"messages": [response]}

También puedes combinar ambos. Muchos equipos usan las abstracciones de modelos y herramientas de LangChain junto con LangGraph para controlar el flujo de ejecución.

Si no necesitas un grafo personalizado, el asistente preconstruido create_react_agent de LangGraph, disponible en langgraph.prebuilt, permite crear un agente con herramientas en pocas líneas.

	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 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. Antes de copiar snippets antiguos, verifica tu versión instalada y la referencia oficial para confirmar la ruta de importación exacta.

Si quieres una visión más amplia sobre el diseño de agentes, consulta este tutorial sobre cómo construir un agente de IA personalizado.

Plataforma y Studio de LangGraph

La biblioteca open source es el núcleo, pero hay dos productos relacionados que importan cuando pasas de prototipo a depuración y despliegue.

LangGraph Studio

LangGraph Studio es un IDE visual de agentes. Renderiza tu grafo, permite ejecutarlo y muestra el estado en cada nodo.

Para grafos con ciclos y enrutamiento condicional, visualizar la ruta real tomada por el agente suele ser más útil que leer logs. Puedes comprobar:

• qué nodo se ejecutó;
• qué estado recibió;
• qué actualización devolvió;
• qué arista condicional se eligió;
• dónde se detuvo o falló el flujo.

LangGraph Platform

LangGraph Platform es el lado gestionado de despliegue. Proporciona puntos finales de API para agentes, persistencia integrada para ejecuciones de larga duración y opciones de alojamiento que van desde autoalojado hasta nube gestionada.

No necesitas LangGraph Platform para usar la biblioteca. Es útil cuando quieres infraestructura para agentes en producción sin construir tú mismo toda la capa de ejecución, persistencia y exposición de APIs.

Cuándo usar LangGraph

Usa LangGraph cuando tu agente tenga flujo de control real.

Buenas señales:

• el trabajo es un bucle, no una secuencia;
• el agente debe llamar herramientas, verificar resultados y repetir;
• necesitas bifurcar según lo que decidió el modelo;
• una ejecución puede durar mucho y debe reanudarse después de fallos;
• una persona debe aprobar o editar algo a mitad de la ejecución;
• coordinas múltiples actores o subagentes que comparten estado.

Evítalo cuando una llamada única al modelo o una cadena corta resuelva el caso. Para tareas como “resume este texto” o “clasifica esta entrada”, un grafo puede ser sobrecarga innecesaria.

Dónde encajan las pruebas y simulaciones de API

Un agente de LangGraph es tan fiable como las APIs que llama. Normalmente depende de varias superficies externas:

• el endpoint del LLM;
• APIs de herramientas;
• servicios internos;
• CRMs;
• motores de búsqueda;
• bases de datos expuestas por API.

LangGraph orquesta esas llamadas, pero no prueba esas APIs. Ahí es donde Apidog entra en el flujo de desarrollo.

1. Simula APIs para iterar sin coste ni límites de tasa

Durante el desarrollo, no conviene llamar APIs reales en cada ejecución del agente. Puedes consumir tokens, golpear límites de tasa o depender de datos cambiantes.

Una alternativa es simular la API que usa el agente.

Por ejemplo, si tu nodo tools llama a un endpoint de pedidos, puedes simular una respuesta estable:

{
  "order_id": "ORD-123",
  "status": "shipped",
  "estimated_delivery": "2026-06-28"
}

Así pruebas el enrutamiento del grafo sin depender del backend real.

También puedes simular el endpoint del LLM para validar lógica como:

def should_continue(state: MessagesState) -> str:
    last = state["messages"][-1]
    return "tools" if last.tool_calls else END

Con respuestas deterministas, puedes comprobar si el grafo toma la ruta esperada.

2. Usa aserciones para proteger contratos de respuesta

Tus nodos normalmente asumen una forma de respuesta:

status = api_response["status"]

Si una API cambia status por order_status, el nodo puede fallar o, peor, tomar una decisión incorrecta.

Las aserciones de API ayudan a detectar ese desvío antes de que llegue al grafo. Puedes validar que:

• el código de estado sea el esperado;
• los campos requeridos existan;
• los tipos sean correctos;
• los valores sigan un formato esperado;
• la respuesta cumpla el contrato que consume el agente.

3. Separa secretos por entorno

Los agentes suelen usar claves diferentes para desarrollo, staging y producción. Mantener esas claves en entornos evita hardcodearlas en nodos.

En lugar de esto:

API_KEY = "sk-..."

usa variables de entorno o configuración externa:

API_KEY = os.environ["TOOL_API_KEY"]

Apidog puede ayudarte a organizar esas llamadas y entornos para probar las APIs subyacentes sin mezclar credenciales.

Si quieres el flujo completo centrado en agentes, el arnés de prueba de Apidog para agentes de IA explica el enfoque de principio a fin.

Para ser claros: Apidog no orquesta el agente. LangGraph hace la orquestación. Apidog prueba, simula y valida las APIs que el agente usa.

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.

Puedes ejecutar LangGraph sin LangChain o usarlos juntos. LangGraph se enfoca en flujo de control con estado, ciclos, bifurcaciones, persistencia y reanudación.

¿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 opcionales. Empieza con las primitivas principales de LangGraph y añade otras abstracciones solo cuando las necesites.

¿Cómo recuerda LangGraph las cosas entre llamadas?

Mediante checkpointers.

Compilas el grafo con un checkpointer y pasas un thread_id. LangGraph guarda una instantánea del estado después de cada paso y la restaura en la siguiente llamada para ese hilo.

config = {
    "configurable": {
        "thread_id": "user-42"
    }
}

Eso permite memoria conversacional, recuperación de fallos y pausas para revisión humana sin cambiar la lógica de tus nodos.

¿Cómo pruebo las APIs a las que llama mi agente?

Pruébalas y simúlalas fuera del grafo.

Un flujo práctico es:

1. Define el contrato esperado de cada API.
2. Crea mocks para respuestas normales y errores.
3. Ejecuta el grafo contra esos mocks.
4. Añade aserciones para validar campos críticos.
5. Ejecuta pruebas contra staging antes de producción.

Para APIs tipo ChatGPT, esta guía sobre cómo probar la API de ChatGPT cubre autenticación, streaming y llamadas a herramientas, que son superficies comunes en agentes.

Conclusión

LangGraph te da una estructura clara para agentes que hacen bucles, se ramifican, persisten y pausan para intervención humana. Define el flujo como un grafo, usa estado compartido para coordinar nodos, añade checkpointers para reanudación y apóyate en Studio o Platform cuando necesites depurar o desplegar.

El framework se encarga de la orquestación. Las APIs que llama tu agente siguen necesitando pruebas propias. Simúlalas y valídalas en Apidog para iterar más rápido, reducir coste durante desarrollo y detectar cambios de contrato antes de que rompan tu grafo. Descarga Apidog para simular un endpoint y verificar sus respuestas antes de conectarlo a tu agente.