Orquestacion De Agentes

��# 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 [](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 % % % % % % % % =�9� buscar_clientes =�9� perfil_consumo_cliente % % % % =�9� clientes_alto_valor =�9� top_productos_vendidos % % % % =�9� analisis_categoria =�9� ventas_por_region % % % % =�9� preferencia_metodo_pago =�9� 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? * * * ### S' 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) ## =�d� 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." P+ Si este proyecto te ha sido �til, �no olvides darle una estrella en GitHub! P+ </div> _Versi�n 1.0 - Julio 2026_