Crea un catálogo de comercio electrónico inteligente con persistencia de varias bases de datos

1. Introducción

En el comercio minorista moderno, tus datos son un ecosistema diverso y en expansión. Tienes datos transaccionales sólidos (precios e inventario), catálogos polimórficos "desordenados" (especificaciones de productos electrónicos en comparación con tallas de ropa) y petabytes de registros de comportamiento. Forzar estos elementos en un solo monolito no solo genera deuda técnica, sino que también arruina la experiencia del usuario.

En este codelab, diseñarás una potencia políglota que armoniza lo siguiente:

• AlloyDB: Es la columna vertebral transaccional para la coherencia de alta velocidad y los embeddings de imágenes.
• MongoDB Atlas en Google Cloud: Tu capa de catálogo flexible y que no depende de esquemas.
• Cloud Storage: Tu cerebro analítico para la previsión de tendencias en tiempo real.
• BigQuery: Tu almacén digital de alta resolución.

¿Cuál es el "ingrediente secreto"? Usarás MCP Toolbox para bases de datos para organizar y unificar de forma inteligente las fuentes de datos que se ejecutan en Cloud Run como un puente semántico y, luego, implementarás una app de chat multiagente con el Kit de desarrollo de agentes (ADK). No solo estás creando una barra de búsqueda, sino un cerebro inteligente para el comercio minorista que comprende el contexto, respeta las restricciones y cierra la brecha entre los datos sin procesar y la intención humana.

La consulta imposible del usuario

Los agentes de comercio electrónico estándar fallan en el razonamiento multidimensional (combinar restricciones negativas, similitud visual y el inventario en tiempo real). Por ejemplo, por lo general, quiero hablar con un sitio de venta minorista de la siguiente manera:

"Hola, estoy planeando un viaje para tomar fotos a gran altitud. Muéstrame algunas mochilas resistentes a la intemperie con un estilo similar al de la "AeroGlow Pro", pero sin componentes de cuero. Además, dime si realmente están en stock y si otros fotógrafos se quejaron de la durabilidad de la correa en las opiniones".

Por qué esta consulta es "The Agent Killer":

• Similitud visual (AlloyDB + Vector Search): "Similar in style to the AeroGlow Pro" requiere una comparación de embeddings de imágenes.
• Restricción negativa (MongoDB): "Sin cuero" requiere filtrar a través de atributos anidados y flexibles que no suelen estar en un esquema de SQL estándar.
• Inventario en tiempo real (AlloyDB): Para saber si un producto está "realmente en stock", se requiere una verificación transaccional en tiempo real (no un índice de búsqueda desactualizado).
• Síntesis semántica (BigQuery y multiagente): El análisis de las opiniones sobre la "durabilidad de la correa" requiere que el agente resuma los comentarios no estructurados de BigQuery sobre la marcha.

La mayoría de los bots de venta minorista solo verían "mochila" y "cuero", y mostrarían 10 mochilas de cuero. ¿Cómo lo detenemos?

Porque no solo buscamos coincidencias con palabras clave. Usaremos MCP Toolbox para permitir que nuestros agentes “razonen” en todas estas fuentes, la verdad transaccional en AlloyDB y los atributos flexibles en MongoDB de forma simultánea. ¡Vamos a crearla!

Actividades

• Aprovisionar un clúster de AlloyDB para los datos de productos principales
• Configura MongoDB Atlas en Google Cloud para almacenar detalles de productos semiestructurados
• Crea un bucket de Cloud Storage para entregar imágenes de productos
• Implementar MCP Toolbox para bases de datos en Cloud Run para obtener un acceso uniforme a los datos
• Ejecutar procesos de ETL para enviar datos a BigQuery para su análisis
• Conversar con un agente de IA en lenguaje natural

Requisitos previos

• Un navegador web, como Chrome
• Un proyecto de Google Cloud con la facturación habilitada.
• Una cuenta gratuita de MongoDB Atlas en Google Cloud

2. Antes de comenzar

