Crea un catalogo e-commerce intelligente con la persistenza multibase di dati

1. Introduzione

Nel retail moderno, i dati costituiscono un ecosistema diversificato e in espansione. Disponi di dati transazionali solidi (prezzi e inventario), cataloghi polimorfici "disordinati" (specifiche di elettronica rispetto alle taglie di abbigliamento) e petabyte di log comportamentali. Forzare questi elementi in un unico monolite non solo crea un debito tecnico, ma distrugge l'esperienza utente.

In questo codelab, progetterai un sistema poliglotta che armonizza:

• AlloyDB: la tua base transazionale per la coerenza ad alta velocità e gli embedding delle immagini.
• MongoDB Atlas su Google Cloud: il tuo livello di catalogo flessibile e indipendente dallo schema.
• Cloud Storage: il tuo cervello analitico per la previsione delle tendenze in tempo reale.
• BigQuery: il tuo data warehouse digitale ad alta risoluzione.

La "formula magica"? Utilizzerai MCP Toolbox for Databases per orchestrare e unificare in modo intelligente le origini dati in esecuzione su Cloud Run come bridge semantico, quindi eseguirai il deployment di un'app di chat multi-agente utilizzando Agent Development Kit (ADK). Non stai solo creando una barra di ricerca, ma un cervello intelligente per la vendita al dettaglio che comprende il contesto, rispetta i vincoli e colma il divario tra i dati non elaborati e l'intento umano.

La query utente impossibile

Gli agenti di e-commerce standard non riescono a eseguire un ragionamento multidimensionale (combinando vincoli negativi, somiglianza visiva e inventario in tempo reale). Ad esempio, in genere voglio parlare con un sito di vendita al dettaglio in questo modo:

"Ciao, sto pianificando un viaggio fotografico ad alta quota. Mostrami alcuni zaini resistenti agli agenti atmosferici simili nello stile ad "AeroGlow Pro", ma senza componenti in pelle. Inoltre, fammi sapere se sono effettivamente disponibili e se altri fotografi si sono lamentati della durata della cinghia nelle recensioni."

Perché questa query è "The Agent Killer":

• Somiglianza visiva (AlloyDB + Vector Search): "Stile simile ad AeroGlow Pro" richiede il confronto degli embedding delle immagini.
• Vincolo negativo (MongoDB): "Senza pelle" richiede l'applicazione di filtri tramite attributi nidificati flessibili che di solito non sono presenti in uno schema SQL standard.
• Inventario in tempo reale (AlloyDB): "Effettivamente disponibile" richiede un controllo transazionale in tempo reale (non un indice della Ricerca obsoleto).
• Sintesi semantica (BigQuery + multi-agente): l'analisi delle recensioni per "durabilità del cinturino" richiede che l'agente riassuma al volo il feedback non strutturato di BigQuery.

La maggior parte dei bot di vendita al dettaglio vedrebbe solo "zaino" e "pelle" e mostrerebbe 10 zaini in pelle. Come facciamo a impedirlo?

Perché non ci limitiamo a trovare corrispondenze tra le parole chiave. Utilizziamo MCP Toolbox per consentire ai nostri agenti di "ragionare" su tutte queste fonti, ovvero la verità transazionale in AlloyDB e gli attributi flessibili in MongoDB, contemporaneamente. Creiamolo.

In questo lab proverai a:

• Esegui il provisioning di un cluster AlloyDB per i dati di prodotto principali
• Configura MongoDB Atlas su Google Cloud per archiviare i dettagli dei prodotti semistrutturati
• Crea un bucket Cloud Storage per pubblicare le immagini dei prodotti
• Esegui il deployment di MCP Toolbox for Databases in Cloud Run per un accesso uniforme ai dati
• Eseguire processi ETL per inviare i dati a BigQuery per l'analisi
• Conversa con un agente AI in linguaggio naturale.

Prerequisiti

