Sales Agent

Autora: Carolina Mantilla Fecha: Mayo 31 de 2026

---

📌 Propósito del taller

Este proyecto tiene como objetivo construir un agente inteligente capaz de analizar datos de ventas a partir de preguntas en lenguaje natural.

La idea principal del taller es practicar cómo un agente puede conectarse con una base de datos SQL, interpretar lo que el usuario necesita y ejecutar acciones como consultar información, generar gráficos o guardar resultados en archivos.

En lugar de que el usuario escriba directamente consultas SQL, puede hacer preguntas como:

Top 5 productos más vendidos en Medellín

o:

Guarda las ventas por vendedor en un archivo CSV

Y el agente se encarga de interpretar la intención, consultar la base de datos y devolver el resultado adecuado.

---

🎯 ¿Qué hace el proyecto?

El agente permite:

• Recibir preguntas en lenguaje natural sobre ventas.
• Consultar una base de datos SQL con información de ventas.
• Generar respuestas en texto o formato de tabla.
• Crear gráficos de barras.
• Exportar resultados a archivos CSV o Excel.
• Usar herramientas conectadas mediante MCP.
• Ejecutar el flujo localmente usando un modelo de lenguaje con Ollama.

---

🧱 Estructura del proyecto

s2026q2xy-agente-ventas-cmantilla/
│
├── data/
│   └── ventas.csv
│
├── database/
│   └── ventas.db
│
├── outputs/
│   ├── ventas_por_vendedor.csv
│   ├── ventas_por_vendedor.xlsx
│   └── ventas_por_vendedor.png
│
├── src/
│   ├── agent.py
│   ├── charts.py
│   ├── database.py
│   ├── exports.py
│   ├── main.py
│   ├── mcp_server.py
│   └── tools.py
│
├── requirements.txt
├── .gitignore
└── README.md

---

🛠️ Herramientas utilizadas

Python 🐍

Se usó Python como lenguaje principal del proyecto porque permite trabajar fácilmente con bases de datos, archivos, análisis de datos, gráficos y frameworks de agentes.

---

SQLite 🗄️

Se usó SQLite como base de datos local.

La tabla principal del proyecto es ventas, con las siguientes columnas:

id, vendedor, sede, producto, cantidad, precio, fecha

SQLite fue una buena opción porque no requiere instalar un servidor externo de base de datos. Todo queda en un archivo local llamado:

database/ventas.db

---

Pandas 📊

Pandas se usó para manejar los resultados de las consultas SQL como tablas.

Esto facilita mostrar resultados, exportarlos a CSV/Excel y usarlos para generar gráficos.

---

Matplotlib 📈

Matplotlib se utilizó para generar gráficos de barras a partir de los resultados consultados en la base de datos.

Por ejemplo, el agente puede generar un gráfico de ventas por vendedor y guardarlo en la carpeta outputs/.

---

FastMCP 🔌

FastMCP se usó para crear un servidor MCP local.

Este servidor expone herramientas que el agente puede usar, como:

• Consultar la base de datos.
• Exportar resultados a CSV.
• Exportar resultados a Excel.
• Generar gráficos.

Esto permite que el agente no acceda directamente a todo el código, sino que use herramientas específicas y controladas.

---

LangChain 🧠

LangChain se usó como framework de agentes.

Su función principal en el proyecto es conectar el modelo de lenguaje con las herramientas disponibles mediante MCP.

---

Ollama 🤖

Inicialmente se intentó usar modelos en la nube, pero por temas de cuota y facturación se decidió usar Ollama.

Ollama permite ejecutar modelos de lenguaje localmente, sin depender de créditos externos ni APIs pagas.

El modelo usado fue:

llama3.2:3b

Esta decisión permitió mantener el enfoque del taller: usar un modelo de lenguaje para interpretar la intención del usuario, pero ejecutándolo de forma local.

---

⚙️ Cómo correr el proyecto

1. Clonar el repositorio