Crea un proyecto de Google Cloud

1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto.

Inicie Cloud Shell

Cloud Shell es un entorno de línea de comandos que se ejecuta en Google Cloud y que viene precargado con las herramientas necesarias.

1. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
2. Una vez que te conectes a Cloud Shell, verifica tu autenticación:

   gcloud auth list
   

3. Confirma que tu proyecto esté configurado:

   gcloud config get project
   

4. Si tu proyecto no está configurado como se espera, configúralo:

   export PROJECT_ID=<YOUR_PROJECT_ID>
   gcloud config set project $PROJECT_ID
   

Establecer las variables

En Cloud Shell, configura las variables de entorno para el ID y el número de tu proyecto:

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

Si se desconecta tu sesión de Cloud Shell, vuelve a ejecutar estos comandos de export (y los demás que agregues más adelante en este codelab).

Habilita las APIs obligatorias

Ejecuta este comando para habilitar todas las APIs requeridas:

gcloud services enable \
  alloydb.googleapis.com \
  bigquery.googleapis.com \
  storage.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  iam.googleapis.com \
  secretmanager.googleapis.com \
  compute.googleapis.com \
  servicenetworking.googleapis.com \
  aiplatform.googleapis.com

3. Configura Cloud Storage

Cloud Storage funciona como un almacén masivo de recursos multimedia no estructurados, como imágenes de productos.

1. En la consola de Google Cloud, navega a Cloud Storage y haz clic en Crear bucket.
2. Asígnale un nombre único a nivel global, por ejemplo, -ecommerce-images.
3. Haz clic en Crear.
4. Para permitir que la aplicación de demostración acceda a las imágenes sin autenticación, desmarca la opción Aplicar la prevención de acceso público a este bucket y haz clic en Confirmar.
5. Ve a la pestaña Permisos.
6. En Permisos, haz clic en Otorgar acceso.
7. En Principales nuevas, ingresa allUsers.
8. En Selecciona un rol, elige Cloud Storage > Visualizador de objetos de Storage.
9. Haz clic en Guardar y, luego, en Permitir acceso público para confirmar que harás público el recurso.
10. En Cloud Shell, guarda el nombre del bucket en una variable:

    export BUCKET=<your-bucket-name>
    

    Reemplaza por el nombre del bucket que creaste.

Sube imágenes de marcador de posición

El proyecto usa imágenes de marcadores de posición para brindar la mejor experiencia visual.

1. En Cloud Shell, clona el repositorio:

   git clone https://github.com/AbiramiSukumaran/polyglot-persist-ecommerce.git
   

2. Navega a la carpeta UploadImages:

   cd polyglot-persist-ecommerce/UploadImages
   

3. Sube las imágenes de muestra a tu bucket:

   gcloud storage cp *.jpg gs://$BUCKET/
   

4. Configura AlloyDB

AlloyDB funciona como la fuente única de información para los datos estructurados, transaccionales y críticos, como los IDs de productos, los nombres, los SKU, los precios y el inventario. AlloyDB también potencia el agente de IA con capacidades de búsqueda de similitud para recomendaciones y consultas en lenguaje natural.

Para configurar rápidamente un clúster, una instancia y una red para tu entorno de desarrollo con una interfaz web, sigue los pasos de este codelab.

Aprovisiona un clúster de AlloyDB

1. En la consola de Google Cloud, navega a AlloyDB para PostgreSQL.
2. Haz clic en Crear clúster.
3. En ID de clúster, ingresa ecommerce-cluster.
4. Establece una contraseña segura para el usuario postgres. Para fines de aprendizaje, puedes usar alloydb.
5. En Versión de la base de datos, mantén la opción predeterminada.
6. En Región, selecciona us-central1 (o la región que prefieras).

Configura la instancia principal