• Un browser web come Chrome
• Un progetto cloud Google Cloud con la fatturazione abilitata
• Un account MongoDB Atlas su Google Cloud senza costi

2. Prima di iniziare

Crea un progetto Google Cloud

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Avvia Cloud Shell

Cloud Shell è un ambiente a riga di comando in esecuzione in Google Cloud in cui sono precaricati gli strumenti necessari.

1. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
2. Una volta eseguita la connessione a Cloud Shell, verifica l'autenticazione:

   gcloud auth list
   

3. Verifica che il progetto sia configurato:

   gcloud config get project
   

4. Se il progetto non è impostato come previsto, impostalo:

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

Imposta variabili

In Cloud Shell, imposta le variabili di ambiente per l'ID e il numero del progetto:

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

Se la sessione di Cloud Shell si disconnette, esegui di nuovo questi comandi export (e gli altri che aggiungerai in seguito in questo codelab).

Abilita le API richieste

Esegui questo comando per abilitare tutte le API richieste:

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 funge da enorme archivio per asset multimediali non strutturati, come le immagini dei prodotti.

1. Nella console Google Cloud, vai a Cloud Storage e fai clic su Crea bucket.
2. Assegna al bucket un nome univoco globale, ad esempio -ecommerce-images.
3. Fai clic su Crea.
4. Per consentire all'applicazione demo di accedere alle immagini senza autenticazione, deseleziona l'opzione Applica la prevenzione dell'accesso pubblico in questo bucket e fai clic su Conferma.
5. Vai alla scheda Autorizzazioni.
6. In Autorizzazioni, fai clic su Concedi l'accesso.
7. In Nuove entità, inserisci allUsers.
8. In Seleziona un ruolo, scegli Cloud Storage > Storage Object Viewer.
9. Fai clic su Salva, quindi su Consenti accesso pubblico per confermare che stai rendendo pubblica la risorsa.
10. In Cloud Shell, salva il nome del bucket in una variabile:

    export BUCKET=<your-bucket-name>
    

    Sostituisci con il nome del bucket che hai creato.

Carica immagini segnaposto

Il progetto utilizza immagini segnaposto per la migliore esperienza visiva.

1. In Cloud Shell, clona il repository:

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

2. Vai alla cartella UploadImages:

   cd polyglot-persist-ecommerce/UploadImages
   

3. Carica le immagini di esempio nel tuo bucket:

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

4. Configura AlloyDB

AlloyDB funge da Single Source Of Truth per i dati strutturati, transazionali e critici, come ID prodotto, nomi, SKU, prezzi e inventario. AlloyDB fornisce inoltre all'agente AI funzionalità di ricerca per somiglianza per i suggerimenti e le query in linguaggio naturale.

Per configurare rapidamente un cluster, un'istanza e una rete per il tuo ambiente di sviluppo utilizzando un'interfaccia web, segui i passaggi descritti in questo codelab.

Esegui il provisioning di un cluster AlloyDB

1. Nella console Google Cloud, vai ad AlloyDB per PostgreSQL.
2. Fai clic su Crea cluster.
3. In ID cluster, inserisci ecommerce-cluster.
4. Imposta una password efficace per l'utente postgres. A scopo di apprendimento, puoi utilizzare alloydb.
5. Per Versione database, mantieni l'impostazione predefinita.
6. In Regione, seleziona us-central1 (o la regione che preferisci).

Configura l'istanza principale

1. In ID istanza, inserisci ecommerce-cluster-primary.
2. In Disponibilità a livello di zona, seleziona Zona singola.
3. Per Serie di macchine, seleziona N2 e per Tipo di macchina, seleziona 4 vCPU, 32 GB.
4. In Connettività IP privato, seleziona Accesso privato ai servizi (PSA) e seleziona la rete default.Se la rete predefinita non è già impostata, fai clic su Conferma configurazione di rete per crearne una.
5. In Connettività IP pubblico, seleziona la casella di controllo Abilita IP pubblico per consentire alla toolbox MCP di connettersi correttamente in questo codelab. La console attiva automaticamente il flag password.enforce_complexity, richiesto da AlloyDB per l'IP pubblico.
6. In Reti esterne autorizzate, inserisci 0.0.0.0/0. Seleziona la casella di controllo Sono consapevole dei rischi e fai clic su Salva.
7. Fai clic su Crea cluster.

