# MCP Orquestacion de Agentes
# 🧠 MCP - Orquestación de Agentes con FastMCP y Groq

## Creación del primer flujo de orquestación/integración de capacidades en un sistema de agentes

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tu-usuario/MCP-Orquestacion-Agentes/blob/main/notebooks/PlantillaMCPMultiFuenteFastMCPLangChainOpenAI-david-yurivilca.ipynb)

---

## 📋 INFORMACIÓN GENERAL

| Campo | Valor |
|-------|-------|
| **Título** | Creación del primer flujo de orquestación/integración de capacidades en un sistema de agentes |
| **Curso** | CERTI AI ARCHITECT ONLINE 2026 II LIMA |
| **Docente** | IGNACIO ALEXIS ZAMBRANO CARRILLO |
| **Autor** | David Yurivilca |
| **Fecha** | Julio 2026 |
| **Institución** | BSG Institute |

---

## 🎯 OBJETIVO

Diseñar, construir y orquestar un sistema de agentes que integra múltiples capacidades utilizando el **Model Context Protocol (MCP)** como estándar de comunicación, demostrando:

- ✅ Identificación de capacidades de negocio
- ✅ Diseño de herramientas (tools) MCP
- ✅ Implementación con FastMCP
- ✅ Orquestación con LangChain + Groq
- ✅ Trazabilidad y seguridad

---

## 📊 CONTEXTO DEL NEGOCIO

**E-commerce de productos alimenticios en Argentina**

El dataset simula las operaciones de una empresa de e-commerce, permitiendo:

- Análisis de clientes por región (6 regiones argentinas)
- Evaluación de productos y categorías (8 categorías)
- Estudio de métodos de pago (5 métodos)
- Identificación de oportunidades comerciales

### 📈 Datos disponibles

| Tabla | Registros | Descripción |
|-------|-----------|-------------|
| `clientes` | 326 | Datos demográficos de clientes |
| `ventas` | 3,029 | Transacciones completas |
| `productos` | 38 | Catálogo de productos |
| `categorias` | 8 | Clasificación de productos |
| `metodos_pago` | 5 | Medios de pago disponibles |

---

## 🛠️ TECNOLOGÍAS UTILIZADAS

| Tecnología | Propósito |
|------------|-----------|
| **Python 3.10+** | Lenguaje principal |
| **FastMCP** | Framework para servidores MCP |
| **LangChain 1.0+** | Orquestación de agentes |
| **LangGraph** | Backend de agentes con estado |
| **Groq (LLaMA 3.3 70B)** | Modelo LLM con tool calling |
| **SQLite** | Base de datos local |
| **Google Colab** | Entorno de ejecución |

---

## 🚀 ARQUITECTURA DEL SISTEMA

