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 y stock), catálogos polimórficos "desordenados" (especificaciones de electrónica frente a tallas de indumentaria) y petabytes de registros de comportamiento. Forzar la integración de todos estos elementos en un solo monolito no solo genera deuda técnica, sino que también afecta la experiencia del usuario.

En este codelab, diseñarás un centro políglota que armonice lo siguiente:

• AlloyDB: Tu 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 sin esquema.
• 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 el kit de herramientas de MCP 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 con varios agentes usando el Kit de desarrollo de agentes (ADK). No solo estás creando una barra de búsqueda, sino un cerebro inteligente de venta minorista que comprende el contexto, respeta las restricciones y une la brecha entre los datos sin procesar y la intención humana.

La consulta del usuario imposible

Los agentes de comercio electrónico estándar no logran realizar un razonamiento multidimensional (combinan restricciones negativas, similitud visual y el inventario en tiempo real). Por ejemplo, por lo general, quiero hablar con un sitio de venta minorista como este:

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

Por qué esta búsqueda es "The Agent Killer":

• Similitud visual (AlloyDB + Búsqueda de vectores): "Similar en estilo a AeroGlow Pro" requiere la comparación de la incorporación de imágenes.
• Restricción negativa (MongoDB): "Sin cuero" requiere filtrar a través de atributos flexibles y anidados que no suelen estar en un esquema SQL estándar.
• Inventario en tiempo real (AlloyDB): "En stock" requiere una verificación transaccional en vivo (no un índice de búsqueda desactualizado).
• Síntesis semántica (BigQuery + Multi-Agent): Analizar 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 estamos deteniendo?

Porque no solo buscamos coincidencias para las palabras clave. Usamos 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. Construyámoslo.

Actividades

• Aprovisiona un clúster de AlloyDB para los datos principales del producto
• Configura MongoDB Atlas en Google Cloud para almacenar detalles de productos semiestructurados
• Crea un bucket de Cloud Storage para publicar imágenes de productos
• Implementa MCP Toolbox para bases de datos en Cloud Run para un acceso uniforme a los datos
• Ejecuta procesos de ETL para enviar datos a BigQuery para el 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 esperaba, configúralo:

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

Habilita las API 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 enorme almacén para 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 a tu bucket un nombre único a nivel global (p.ej., ecommerce-app-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 > Usuario de objetos de Storage.
9. Haz clic en Guardar y, luego, en Permitir acceso público para confirmar que el recurso será público.

Sube imágenes de marcador de posición

El archivo BRK2-149-multidb-ecommerce usa imágenes de marcador de posición para brindar la mejor experiencia visual.

1. En Cloud Shell, clona el repositorio next-26-sessions:

   git clone https://github.com/GoogleCloudPlatform/next-26-sessions.git
   

2. Navega a la carpeta UploadImages:

   cd next-26-sessions/BRK2-149-multidb-ecommerce/UploadImages
   

3. En la consola de Google Cloud, navega a Cloud Storage y haz clic en Buckets.
4. Haz clic en el nombre del bucket que acabas de crear.
5. Haz clic en Subir > Subir archivos, selecciona las imágenes de muestra descargadas y haz clic en Abrir.

4. Configura AlloyDB

AlloyDB sirve como la única fuente de información para los datos estructurados, transaccionales y críticos, como los IDs, los nombres, los SKU, los precios y el inventario de los productos. AlloyDB también potencia el agente de IA con capacidades de búsqueda por 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).

Configurar la instancia principal

1. En ID de instancia (Instance ID), ingresa ecommerce-cluster-primary.
2. En Disponibilidad zonal, selecciona Zona única.
3. En Tipo de máquina, elige un tipo de máquina pequeño (p.ej., N2, 4 CPU virtuales, 32 GB de RAM).
4. En Conectividad de IP privada, selecciona Acceso privado a servicios (PSA) y, luego, la red default.Si aún no se configuró 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.
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.