1. En ID de instancia (Instance ID), ingresa ecommerce-cluster-primary.
2. En Disponibilidad zonal, selecciona Zona única.
3. En Serie de máquinas, selecciona N2 y, en Tipo de máquina, selecciona 4 vCPU, 32 GB.
4. En Conectividad de IP privada, selecciona Acceso privado a servicios (PSA) y la red default.Si aún no se estableció la red predeterminada, haz clic en Confirmar configuración de red para crear una.
5. En Conectividad de IP pública, selecciona la casilla de verificación Habilitar IP pública para que la caja de herramientas de MCP se conecte correctamente en este codelab. La consola habilita automáticamente la marca password.enforce_complexity, que AlloyDB requiere para la IP pública.
6. En Redes externas autorizadas, ingresa 0.0.0.0/0. Selecciona la casilla de verificación Reconozco los riesgos y haz clic en Guardar.
7. Haz clic en Crear clúster.

La creación del clúster y la instancia tarda hasta 10 minutos.

Inicializa la base de datos

1. Haz clic en AlloyDB Studio en el menú de navegación de la izquierda.
2. En el menú desplegable Base de datos, selecciona postgres.
3. Selecciona Autenticación integrada para acceder a la base de datos.
4. En Nombre de usuario, usa el usuario postgres.
5. En Contraseña, ingresa la que configuraste antes.
6. Haz clic en Autenticar.
7. En la vista de edición, abre una nueva pestaña de consulta sin título.
8. Copia el siguiente DDL y haz clic en Ejecutar:

   CREATE TABLE products_core_table (
     product_id UUID PRIMARY KEY,
     name VARCHAR(255) NOT NULL,
     sku VARCHAR(50) UNIQUE NOT NULL,
     price NUMERIC(10, 2) NOT NULL,
     stock INT NOT NULL
   );
   

9. En Cloud Shell, navega a la carpeta raíz del proyecto:

   cd ~/polyglot-persist-ecommerce
   

10. Abre el archivo alloydb_insert_queries.sql en Cloud Shell y copia las consultas de inserción.

    cat alloydb_insert_queries.sql
    

11. En una nueva pestaña de consulta sin título, pega solo las declaraciones INSERT y haz clic en Ejecutar.
12. En una nueva pestaña de consulta sin título, copia el siguiente DDL y haz clic en Ejecutar para crear un índice en la tabla products_core_table:

    CREATE INDEX idx_products_core_sku ON products_core_table(sku);
    

Crear embeddings de imágenes para que el agente de IA recupere productos similares

La integración del agente de IA usa embeddings de imágenes para recuperar productos similares. Los embeddings se generan con el modelo multimodalembedding@001 y se almacenan en la base de datos de AlloyDB. Los embeddings son vectores dimensionales de 1408 y se almacenan en la columna img_embeddings.

Antes de generar embeddings, debemos otorgar los roles necesarios a la cuenta de servicio de AlloyDB para que acceda a Cloud Storage.

Otorga roles a la cuenta de servicio de AlloyDB para acceder a Cloud Storage

Otorga a la cuenta de servicio de AlloyDB los roles que necesita para leer imágenes de Cloud Storage y generar embeddings de Vertex AI:

for role in roles/storage.objectUser roles/storage.objectViewer roles/aiplatform.user; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-alloydb.iam.gserviceaccount.com" \
    --role=$role --condition=None
done

Habilita las extensiones

Para compilar esta app, usaremos las extensiones pgvector y google_ml_integration. La extensión pgvector te permite almacenar y buscar embeddings de vectores. La extensión google_ml_integration proporciona funciones que usas para acceder a los extremos de predicción de Vertex AI y obtener predicciones en SQL. Ejecuta las siguientes DDL para habilitar estas extensiones:

1. En la consola de Google Cloud, navega a AlloyDB para PostgreSQL.
2. Haz clic en AlloyDB Studio en el menú de navegación de la izquierda.
3. En la vista de edición, abre una nueva pestaña de consulta sin título.
4. Copia el siguiente DDL y haz clic en Ejecutar:

   CREATE EXTENSION IF NOT EXISTS vector;
   CREATE EXTENSION IF NOT EXISTS google_ml_integration;
   