La creazione del cluster e dell'istanza richiede fino a 10 minuti.

Inizializza il database

1. Fai clic su AlloyDB Studio nel menu di navigazione a sinistra.
2. Nel menu a discesa Database, seleziona postgres.
3. Seleziona Autenticazione integrata per accedere al database.
4. In Nome utente, utilizza l'utente postgres.
5. In Password, inserisci la password che hai impostato in precedenza.
6. Fai clic su Authenticate (Autentica).
7. Nella visualizzazione dell'editor, apri una nuova scheda della query senza titolo.
8. Copia il seguente DDL e fai clic su Esegui:

   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. In Cloud Shell, vai alla cartella root del progetto:

   cd ~/polyglot-persist-ecommerce
   

10. Apri il file alloydb_insert_queries.sql in Cloud Shell e copia le query di inserimento.

    cat alloydb_insert_queries.sql
    

11. In una nuova scheda della query senza titolo, incolla solo le istruzioni INSERT e fai clic su Esegui.
12. In una nuova scheda Query senza titolo, copia il seguente DDL e fai clic su Esegui per creare un indice nella tabella products_core_table:

    CREATE INDEX idx_products_core_sku ON products_core_table(sku);
    

Crea embedding delle immagini per consentire all'agente AI di recuperare prodotti simili

L'integrazione dell'agente AI utilizza gli embedding delle immagini per recuperare prodotti simili. Gli embedding vengono generati utilizzando il modello multimodalembedding@001 e archiviati nel database AlloyDB. Gli embedding sono vettori di 1408 dimensioni e sono archiviati nella colonna img_embeddings.

Prima di poter generare gli embedding, dobbiamo concedere i ruoli richiesti al service account AlloyDB per accedere a Cloud Storage.

Concedi i ruoli al service account AlloyDB per accedere a Cloud Storage

Concedi al service account AlloyDB i ruoli necessari per leggere le immagini da Cloud Storage e generare embedding di 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

Attiva le estensioni

Per creare questa app, utilizzeremo le estensioni pgvector e google_ml_integration. L'estensione pgvector consente di archiviare e cercare vector embedding. L'estensione google_ml_integration fornisce funzioni che utilizzi per accedere agli endpoint di previsione di Vertex AI per ottenere previsioni in SQL. Abilita queste estensioni eseguendo i seguenti DDL:

1. Nella console Google Cloud, vai ad AlloyDB per PostgreSQL.
2. Fai clic su AlloyDB Studio nel menu di navigazione a sinistra.
3. Nella visualizzazione dell'editor, apri una nuova scheda della query senza titolo.
4. Copia il seguente DDL e fai clic su Esegui:

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

Inizializza il database con gli embedding

1. Aggiungi la colonna img_embeddings a products_core_table.

   ALTER TABLE products_core_table
   ADD COLUMN img_embeddings vector(1408);
   

2. Stampa la query sugli embedding con il nome del bucket compilato:

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

3. Copia l'output, incollalo in una nuova scheda di query di AlloyDB Studio e fai clic su Esegui. Ci vorrà circa un minuto. Se si verifica un timeout, eseguilo di nuovo. I prodotti che hanno già embedding vengono ignorati.

   Lo script elabora solo i prodotti che hanno un'immagine in UploadImages/.

5. Configura MongoDB Atlas su Google Cloud

MongoDB archivia dettagli dei prodotti semistrutturati e dettagliati e dati flessibili sul comportamento degli utenti (come clic e visualizzazioni).