Nota: Asegúrate de anotar tu dirección IP pública (se parece a 34.124.240.26).

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 contraseña que configuraste anteriormente.
6. Haz clic en Autenticar.
7. En la vista del editor, 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 BRK2-149-multidb-ecommerce:

   cd next-26-sessions/BRK2-149-multidb-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 instrucciones 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);
    

Crea 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 de 1,408 dimensiones y se almacenan en la columna img_embeddings.

Antes de generar incorporaciones, debemos otorgar los roles necesarios a la cuenta de servicio de AlloyDB para acceder a Cloud Storage.

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

Otorga los roles de usuario de objetos de almacenamiento y visualizador de objetos de almacenamiento a la cuenta de servicio de AlloyDB para permitirle leer objetos del bucket de Cloud Storage.

1. Navega a IAM y administración.
2. Haz clic en Otorgar acceso.
3. En el campo Principales nuevas, ingresa la búsqueda de la cuenta de servicio de AlloyDB. La cuenta de servicio se verá de la siguiente manera: [e-mail].
4. Haz clic en Selecciona un rol.
5. Busca y selecciona el rol Usuario de objetos de Storage.
6. Haz clic en Agregar otro rol y selecciona el rol Visualizador de objetos de Storage.
7. Haz clic en Agregar otro rol y selecciona el rol Usuario de Vertex AI.
8. Haz clic en Guardar.

Habilitar 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. Para habilitar estas extensiones, ejecuta los siguientes DDL:

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 del editor, 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. Genera embeddings para las imágenes y almacénalos en la columna img_embeddings.

   UPDATE products_core_table
   SET img_embeddings = google_ml.image_embedding(
       model_id => 'multimodalembedding@001',
       image => 'gs://<STORAGE_BUCKET_NAME>/' || sku || '.jpg',
       mimetype => 'image/jpeg')
   WHERE sku IN (
       SELECT
       sku
       FROM
       products_core_table
       WHERE
       img_embeddings IS NULL
       AND sku IS NOT NULL
       LIMIT 10
   );
   

   Reemplaza por el nombre de tu bucket de Cloud Storage.
3. Repite la consulta anterior al menos 5 veces para generar incorporaciones de imágenes para todo el conjunto, ya que Studio tiene una limitación de 5 minutos. Si esta consulta agota el tiempo de espera, cambia LIMIT por 5 y vuelve a ejecutar la consulta diez veces. Este paso puede tardar unos minutos en completarse.

5. Configura MongoDB Atlas en Google Cloud

MongoDB almacena detalles de productos enriquecidos y semiestructurados, y datos flexibles del comportamiento del usuario (como clics y vistas).\

Crea un clúster de MongoDB

1. Ve a MongoDB Atlas en Google Cloud y selecciona una cuenta de nivel gratuito.
2. Selecciona el nivel de clúster Gratis y, luego, ingresa un nombre para el clúster, por ejemplo, ecommerce-cluster.
3. Selecciona Google Cloud como proveedor y asegúrate de que la región coincida con tu región de Google Cloud (p.ej., us-central1).
4. Haz clic en Create Deployment.
5. Haz clic en Cerrar.

Configura el acceso a la red

1. En la consola de Atlas, ve a Database & Network Access.
2. Haz clic en Lista de acceso por IP.
3. Haz clic en Agregar dirección IP.
4. Agrega 0.0.0.0/0, que permite el acceso desde cualquier lugar.
5. Haz clic en Confirmar.

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.

Crea un usuario de base de datos

1. En la consola de Atlas, ve a Database & Network Access.
2. Haz clic en Usuarios de la base de datos.
3. Haz clic en Agregar usuario nuevo de la base de datos.
4. Selecciona Contraseña como método de autenticación.
5. Ingresa el nombre de usuario como store-user y la contraseña como storeuser.
6. Haz clic en Agregar rol integrado y selecciona Leer y escribir en cualquier base de datos.
7. Haz clic en Agregar usuario.