Inicializa la base de datos con embeddings

1. Agrega la columna img_embeddings a products_core_table.

   ALTER TABLE products_core_table
   ADD COLUMN img_embeddings vector(1408);
   

2. Imprime la consulta de embeddings con el nombre de tu bucket completado:

   cd ~/polyglot-persist-ecommerce
   sed "s/<STORAGE_BUCKET_NAME>/$BUCKET/g" alloydb_generate_embeddings.sql
   

3. Copia el resultado, pégalo en una nueva pestaña de consulta de AlloyDB Studio y haz clic en Ejecutar. Este proceso tarda aproximadamente un minuto. Si se agota el tiempo de espera, vuelve a ejecutarlo. Se omitirán los productos que ya tengan incorporaciones.

   La secuencia de comandos solo procesa los productos que tienen una imagen en UploadImages/.

5. Configura MongoDB Atlas en Google Cloud

MongoDB almacena detalles de productos enriquecidos y semiestructurados, y datos flexibles de comportamiento de los usuarios (como clics y vistas).

Crea un clúster de MongoDB

1. Accede a MongoDB Atlas (crea una cuenta gratuita si es necesario).
2. En Implementa tu clúster, selecciona Gratis. (Atlas preselecciona un nivel pagado; asegúrate de que esté seleccionado el nivel gratuito).
3. En Proveedor, selecciona Google Cloud y, en Región, selecciona Iowa (us-central1).
4. En Nombre, ingresa ecommerce-cluster y borra Cargar previamente el conjunto de datos de muestra.
5. Haz clic en Create Deployment.

Permite el acceso y crea un usuario de base de datos

Atlas abre el diálogo Connect to ecommerce-cluster.

1. Haz clic en Agregar una dirección IP diferente, ingresa 0.0.0.0/0 y agrégala.

   El uso de 0.0.0.0/0 permite el acceso desde cualquier dirección IP. Esto es aceptable para una demostración temporal, pero en producción, debes restringir el acceso a rangos de IP específicos.

2. Ingresa store-user en Nombre de usuario y storeuser en Contraseña. Luego, haz clic en Crear usuario de base de datos.
3. Haz clic en Elige un método de conexión y, luego, en Controladores y bibliotecas cliente.
4. En Usa esta cadena de conexión en tu aplicación, copia la cadena de conexión. Se verá de esta forma mongodb+srv://store-user:@ecommerce-cluster.xxxxx.mongodb.net/. Reemplaza por storeuser y guarda la cadena; la usarás en tools.yaml.

Si cerraste el cuadro de diálogo, abre Base de datos > Clústeres y haz clic en Conectar en ecommerce-cluster.

Crea una base de datos y una colección

1. En el panel de navegación de la izquierda, haz clic en Explorador de datos, luego, en Crear base de datos y, por último, ingresa los detalles:
   • Nombre de la base de datos: ecommerce_db
   • Nombre de la colección: product_details_collection
2. Haz clic en Crear base de datos.
3. En el Explorador de datos, selecciona el nombre de la colección.
4. Haz clic en el ícono Agregar datos (+) y, luego, en Insertar documento.
5. Copia el contenido JSON de product_details_export.json y pégalo en el diálogo del editor Insert Document.
6. Atlas muestra un banner en el que se ofrece convertir el texto en sintaxis de shell. Haz clic en CONVERTIR y, luego, en Insertar. Verifica que se hayan agregado 192 documentos.
7. En el Explorador de datos, haz clic en Crear colección (+) junto a la base de datos ecommerce_db.
8. Ingresa user_interactions_collection como nombre de la colección y haz clic en Crear colección.
9. En el Explorador de datos, selecciona la colección user_interactions_collection.
10. Haz clic en el ícono Agregar datos (+) y, luego, en Insertar documento.
11. Copia el contenido JSON de user_interactions_export.json y pégalo en el cuadro de diálogo del editor Insert Document.
12. Atlas muestra un banner en el que se ofrece convertir el texto en sintaxis de shell. Haz clic en CONVERTIR y, luego, en Insertar. Verifica que se hayan agregado 211 documentos.