Crea un cluster MongoDB

1. Accedi a MongoDB Atlas (se necessario, crea un account senza costi).
2. In Esegui il deployment del cluster, seleziona Senza costi. (Atlas preseleziona un livello a pagamento; assicurati che sia selezionato Free.)
3. In Provider, seleziona Google Cloud e in Regione, seleziona Iowa (us-central1).
4. In Nome, inserisci ecommerce-cluster e deseleziona Precarica set di dati di esempio.
5. Fai clic su Crea deployment.

Consenti l'accesso e crea un utente del database

Atlas apre la finestra di dialogo Connect to ecommerce-cluster (Connettiti al cluster di e-commerce).

1. Fai clic su Aggiungi un indirizzo IP diverso, inserisci 0.0.0.0/0 e aggiungilo.

   L'utilizzo di 0.0.0.0/0 consente l'accesso da qualsiasi indirizzo IP. Questo è accettabile per una demo temporanea, ma in produzione dovresti limitare l'accesso a intervalli IP specifici.

2. Inserisci store-user in Nome utente e storeuser in Password, quindi fai clic su Crea utente database.
3. Fai clic su Scegli un metodo di connessione, quindi su Driver e librerie client.
4. Nella sezione Utilizza questa stringa di connessione nella tua applicazione, copia la stringa di connessione. Sembra mongodb+srv://store-user:@ecommerce-cluster.xxxxx.mongodb.net/. Sostituisci con storeuser e salva la stringa, che utilizzerai in tools.yaml.

Se hai chiuso la finestra di dialogo, apri Database > Cluster e fai clic su Connetti in ecommerce-cluster.

Crea database e raccolta

1. Nel menu di navigazione a sinistra, fai clic su Esplora dati, poi su Crea database e inserisci i dettagli:
   • Nome database: ecommerce_db
   • Nome raccolta: product_details_collection
2. Fai clic su Crea database.
3. In Esplora dati, seleziona il nome della raccolta.
4. Fai clic sull'icona Aggiungi dati (+), quindi su Inserisci documento.
5. Copia i contenuti JSON da product_details_export.json e incollali nella finestra di dialogo dell'editor Inserisci documento.
6. Atlas mostra un banner che offre di convertire il testo in sintassi shell. Fai clic su CONVERTI, poi su Inserisci. Verifica che siano stati aggiunti 192 documenti.
7. In Esplora dati, fai clic su Crea raccolta (+) accanto al database ecommerce_db.
8. Inserisci user_interactions_collection come nome della raccolta e fai clic su Crea raccolta.
9. In Esplora dati, seleziona la raccolta user_interactions_collection.
10. Fai clic sull'icona Aggiungi dati (+), quindi su Inserisci documento.
11. Copia i contenuti JSON da user_interactions_export.json e incollali nella finestra di dialogo dell'editor Inserisci documento.
12. Atlas mostra un banner che offre di convertire il testo in sintassi shell. Fai clic su CONVERTI, poi su Inserisci. Verifica che siano stati aggiunti 211 documenti.

6. Configura BigQuery

BigQuery aggrega e analizza il comportamento storico degli utenti per generare report e suggerimenti intelligenti.

Crea il set di dati

1. Nella console Google Cloud, vai a BigQuery.
2. Accanto all'ID progetto nel riquadro Explorer, fai clic sul menu con tre puntini e seleziona Crea set di dati.
3. Inserisci ecommerce_analytics per ID set di dati.
4. Per Località dei dati, seleziona US (multiple regions) (la configurazione tools.yaml prevede la località US).
5. Fai clic su Crea set di dati.

Crea la tabella di Analytics

1. Apri una nuova query nell'area di lavoro di BigQuery.
2. Esegui la seguente istruzione SQL per creare la tabella di riepilogo che collega gli utenti alle interazioni con i prodotti:

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

Concedi i ruoli al service account Compute

