CSVAgent

⚠️ ADVERTENCIA DE DEPRECACIÓN

Este componente está deprecado y será eliminado en una versión futura de Nappai. Por favor, migra a los componentes alternativos recomendados.

Este componente actúa como un asistente inteligente diseñado para trabajar con archivos de datos tabulares (CSV). Su función principal es conectar tus datos con un modelo de inteligencia artificial, permitiendo que Nappai entienda tus preguntas en lenguaje natural y responda analizando la información de tus hojas de cálculo. Es ideal para quienes necesitan insights rápidos, resúmenes o respuestas específicas sin escribir código complejo.

¿Cómo funciona?

Cuando conectas un archivo CSV a este nodo y lo asocias con un modelo de IA, el sistema carga los datos en la memoria y prepara un “cerebro” de agente especializado. Este agente entiende tu contexto, procesa tus consultas paso a paso y devuelve respuestas claras basadas en la información del archivo.

Internamente, el componente utiliza un manejador asíncrono que registra cada pensamiento y acción en tiempo real, lo que te permite ver el progreso del agente directamente en tu panel de flujo de trabajo. Al final, entrega un objeto listo para ser usado por otros nodos del flujo, que puede seguir analizando datos o enviar los resultados a visualizaciones, reportes o bases de datos.

Conexión y Credenciales

Este componente requiere que tengas configurado previamente un Modelo de Lenguaje (LLM) en el panel de Nappai para poder funcionar correctamente:

Dirígete a la sección de Credenciales en tu panel de Nappai.
Crea una nueva credencial del tipo correspondiente a tu proveedor de IA (por ejemplo, OpenAI, Azure, etc.) e ingresa las claves de API o tokens requeridos.
En tu flujo de trabajo, conecta esa credencial al campo Model de este nodo para habilitar la generación de respuestas.

Entradas

Los siguientes campos están disponibles para configurar este componente:

Model [REQUERIDO]: El modelo de inteligencia artificial que interpretará tus preguntas y generará las respuestas. Necesitas conectar uno activo y válido.
File Path [REQUERIDO]: La ruta o ubicación del archivo CSV que contiene los datos que deseas analizar. Solo se permiten archivos con extensión .csv.
Agent Type: El método de razonamiento que usará el agente. Por defecto está en openai-tools, pero puedes cambiarlo si necesitas explicaciones paso a paso o funciones personalizadas.
Handle Parse Errors: Opción para manejar automáticamente errores menores si el formato del archivo CSV no es perfecto.
Input: Campo adicional para inyectar contexto extra o datos de referencia que complementen el archivo principal.
Max Iterations: Límite de pasos que el agente puede dar para procesar una solicitud, evitando que se quede en bucles infinitos.
Verbose: Activa un registro detallado de cada acción que realiza el agente. Útil para depuración, pero puede generar muchos logs.

Salidas

Este componente genera dos tipos de salidas principales que puedes conectar a otros nodos de tu flujo:

Agent: Un ejecutor configurado que mantiene el agente vivo en el flujo. Útil cuando necesitas que otros nodos sigan interactuando con el mismo contexto de datos.
Response: El mensaje final con el análisis, resumen o respuesta generada. Este es el resultado principal que suele mapearse a visualizaciones, reportes o nodos de salida.

Ejemplo de Respuesta JSON

Cuando el componente devuelve la salida Response, el formato JSON que podrás mapear en los siguientes nodos se verá similar a este ejemplo: json { “status”: “success”, “agent_name”: “CSVAgent_v1”, “answer”: “He analizado tu archivo de ventas. El total de ingresos del último trimestre fue de $45,230, con un crecimiento del 12% respecto al trimestre anterior. El producto más vendido fue ‘Sofá Modular’.”, “data_processed_rows”: 1250, “confidence_score”: 0.92, “timestamp”: “2024-05-20T10:30:00Z”, “metadata”: { “model_used”: “gpt-4”, “csv_columns_analyzed”: [“Fecha”, “Producto”, “Ingresos”, “Cliente”] } }

Conectividad

