Resolución de Problemas

Esta guía es tu primer punto de referencia cuando algo no funciona como esperas. Aquí cubrimos los errores más comunes y te enseñamos a interpretar los logs para encontrar la solución.

Errores Comunes de Componentes

Problemas con API Request

Cuando un componente API Request falla, no es un error de NappAI, sino una respuesta de error del servicio externo que estás consultando.

• Cómo Diagnosticar: El primer paso es siempre inspeccionar la salida del nodo. El componente API Request te entregará como output el código de estado y el mensaje de error exacto que la API externa devolvió.
• Interpretando los Códigos de Error: Aunque cada API tiene su propia documentación, la mayoría sigue un estándar:
  • Errores 5xx (ej. 500, 503): Indican un error interno en el servidor de la API que estás consultando. El problema no está en tu configuración, sino en el servicio externo.
  • Errores 4xx (ej. 401, 403, 404): Generalmente son problemas de acceso o autorización. Revisa que tu API Key o Bearer Token sean correctos y que tengas permiso para acceder a ese recurso. Un 404 Not Found significa que la URL (endpoint) es incorrecta.
  • Errores 3xx (ej. 301, 302): Indican redirecciones. La API te está diciendo que el recurso que buscas ha sido movido a una nueva URL.

Regla de Oro: Para entender en profundidad un error de API, la documentación oficial de esa API es siempre la fuente de verdad definitiva.

Problemas Comunes con Agentes

Los agentes son potentes, pero su depuración requiere entender su “proceso de pensamiento”.

• El Agente se queda “pensando” (Timeout):

  • Causa: El Agente está intentando resolver una tarea muy compleja o la herramienta que ha llamado (ej: una API externa) está tardando demasiado en responder.
  • Solución: Aumenta el Max Iterations en la configuración avanzada del Agente. Si el problema persiste, simplifica el System Prompt o revisa el rendimiento de las herramientas que utiliza.

• El Agente no usa la herramienta correcta:

  • Causa: La descripción de la herramienta (Tool Description) no es lo suficientemente clara. El Agente decide qué herramienta usar basándose únicamente en esa descripción.
  • Solución: Reescribe la descripción para que sea muy explícita. En lugar de “Gestiona Airtable”, escribe “Utiliza esta herramienta para LEER registros de la tabla de Productos. No puede escribir ni borrar.”

• El Agente devuelve un resultado con formato incorrecto:

  • Causa: El System Prompt no es lo suficientemente estricto.
  • Solución: Añade reglas explícitas al prompt. Por ejemplo: Responde SIEMPRE con un objeto JSON. No añadas texto introductorio. El JSON debe tener las claves "nombre" y "email".

El Agente “Alucina”, Pierde el Hilo o Tarda Demasiado

Este es uno de los problemas más comunes al diseñar agentes complejos y suele deberse a la saturación de información o de contexto.

• La Causa Raíz: Un único Agente al que se le asignan demasiadas tareas, se le conectan demasiadas herramientas o se le pide que procese una cantidad masiva de datos en una sola interacción puede sobrecargarse.

  • Saturación de Memoria: El Agente depende de una memoria temporal para saber qué ha hecho y qué le falta por hacer. Con demasiadas tareas, puede “perder el hilo” y no completar todo el proceso correctamente.
  • Exceso de Contexto al LLM: Cada herramienta, cada instrucción y cada pieza de dato se envía al modelo de lenguaje (LLM) subyacente. Un contexto masivo no solo incrementa drásticamente el coste en tokens, sino que también puede confundir al modelo, provocando que ignore instrucciones, tarde demasiado en responder o genere “alucinaciones” (respuestas incorrectas).

• La Solución: Arquitecturas Multi-Agente En lugar de crear un único “superagente” que lo haga todo, la estrategia más robusta, eficiente y económica es dividir el trabajo en un equipo de agentes especializados.

  • Menos Costes y Más Eficiencia: Enviar datos de forma incremental a agentes más pequeños y enfocados es mucho más barato y rápido que enviar un gran bloque de información a un solo LLM.
  • Mayor Fiabilidad: Cada agente tiene una única tarea clara, lo que reduce drásticamente la posibilidad de que “pierda el hilo”.
  • Uso de Modelos Más Baratos: Una tarea simple y bien definida a menudo puede ser resuelta por un modelo más pequeño y económico, reservando los modelos más potentes solo para las tareas que realmente lo requieren.

  Considera implementar patrones como:

  • Agentes Secuenciales (Línea de Ensamblaje): Donde un agente planifica, otro investiga y un tercero escribe.
  • Agentes como Herramientas (Tool): Un agente principal que puede llamar a otros sub-agentes para tareas específicas.
  • Agentes Trabajadores (Worker Agents): Un orquestador que distribuye tareas a un equipo de agentes.

Cómo Leer los Logs de Ejecución

La mejor herramienta de depuración es el propio historial de ejecuciones.

• Nodos en Verde vs. Rojo: Un nodo en verde se ejecutó con éxito. Un nodo en rojo es donde ocurrió el error.
• El Panel de Inspección: Haz clic en cualquier nodo después de una ejecución y selecciona “Inspect outputs”. Podrás ver las salidas exactas que produjo. Esto te permite rastrear el flujo de datos paso a paso y ver dónde se corrompió o cambió de forma inesperada.