Concedi al service account Compute predefinito i ruoli necessari per MCP Toolbox e l'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

In alternativa, nella console vai a IAM e amministrazione > IAM, fai clic su Concedi l'accesso, inserisci il service account e aggiungi gli stessi ruoli.

7. Comprendi l'applicazione end-to-end

Per scoprire come interagiscono i vari componenti, creeremo un'applicazione di e-commerce che utilizza più database e servizi. L'applicazione è creata con un backend Python (Flask) e integra più servizi e database Google Cloud.

Comprendi la struttura della directory

Nella sezione successiva, clonerai il repository polyglot-persist-ecommerce e lo utilizzerai per eseguire l'applicazione localmente. Dopo aver testato l'applicazione localmente, eseguiremo il deployment di MCP Toolbox e dell'applicazione su Cloud Run.

Esplora i file scaricati in questa directory. Sono presenti le seguenti directory di primo livello:

• UploadImages: archivia gli asset immagine, utilizzati principalmente per la documentazione o i contenuti visivi del catalogo dei prodotti di e-commerce.
• static: archivia gli asset web statici dell'applicazione, come i file CSS e JavaScript, utilizzati per definire lo stile e aggiungere interattività all'interfaccia utente ( origine).
• templates: archivia i template HTML (probabilmente Jinja2 per Flask) utilizzati dall'applicazione Python per eseguire il rendering dinamico delle pagine web per il catalogo di e-commerce ( origine).

I file in questo repository interagiscono per creare, configurare ed eseguire il deployment di un'applicazione di e-commerce multidb. I file centrali come app.py orchestrano il backend integrando diverse origini dati definite nei file SQL e JSON, mentre i file di configurazione garantiscono un deployment senza problemi negli ambienti cloud:

• app.py: orchestra il backend Flask e le integrazioni di più database.
• agentengine.py: logica di base per l'inizializzazione e la configurazione degli agenti Vertex AI.
• .env: archivia i secret per le connessioni al database e allo spazio di archiviazione.
• tools.yaml: configura MCP Toolbox per le operazioni su più database.
• Dockerfile: definisce l'immagine container e la configurazione dell'ambiente.
• requirements.txt: elenca le librerie Python necessarie per il runtime dell'applicazione.
• tools.yaml: configurazioni per MCP Toolbox.
• Procfile: specifica i comandi di esecuzione di produzione per il deployment.
• alloydb_insert_queries.sql: contiene query SQL per i dati relazionali.
• product_details_export.json e user_interactions_export.json: forniscono dati JSON di esempio per il database NoSQL.
• README.md: guida alla configurazione, al deployment e alla comprensione del progetto.

Flusso end-to-end dell'applicazione

• Configurazione di AlloyDB: esegui il provisioning di un cluster ad alte prestazioni e utilizza gli script SQL forniti per creare la tabella products_core_table con colonne vettoriali per gli embedding delle immagini.
• Configurazione di MongoDB Atlas: esegui il deployment di un cluster su Google Cloud per archiviare gli attributi dei prodotti fluidi in product_details e registrare i clickstream in tempo reale in user_interactions.
• Analisi di BigQuery: crea un set di dati per aggregare i log delle interazioni, consentendo query analitiche complesse che identificano i "primi 5" elementi di tendenza in milioni di eventi.
• Repository Cloud Storage: crea un bucket pubblico per ospitare immagini dei prodotti ad alta risoluzione, assicurandoti che ogni asset sia accessibile utilizzando un URL firmato o pubblico per il frontend.
• Deployment di MCP Toolbox: esegui il deployment di Toolbox su Cloud Run, stabilendolo come bridge RESTful centrale che traduce l'intent del linguaggio naturale in query multi-database.
• Configurazione di Tools.yaml: definisci i tuoi "strumenti", come get_product_core_data o get_top_5_views, mappando operazioni SQL e NoSQL specifiche a nomi semplici leggibili dall'agente.
• Logica di backend Flask: implementa le route app.py che si interfacciano con MCP Toolbox, gestendo il coordinamento del recupero dei dati e fungendo da API per l'interfaccia utente.
• Orchestrazione multi-agente: configura gli agenti ADK all'interno del codice per ragionare in base allo user intent, selezionando lo "strumento" giusto per risolvere query di vendita al dettaglio complesse e provenienti da più fonti.
• Integrazione del frontend: crea un'interfaccia index.html con il catalogo dei prodotti e la funzionalità di registrazione delle interazioni, la scheda Analytics per comprendere l'analisi del rendimento dei prodotti e una "scheda Agente" dedicata che utilizza la chat multi-agente ADK per offrire un'esperienza di acquisto conversazionale fluida.