git clone [<URL_DEL_REPOSITORIO>](https://github.com/ai-scm/s2026q2xy-agente-ventas-cmantilla)
cd s2026q2xy-agente-ventas-cmantilla

---

2. Crear y activar el entorno virtual

python3 -m venv .venv
source .venv/bin/activate

---

3. Instalar dependencias

pip install -r requirements.txt

---

4. Instalar y ejecutar Ollama

Si estás en Mac y tienes Homebrew:

brew install ollama

Luego inicia el servidor de Ollama:

ollama serve

Es importante dejar esta terminal abierta mientras se ejecuta el agente.

---

5. Descargar el modelo local

En otra terminal, ejecuta:

ollama pull llama3.2:3b

Puedes verificar que el modelo quedó instalado con:

ollama list

---

6. Configurar el archivo .env

Crear un archivo .env en la raíz del proyecto con el siguiente contenido:

MODEL_PROVIDER=ollama
MODEL_NAME=llama3.2:3b

Este archivo no se debe subir al repositorio.

---

7. Crear la base de datos

Antes de correr el agente, se debe crear la base de datos SQLite a partir del archivo CSV:

python3 src/database.py

Esto genera el archivo:

database/ventas.db

---

8. Ejecutar el agente

Con el entorno virtual activo:

python3 src/main.py

Luego puedes escribir preguntas como:

Top 5 productos más vendidos en Medellín

Para salir del agente:

salir

---

🧠 ¿Cómo lo hicimos?

El proyecto se construyó por partes.

Primero se creó un archivo CSV con datos de ventas. Luego, esos datos se cargaron en una base SQLite mediante src/database.py.

Después se creó una herramienta para ejecutar consultas SQL de forma segura, permitiendo únicamente consultas SELECT. Esto se hizo para evitar que el agente pudiera modificar o borrar información de la base de datos.

También se agregaron herramientas para exportar resultados a CSV o Excel y para generar gráficos de barras.

Luego se implementó un servidor MCP local usando FastMCP. Este servidor expone las herramientas principales para que el agente pueda usarlas.

Finalmente, se conectó el agente con LangChain y Ollama. El modelo local interpreta la pregunta del usuario y decide qué herramienta debe usar.

---

🔍 Ajustes importantes realizados

Durante las pruebas se encontró que el problema no estaba en la base de datos, sino en cómo el modelo generaba algunas consultas SQL.

Por ejemplo, para Medellín a veces generaba valores incorrectos como:

Medellñn

o versiones sin tilde como:

Medellin

Como SQLite compara texto de forma exacta, esas variantes no encontraban registros.

Para solucionarlo, se agregó una normalización en src/tools.py, permitiendo reconocer variantes como:

medellin
Medellín
MEDELLÍN
Medellñn
Bogota
Bogotá
Cali

También se ajustó el arranque del servidor MCP para usar sys.executable, asegurando que se ejecute con el mismo entorno virtual del proyecto.

Esto evitó errores relacionados con dependencias instaladas en el .venv, como pandas o fastmcp.

Además, se cambió la respuesta de las herramientas para que el modelo recibiera resultados en formato de tabla legible, no solo JSON compacto. Esto ayudó a que el modelo interpretara mejor los resultados devueltos por la base de datos.

---

🧪 Pruebas realizadas

1. Top productos más vendidos en Medellín

Pregunta:

Top 5 productos más vendidos en Medellín

Resultado esperado:

1. Mouse - 22 unidades
2. Tablet - 7 unidades
3. Laptop - 3 unidades
4. Monitor - 2 unidades

Esta prueba valida que el agente pueda filtrar por sede, agrupar por producto y sumar cantidades vendidas.

---

2. Variante sin tilde

Pregunta:

Top productos más vendidos en Medellin

Resultado esperado:

Mouse - 22 unidades
Tablet - 7 unidades
Laptop - 3 unidades
Monitor - 2 unidades

Esta prueba valida que la normalización de texto funcione aunque el usuario escriba sin tilde.

---

3. Vendedor con más ventas en Bogotá

Pregunta:

Quién fue el vendedor con más ventas en Bogotá

Resultado esperado:

Ana - 10,640,000

Esta prueba valida que el agente pueda calcular ventas en dinero usando:

SUM(cantidad * precio)

---

4. Ventas por vendedor

Pregunta:

Cuánto vendió cada vendedor

Resultado esperado:

María  - 13,600,000
Ana    - 10,640,000
Carlos - 8,860,000
Pedro  - 7,350,000
Luisa  - 6,770,000

Esta prueba valida agrupación por vendedor y ordenamiento por total vendido.

---

5. Gráfico de ventas por vendedor

Pregunta:

Hazme un gráfico de ventas por vendedor

Resultado esperado:

outputs/ventas_por_vendedor.png

Esta prueba valida que el agente pueda generar una visualización a partir de una consulta SQL.

---

6. Exportación a CSV

Pregunta:

Guarda las ventas por vendedor en un archivo CSV

Resultado esperado:

outputs/ventas_por_vendedor.csv

Esta prueba valida que el agente pueda guardar resultados en archivos.

---

7. Exportación a Excel

Pregunta:

Guarda las ventas por vendedor en un archivo Excel

Resultado esperado:

outputs/ventas_por_vendedor.xlsx

Esta prueba valida la persistencia de resultados en formato Excel.

---

📁 Archivos generados

Los resultados generados por el agente se guardan en la carpeta:

outputs/

Algunos ejemplos de archivos generados son:

ventas_por_vendedor.csv
ventas_por_vendedor.xlsx
ventas_por_vendedor.png

---