Obtén la cadena de conexión

1. Ve a Base de datos > Clústeres > Conectar.
2. En Connect your application, haz clic en Drivers.
3. Copia la cadena de conexión que se muestra en Agrega tu cadena de conexión al código de tu aplicación. La cadena se ve de la siguiente manera:

   mongodb+srv://store-user:<db_password>@ecommerce-cluster.g8vaekh.mongodb.net/?appName=ecommerce-cluster
   

   Reemplaza db_password por tu contraseña de MongoDB. En este codelab, es storeuser.

Guarda esta cadena de conexión. La usarás más adelante para la variable de entorno MONGODB_CONNECTION_STRING.

Crea una base de datos y una colección

1. En la consola de Atlas, ve a Database > Clusters > Browse Collections.
2. Haz clic en Crear base de datos y, luego, ingresa los detalles:
   • Nombre de la base de datos: ecommerce_db
   • Nombre de la colección: product_details_collection
3. Haz clic en Crear base de datos.
4. En el Explorador de datos, selecciona el nombre de la colección.
5. Haz clic en el ícono Agregar datos (+) y, luego, en Insertar documento.
6. Copia el contenido JSON de product_details_export.json y pégalo en el diálogo del editor Insert Document.
7. Haz clic en Insertar para insertar el array de documentos y verificar que se agregaron 192 documentos.
8. En el Explorador de datos, haz clic en Crear colección (+) junto a la base de datos ecommerce_db.
9. Ingresa user_interactions_collection como nombre de la colección y haz clic en Crear colección.
10. En el Explorador de datos, selecciona la colección user_interactions_collection.
11. Haz clic en el ícono Agregar datos (+) y, luego, en Insertar documento.
12. Copia el contenido JSON de user_interactions_export.json y pégalo en el diálogo del editor Insert Document.
13. Haz clic en Insertar documento.

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 de tu proyecto en el panel Explorador, haz clic en el menú de tres puntos y selecciona Crear conjunto de datos.
3. Ingresa ecommerce_analytics para el ID del conjunto de datos.
4. 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 instrucción de SQL para crear la tabla de resumen que vincula a los usuarios con las interacciones de 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 para MCP Toolbox

Otorga roles a la cuenta de servicio de Compute que se usa para nuestra Caja de herramientas. Esto se hace para permitir que la caja de herramientas de MCP acceda a BigQuery, Secret Manager y otros servicios en la nube.

Para encontrar el número de proyecto, en la consola de Google Cloud, haz clic en Descripción general de Cloud > Panel. Anota el número de proyecto que se indica en la tarjeta Información del proyecto.

Para otorgar roles, completa los siguientes pasos:

1. Navega a IAM y administración.
2. Haz clic en Otorgar acceso.
3. En el campo Principales nuevas, ingresa la cuenta de servicio predeterminada de Compute llamada [e-mail]. Reemplaza YOUR_PROJECT_NUMBER por tu número de proyecto de Google Cloud.
4. Haz clic en Selecciona un rol.
5. Busca y selecciona el rol Editor de datos de BigQuery.
6. Haz clic en Agregar otro rol y selecciona el rol Usuario de trabajo de BigQuery.
7. Haz clic en Agregar otro rol y selecciona el rol Descriptor de acceso a secretos de Secret Manager.
8. Haz clic en Agregar otro rol y selecciona el rol de Editor.
9. Haz clic en Guardar.

7. Comprende la aplicación de extremo a extremo

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

Comprende la estructura del directorio

En la siguiente sección, clonarás el repositorio BRK2-149-multidb-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. Están presentes los siguientes directorios de alto nivel:

• UploadImages: Almacena recursos de imagen y se usa 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).
• toolbox-implementation: Almacena detalles de configuración y de implementación de la caja de herramientas del Protocolo de contexto del modelo (MCP), lo que facilita las interacciones con bases de datos multidb a través de herramientas predefinidas.