Ora implementiamo l'orchestrazione e i deployment.

8. Configura MCP Toolbox ed esegui il deployment in Cloud Run

MCP Toolbox astrae le nostre molteplici origini dati, consentendo alla nostra applicazione di recuperare e scrivere i dati in modo uniforme.

Installa MCP Toolbox in locale

Scarica il file binario di MCP Toolbox nella tua home directory e rendilo eseguibile:

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

Devi definire le astrazioni per AlloyDB, MongoDB e BigQuery. Il file tools.yaml indica alla toolbox MCP come interagire tra loro.

1. Il repository include già tools.yaml. Aprilo:

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

2. Sostituisci i segnaposto ***** con i tuoi valori:

   Database	Campo	Valore di esempio
   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 (aggiungi questa riga sotto alloydb-source se non è presente)
   MongoDB	uri	la stringa di connessione che hai salvato in precedenza

3. Indica le anteprime delle immagini nel tuo bucket:

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

Testa la UI dello strumento

1. Nel terminale Cloud Shell, esegui la toolbox localmente per pubblicare l'UI:

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

2. In Cloud Shell, fai clic su Anteprima web > Cambia porta, inserisci 5000 e aggiungi /ui alla fine dell'URL che si apre.

Viene visualizzata la seguente UI di MCP Toolbox:

Al termine, premi Ctrl+C per arrestare la toolbox locale.

Esegui il deployment in Cloud Run

Esegui il deployment di MCP Toolbox su Cloud Run per renderlo disponibile come servizio gestito sicuro che la nostra applicazione può utilizzare per eseguire query sui database. La configurazione verrà archiviata in Secret Manager per proteggere i dettagli sensibili della connessione.

1. Carica la configurazione tools.yaml in Google Secret Manager:

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

   Se in un secondo momento modifichi tools.yaml, carica una nuova versione con:

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

2. Esegui il deployment utilizzando l'immagine container pubblica di 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 attiva l'API REST utilizzata dall'app web.
3. Salva l'URL della casella degli strumenti:

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

   Puoi aprire $TOOLBOX_URL/ui nel browser per visualizzare gli strumenti.

9. Configura l'applicazione di e-commerce ed esegui il deployment in Cloud Run

Con i nostri database in esecuzione e l'astrazione di MCP Toolbox di cui è stato eseguito il deployment, possiamo eseguire l'applicazione web Flask.

Per pubblicare il catalogo dei prodotti, l'applicazione Flask elabora i dati eseguendo i seguenti passaggi:

1. Recupera i dati principali: recupera l'elenco completo dei prodotti da AlloyDB (list_products_core).
2. Recupera i dettagli estesi: recupera tutti i dettagli del prodotto da MongoDB (list_all_product_details).
3. Combina elenchi: concatena i due elenchi.
4. Arricchisci con contenuti multimediali: aggiunge l'URL dell'immagine di Cloud Storage a ogni elemento.

Crea l'Agent Engine

1. Installa le dipendenze:

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

   Nota: questo passaggio può richiedere diversi minuti per risolvere e installare i pacchetti.
2. Inizializza e registra l'agente AI utilizzando Vertex AI Reasoning Engine:

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

   L'output sarà simile al seguente:

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