Este componente funciona como un puente entre tus datos tabulares y la inteligencia artificial del sistema. Lógicamente, la entrada Model se conecta a nodos de configuración de IA o credenciales, mientras que la entrada File Path se vincula a nodos de carga de archivos o almacenamiento local.

En el flujo, la salida Agent suele conectarse a nodos de transformación, filtros o a otros agentes que necesiten seguir refinando los datos. Por su parte, la salida Response se mapea comúnmente a visualizaciones (gráficos, tablas), nodos de reporte o APIs de notificación. Esta conexión tiene sentido porque transforma datos crudos en información accionable, cerrando el ciclo de análisis automatizado en Nappai.

Ejemplo de Uso

Imagina que eres responsable de marketing y necesitas entender el rendimiento de tus ventas mensuales. Subes un archivo ventas_2024.csv al campo File Path y conectas tu modelo de OpenAI al campo Model. En lugar de abrir la hoja de cálculo manualmente, envías una pregunta al flujo: “¿Cuál fue el producto con mayor crecimiento en marzo?”.

El agente procesa el archivo, razona sobre los datos y devuelve una Response con el producto destacado y el porcentaje de crecimiento. Conectas esta salida a un nodo de Gráfico en Nappai y, automáticamente, se genera un gráfico de barras visual. Todo ocurre en segundos, sin escribir una sola línea de código.

Notas Importantes

🔒 Sensitive Data Handling 🔴 Cualquier dato dentro del archivo CSV se enviará al proveedor del modelo de IA cuando el agente se ejecute. Evita incluir información personal o confidencial a menos que uses un modelo privado o instalado localmente.

⚠️ CSV File Size 🟡 El agente carga todo el archivo en la memoria del sistema. Si el archivo es muy grande (cientos de megabytes), podría ralentizar el flujo o causar errores de memoria. Si encuentras problemas, divide tus datos en archivos más pequeños antes de subirlos.

⚠️ CSV Format Requirements 🟡 El archivo CSV debe tener una fila de encabezado clara y usar comas para separar los datos. Si faltan los encabezados o usa separadores extraños, aparecerán errores de parseo. Verifica y limpia el archivo antes de subirlo.

📋 Model Configuration 🔴 Es necesario tener un modelo de lenguaje configurado y accesible (por ejemplo, una clave de API válida). Sin un modelo activo, el agente no podrá interpretar preguntas ni generar respuestas.

💡 Choose the Right Agent Type 🟢 openai-tools es la opción predeterminada y funciona bien en la mayoría de los casos. Si necesitas que el agente explique su razonamiento paso a paso, usa zero-shot-react-description. Cambia a openai-functions si tus consultas requieren llamar a funciones personalizadas.

💡 Keep File Paths Simple 🟢 Utiliza rutas locales o relativas a tus archivos CSV. Evita rutas de red complejas o variables dinámicas, ya que podrían fallar cuando el flujo se ejecute en diferentes entornos o servidores.

⚙️ Logging and Monitoring 🟢 El componente registra automáticamente cada paso que realiza. Activa el registro detallado en la configuración de tu flujo para ver el historial de acciones y resolver problemas de forma más rápida y clara.

Consejos y Mejores Prácticas

Comienza siempre con archivos CSV pequeños y limpios para entender cómo se comporta el agente antes de escalar a volúmenes grandes de datos.
Revisa los encabezados de tus archivos para asegurar que el agente identifique correctamente las columnas y no asuma datos incorrectos.
Usa la opción Verbose solo en entornos de prueba o desarrollo; en producción puede saturar los registros innecesariamente.
Mantén actualizado tu panel de Nappai; los componentes legacy suelen recibir mejoras de rendimiento y seguridad en las versiones más recientes.
Si el agente tarda demasiado en responder, revisa el límite de Max Iterations o reduce el tamaño del archivo para optimizar el rendimiento.

Consideraciones de Seguridad

Asegúrate de que los datos que compartas con el agente no contengan información sensible o protegida por normativas (como GDPR o HIPAA). Utiliza claves de API seguras almacenadas en el panel de credenciales de Nappai y limita el acceso a archivos críticos. El sistema está diseñado para operar dentro de entornos controlados; evita compartir archivos con datos personales sin antes anonimizarlos o enmascararlos.