Tu agente de LangGraph funcionaba en el notebook y ahora se queda dando vueltas, o corta a mitad de camino, o responde cualquier cosa. El problema casi nunca es el modelo: es el grafo. Y lo bueno de LangGraph —que el flujo sea explícito, con nodos y aristas— es justo lo que hace que el error sea encontrable, si sabes dónde mirar.
Estos son los cuatro motivos que más veo cuando alguien trae un agente roto al taller de creación de agentes con LangGraph, en orden de frecuencia.
1. El bucle que nunca llega al final
Es el síntoma más común: el agente llama una herramienta, vuelve al nodo del modelo, vuelve a llamar la misma herramienta y así hasta que LangGraph corta con un error de límite de recursión. Ese límite es una red de seguridad, no el problema. El problema está en la arista condicional: tu función de ruteo nunca devuelve el camino que termina el grafo.
Las dos causas típicas: la condición revisa el último mensaje pero el nodo anterior agregó dos, o el modelo insiste en pedir la herramienta porque el resultado que le devolviste no contesta su pregunta —le mandas un JSON vacío y él lo interpreta como "intenta de nuevo". Antes de subir el límite de recursión, imprime qué devuelve tu condicional en cada vuelta. Subirlo solo hace que el bucle sea más caro.
2. El estado que se pisa a sí mismo
En LangGraph cada nodo devuelve un pedazo de estado y el grafo lo mezcla con lo que ya había. Cómo lo mezcla lo decides tú al definir el estado: si el campo no tiene un reductor que acumule, el valor nuevo reemplaza al viejo. Por eso mucha gente descubre que su historial de mensajes tiene un solo elemento, o que el agente "olvida" lo que acaba de calcular.
La regla práctica: lo que debe acumularse (mensajes, resultados parciales, documentos recuperados) necesita un reductor que los sume; lo que debe reemplazarse (el paso actual, una bandera, el usuario) va plano. Cuando el bug es raro y aparece solo con varios nodos corriendo, mira esto primero.
3. Herramientas que fallan en silencio
Una API externa responde 500, tu función atrapa la excepción, devuelve un string de error y el grafo sigue como si nada. El modelo lee ese texto, improvisa una respuesta plausible y el usuario recibe un dato inventado con total seguridad. No hay traza roja en ningún lado: todo "funcionó".
- ▸Marca el fallo en el estado, no solo en el texto que devuelves a la herramienta.
- ▸Define a dónde va el grafo cuando la herramienta falla: reintento acotado, camino alternativo o una respuesta honesta de "no pude consultarlo".
- ▸Valida la salida antes de entregársela al modelo. Si esperabas una lista y llegó vacía, eso es una decisión del grafo, no una opinión del LLM.
4. El prompt que ningún grafo arregla
A veces el grafo está impecable y el agente igual se comporta mal porque le diste ocho herramientas con descripciones parecidas. El modelo elige la equivocada y tú terminas depurando aristas durante dos días. Cuando la traza muestra que llama una herramienta razonable pero no la correcta, el problema es la descripción, no el código.
El método que ahorra horas
Depurar un agente a punta de print es lento porque el error aparece en la vuelta siete, no en la primera. Tres cosas cambian el panorama:
- ▸Ejecuta el grafo en modo streaming de actualizaciones para ver qué nodo se activa y qué devuelve, en orden. La mitad de los bugs se cae sola ahí.
- ▸Activa trazas con LangSmith. Ver el árbol de llamadas con sus entradas, salidas y tiempos es la diferencia entre adivinar y leer.
- ▸Usa el checkpointing a tu favor: si guardas el estado por hilo, puedes retomar la conversación rota en el punto exacto y probar un arreglo sin repetir los seis pasos anteriores.
Lo que nadie te dice: un agente que falla el 10% de las veces no se arregla con un prompt mejor. Se arregla poniendo un humano en el camino para ese 10%, y eso es una decisión de diseño del grafo.
Antes de llevarlo a producción
Arma una lista de diez casos reales —incluidos los feos: datos faltantes, usuario que cambia de tema, herramienta caída— y córrela cada vez que toques el grafo. Sin eso, cada arreglo es una apuesta. Y pon un tope de pasos por conversación: no por elegancia, sino porque un bucle en producción se paga en tokens.
Si quieres construir esto en orden y no a tropezones, el taller de agentes con LangGraph son cuatro sesiones que van de los fundamentos del grafo al enrutamiento condicional, la memoria persistente y los flujos con aprobación humana y varios agentes: once horas, proyecto propio y certificado. Para el camino completo hacia sistemas con varios agentes en producción está la ruta AI Agentic Engineer, y si te falta la base de cadenas y herramientas, empieza por Creación de Agentes con LangChain.
Traer tu grafo roto y depurarlo en vivo con otros es, de lejos, la forma más rápida de aprender esto: lo hacemos cada semana en la Comunidad AI Builders, desde 19 USD al mes.