Los archivos de este repositorio funcionan en conjunto para compilar, configurar e implementar una aplicación de comercio electrónico multidb. 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 entornos de nube:

• app.py: Coordina el backend de Flask y las integraciones de varias bases de datos.
• agentengine.py: Es la lógica principal para inicializar y configurar los 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 del contenedor y la configuración del entorno.
• requirements.txt: Enumera las bibliotecas de Python necesarias para el tiempo de ejecución de la aplicación.
• tools.yaml: Son configuraciones para 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: Proporcionan 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: Provisiona 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.
• BigQuery Analytics: Crea un conjunto de datos para agregar registros de interacción, lo que permite realizar consultas analíticas complejas que identifican los "5 principales" elementos de tendencia 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 a través de una URL firmada o pública para el frontend.
• Implementación de MCP Toolbox: Implementa Toolbox en Cloud Run y establécela como el puente central de RESTful que traduce la intención en 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, que asignan operaciones específicas de SQL y NoSQL a nombres simples y legibles para el agente.
• Lógica de backend de Flask: Implementa rutas de app.py que interactúan con el kit de herramientas de MCP, controlando la coordinación de la recuperación de datos y sirviendo como la API para la IU.
• Organización de varios agentes: Configura los agentes del ADK dentro del código para razonar sobre la intención del usuario y seleccionar la "Herramienta" adecuada para resolver consultas complejas de venta minorista de múltiples 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 brindar una experiencia de compra conversacional fluida.

Ahora, implementemos la organización y las implementaciones.

8. Configura MCP Toolbox y realiza la implementación 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

1. En Cloud Shell, navega a la carpeta toolbox-implementation:

   cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation
   

2. Descarga el objeto binario de MCP Toolbox y haz que sea ejecutable:

   export VERSION=0.29.0
   curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/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. Crea y edita el archivo tools.yaml con el editor integrado:

   cloudshell edit tools.yaml
   

   El archivo tools.yaml completo se puede encontrar en el repositorio de GitHub. Copia su contenido en el nuevo archivo tools.yaml.
2. Actualiza el host, el usuario, las contraseñas, los IDs del proyecto y las cadenas de conexión para que coincidan con la infraestructura que aprovisionaste en los pasos anteriores:

   Base de datos	Campo	Valor de ejemplo
   AlloyDB/BigQuery	project_id	YOUR_PROJECT_ID
   AlloyDB	region	us-central1
   AlloyDB	cluster	ecommerce-cluster
   AlloyDB	instance	ecommerce-cluster-primary
   AlloyDB	database	postgres
   AlloyDB	password	alloydb
   MongoDB	connection_string	mongodb+srv://store-user:[e-mail]

Otorga roles a la cuenta de servicio de Compute para MCP Toolbox

Otorga roles a la cuenta de servicio de Compute que se usa para nuestra Caja de herramientas. Esto se hace para permitir que MCP Toolbox acceda a AlloyDB.

1. Navega a IAM y administración.
2. Haz clic en Otorgar acceso.
3. En el campo Principales nuevas, ingresa la cuenta de servicio predeterminada de Compute llamada [e-mail]. Reemplaza YOUR_PROJECT_NUMBER por tu número de proyecto de Google Cloud.

   Número de proyecto: Para encontrar el número de proyecto, en la consola de Google Cloud, haz clic en Descripción general de Cloud > Panel. Anota el número de proyecto que se indica en la tarjeta Información del proyecto.

4. Haz clic en Selecciona un rol.
5. Busca y selecciona el rol Editor de datos de BigQuery.
6. Haz clic en Agregar otro rol y selecciona el rol Cliente de AlloyDB.
7. Haz clic en Agregar otro rol y selecciona el rol Consumidor de Service Usage.
8. Haz clic en Agregar otro rol y selecciona el rol Visualizador de objetos de Storage.
9. Haz clic en Guardar.

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 --ui
   