L'app legge le impostazioni dalle variabili di ambiente, che passi nel comando di deployment di seguito, quindi non è necessario modificare .env.

Esegui il deployment del frontend in Cloud Run

1. Esegui il deployment dell'applicazione web in Cloud Run per completare l'architettura:

   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"
   

   L'app utilizza gemini-3.5-flash, che viene fornito dalla località global; l'Agent Engine rimane in us-central1.

   Se il deployment non va a buon fine, esegui il comando gcloud auth login per autorizzare il deployment, quindi esegui di nuovo il comando di deployment.

La tua applicazione è ora attiva. Apri l'URL del servizio fornito da Cloud Run per visualizzare il catalogo di e-commerce Multidb. L'URL sarà simile a https://polyglot-*********-uc.a.run.app/.

10. Esplora l'applicazione

1. Fai clic su Catalogo dei prodotti per visualizzare tutti i prodotti.
   
2. Fai clic sull'icona di un prodotto per visualizzarne i dettagli del prodotto. Noterai che le immagini provengono da Cloud Storage, i dettagli del prodotto vengono recuperati da MongoDB e l'inventario dei prodotti viene recuperato da AlloyDB.
3. Interagisci con il catalogo dei prodotti per generare visualizzazioni e scritture fittizie inviate a MongoDB.
4. Fai clic su ETL e analisi per visualizzare l'analisi del prodotto. Noterai che l'analisi dei prodotti viene recuperata da BigQuery.
   
5. Fai clic sulla scheda Agente AI per interagire con l'agente AI. Fai domande in linguaggio naturale come le seguenti:
   

   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.
   

   

Come puoi vedere, la ricerca restituisce esattamente ciò che abbiamo chiesto: uno zaino senza componenti in pelle, disponibile e senza reclami sulla durabilità degli spallacci nelle recensioni.

11. Esegui la pulizia

Per evitare addebiti continui sul tuo account Google Cloud, elimina le risorse create durante questo codelab.

Esegui questi comandi di 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

Facoltativamente, elimina l'istanza di Agent Engine:

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

In alternativa, nella console Google Cloud, vai a Vertex AI > Agent Engine ed elimina l'istanza.

Facoltativamente, per eliminare l'intero progetto Google Cloud e tutte le relative risorse, esegui questo comando:

gcloud projects delete $PROJECT_ID

Infine, apri MongoDB Atlas su Google Cloud ed elimina il cluster ecommerce-cluster che hai creato per assicurarti che non rimangano utilizzi del Livello senza costi.

12. Complimenti

Complimenti! Hai creato un'architettura Multidb cross-cloud.

Hai dimostrato come MCP Toolbox funge da collante architetturale per un'applicazione moderna e specializzata. Abbinando il database più adatto al lavoro giusto, hai ottenuto:

• Scritture di dati flessibili: MongoDB per i log eventi.
• Coerenza transazionale: AlloyDB per l'integrità di base.
• Analisi ad alte prestazioni: BigQuery per la business intelligence.
• Sviluppo unificato: un unico backend Python che astrae tutta la complessità utilizzando MCP Toolbox.

Documenti di riferimento

Scopri di più sui prodotti Google Cloud correlati ed esplora questi codelab:

• AlloyDB AI: Inizia a utilizzare il vector embedding con l'AI di AlloyDB
• AlloyDB AI: embedding multimodali in AlloyDB
• MCP Toolbox: Installazione e configurazione di MCP Toolbox for Databases su AlloyDB

Per saperne di più sui prodotti utilizzati in questo codelab, consulta:

• Documentazione di AlloyDB per PostgreSQL
• Documentazione di MongoDB Atlas su Google Cloud
• Documentazione di BigQuery
• Documentazione di Cloud Storage
• Documentazione di Cloud Run
• Documentazione di Cloud Build
• Implementazione di MCP Toolbox