6. Configura BigQuery

BigQuery agrega y analiza el comportamiento histórico de los usuarios para generar informes y recomendaciones inteligentes.

Crea el conjunto de datos

1. En la consola de Google Cloud, navega a BigQuery.
2. Junto al ID del proyecto en el panel Explorador, haz clic en el menú de tres puntos y selecciona Crear conjunto de datos.
3. Ingresa ecommerce_analytics en ID del conjunto de datos.
4. En Ubicación de los datos, selecciona US (multiple regions) (la configuración de tools.yaml espera la ubicación US).
5. Haz clic en Crear conjunto de datos.

Crea la tabla de Analytics

1. Abre una consulta nueva en el espacio de trabajo de BigQuery.
2. Ejecuta la siguiente sentencia de SQL para crear la tabla de resumen que vincula a los usuarios con las interacciones con los productos:

CREATE TABLE ecommerce_analytics.user_product_interactions (
    user_id STRING DEFAULT 'any user',
    product_id STRING,
    interaction_score INT
);

Otorga roles a la cuenta de servicio de Compute

Otorga a la cuenta de servicio predeterminada de Compute los roles que necesitan MCP Toolbox y la app:

for role in \
  roles/bigquery.dataEditor \
  roles/bigquery.jobUser \
  roles/secretmanager.secretAccessor \
  roles/alloydb.client \
  roles/serviceusage.serviceUsageConsumer \
  roles/storage.objectViewer \
  roles/aiplatform.user \
  roles/artifactregistry.writer; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
    --role="$role" \
    --condition=None
done

Como alternativa, en la consola, ve a IAM y administración > IAM, haz clic en Otorgar acceso, ingresa la cuenta de servicio y agrega los mismos roles.

7. Comprende la aplicación de extremo a extremo

Para aprender cómo funciona cada componente con los demás, crearemos una aplicación de comercio electrónico que use varias bases de datos y servicios. La aplicación se compila con un backend de Python (Flask) y, además, integra varias bases de datos y servicios de Google Cloud.

Comprende la estructura de directorios

En la siguiente sección, clonarás el repositorio polyglot-persist-ecommerce y lo usarás para ejecutar la aplicación de forma local. Una vez que probemos la aplicación de forma local, implementaremos MCP Toolbox y la aplicación en Cloud Run.

Explora los archivos descargados en este directorio. Se incluyen los siguientes directorios de alto nivel:

• UploadImages: Almacena recursos de imagen, que se usan principalmente para la documentación o el contenido visual del catálogo de productos de comercio electrónico.
• static: Almacena los recursos web estáticos de la aplicación, como los archivos CSS y JavaScript, que se usan para diseñar y agregar interactividad a la interfaz de usuario ( fuente).
• templates: Almacena las plantillas HTML (probablemente Jinja2 para Flask) que usa la aplicación de Python para renderizar de forma dinámica las páginas web del catálogo de comercio electrónico ( fuente).

Los archivos de este repositorio funcionan en conjunto para compilar, configurar e implementar una aplicación de comercio electrónico con varias bases de datos. Los archivos centrales, como app.py, organizan el backend integrando diversas fuentes de datos definidas en archivos SQL y JSON, mientras que los archivos de configuración garantizan una implementación sin problemas en los entornos de nube:

• app.py: organiza el backend de Flask y las integraciones de varias bases de datos.
• agentengine.py: Es la lógica principal para inicializar y configurar agentes de Vertex AI.
• .env: Almacena secretos para las conexiones de bases de datos y almacenamiento.
• tools.yaml: Configura MCP Toolbox para operaciones de bases de datos multidb.
• Dockerfile: Define la imagen de contenedor y la configuración del entorno.
• requirements.txt: Enumera las bibliotecas de Python necesarias para el entorno de ejecución de la aplicación.
• tools.yaml: Son los parámetros de configuración de MCP Toolbox.
• Procfile: Especifica los comandos de ejecución de producción para la implementación.
• alloydb_insert_queries.sql: contiene consultas en SQL para datos relacionales.
• product_details_export.json y user_interactions_export.json: Proporciona datos JSON de muestra para la base de datos NoSQL.
• README.md: guía la configuración, la implementación y la comprensión del proyecto.