2. Abre la vista previa en la Web en Cloud Shell en el puerto 5000 y navega a la página de herramientas. Por ejemplo, según la URL de tu sesión, puedes verla en https://5000-cs-71152278760-default.cs-asia-southeast1-cash.cloudshell.dev/ui.

Cómo acceder a la IU de MCP en Cloud Shell: Cloud Shell expone puertos locales con la función de vista previa en la Web. En lugar de abrir localhost:8080, debes usar la URL de vista previa en la Web y agregar /ui, por ejemplo: https://5000-cs-.../ui?authuser=0. Sin esto, solo se muestra un mensaje simple de "Hello World" en lugar del panel de IU cargado.

Se muestra la siguiente IU de MCP Toolbox:

Implementa en Cloud Run

Implementa MCP Toolbox en Cloud Run para que esté disponible como un servicio seguro y administrado 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. Abre una nueva sesión de Cloud Shell.
2. Navega a la carpeta toolbox-implementation:

   cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation
   

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

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

   Nota: Para agregar una versión nueva al secreto existente, usa el siguiente comando:

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

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

   export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:0.29.0
   export PROJECT_ID=$(gcloud config get-value project)
   
   gcloud run deploy toolbox \
       --image $IMAGE \
       --region us-central1 \
       --service-account $(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")[e-mail] \
       --set-secrets "/app/tools.yaml=tools:latest" \
       --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--ui" \
       --allow-unauthenticated
   

5. Una vez implementado, anota la URL del servicio de Cloud Run proporcionada. Debería verse como https://toolbox-*********-uc.a.run.app/ui.

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 publicar el catálogo de productos, la aplicación de Flask procesa los datos siguiendo estos 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. Enrich with media: Agrega la URL de la imagen de Cloud Storage a cada elemento.

Genera la ruta de acceso de la aplicación del motor de inferencia

Para inicializar y registrar un agente de IA con el motor de inferencia de Vertex AI de Google Cloud, ejecuta el siguiente comando:

1. En la terminal de Cloud Shell, navega a la carpeta BRK2-149-multidb-ecommerce.

   cd next-26-sessions/BRK2-149-multidb-ecommerce
   

2. Ejecuta requirements.txt para instalar las dependencias.

   pip install -r requirements.txt
   

3. Ejecuta la secuencia de comandos agentengine.py para generar la ruta de acceso a la aplicación de Reasoning Engine:

   python agentengine.py
   

El resultado será similar al siguiente ejemplo:

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

Configura las variables de entorno

1. Crea un archivo .env y edítalo:

   cloudshell edit .env
   

2. Reemplaza los valores por tus conexiones de base de datos específicas y la nueva URL de Cloud Run Toolbox:

   # 1. MongoDB Connection String
   MONGODB_CONNECTION_STRING="mongodb+srv://<db_user>:<db_password>@cluster0.mongodb.net"
   
   # 2. MCP Toolbox Server Location
   # Must match the address where you run the toolbox server
   MCP_TOOLBOX_SERVER_URL="https://toolbox-*********-uc.a.run.app"
   
   # 3. Google Cloud Storage Bucket Name
   GCS_PRODUCT_BUCKET="ecommerce-app-images"
   
   # 4. Fallback image URL
   FALLBACK_IMAGE_URL="https://storage.googleapis.com/ecommerce-media-bold-circuit-492711-n9/fallback.jpg"
   
   # 5. Google Gen AI Vertex AI flag
   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   
   # 6. Project ID
   PROJECT_ID=codelab-project-491117
   
   # 7. Google Cloud Location of AlloyDB, BigQuery databases
   GOOGLE_CLOUD_LOCATION=us-central1
   
   # 8. Reasoning engine application path
   APP_NAME=projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856
   
   # 9. Model ID
   MODEL=gemini-1.5-flash-lite
   

   Es posible que notes que no todas las imágenes se cargan de inmediato; algunos vínculos podrían faltar o apuntar de forma incorrecta según cómo se asignen las propiedades a los SKU de productos en el conjunto de datos de la aplicación clonada. Verifica las políticas de acceso público de tu bucket de GCS y asegúrate de que los nombres de los archivos se asignen correctamente.

Implementa el frontend en Cloud Run

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

   gcloud run deploy polyglot --source . --platform managed \
     --region us-central1 \
     --allow-unauthenticated \
     --set-env-vars \
     MONGODB_CONNECTION_STRING="<MONGODB_CONNECTION_STRING>", \
     MCP_TOOLBOX_SERVER_URL="<MCP_TOOLBOX_SERVER_URL>", \
     GCS_PRODUCT_BUCKET="<GCS_PRODUCT_BUCKET>", \
     FALLBACK_IMAGE_URL="<FALLBACK_IMAGE_URL>", \
     GOOGLE_GENAI_USE_VERTEXAI=TRUE, \
     PROJECT_ID="YOUR_PROJECT_ID", \
     GOOGLE_CLOUD_LOCATION=us-central1, \
     APP_NAME="<YOUR_REASONING_ENGINE_APP_PATH>", \
     MODEL="gemini-1.5-flash-lite"
   

   Reemplaza los siguientes valores:
   • YOUR_PROJECT_ID: Es el ID de tu proyecto de Google Cloud.
   • YOUR_REASONING_ENGINE_APP_PATH: Es el resultado de ejecutar python agentengine.py, por ejemplo, projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856.
   • MCP_TOOLBOX_SERVER_URL: Es la URL de tu servidor de la caja de herramientas de MCP, por ejemplo, https://toolbox-*********-uc.a.run.app.
   • GCS_PRODUCT_BUCKET: Es el nombre de tu bucket de Google Cloud Storage, por ejemplo, ecommerce-app-images.
   • MONGODB_CONNECTION_STRING: Es la cadena de conexión de tu base de datos de MongoDB, por ejemplo, mongodb+srv://store-user:[e-mail].
   • FALLBACK_IMAGE_URL: URL de la imagen de resguardo, por ejemplo, https://storage.googleapis.com/ecommerce-app-images/fallback.jpg

   Si falla la implementación, 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 comercio electrónico de Multidb. 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 sus detalles. Notarás que las imágenes provienen de Cloud Storage, los detalles del producto se recuperan de MongoDB y el inventario del producto 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. Verás que las estadísticas del producto 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 a tu cuenta de Google Cloud, borra los recursos que creaste durante este codelab.

Ejecuta los siguientes comandos de Cloud Shell:

gcloud run services delete toolbox --region us-central1 --quiet
gcloud run services delete multi-db-app --region us-central1 --quiet
bq rm -r -f -d $PROJECT_ID:ecommerce_analytics
gcloud storage rm --recursive gs://ecommerce-app-images
gcloud alloydb clusters delete ecommerce-cluster --region us-central1 --force --quiet

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 Cluster0 que creaste para asegurarte de que no haya uso del nivel gratuito sin asignar.

12. ¡Felicitaciones!

¡Felicitaciones! Creaste correctamente una arquitectura de Multidb en varias nubes.

Demostraste cómo la caja de herramientas de MCP sirve como nexo arquitectónico para una aplicación moderna y especializada. Al hacer coincidir la base de datos correcta con el trabajo adecuado, lograste lo siguiente:

• Escrituras de datos flexibles: MongoDB para registros de eventos.
• Coherencia transaccional: AlloyDB para la integridad principal.
• High-Performance Analytics: BigQuery para la inteligencia empresarial
• Desarrollo unificado: Un solo backend de Python que abstrae toda la complejidad con el kit de herramientas de MCP.

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 recursos:

• 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 la caja de herramientas del MCP