EcomInsight Agent es un sistema multiagente orientado al análisis de datos de e-commerce mediante lenguaje natural. El objetivo es permitir que un usuario de negocio pueda realizar preguntas sobre ventas, clientes, productos, pedidos y oportunidades comerciales sin necesidad de escribir SQL directamente.
El sistema utiliza un agente supervisor, dos subagentes especializados, una fuente de datos fundamentada en BigQuery y un servidor MCP propio para generar informes y guardar evidencias del análisis.
El proyecto está pensado para cumplir los requisitos del trabajo final: construir un sistema multiagente funcional, con herramientas MCP y grounding sobre una fuente de datos real.
En muchos entornos de e-commerce, los datos están disponibles en almacenes analíticos como BigQuery, pero no todos los perfiles de negocio tienen conocimientos suficientes para consultar la información con SQL.
Este proyecto busca resolver ese problema mediante un asistente conversacional capaz de:
- Responder preguntas de negocio sobre datos reales.
- Consultar BigQuery de forma segura.
- Interpretar resultados desde una perspectiva comercial.
- Generar informes ejecutivos en Markdown.
- Guardar snapshots del análisis para trazabilidad.
- Gestionar de forma controlada preguntas fuera de alcance o consultas peligrosas.
Los objetivos principales del sistema son:
- Permitir consultas en lenguaje natural sobre un dataset de e-commerce.
- Traducir preguntas de negocio en consultas analíticas seguras.
- Ejecutar únicamente consultas de lectura sobre BigQuery.
- Interpretar los resultados con lenguaje comprensible para negocio.
- Generar informes reutilizables mediante una herramienta MCP.
- Demostrar una arquitectura multiagente con supervisor y subagentes.
- Documentar limitaciones, costes, modos de fallo y posibles mejoras.
El usuario objetivo sería un perfil de negocio, analista comercial, responsable de marketing o responsable de e-commerce que quiere analizar el comportamiento de la tienda online.
Ejemplos de preguntas:
- ¿Qué categorías generan más ingresos?
- ¿Cuáles son los productos más vendidos?
- ¿Qué países tienen mayor volumen de ventas?
- ¿Qué porcentaje de pedidos se cancela?
- ¿Qué segmentos de clientes parecen más rentables?
- ¿Dónde invertirías más presupuesto de marketing?
- Genera un informe ejecutivo con los principales hallazgos.
- Guarda este análisis para revisarlo posteriormente.
El sistema se compone de los siguientes elementos:
- Usuario
- ADK Web
- Supervisor Agent
- BigQuery Analyst Agent
- Business Consultant Agent
- Safe BigQuery Tool
- BigQuery Dataset
- MCP Reporting Server
- Informes Markdown y snapshots JSON
flowchart TD
U[Usuario] --> UI[ADK Web]
UI --> S[Supervisor Agent]
S --> BQA[Subagente BigQuery Analyst]
S --> BCA[Subagente Business Consultant]
BQA --> SQLTool[Safe BigQuery Query Tool]
SQLTool --> BQ[(BigQuery: thelook_ecommerce)]
S --> MCP[MCP Reporting Server]
MCP --> REP[Informes Markdown]
MCP --> SNAP[Snapshots JSON]
BQA --> S
BCA --> S
MCP --> S
S --> UI
UI --> U
El Supervisor Agent es el punto de entrada principal del sistema. Recibe la consulta del usuario y decide qué componente debe intervenir.
- Interpretar la intención del usuario.
- Decidir si la consulta requiere datos de BigQuery.
- Delegar el análisis técnico al subagente BigQuery.
- Delegar la interpretación al subagente de negocio.
- Invocar el servidor MCP cuando el usuario solicita un informe o snapshot.
- Gestionar errores y consultas fuera de alcance.
- Devolver una respuesta final clara y estructurada.
El BigQuery Analyst Agent es el subagente especializado en obtención de datos.
- Convertir preguntas de negocio en consultas SQL.
- Usar únicamente tablas permitidas.
- Ejecutar consultas mediante la herramienta segura de BigQuery.
- Devolver resultados estructurados.
- Informar de errores SQL o datos insuficientes.
- Evitar operaciones de escritura o modificación de datos.
Para reducir complejidad y aumentar fiabilidad, la primera versión del sistema puede limitarse a consultas analíticas concretas:
- Ingresos por categoría.
- Top productos por ingresos.
- Ventas por país.
- Estado de pedidos.
- Evolución mensual de ventas.
- Clientes por país.
- Ticket medio por país o categoría.
El Business Consultant Agent interpreta los resultados obtenidos por el subagente de datos.
- Traducir datos en conclusiones de negocio.
- Identificar oportunidades comerciales.
- Detectar riesgos o anomalías.
- Proponer recomendaciones accionables.
- Explicar limitaciones del análisis.
- Preparar resúmenes para dirección.
La Safe BigQuery Tool es la capa técnica que ejecuta las consultas contra BigQuery.
- Conectarse a BigQuery usando
google-cloud-bigquery. - Ejecutar consultas de solo lectura.
- Bloquear sentencias peligrosas.
- Añadir límites de filas.
- Configurar un máximo de bytes facturables.
- Devolver los resultados en formato estructurado.
La herramienta debe rechazar consultas que contengan operaciones como:
INSERTUPDATEDELETEDROPTRUNCATEMERGEALTERCREATEEXPORTCALL
También debe comprobar que la consulta empieza por SELECT o WITH.
La fuente de datos principal será BigQuery.
bigquery-public-data.thelook_ecommerce
Este dataset público contiene información realista de un e-commerce, incluyendo:
- usuarios;
- pedidos;
- productos;
- inventario;
- eventos;
- categorías;
- marcas;
- países;
- fechas;
- estados de pedido.
| Tabla | Uso previsto |
|---|---|
orders |
Análisis de pedidos, estados, fechas y usuarios |
order_items |
Cálculo de ingresos y productos vendidos |
products |
Categorías, marcas, departamentos y precios |
users |
Segmentación por país, edad, género o localización |
events |
Análisis de comportamiento web, si se incluye en una fase avanzada |
El MCP Reporting Server es el servidor MCP propio del proyecto. Su función principal es permitir que el sistema genere artefactos persistentes.
Mientras que los subagentes razonan y analizan, el MCP ejecuta acciones concretas fuera del modelo.
El MCP permite:
- Crear informes ejecutivos en Markdown.
- Guardar snapshots del análisis en JSON.
- Registrar la pregunta del usuario.
- Registrar el SQL ejecutado.
- Guardar resultados principales.
- Guardar recomendaciones.
- Facilitar la trazabilidad del sistema.
Genera un informe en Markdown.
{
"title": "Informe de ventas por país",
"question": "¿Qué países generan más ingresos?",
"sql_used": "SELECT ...",
"key_findings": [
"Estados Unidos lidera los ingresos.",
"Reino Unido presenta alto ticket medio.",
"España muestra potencial de crecimiento."
],
"recommendations": [
"Priorizar campañas en mercados con mayor conversión.",
"Analizar costes logísticos por país.",
"Revisar categorías con menor rotación."
],
"limitations": [
"El análisis se basa en datos históricos.",
"No se incluyen costes de adquisición ni margen neto."
]
}{
"status": "ok",
"file_path": "reports/generated/sales_by_country_report.md",
"message": "Informe generado correctamente."
}Guarda un archivo JSON con la trazabilidad del análisis.
{
"timestamp": "2026-05-26T18:00:00",
"user_question": "¿Qué categorías generan más ingresos?",
"agent_used": "BigQuery Analyst Agent",
"sql_used": "SELECT ...",
"rows_returned": 10,
"summary": "Las categorías con mayores ingresos son...",
"recommendations": [
"Reforzar inversión en las categorías top.",
"Analizar margen por categoría antes de tomar decisiones."
]
}{
"status": "ok",
"file_path": "reports/snapshots/analysis_20260526_ventas_categoria.json"
}Genera una ficha KPI sencilla.
{
"kpi_name": "Ingresos totales",
"value": "1.250.000",
"period": "2024",
"interpretation": "Los ingresos se concentran principalmente en tres categorías.",
"risk_level": "medium",
"recommendation": "Analizar margen y recurrencia antes de escalar inversión."
}{
"status": "ok",
"kpi_card": "KPI: Ingresos totales..."
}