```txt
┌─────────────────────────────────────────────────────────────────────────────┐
│                              USUARIO FINAL                                  │
│                     (Interactúa en lenguaje natural)                        │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          AGENTE LANGCHAIN                                   │
│                     (Orquestador + Razonamiento)                            │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────┐        │
│  │  1. Recibe la pregunta del usuario                              │        │
│  │  2. Interpreta la intención usando Groq (LLaMA 3.3 70B)         │        │
│  │  3. Aplica el System Prompt (políticas y reglas)                │        │
│  │  4. Selecciona la(s) herramienta(s) necesaria(s)                │        │
│  │  5. Ejecuta el loop de orquestación                             │        │
│  │  6. Genera respuesta final con evidencia                        │        │
│  └─────────────────────────────────────────────────────────────────┘        │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                       MCP CLIENT (LangChain Adapter)                        │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────┐        │
│  │  • Conecta al servidor MCP vía HTTP                             │        │
│  │  • Descubre herramientas disponibles                            │        │
│  │  • Ejecuta llamadas a herramientas (tool calls)                 │        │
│  │  • Gestiona la comunicación con el servidor MCP                 │        │
│  └─────────────────────────────────────────────────────────────────┘        │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         MCP SERVER (FastMCP)                                │
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────┐       │
│  │  HERRAMIENTAS (TOOLS) EXPUESTAS                                  │       │
│  │                                                                  │       │
│  │  🔹 buscar_clientes          🔹 perfil_consumo_cliente           │       │
│  │  🔹 clientes_alto_valor      🔹 top_productos_vendidos           │       │
│  │  🔹 analisis_categoria       🔹 ventas_por_region                │       │
│  │  🔹 preferencia_metodo_pago  🔹 calcular_nivel_cliente           │       │
│  │                                                                   │      │
│  │  ┌─────────────────────────────────────────────────────────────┐  │      │
│  │  │   ✅ Validación de parámetros (tipos y límites)            │  │      │
│  │  │   ✅ Manejo de errores (try/except)                        │  │      │
│  │  │   ✅ Consultas SQL parametrizadas (seguridad)              │  │      │
│  │  └─────────────────────────────────────────────────────────────┘ │       │
│  └──────────────────────────────────────────────────────────────────┘       │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                          SQLite DATABASE                                      │
│                                                                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │  CLIENTES   │  │   VENTAS    │  │  PRODUCTOS  │  │ CATEGORIAS  │           │
│  │  326 reg.   │  │ 3,029 reg.  │  │  38 reg.    │  │   8 reg.    │           │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘           │
│                                                                               │
│  ┌─────────────┐                                                              │
│  │ METODOS_PAGO│                                                              │
│  │   5 reg.    │                                                              │
│  └─────────────┘                                                              │
└───────────────────────────────────────────────────────────────────────────────┘
```


---

## 🔧 TOOLS IMPLEMENTADAS

| Tool | Propósito | Riesgo |
|------|-----------|--------|
| `buscar_clientes` | Buscar clientes por nombre, apellido o región | Bajo |
| `perfil_consumo_cliente` | Perfil completo de consumo de un cliente | Bajo |
| `clientes_alto_valor` | Identificar clientes con alto gasto | Bajo |
| `top_productos_vendidos` | Productos más vendidos | Bajo |
| `analisis_categoria` | Análisis de ventas por categoría | Bajo |
| `ventas_por_region` | Resumen de ventas por región | Bajo |
| `preferencia_metodo_pago` | Preferencias de métodos de pago | Bajo |
| `calcular_nivel_cliente` | Clasificar clientes (VIP, Premium, Regular) | Bajo |

---

## 📋 GUÍA DE USUARIO PASO A PASO

### 🔧 PRERREQUISITOS

1. **Cuenta de Google** (para acceder a Colab)
2. **Cuenta en Groq** (para obtener API Key gratuita)
   - Registrar en: https://console.groq.com/
   - Generar API Key en el dashboard

### 🚀 EJECUCIÓN EN GOOGLE COLAB

#### Paso 1: Abrir el notebook en Colab

**Opción A - Desde el repositorio:**
```bash
# Clonar el repositorio
git clone https://github.com/tu-usuario/MCP-Orquestacion-Agentes.git

# O abrir directamente en Colab:
# https://colab.research.google.com/github/tu-usuario/MCP-Orquestacion-Agentes/blob/main/notebooks/PlantillaMCPMultiFuenteFastMCPLangChainOpenAI-david-yurivilca.ipynb
```

**Opción B - Subir manualmente:**

1. Descargar el archivo .ipynb
2. Ir a https://colab.research.google.com/
3. Click en "Subir" → Seleccionar el archivo

#### Paso 2: Configurar la API Key de Groq

En la **Fase 3**, el notebook solicitará la API Key:
```python
# Busca esta celda y ejecútala
GROQ_API_KEY: ··········  # Ingresa tu API Key aquí
```

**¿Dónde obtenerla?**
    