Flujo de extremo a extremo de la aplicación

• Configuración de AlloyDB: Aprovisiona un clúster de alto rendimiento y usa las secuencias de comandos de SQL proporcionadas para crear la tabla products_core_table con columnas de vectores para los embeddings de imágenes.
• Configuración de MongoDB Atlas: Implementa un clúster en Google Cloud para almacenar atributos de productos fluidos en product_details y registrar flujos de clics en tiempo real en user_interactions.
• Estadísticas de BigQuery: Crea un conjunto de datos para agregar registros de interacciones, lo que permite realizar consultas analíticas complejas que identifican los "5 elementos más populares" en millones de eventos.
• Repositorio de Cloud Storage: Crea un bucket público para alojar imágenes de productos de alta resolución y asegúrate de que se pueda acceder a cada recurso con una URL firmada o pública para el frontend.
• Implementación de MCP Toolbox: Implementarás Toolbox en Cloud Run, lo que lo establecerá como el puente RESTful central que traduce la intención de lenguaje natural en consultas de varias bases de datos.
• Configuración de Tools.yaml: Define tus "herramientas", como get_product_core_data o get_top_5_views, asignando operaciones específicas de SQL y NoSQL a nombres simples que el agente pueda leer.
• Lógica de backend de Flask: Implementa rutas de app.py que interactúen con MCP Toolbox, controlen la coordinación de la recuperación de datos y funcionen como la API para la IU.
• Organización de varios agentes: Configura los agentes del ADK en el código para que razonen según la intención del usuario y seleccionen la "herramienta" adecuada para resolver consultas complejas de venta minorista de varias fuentes.
• Integración de frontend: Crea una interfaz index.html que incluya el catálogo de productos con la función de registro de interacciones, la pestaña Analytics para comprender las estadísticas de rendimiento de los productos y una "pestaña de agente" dedicada que use el chat multiagente del ADK para proporcionar una experiencia de compra conversacional fluida.

Ahora, implementemos la organización y las implementaciones.

8. Configura MCP Toolbox y, luego, impleméntalo en Cloud Run

MCP Toolbox abstrae nuestras múltiples fuentes de datos, lo que permite que nuestra aplicación recupere y escriba datos de manera uniforme.

Instala MCP Toolbox de forma local

Descarga el objeto binario de MCP Toolbox en tu directorio principal y haz que sea ejecutable:

export VERSION=1.15.0
curl -L -o ~/toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x ~/toolbox

Configura tools.yaml

Debes definir las abstracciones para AlloyDB, MongoDB y BigQuery. El archivo tools.yaml le indica a la caja de herramientas de MCP cómo interactuar entre sí.

1. El repositorio ya incluye tools.yaml. Ábrelo:

   cd ~/polyglot-persist-ecommerce
   cloudshell edit tools.yaml
   

2. Reemplaza los marcadores de posición ***** por tus valores:

   Base de datos	Campo	Valor de ejemplo
   AlloyDB/BigQuery	project	YOUR_PROJECT_ID
   AlloyDB	region	us-central1
   AlloyDB	cluster	ecommerce-cluster
   AlloyDB	instance	ecommerce-cluster-primary
   AlloyDB	database	postgres
   AlloyDB	password	alloydb
   AlloyDB	ipType	public (agrega esta línea debajo de alloydb-source si no está allí)
   MongoDB	uri	la cadena de conexión que guardaste antes

3. Apunta las vistas previas de las imágenes a tu bucket:

   sed -i "s/ecommerce-app-images/$BUCKET/g" tools.yaml
   

Prueba la IU de tu herramienta

