Si te pasaste horas armando un agente de IA en n8n y de repente te respondió cualquier disparate (o peor: nada), no te desesperes. Saber cómo depurar agentes IA n8n es la diferencia entre un flujo que parece magia y uno que es puro dolor de cabeza. En esta guía te muestro paso a paso cómo detectar errores, revisar logs y dejar tu automatización funcionando redondo, sin necesidad de ser experto en código. Ya sea que estés usando GPT, Claude o modelos locales, estos trucos te sacarán de cualquier aprieto.

¿Qué es depurar agentes IA n8n?

Depurar (o debuggear, como le dicen los cracks del código) significa encontrar y corregir errores en tus flujos de trabajo. Pero cuando hablamos de agentes de IA en n8n, esto va un paso más allá de solo verificar si un nodo se conectó bien. Acá estás lidiando con LangChain, prompts de sistema, herramientas externas y respuestas que a veces parecen tener vida propia. Depurar implica entender por qué tu agente decidió llamar a una herramienta que no existe, por qué ignoró el contexto que le pasaste o por qué se quedó pensando eternamente sin responder. Es un proceso sistemático de aislar problemas: desde credenciales vencidas hasta prompts mal escritos que confunden al modelo. La clave es tener paciencia y saber dónde mirar, porque n8n tiene herramientas muy potentes para ver exactamente qué está pasando bajo el capó de tu agente.

Pasos para depurar tu agente IA paso a paso

Antes de empezar, asegurate de tener a mano el flujo que querés arreglar. Si todavía no creaste tu primer agente, te recomiendo primero ver esta guía sobre Crear un Agente de IA con n8n: Guía Paso a Paso para tener las bases claras. Una vez que tengas tu agente armado y fallando, seguí estos pasos:

1. Activa el modo ejecución y analizá los logs en detalle

El primer lugar donde tenés que mirar es el panel de ejecuciones. Hacé clic en «Execute Workflow» y observá cada nodo mientras corre. Cuando falla algo, n8n te marca el nodo problemático con un rojo alarmante (o amarillo si es advertencia). Pero no te quedes solo con el color: hacé clic en el nodo y seleccioná «View Output». Acá está el secreto: vas a ver exactamente qué datos entraron y qué salieron. Fijate especialmente en la pestaña «JSON» para ver la estructura real de los datos. Muchas veces el agente no está «roto», sino que recibió un campo llamado «message» cuando esperaba «input». Compará el input que espera el nodo de IA con el output del nodo anterior. Si ves «undefined» o campos vacíos donde debería haber texto, ahí tenés al culpable.

2. Verificá credenciales, rate limits y tokens disponibles

Este es el clásico que nos vuelve locos a todos. Si tu agente de repente empezó a fallar sin que tocaras nada, lo más probable es que se te haya vencido la API key o hayas alcanzado el límite de requests. En n8n, andá a «Settings» > «Credentials» y verificá que las claves de OpenAI, Anthropic o Google estén activas. Pero ojo: también fijate en los logs de ejecución si aparecen errores tipo «429 Too Many Requests» o «insufficient_quota». Otro detalle silencioso es el límite de tokens: si estás mandando mucho contexto (por ejemplo, chunks grandes de un Vector Store), puede que estés excediendo la ventana de contexto del modelo y el agente simplemente no responda o corte la conversación. Para casos de RAG complejos, te conviene revisar esta guía sobre n8n con Vector Store y Embeddings para optimizar cómo enviás la información a la IA.

3. Analizá el system prompt y el contexto enviado

A veces el error no es técnico, es de comunicación. Los modelos de IA son literalistas: si tu prompt de sistema dice «Respondé solo con sí o no» pero después le pedís que explique algo, el agente se va a confundir o va a ignorar instrucciones. Abrí el nodo del agente o del modelo de chat y revisá exactamente qué le estás mandando en el «System Message». ¿Le estás dando instrucciones contradictorias? ¿Le pedís que use herramientas que no tenés configuradas? Probá simplificar el prompt al mínimo indispensable, ejecutá de nuevo, y si funciona, anda agregando complejidad de a poco. Esta técnica se llama «prompt debugging» y ahorra horas de frustración. También verificá que las variables entre corchetes {{$json.campo}} estén bien escritas y que realmente existan en el JSON de entrada.

4. Aislaba el problema probando nodo por nodo

Cuando el flujo es complejo, con varias herramientas y nodos de IA encadenados, la mejor estrategia es la división y conquista. Desconectá temporalmente los nodos que vienen después del que sospechás que falla. n8n te permite hacer clic derecho en un nodo y seleccionar «Execute Node» para correr solo ese paso con datos de prueba. Si el nodo individual funciona perfecto, el problema está en cómo se conecta con el siguiente. Si tenés un agente con múltiples tools, desactivá todas menos una y probá. Si funciona, activá la segunda, y así sucesivamente hasta encontrar cuál tool rompe el flujo. Muchas veces el agente se queda en un loop infinito entre herramientas porque el prompt no es claro sobre cuándo parar o porque dos tools tienen nombres similares y el modelo las confunde.

Errores comunes que te vuelven loco y cómo solucionarlos

Después de haber depurado decenas de agentes, hay errores que aparecen una y otra vez. Acá te dejo los más frecuentes para que no pierdas tiempo:

El agente «alucina» herramientas que no existen: Esto pasa cuando el prompt es ambiguo y mencionás algo como «buscá en internet» pero no tenés configurada una tool de búsqueda web. El modelo inventa que la usó. Solución: sé específico en el system prompt sobre qué herramientas existen realmente.

Contexto window excedido (ventana de contexto): Si tu agente usa memoria o RAG y de repente empieza a ignorar instrucciones básicas, probablemente estés mandando demasiados tokens. Solución: limitá el tamaño de los chunks en tu Vector Store o resumí la conversación antes de enviarla.

Variables undefined entre nodos: Cuando pasás datos de un nodo HTTP Request o Code a un nodo de IA, asegurate de que el campo exista. Si el nodo anterior devuelve un array y vos llamás a un campo como si fuera objeto, vas a mandar «undefined» a la IA.

Timeouts en respuestas largas: Si tu agente genera textos largos y se corta a la mitad, aumentá el timeout en la configuración del nodo y verificá los límites de tokens de salida (max_tokens).

Loops infinitos entre tools: Cuando el agente pasa indefinidamente entre Tool A y Tool B sin llegar a una respuesta. Solución: agregá instrucciones claras en el prompt sobre el orden de uso de herramientas y cuándo detenerse.

Ejemplos reales de depuración en producción

Te comparto tres casos reales para que veas cómo se aplica todo esto:

Caso 1: Agente de soporte que no encontraba documentos El usuario tenía un agente RAG configurado para responder sobre documentación interna, pero siempre decía «no tengo información». Al revisar los logs, se descubrió que el nodo de Vector Store retornaba los documentos correctamente, pero el campo se llamaba «pageContent» y el prompt del agente buscaba «content». Simplemente cambiando la referencia en el template, empezó a funcionar.

Caso 2: Agente con integración de ChatGPT que se quedaba colgado En este escenario, el flujo se ejecutaba pero nunca terminaba. Revisando las credenciales se descubrió que la API key estaba bien, pero el modelo GPT-4 estaba saturado. Al cambiar a GPT-3.5-turbo o ajustar el parámetro de timeout a 60 segundos, el flujo volvió a responder. Si estás usando ChatGPT integrado con n8n, siempre tené un plan B de modelo.

Caso 3: Agente multi-herramienta que usaba la tool equivocada Un agente que debía enviar emails o buscar en CRM según la intención del usuario, siempre elegía enviar email. El problema estaba en los nombres de las herramientas: una se llamaba «send_message_to_user» y otra «send_email». El modelo confundía «message» con email. Al renombrar las tools a «email_sender» y «crm_lookup» con descripciones explícitas, el comportamiento se corrigió.

Preguntas frecuentes sobre depuración de agentes

Acá respondemos las dudas más comunes que aparecen cuando estás tratando de hacer funcionar tu automatización.

Preguntas frecuentes

¿Por qué mi agente IA en n8n responde «No tengo información» si le cargué documentos?

Generalmente esto pasa porque el nodo de Vector Store no está retornando los documentos en el formato que espera el agente, o porque el campo de contenido tiene un nombre diferente al que referenciás en el prompt. Revisá la pestaña de output del nodo Vector Store y asegurate de que los datos lleguen correctamente al nodo del agente. También puede ser que los embeddings no se hayan generado bien al cargar los documentos.

¿Cómo puedo ver exactamente qué datos le llegan al modelo de IA?

Hacé clic en el nodo del agente o del modelo de chat después de ejecutar el flujo, seleccioná «View Output» y mirá la pestaña «JSON». Ahí vas a ver el campo «messages» que contiene el historial completo de la conversación, incluyendo el system prompt y los tool results. Eso es exactamente lo que ve la IA antes de responder.

Mi agente entra en un bucle infinito usando herramientas, ¿qué hago?

Limitá el número de iteraciones en la configuración del nodo Agent (parámetro «Max Iterations») para que no se ejecute eternamente. Después, revisá tu system prompt: tenés que especificar claramente bajo qué condiciones debe detenerse y responder al usuario, y dar nombres descriptivos únicos a cada herramienta para evitar confusiones.

¿Es normal que la depuración consuma muchos tokens de la API?

Sí, desafortunadamente depurar consume tokens porque estás haciendo múltiples pruebas. Para reducir costos, usá modelos más baratos como GPT-3.5-turbo o Claude Haiku durante la fase de debugging, y recién cuando todo funcione perfecto, cambiá al modelo más potente. También podés usar el modo de ejecución manual con datos de prueba cortos.

¿Puedo depurar un agente sin ejecutar el flujo completo?

Absolutamente. Usá la función «Execute Node» (clic derecho en el nodo) para probar pasos individuales. También podés desconectar nodos posteriores arrastrándolos lejos temporalmente, o usar nodos «No Operation» (NoOp) para cortar el flujo donde necesites ver los datos hasta ese punto.

Tu turno

Depurar agentes IA en n8n es más un arte que una ciencia exacta, pero con estos pasos vas a ahorrarte horas de frustración. Recordá siempre empezar por los logs, verificar credenciales y aislar el problema probando nodo por nodo. No te desanimes si al principio parece complejo: cada error que solucionás te hace entender mejor cómo piensa la IA y cómo estructurar mejores flujos. Ahora te toca aplicar estos conocimientos en ese agente que tenés pendiente. ¿Qué error te está volviendo loco hoy? ¡Metele mano y contanos cómo te fue!