1.  Ve a [https://console.groq.com/](https://console.groq.com/)
2.  Inicia sesión con tu cuenta
3.  Ve a "API Keys" en el menú lateral
4.  Click en "Create API Key"
5.  Copia la clave generada
    

* * *

#### Paso 3: Subir los archivos CSV

En la **Fase 3**, el notebook mostrará un botón para subir archivos:

1.  Haz clic en "Choose Files"
    
2.  Selecciona los 5 archivos CSV:
    
    -   `clientes.csv`
        
    -   `ventas.csv`
        
    -   `productos.csv`
        
    -   `categorias.csv`
        
    -   `metodos_pago.csv`
        

[https://via.placeholder.com/600x200?text=Upload+CSV+Files](https://via.placeholder.com/600x200?text=Upload+CSV+Files)

* * *

#### Paso 4: Ejecutar el notebook secuencialmente

El notebook está organizado en **11 fases**. Ejecuta cada celda en orden:

| Fase | Celdas | Qué hace | Tiempo estimado |
| --- | --- | --- | --- |
| **Fase 0-2** | 1-6 | Diseño y planificación | 5 min |
| **Fase 3** | 7-10 | Carga de datos a SQLite | 3 min |
| **Fase 4** | 11-19 | Pruebas de consultas SQL | 5 min |
| **Fase 5** | 20-22 | Creación del MCP Server | 2 min |
| **Fase 6** | 23 | Levantar el servidor | 1 min |
| **Fase 7** | 24-25 | Descubrir y probar tools | 3 min |
| **Fase 8** | 26 | Definir System Prompt | 1 min |
| **Fase 9** | 27-30 | Crear el agente con Groq | 2 min |
| **Fase 10** | 31-37 | Ejecutar pruebas | 10 min |
| **Fase 11** | 38-39 | Evaluación y limpieza | 2 min |

* * *

#### Paso 5: Verificar el servidor MCP

En la **Fase 6**, verás un mensaje como este:
```txt
✅ MCP Server activo!
   URL: http://127.0.0.1:8000/mcp
   PID: 12345
   Log: /content/mi_mcp_server.log
```

**Si ves este mensaje, el servidor está funcionando correctamente.** 🎉

* * *

#### Paso 6: Ejecutar las pruebas

En la **Fase 10**, verás preguntas de ejemplo:
```python
# Prueba 1: Producto más vendido
resultado = await consultar_agente(
    "¿Cuál es el producto más vendido en cantidad?"
)
```
*** Resultado Esperado ***
```txt
📝 RESPUESTA FINAL
El producto más vendido en cantidad es el de Hamburgesas congeladas, 
con un total de 382 unidades vendidas y $3,438 de ingresos totales.
```

**Resultado esperado:**

```text

📝 RESPUESTA FINAL
El producto más vendido en cantidad es el de Hamburgesas congeladas, 
con un total de 382 unidades vendidas y $3,438 de ingresos totales.
```
* * *

### 📝 EJEMPLOS DE PREGUNTAS PARA PROBAR

#### Básicas (1 tool)

```text

"¿Cuál es el producto más vendido?"
"Busca clientes de la región Patagonia"
"Dame el perfil del cliente Dan Parkin (ID: 4)"
"¿Qué categoría de productos genera más ingresos?"
```
#### Intermedias (2-3 tools)

```text

"Identifica los 5 clientes que más han gastado, dime su región y clasifica su nivel"
"¿Cuánto vendimos en la región Buenos Aires?"
"¿Qué método de pago es el más utilizado por los clientes?"
```

#### Avanzadas (5+ tools) - Desafío

```text
Realiza un análisis completo de la región Patagonia:
1. ¿Cuántos clientes hay en Patagonia?
2. ¿Cuáles son los 3 productos más vendidos en Patagonia?
3. ¿Qué categoría genera más ingresos en Patagonia?
4. ¿Qué método de pago prefieren los clientes de Patagonia?
5. ¿Qué recomendaciones darías para aumentar las ventas en esta región?
```
* * *

### ❓ SOLUCIÓN DE PROBLEMAS COMUNES

#### Error: "GROQ\_API\_KEY no configurada"

```bash
# Asegúrate de haber ejecutado la celda que solicita la API Key
# Si no funciona, reinicia el runtime y vuelve a ejecutar
```

#### Error: "El servidor no inició"

```bash
# Verifica que la base de datos se creó correctamente
!ls -la /content/mcp_laboratorio.db
# Verifica que el archivo del servidor existe
!ls -la /content/mi_mcp_server.py
# Revisa el log del servidor
!cat /content/mi_mcp_server.log
```

#### Error: "Puerto 8000 ocupado"

```bash

# Libera el puerto y reinicia
!fuser -k 8000/tcp 2>/dev/null || true
```

#### Error en las pruebas SQL

```bash
# Verifica que los archivos CSV se subieron correctamente
# Ejecuta la Fase 3 nuevamente
```
* * *

## 📊 RESULTADOS DEL LABORATORIO

| Métrica | Valor |
| --- | --- |
| Capacidades identificadas | 8 |
| Tools implementadas | 8 |
| Pruebas SQL exitosas | 8/8 |
| Pruebas manuales exitosas | 8/8 |
| Pruebas del agente exitosas | 7/7 |
| Criterios de evaluación | 8/8 (100%) |

### Principales hallazgos de negocio

| Hallazgo | Valor |
| --- | --- |
| **Producto más vendido** | Hamburgesas congeladas (382 unidades) |
| **Categoría con más ingresos** | Carnicería ($27,615 - 27.58%) |
| **Región con más ventas** | Buenos Aires ($35,820 - 1,041 órdenes) |
| **Método de pago más usado** | Mercado Pago (28.79%) |
| **Cliente con mayor gasto** | Pinchas Stollsteiner ($760) |

* * *

## 🔒 MEDIDAS DE SEGURIDAD

| Medida | Implementación |
| --- | --- |
| **SQL Injection** | ✅ Consultas parametrizadas con `?` |
| **Exposición de SQL** | ✅ No se expone SQL libre al LLM |
| **Validación de tipos** | ✅ `asegurar_int()` convierte y valida |
| **Límites de resultados** | ✅ `limite` acotado (1-25, 1-50, 1-20) |
| **Solo lectura** | ✅ Todas las tools usan `SELECT` |
| **Manejo de errores** | ✅ Try/except en `ejecutar_sql` |

* * *

## 📁 ESTRUCTURA DE ARCHIVOS

```text
📂 MCP-Orquestacion-Agentes/
│
├── 📄 README.md                               # Este archivo
├── 📄 requirements.txt                         # Dependencias
├── 📄 .env.example                             # Variables de entorno
│
├── 📂 notebooks/
│   └── 📄 PlantillaMCPMultiFuenteFastMCPLangChainOpenAI-david-yurivilca.ipynb
│
├── 📂 datasets/
│   ├── 📄 clientes.csv                         # 326 clientes
│   ├── 📄 ventas.csv                           # 3,029 transacciones
│   ├── 📄 productos.csv                        # 38 productos
│   ├── 📄 categorias.csv                       # 8 categorías
│   └── 📄 metodos\_pago.csv                     # 5 métodos de pago
│
└── 📂 docs/
    ├── 📄 guia-usuario.md                      # Guía detallada (este documento)
    └── 📄 arquitectura.md                      # Explicación técnica
```
* * *

## 📦 INSTALACIÓN LOCAL (OPCIONAL)

Si deseas ejecutar localmente en lugar de Colab:

```bash

# Clonar el repositorio
git clone https://github.com/tu-usuario/MCP-Orquestacion-Agentes.git
cd MCP-Orquestacion-Agentes
# Crear entorno virtual
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows
# Instalar dependencias
pip install -r requirements.txt
# Configurar variables de entorno
cp .env.example .env
# Editar .env con tu GROQ_API_KEY
# Ejecutar el notebook
jupyter notebook notebooks/
```
* * *

## 📄 requirements.txt

```txt

fastmcp>=0.1.0
langchain>=1.0.0
langchain-mcp-adapters>=0.1.0
langchain-groq>=1.0.0
pandas>=2.0.0
sqlite3
jupyter>=1.0.0
```

* * *

## 📄 .env.example

```bash
# Groq API Configuration
GROQ_API_KEY=tu_api_key_aqui
GROQ_MODEL=llama-3.3-70b-versatile
# Opciones de modelo alternativas:
# GROQ_MODEL=llama-3.1-8b-instant
# GROQ_MODEL=mixtral-8x7b-32768
# GROQ_MODEL=gemma2-9b-it
```
* * *

## 🧠 APRENDIZAJES CLAVE

1.  **MCP estandariza la conectividad** - Un servidor MCP puede servir a múltiples agentes
    
2.  **La orquestación es responsabilidad del agente** - MCP conecta, el agente decide
    
3.  **Las tools deben ser atómicas** - Una tool = una capacidad de negocio
    
4.  **La seguridad es por capas** - Server valida, orquestador controla, prompt guía
    
5.  **La trazabilidad es fundamental** - Ver qué tools usó el LLM y por qué
    
6.  **Groq es una alternativa viable** - Rápido, económico y con tool calling
    



---

## 📋 GUÍA DE USUARIO ADICIONAL PARA COLAB

### 🔗 Enlace directo para abrir en Colab

En el README, el badge de Colab ya está incluido:

```markdown
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tu-usuario/MCP-Orquestacion-Agentes/blob/main/notebooks/PlantillaMCPMultiFuenteFastMCPLangChainOpenAI-david-yurivilca.ipynb)
```

### ⚠️ IMPORTANTE PARA COLAB

1. **Runtime**: Asegúrate de usar un runtime con GPU habilitada
   - Runtime → Change runtime type → T4 GPU (recomendado)

2. **Tiempo de ejecución**: El notebook completo toma ~30-40 minutos

3. **Guardar progreso**: Colab guarda automáticamente en tu Drive
   - Archivo → Guardar una copia en Drive

4. **Reconexión**: Si se desconecta, vuelve a ejecutar desde la Fase 3
   - Las variables se reinician al reconectar

5. **Costos**: Groq es gratuito, pero verifica tu límite de uso
   - Gratis: 30 requests/minuto

* * *




## 📚 REFERENCIAS

### Documentación oficial

-   [Model Context Protocol - Specification](https://modelcontextprotocol.io/specification/)
    
-   [Model Context Protocol - Architecture](https://modelcontextprotocol.io/docs/learn/architecture)
    
-   [FastMCP Documentation](https://github.com/jlowin/fastmcp)
    
-   [LangChain MCP Adapters](https://docs.langchain.com/oss/python/langchain/mcp)
    
-   [LangGraph Overview](https://docs.langchain.com/oss/python/langgraph/overview)
    
-   [Groq Documentation](https://console.groq.com/docs)
    

### Material del curso

-   PDF: Estrategias de Integración CERTI AI ARCHITECT ONLINE 2026 II LIMA
    
-   PDF: Guía Teórica - Orquestación de MCP con Agentes
    

* * *

## 📝 NOTAS FINALES

### Sobre el uso de Groq vs OpenAI

Este laboratorio fue adaptado para usar **Groq** en lugar de OpenAI debido a:

-   ✅ Tier gratuito generoso para desarrollo educativo
    
-   ✅ Inferencia ultrarrápida
    
-   ✅ Excelente soporte para tool calling
    
-   ✅ Buen rendimiento en español
    

### Sobre el dataset

El dataset fue diseñado para simular un e-commerce real con:

-   Distribución geográfica realista (6 regiones argentinas)
    
-   Variedad de categorías de productos alimenticios
    
-   Métodos de pago comunes en Latinoamérica
    
-   Volumen de datos adecuado para análisis (3,029 transacciones)
    

* * *

## 👤 DATOS DEL AUTOR

| Campo | Valor |
| --- | --- |
| **Nombre** | David Yurivilca |
| **Curso** | CERTI AI ARCHITECT ONLINE 2026 II LIMA |
| **Institución** | BSG Institute |
| **Fecha de entrega** | Julio 2026 |

* * *

## 📄 LICENCIA

Este proyecto es de uso educativo para el curso **CERTI AI ARCHITECT ONLINE 2026 II LIMA** de **BSG Institute**.

* * *

<div align="center">

**📌 "No se trata de dar 'acceso a todo' al LLM.**  
**Se trata de exponer las capacidades mínimas necesarias,**  
**bajo permisos explícitos, con herramientas bien descritas,**  
**evidencia verificable, acciones controladas y trazabilidad completa."**

* * *

⭐ **Si este proyecto te ha sido útil, ¡no olvides darle una estrella en GitHub!** ⭐

</div>

* * *

_Versión 1.0 - Julio 2026_