1. En la terminal de Cloud Shell, ejecuta la caja de herramientas de forma local para entregar la IU:

   ~/toolbox --config tools.yaml --ui --enable-api
   

2. En Cloud Shell, haz clic en Vista previa en la Web > Cambiar puerto, ingresa 5000 y agrega /ui al final de la URL que se abre.

Se muestra la siguiente IU de MCP Toolbox:

Cuando termines, presiona Ctrl+C para detener la caja de herramientas local.

Implementa en Cloud Run

Implementar MCP Toolbox en Cloud Run para que esté disponible como un servicio administrado y seguro que nuestra aplicación pueda usar para consultar las bases de datos Almacenaremos la configuración en Secret Manager para proteger los detalles de conexión sensibles.

1. Sube la configuración de tools.yaml a Google Secret Manager:

   gcloud secrets create tools --data-file=tools.yaml
   

   Si cambias tools.yaml más adelante, sube una versión nueva con lo siguiente:

   gcloud secrets versions add tools --data-file=tools.yaml
   

2. Implementa con la imagen de contenedor pública de MCP Toolbox:

   gcloud run deploy toolbox \
       --image us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION \
       --region us-central1 \
       --service-account ${PROJECT_NUMBER}[e-mail] \
       --set-secrets "/app/tools.yaml=tools:latest" \
       --args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080","--ui","--enable-api" \
       --allow-unauthenticated
   

   --enable-api activa la API de REST que usa la app web.
3. Guarda la URL de Toolbox:

   export TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format='value(status.url)')
   echo $TOOLBOX_URL
   

   Puedes abrir $TOOLBOX_URL/ui en tu navegador para ver las herramientas.

9. Configura la aplicación de comercio electrónico y, luego, impleméntala en Cloud Run

Con nuestras bases de datos en ejecución y la abstracción de MCP Toolbox implementada, podemos ejecutar la aplicación web de Flask.

Para entregar el catálogo de productos, la aplicación de Flask procesa los datos con los siguientes pasos:

1. Recuperar datos principales: Recupera la lista completa de productos de AlloyDB (list_products_core).
2. Recuperar detalles extendidos: Recupera todos los detalles del producto de MongoDB (list_all_product_details).
3. Combinar listas: Concatena las dos listas.
4. Enriquecer con contenido multimedia: Agrega la URL de la imagen de Cloud Storage a cada elemento.

Crea el motor del agente

1. Instala las dependencias:

   cd ~/polyglot-persist-ecommerce
   pip install -r requirements.txt
   

   Nota: Este paso puede tardar varios minutos en resolver e instalar paquetes.
2. Inicializa y registra el agente de IA con Vertex AI Reasoning Engine:

   export REASONING_ENGINE_LOCATION=us-central1
   export APP_NAME=$(python agentengine.py)
   echo $APP_NAME
   

   El resultado será similar al siguiente ejemplo:

   projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856
   

La app lee su configuración de las variables de entorno, que pasas en el comando de implementación que se muestra a continuación, por lo que no necesitas editar .env.

Implementa el frontend en Cloud Run

1. Implementa la aplicación web en Cloud Run para completar la arquitectura:

   gcloud run deploy polyglot --source . \
     --region us-central1 \
     --allow-unauthenticated \
     --set-env-vars="MCP_TOOLBOX_SERVER_URL=$TOOLBOX_URL,GCS_PRODUCT_BUCKET=$BUCKET,FALLBACK_IMAGE_URL=https://storage.googleapis.com/$BUCKET/fallback.jpg,GOOGLE_GENAI_USE_VERTEXAI=TRUE,PROJECT_ID=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global,REASONING_ENGINE_LOCATION=$REASONING_ENGINE_LOCATION,APP_NAME=$APP_NAME,MODEL=gemini-3.5-flash"
   

   La app usa gemini-3.5-flash, que se entrega desde la ubicación global. El motor de agentes permanece en us-central1.

   Si la implementación falla, ejecuta el comando gcloud auth login para autorizarla y, luego, vuelve a ejecutar el comando de implementación.

