Google ADK + MongoDB MCP Toolbox: Conecta Gemini a tus Datos Operacionales

El Fin de los Agentes Pasivos: De Chatbots a Operadores de Datos

Durante los últimos dos años, la mayoría de implementaciones de IA empresarial quedaron atrapadas en el paradigma de Retrieval-Augmented Generation (RAG) estático. En estos esquemas, el modelo de lenguaje se limita a consultar índices vectoriales para generar texto descriptivo, sin capacidad real de interactuar con el estado transaccional de la empresa.

Cuando un cliente solicita una orden o verifica existencias en tiempo real, el modelo necesita "manos y ojos": herramientas deterministas para inspeccionar documentos NoSQL, reservar stock y desencadenar flujos de facturación. Google ADK (Agent Development Kit) proporciona el marco de orquestación de agentes más robusto para los modelos Gemini, mientras que la arquitectura Toolbox basada en el estándar Model Context Protocol (MCP) establece un contrato de interfaz seguro entre la inteligencia generativa y los motores de almacenamiento.

Matriz de Decisión: Estrategias de Conexión IA-Bases de Datos

La elección del patrón de integración define la latencia, la consistencia y, sobre todo, la seguridad del sistema ante inyecciones de código o modificaciones erráticas:

Implementación Práctica: Orquestación Multi-Agente con Google ADK y MCP

A continuación se presenta la arquitectura en Python modular que define los agentes especializados, la herramienta de webhook para el enlace de pago en n8n y el conector MCP a MongoDB:

import os
import requests
from dotenv import load_dotenv
from google.adk.agents import Agent
from google.adk.tools import FunctionTool, McpTool
from google.adk.connection import DockerConnectionParams

load_dotenv()

# -------------------------------------------------------------------------
# 1. TOOL DETERMINISTA: Desencadenador Transaccional (n8n Webhook)
# -------------------------------------------------------------------------
def generate_payment_link(product_name: str, amount: float, customer_email: str) -> str:
    """Dispara un webhook hacia n8n para enviar el enlace de pago por correo."""
    webhook_url = os.getenv("N8N_PAYMENT_WEBHOOK_URL", "http://localhost:5678/webhook/payment-link")
    payload = {
        "product_name": product_name,
        "amount": amount,
        "customer_email": customer_email
    }
    
    try:
        response = requests.post(webhook_url, json=payload, timeout=10)
        response.raise_for_status()
        return "SUCCESS: Enlace de pago generado y enviado por correo vía n8n."
    except Exception as exc:
        return f"ERROR: Fallo al procesar el enlace de cobro: {str(exc)}"

payment_tool = FunctionTool(
    fn=generate_payment_link,
    name="generate_payment_link",
    description="Genera y envía por correo un link de pago seguro de Stripe para un cliente."
)

# -------------------------------------------------------------------------
# 2. SUB-AGENTE: Especialista de Inventario (MongoDB MCP - Sólo Lectura)
# -------------------------------------------------------------------------
inventory_agent = Agent(
    name="InventoryAgent",
    model="gemini-1.5-flash",
    instruction="""Eres el agente especialista de inventario.
    Tu única función es consultar MongoDB para comprobar disponibilidad y precios exactos.
    Nunca inventes precios ni confirmes órdenes directamente.""",
    tools=[
        McpTool(
            server_params=DockerConnectionParams(
                image="mcp/mongodb-server:latest",
                environment={"MONGODB_URI": os.getenv("MONGO_CONNECTION_STRING")}
            ),
            read_only=True,
            allowed_collections=["products"]
        )
    ]
)

# -------------------------------------------------------------------------
# 3. SUB-AGENTE: Especialista de Ventas y Transacciones (MongoDB MCP - Escritura Controlada)
# -------------------------------------------------------------------------
sales_agent = Agent(
    name="SalesAgent",
    model="gemini-1.5-flash",
    instruction="""Eres el agente de ventas y facturación.
    Cuando el cliente confirme la compra y provea su email:
    1. Ejecuta generate_payment_link con el monto exacto.
    2. Actualiza el stock en MongoDB decrementando la cantidad vendida.""",
    tools=[
        payment_tool,
        McpTool(
            server_params=DockerConnectionParams(
                image="mcp/mongodb-server:latest",
                environment={"MONGODB_URI": os.getenv("MONGO_CONNECTION_STRING")}
            ),
            read_only=False,
            allowed_collections=["products", "orders"]
        )
    ]
)

# -------------------------------------------------------------------------
# 4. AGENTE RAÍZ / ROUTER: OpsManager
# -------------------------------------------------------------------------
ops_manager = Agent(
    name="OpsManager",
    model="gemini-1.5-flash",
    instruction="""Eres el orquestador principal de operaciones de la tienda.
    - Si el usuario pregunta por productos o existencias: Delega a InventoryAgent.
    - Si el usuario desea concretar una compra: Delega a SalesAgent.
    Sé cordial, conciso y profesional en tus respuestas.""",
    sub_agents=[inventory_agent, sales_agent]
)

if __name__ == "__main__":
    # Ejecución del servidor web ADK local para pruebas de desarrollo
    print("Iniciando Google ADK Web Runner en http://127.0.0.1:8000 ...")
    ops_manager.serve(host="0.0.0.0", port=8000)

Patrones de Diseño y Gobernanza para Producción

Al trasladar este entorno local de Docker a infraestructura empresarial en Google Cloud Platform (GCP) (desplegando los agentes en Cloud Run o Google Kubernetes Engine), es imperativo respetar los siguientes pilares de arquitectura:

Framework de Implementación en 5 Pasos

1. Despliegue de Infraestructura Base: Levanta MongoDB (o MongoDB Atlas) y tu instancia de n8n utilizando contenedores Docker independientes orquestados con Docker Compose.
2. Definición del Pipeline en n8n: Configura un nodo Webhook con método POST, encadénalo con el nodo de envío de correos (SMTP o Gmail API) y responde un JSON estructurado con el estado de la operación.
3. Especificación de Esquemas MCP: Inicializa el servidor Model Context Protocol de MongoDB especificando los tipos de datos exactos de cada documento (ID, stock_quantity, price_usd, etc.).
4. Construcción de Agentes en Google ADK: Instancia los agentes modulares en Python, configurando el OpsManager como router jerárquico y asociando las herramientas según su alcance de privilegios.
5. Validación y Pruebas End-to-End: Ejecuta adk web, interactúa desde la consola para comprobar el ciclo completo: lectura de catálogo ➔ selección ➔ envío de enlace por email ➔ decremento del stock en base de datos.

Preguntas Frecuentes (FAQ)