Tu aplicación ya está disponible. Abre la URL del servicio que proporciona Cloud Run para ver el catálogo de Multidb Ecommerce. La URL será similar a https://polyglot-*********-uc.a.run.app/.

10. Explora la aplicación

1. Haz clic en Catálogo de productos para ver todos los productos.
   
2. Haz clic en el ícono de un producto para ver los detalles del producto. Notarás que las imágenes provienen de Cloud Storage, los detalles del producto se recuperan de MongoDB y el inventario de productos se recupera de AlloyDB.
3. Interactúa con el catálogo de productos para generar vistas y escrituras simuladas que se envían a MongoDB.
4. Haz clic en ETL y Analytics para ver las estadísticas del producto. Notarás que las estadísticas de productos se recuperan de BigQuery.
   
5. Haz clic en la pestaña Agente de IA para interactuar con el agente de IA. Haz preguntas en lenguaje natural, como las siguientes:
   

   I'm planning a high-altitude photography trip.
   Show me some weather-resistant backpacks similar in style to aero glow pro
   but without any leather components. Also, let me know if they are actually in
   stock and if other photographers have complained about the strap durability
   in the reviews.
   

   

Puedes ver que la búsqueda devuelve exactamente lo que pedimos: una mochila sin componentes de cuero, en stock y sin quejas sobre la durabilidad de las correas en las opiniones.

11. Limpia

Para evitar que se apliquen cargos continuos a tu cuenta de Google Cloud, borra los recursos que creaste durante este codelab.

Ejecuta estos comandos de Cloud Shell:

gcloud run services delete toolbox --region us-central1 --quiet
gcloud run services delete polyglot --region us-central1 --quiet
gcloud secrets delete tools --quiet
bq rm -r -f -d $PROJECT_ID:ecommerce_analytics
gcloud storage rm --recursive gs://$BUCKET
gcloud alloydb clusters delete ecommerce-cluster --region us-central1 --force --quiet

De manera opcional, borra la instancia de Agent Engine:

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://us-central1-aiplatform.googleapis.com/v1/$APP_NAME?force=true"

Como alternativa, en la consola de Google Cloud, navega a Vertex AI > Agent Engine y borra la instancia.

De manera opcional, para borrar todo el proyecto de Google Cloud y todos sus recursos, ejecuta el siguiente comando:

gcloud projects delete $PROJECT_ID

Por último, abre MongoDB Atlas en Google Cloud y borra el clúster ecommerce-cluster que creaste para asegurarte de que no haya un uso pendiente del nivel gratuito.

12. ¡Felicitaciones!

¡Felicitaciones! Creaste correctamente una arquitectura de varias bases de datos multinube.

Demostraste cómo MCP Toolbox sirve como el pegamento arquitectónico para una aplicación moderna y especializada. Si asignas la base de datos correcta al trabajo adecuado, lograrás lo siguiente:

• Escrituras de datos flexibles: MongoDB para registros de eventos.
• Coherencia transaccional: AlloyDB para la integridad principal.
• Análisis de alto rendimiento: BigQuery para la inteligencia empresarial.
• Desarrollo unificado: Un solo backend de Python que abstrae toda la complejidad con MCP Toolbox.

Documentos de referencia

Obtén más información sobre los productos relacionados de Google Cloud y explora estos codelabs:

• AlloyDB AI: Comienza a usar embeddings de vectores con AlloyDB AI
• IA de AlloyDB: Incorporaciones multimodales en AlloyDB
• MCP Toolbox: Instala y configura MCP Toolbox para bases de datos en AlloyDB

Para obtener más información sobre los productos que se usan en este codelab, consulta los siguientes vínculos:

• Documentación de AlloyDB para PostgreSQL
• Documentación de MongoDB Atlas en Google Cloud
• Documentación de BigQuery
• Documentación de Cloud Storage
• Documentación de Cloud Run
• Documentación de Cloud Build
• Implementación de MCP Toolbox