Questa pagina è stata tradotta dall'API Cloud Translation.

Creare un assistente AI per agenti di negozi di articoli sportivi con ADK, MCP Toolbox e AlloyDB

1. Introduzione

Cosa creerai

In questo codelab, imparerai a creare un assistente AI Sports Shop Agent. Questa applicazione di AI per agenti di nuova generazione, basata su ADK, MCP Toolbox e AlloyDB, aiuterà gli utenti in varie attività, tra cui:

Cercare prodotti utilizzando un linguaggio naturale.
Trovare negozi nelle vicinanze per acquistare i prodotti consigliati.
Effettuare nuovi ordini.
Controllare gli stati degli ordini esistenti.
Aggiornamento degli ordini con i metodi di consegna preferiti.

Cosa imparerai a fare

Provisioning e popolamento di un database AlloyDB per PostgreSQL.
Configurazione di MCP Toolbox for Databases con l'istanza AlloyDB per PostgreSQL.
Progettazione e sviluppo di un agente AI utilizzando l'Agent Development Kit (ADK) per assistere con le query dei negozi di articoli sportivi.
Testare l'agente e MCP Toolbox for Databases in un ambiente cloud.
Sfruttare le funzionalità avanzate di query di AlloyDB per le risposte degli agenti intelligenti.

Che cosa ti serve

Per completare questo codelab, ti serviranno:

Un browser web Chrome.
Un account Gmail.
Un progetto Google Cloud con la fatturazione abilitata.

Questo codelab è pensato per sviluppatori di tutti i livelli, inclusi i principianti.

2. Prima di iniziare

Questa sezione ti guida nella configurazione iniziale richiesta nel tuo progetto Google Cloud prima di poter iniziare a creare l'assistente AI Sports Shop Agent.

Creare un progetto

Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto .
Attiva Cloud Shell facendo clic su questo link. Puoi passare dal terminale Cloud Shell (per eseguire comandi cloud) all'editor (per creare progetti) facendo clic sul pulsante corrispondente in Cloud Shell.

Una volta eseguita la connessione a Cloud Shell, verifica di essere già autenticato e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:

gcloud auth list

Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.

gcloud config list project

Imposta la variabile PROJECT_ID utilizzando il seguente comando:

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

Abilita le seguenti API eseguendo questi comandi:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com

3. Crea l'istanza AlloyDB

In questa sezione configurerai il cluster e l'istanza del database AlloyDB e configurerai le autorizzazioni e il networking necessari per l'agente AI.

Innanzitutto, esegui questo comando nel terminale Cloud Shell per creare il cluster AlloyDB:

gcloud alloydb clusters create alloydb-cluster \
    --password=alloydb\
    --network=default \
    --region=us-central1 \
    --database-version=POSTGRES_16

AlloyDB si basa sulla connettività IP privato per un accesso sicuro e ad alte prestazioni. Devi allocare un intervallo IP privato all'interno del tuo VPC affinché Google lo utilizzi per la connessione di peering del servizio all'infrastruttura di service networking gestita da Google. Esegui questo comando:

gcloud compute addresses create peering-range-for-alloydb \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --description="Automatically allocated IP range for service networking" \
    --network=default

Successivamente, crea la connessione di peering di servizio VPC. In questo modo, la tua rete VPC (Virtual Private Cloud) di Google Cloud può comunicare in modo sicuro e privato con i servizi gestiti di Google, incluso AlloyDB. Esegui questo comando:

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=peering-range-for-alloydb \
--network=default

Ora crea l'istanza principale all'interno del cluster AlloyDB. Questo è l'endpoint del database effettivo a cui si connetteranno le tue applicazioni. Esegui questo comando per creare un'istanza AlloyDB:

gcloud alloydb instances create alloydb-inst \
     --instance-type=PRIMARY \
     --cpu-count=2 \
     --region=us-central1 \
     --cluster=alloydb-cluster \
     --availability-type=ZONAL \
     --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

Nota: la creazione dell'istanza può richiedere circa 10 minuti. Attendi il completamento di questa operazione prima di procedere.

Abilita l'integrazione di Vertex AI

Per consentire all'istanza AlloyDB di eseguire query di ricerca vettoriale (essenziali per le funzionalità di AI come la ricerca semantica) e chiamare i modelli di cui è stato eseguito il deployment in Vertex AI, devi concedere le autorizzazioni di Vertex AI all'agente di servizio AlloyDB.

Innanzitutto, recupera il numero del progetto Google Cloud, poiché è necessario per il binding IAM.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Poi concedi a Vertex AI l'autorizzazione per l'agente di servizio AlloyDB:

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

Abilita IP pubblico

In preparazione ai passaggi successivi, attiveremo la connettività IP pubblico nella nostra istanza AlloyDB.

Nella console, vai al campo di ricerca nella parte superiore al centro dello schermo e inserisci "alloydb", quindi modifica e vai alla sezione Connettività IP pubblico. Seleziona la casella di controllo "Abilita IP pubblico" e inserisci l'indirizzo IP della tua macchina Cloud Shell.

Per ottenere l'IP della tua macchina Cloud Shell, vai al terminale Cloud Shell e inserisci il comando "ifconfig | grep -A 1 eth0". Dal risultato, sostituisci le ultime due cifre con 0.0 con una dimensione della maschera "/16". Ad esempio, "XX.XX.0.0/16", dove XX sono numeri.

Incolla questo IP nella casella di testo "Reti" delle reti esterne autorizzate della pagina di modifica dell'istanza.

Nota: l'operazione di aggiornamento può richiedere fino a 3 minuti.

4. Caricare il database

Crea il database del negozio

Ora è il momento di creare il database e caricare i dati iniziali per il tuo negozio di articoli sportivi.

Per consentire a psql di connettersi alla tua istanza AlloyDB privata da Cloud Shell, utilizzerai il proxy di autenticazione AlloyDB. Questa utilità esegue il tunneling della connessione al database in modo sicuro. (fai riferimento al proxy di autenticazione AlloyDB)

Scarica il proxy di autenticazione AlloyDB utilizzando il seguente comando:

wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.3/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

Rendi eseguibile il file:

chmod +x alloydb-auth-proxy

Esegui questo comando nella prima finestra del terminale Cloud Shell. Il proxy verrà eseguito in background e inoltrerà le connessioni.

./alloydb-auth-proxy "projects/$PROJECT_ID/locations/us-central1/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip

Importante:lascia questa finestra del terminale aperta e il proxy in esecuzione. Non chiuderla.

Apri una nuova finestra del terminale in Cloud Shell (fai clic sull'icona + accanto alla scheda "Terminale Cloud Shell" in alto).

Connettiti all'istanza AlloyDB utilizzando psql:

psql -h 127.0.0.1 -U postgres

Nota:quando richiesto, inserisci la password impostata per l'utente postgres durante la creazione del cluster (se segui direttamente la documentazione, la password è alloydb).

e crea il database del negozio per la nostra applicazione (esegui i comandi uno alla volta):

CREATE DATABASE store;
\c store
exit

Codice sorgente

Ora clona il repository del codice sorgente del codelab. Prima di clonare, assicurati di trovarti nella directory home o in una posizione adatta ed esegui questo comando:

git clone https://github.com/mtoscano84/sports-agent-adk-mcp-alloydb.git

Compilare il database

Vai alla cartella data del progetto clonato per accedere al file di dump del database.

cd sports-agent-adk-mcp-alloydb/data

Quindi, importa il set di dati di esempio nel tuo database store utilizzando il file store_backup.sql dal repository.

psql -h 127.0.0.1 -U postgres -d store -f store_backup.sql

Nota:durante questa importazione potresti visualizzare alcuni messaggi di AVVISO ed ERRORE, che possono essere ignorati tranquillamente per questo codelab. Questi spesso si riferiscono a autorizzazioni o oggetti già esistenti se il dump contiene lo schema completo.Troverai alcuni AVVISI ed ERRORI che possono essere ignorati

5. Configurazione del servizio di autorizzazione

In questa sezione configurerai il servizio di autorizzazione per la tua applicazione. Questo servizio è fondamentale per proteggere l'accesso e fornire protezione contro le vulnerabilità di prompt injection nel tuo agente AI.

Innanzitutto, aggiungi un utente di esempio alla tabella users nel database store. Questo utente verrà utilizzato per l'autenticazione nella tua applicazione.

Vai alla console e naviga ad AlloyDB, seleziona l'istanza principale e poi AlloyDB Studio:

Quando richiesto, accedi ad AlloyDB Studio utilizzando le credenziali che hai creato durante la configurazione del cluster:

Nome utente: "postgres"
Database: "store"
Password: "alloydb"

Nell'editor SQL, esegui un'istruzione INSERT per aggiungere l'utente al database. Modifica il nome, il cognome e l'indirizzo email.

Importante:

Mantieni la posizione così com'è nell'esempio
Utilizza lo stesso indirizzo email che usi per registrarti in Google Cloud Console

INSERT INTO users (user_id, first_name, last_name, Address, city, postal_code, location, email)
VALUES (10,'John', 'Doe', 'Carrer Muntaner 39', 'Barcelona', '08019', '0101000020E61000008AAE0B3F38B144401FBB0B9414780140', 'john.doe@example.com');

Successivamente, devi configurare la schermata per il consenso OAuth per il tuo progetto. Questa schermata viene mostrata agli utenti quando la tua applicazione richiede l'accesso al loro Account Google e definisce il brand della tua applicazione.

Nella console, vai a "API e servizi", "Consenso OAuth di Google":

Fornisci le seguenti informazioni per creare il brand della tua applicazione:

Nome dell'app: "Sports Shopping Agent AI"
Email per assistenza utenti: "YOUR_EMAIL"
Pubblico: "Esterno"
Informazioni di contatto: "YOUR_EMAIL"

Ora creerai l'ID client OAuth che la tua applicazione frontend utilizzerà per convalidare l'identità dell'utente con Google.

Innanzitutto, assicurati di avere il numero del tuo progetto Google Cloud. Questo passaggio è necessario per configurare correttamente gli URI di reindirizzamento. Esegui questo comando in un terminale Cloud Shell:

Se la variabile PROJECT_ID non è impostata in questa finestra del terminale Cloud Shell, esegui:

export PROJECT_ID=[YOUR_PROJECT_ID]

Quindi, recupera PROJECT_NUMBER utilizzando il seguente comando:

gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Poi, vai ad "API e servizi" -> "Credenziali" -> "Crea credenziali" -> "ID client OAuth".

Utilizza le seguenti informazioni per creare la credenziale:

Tipo di applicazione: "Applicazione web"
Nome: "Sports Shopping Agent AI App"

Origini JavaScript autorizzate:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

URI di reindirizzamento autorizzati:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Nota:l'URL https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app è l'URL di deployment previsto per l'applicazione frontend, che verrà configurata più avanti in questo codelab. Assicurati di sostituire [YOUR_PROJECT_NUMBER] con il numero effettivo che hai copiato.

Importante:dopo la creazione, un popup mostrerà l'ID client OAuth e, a volte, un client secret. Conserva l'ID client OAuth in un posto sicuro, perché ti servirà in un passaggio successivo durante la configurazione del frontend.

6. Configurazione di MCP Toolbox per i database

Toolbox si trova tra il framework di orchestrazione dell'applicazione e il database, fornendo un control plane utilizzato per modificare, distribuire o richiamare gli strumenti. Semplifica la gestione degli strumenti fornendo una posizione centralizzata per archiviarli e aggiornarli, consentendoti di condividerli tra agenti e applicazioni e di aggiornarli senza dover necessariamente eseguire nuovamente il deployment dell'applicazione.

Poiché uno dei database supportati da MCP Toolbox for Databases è AlloyDB e lo abbiamo già eseguito il provisioning nella sezione precedente, procediamo con la configurazione di Toolbox.

Innanzitutto, configurerai il server MCP Toolbox localmente nel tuo ambiente Cloud Shell per verificarne la funzionalità.

Nel terminale Cloud Shell, vai alla cartella toolbox che si trova all'interno del repository del progetto clonato:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Esegui i seguenti comandi per scaricare il file binario di Toolbox e concedergli le autorizzazioni di esecuzione:

# see releases page for other versions
export VERSION=0.7.0

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox

chmod +x toolbox

Nota:qui è specificata la versione 0.7.0. Per gli ambienti di produzione, verifica e utilizza sempre l'ultima release stabile dalla pagina delle release di Toolbox.

Vai all'editor di Cloud Shell (puoi passare dal terminale facendo clic sull'icona dell'editor).

Nella stessa directory sports-agent-adk-mcp-alloydb/src/toolbox, troverai un file denominato tools.yaml. Apri questo file e aggiorna i segnaposto con l'ID client OAuth e l'ID progetto Google Cloud dei passaggi precedenti.

Comprendiamo tools.yaml

Le origini rappresentano le diverse origini dati con cui uno strumento può interagire. Un'origine rappresenta un'origine dati con cui uno strumento può interagire. Puoi definire le origini come una mappa nella sezione sources del file tools.yaml. In genere, una configurazione dell'origine contiene tutte le informazioni necessarie per connettersi al database e interagire con esso.

Gli strumenti definiscono le azioni che un agente può intraprendere, ad esempio leggere e scrivere in una sorgente. Uno strumento rappresenta un'azione che l'agente può intraprendere, ad esempio l'esecuzione di un'istruzione SQL. Puoi definire gli strumenti come una mappa nella sezione degli strumenti del file tools.yaml. In genere, uno strumento richiede un'origine su cui agire.

Per ulteriori dettagli sulla configurazione di tools.yaml, consulta questa documentazione.

Eseguiamo MCP Toolbox for Databases Server

Esegui questo comando (dalla cartella mcp-toolbox) per avviare il server:

./toolbox --tools-file "tools.yaml"

Ora, se apri il server in modalità di anteprima web sul cloud, dovresti essere in grado di vedere il server Toolbox in esecuzione con tutti gli strumenti della nostra applicazione.

Per impostazione predefinita, il server MCP Toolbox viene eseguito sulla porta 5000. Utilizziamo Cloud Shell per testare questa funzionalità.

Fai clic su Anteprima web in Cloud Shell come mostrato di seguito:

Fai clic su Cambia porta e imposta la porta su 5000 come mostrato di seguito, poi fai clic su Cambia e visualizza anteprima.

Dovrebbe essere visualizzato l'output:

MCP Toolkit for Databases descrive un SDK Python per convalidare e testare gli strumenti, documentato qui. Saltiamo questo passaggio e passiamo direttamente all'Agent Development Kit (ADK) nella sezione successiva, che utilizzerà questi strumenti.

Eseguiamo il deployment di Toolbox in Cloud Run

Per rendere il server Toolbox accessibile come endpoint pubblico che può essere integrato con altre applicazioni e con il tuo agente AI, devi eseguirne il deployment in Cloud Run. Le istruzioni dettagliate per l'hosting di Toolbox su Cloud Run sono disponibili qui.

Torna al terminale Cloud Shell e vai alla cartella degli strumenti:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Assicurati che la variabile di ambiente PROJECT_ID sia impostata sull'ID progetto Google Cloud.

export PROJECT_ID=$PROJECT_ID

Successivamente, verifica che i seguenti servizi Google Cloud siano abilitati nel progetto.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

Creiamo un service account separato che fungerà da identità per il servizio Toolbox che verrà sottoposto a deployment su Google Cloud Run. Ci stiamo anche assicurando che questo service account disponga dei ruoli corretti, ovvero la possibilità di accedere a Secret Manager e comunicare con AlloyDB.

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor


gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/alloydb.client'


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/serviceusage.serviceUsageConsumer'

Poi, caricherai il file tools.yaml come secret e, poiché dobbiamo installare Toolbox in Cloud Run, utilizzeremo l'immagine container più recente per Toolbox e la imposteremo nella variabile IMAGE.

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

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

Infine, esegui il deployment del server Toolbox su Cloud Run utilizzando questo comando. Questo comando inserisce l'applicazione in un container, configura il service account, inserisce il secret e lo espone pubblicamente:

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

In questo modo dovrebbe iniziare il processo di deployment del server Toolbox con il file tools.yaml configurato in Cloud Run. Se il deployment va a buon fine, dovresti visualizzare un messaggio simile al seguente:

Deploying container to Cloud Run service [toolbox] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00002-dn2] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app

Ora puoi visitare l'URL del servizio elencato sopra nel browser. Dovrebbe essere visualizzato il messaggio "Hello World" che abbiamo visto in precedenza. Inoltre, puoi visitare il seguente URL per visualizzare gli strumenti disponibili:

https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/api/toolset

Puoi anche visitare Cloud Run dalla console Google Cloud e vedrai il servizio Toolbox disponibile nell'elenco dei servizi in Cloud Run.

7. Agente creato su ADK

In questa sezione, eseguirai il deployment dell'agente AI, creato utilizzando l'Agent Development Kit (ADK), su Cloud Run.

Per prima cosa, abilita le API necessarie nel tuo progetto per creare e distribuire l'agente su Cloud Run e per interagire con Artifact Registry e Cloud Storage. Esegui questo comando nel terminale Cloud Shell:

gcloud services enable artifactregistry.googleapis.com \
                       cloudbuild.googleapis.com \
                       run.googleapis.com \
                       storage.googleapis.com

A questo punto, assegneremo le autorizzazioni necessarie all'account di servizio Compute predefinito nel nostro progetto. Per prima cosa, esegui questo comando nel terminale Cloud Shell per ottenere PROJECT_NUMBER:

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

Assegna le autorizzazioni al service account Compute predefinito:

# Grant Cloud Run service account access to GCS
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role="roles/artifactregistry.repoAdmin"

# Grant Vertex AI User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"

# Grant Vertex AI Model User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.modelUser"

Connettere il nostro agente agli strumenti

Collegheremo il nostro agente agli strumenti. Nel contesto dell'ADK, uno strumento rappresenta una funzionalità specifica fornita a un agente AI, che gli consente di eseguire azioni e interagire con il mondo al di là delle sue capacità di generazione di testo e ragionamento di base.

Nel nostro caso, doteremo l'agente degli strumenti che abbiamo configurato in MCP Toolbox per i database.

Utilizzando l'editor di Cloud Shell, vai a sports-agent-adk-mcp-alloydb/src/backend/ e modifica il file "finn_agent.py" con il seguente codice. Tieni presente che stiamo utilizzando l'URL del servizio Cloud Run dal server MCP ToolBox di cui è stato eseguito il deployment nel passaggio precedente:

Esegui il deployment dell'agente su Cloud Run

Infine, eseguirai il deployment dell'agente AI configurato in Cloud Run, rendendolo accessibile tramite un endpoint HTTP.

Per prima cosa, crea un repository Docker in Artifact Registry per archiviare le immagini container dell'agente. Esegui il comando riportato di seguito in Cloud Shell:

gcloud artifacts repositories create finn-agent-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-agent images"

Successivamente, crea l'immagine Docker per l'agente utilizzando Cloud Build. Esegui questo comando dalla directory principale del progetto clonato (sports-agent-adk-mcp-alloydb/):

gcloud builds submit src/backend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent

Ora esegui il deployment del servizio agente. Questo comando creerà un servizio Cloud Run, eseguirà il pull dell'immagine da Artifact Registry e configurerà le variabili di ambiente.

gcloud run deploy finn-agent \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=TRUE"

Nota:stiamo impostando dinamicamente le variabili di ambiente, inclusa GOOGLE_CLOUD_PROJECT (utilizzando la variabile shell $PROJECT_ID)

Dovresti visualizzare un output simile a questo, che indica l'implementazione riuscita dell'agente:

Deploying container to Cloud Run service [finn-agent] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-agent] revision [finn-agent-00005-476] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-agent-359225437509.us-central1.run.app

Infine, testa l'agente eseguendo questo comando curl dal terminale di Cloud Shell:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}' \
  https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app/chat

L'output sarà simile al seguente:

"Buongiorno. Sono Finn, il tuo assistente per lo shopping sportivo basato sull'AI. Posso aiutarti a trovare prodotti, attrezzature e accessori sportivi. Come posso aiutarti oggi?"

A questo punto, hai convalidato correttamente il deployment di AlloyDB, MCP Toolbox e dell'agente creato utilizzando ADK.

8. Esegui il deployment del frontend

In questa sezione, eseguirai il deployment dell'interfaccia utente conversazionale per l'assistente AI su Cloud Run. Questo frontend è creato utilizzando React e JavaScript.

Prima del deployment, devi aggiornare il codice sorgente del frontend con gli URL dell'agente di cui hai eseguito il deployment e con l'ID client OAuth.

Utilizzando l'editor di Cloud Shell, vai a sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ e apri il file Home.jsx. Dovrai aggiornare il segnaposto per l'URL del servizio Cloud Run dell'agente. quindi sostituiscilo con l'URL del servizio Cloud Run dell'agente del passaggio precedente (ad es. https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app).

Ora, vai a sports-agent-adk-mcp-alloydb/src/frontend/src/components/ e apri il file GoogleSignInButton.jsx. Aggiornerai questo file con l'ID client OAuth ottenuto nella sezione "Configurazione del servizio di autorizzazione":

Esegui il deployment del frontend su Cloud Run

Ora che l'applicazione frontend è configurata, puoi eseguirne il deployment in Cloud Run.

Esegui questo comando in un terminale Cloud Shell dalla directory principale (sports-agent-adk-mcp-alloydb/) per creare un repository Docker in Artifact Registry per le immagini frontend.

gcloud artifacts repositories create finn-frontend-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-frontend images"

Successivamente, crea l'immagine Docker per l'applicazione frontend utilizzando Cloud Build. Esegui questo comando dalla directory principale del tuo progetto:

gcloud builds submit src/frontend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend

Infine, eseguiamo il deployment del frontend su Cloud Run utilizzando questo comando:

gcloud run deploy finn-frontend \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID

Dovresti ottenere un output simile a questo, che indica l'implementazione riuscita del frontend:

Deploying container to Cloud Run service [finn-frontend] in project [sport-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-frontend] revision [finn-frontend-00002-mwc] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-frontend-535807247199.us-central1.run.app

Apri il browser web e utilizza l'URL del servizio del passaggio precedente per aprire l'applicazione appena implementata, basata sul tuo agente AI.

9. Esegui il nostro agente

L'assistente AI dell'agente del negozio di articoli sportivi, Finn, è ora completamente implementato e pronto ad aiutarti con gli acquisti.

Apri il browser web e vai all'URL del servizio dell'applicazione frontend del passaggio precedente. L'URL segue questo formato: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Una volta caricato il frontend, fai clic sul pulsante in alto a destra (in genere etichettato "Accedi" o un prompt simile) per autenticarti utilizzando le tue credenziali Google. Questa azione utilizzerà la configurazione OAuth che hai impostato in precedenza.

Una volta autenticato, puoi iniziare a interagire con Finn. Fai clic sul pulsante "Acquista ora" per iniziare la tua esperienza di shopping conversazionale.

Utilizza il seguente script per testare le varie funzionalità del tuo agente AI. Copia e incolla questi prompt nell'interfaccia della chat uno alla volta:

Ciao Finn!
Sto cercando scarpe da corsa per un'ultra-trail
Forniscimi maggiori dettagli su Ultra Glide
Aggiungi Ultra Glide, taglia 40, colore rosso/grigio alla mia lista della spesa
Mostrami la lista della spesa
Trovare negozi nelle vicinanze
Effettua un ordine utilizzando la mia lista della spesa per il negozio Sports Diagonal Mar
Controllare lo stato dei miei ordini
Elenca i metodi di consegna per il negozio Sports Diagonal Mar
Aggiorna il metodo di consegna alla consegna rapida per il mio ordine [YOUR_ORDER_NUMBER]
Controllare lo stato dei miei ordini
Grazie, Finn.

Per una dimostrazione visiva dell'agente Finn implementato e delle sue funzionalità, guarda il video qui sotto:

Demo di un assistente AI per agenti sportivi basato su AlloyDB

10. Risultati

Dopo aver eseguito lo script precedente, hai convalidato correttamente l'integrazione completa dell'agente ADK, la sua connessione ad AlloyDB e l'utilizzo di MCP Toolbox. Questa sezione mette in evidenza le funzionalità principali che hai implementato.

Servizio di autorizzazione

MCP Toolbox for Databases offre la possibilità di federare un servizio di autorizzazione (nello specifico, Accedi con Google in questo codelab) per autenticare gli utenti all'interno dell'applicazione. Con MCP Toolbox, l'ID client OAuth viene utilizzato per convalidare l'identità dell'utente quando viene richiamato uno strumento.

Questo solido meccanismo di autenticazione offre un'ottima soluzione per proteggere la tua applicazione con agenti dall'prompt injection, un tipo di attacco in cui input dannosi tentano di bypassare o manipolare il comportamento previsto dell'agente. Per maggiori dettagli, puoi consultare l'articolo di Wikipedia sull'iniezione di prompt .

In questa applicazione, questa tecnica viene utilizzata quando un utente chiede di "controllare lo stato dei nostri ordini" o "mostrare la mia lista della spesa". L'agente è progettato per mostrare solo gli ordini appartenenti all'utente autenticato, impedendo l'accesso non autorizzato alle informazioni sugli ordini.

Ricerca vettoriale

La tua applicazione agentica utilizza AlloyDB per PostgreSQL per fornire funzionalità di query avanzate, in particolare tramite la ricerca vettoriale. AlloyDB supporta la generazione di embedding online direttamente all'interno del database utilizzando le funzioni SQL.

Questa potente funzionalità consente all'agente di tradurre l'input in linguaggio naturale di un utente in una rappresentazione numerica dell'incorporamento. Successivamente, può eseguire una ricerca di similarità nel catalogo dei prodotti (o in altri dati pertinenti) in base a questi incorporamenti, consentendo risultati di ricerca altamente pertinenti.

Nella tua applicazione, questa tecnica si verifica quando chiedi a Finn: "Sto cercando scarpe da corsa per un'ultra-trail".

Funzionalità geospaziali (PostGis)

AlloyDB per PostgreSQL mantiene la compatibilità al 100% con le funzionalità PostgreSQL standard. In questa applicazione, utilizziamo la nota estensione PostgreSQL PostGIS per fornire all'agente funzionalità di posizione geospaziale.

Quando chiedi all'agente: "Trova negozi vicino a me", l'agente esegue uno strumento che utilizza gli indici PostGIS all'interno del database per individuare in modo efficiente i negozi più vicini alla posizione specificata o dedotta dell'utente.

11. (Facoltativo) Testa la funzionalità di AlloyDB AI Natural Language to SQL

Questa sezione introduce una funzionalità avanzata pre-GA di AlloyDB per PostgreSQL: Natural Language to SQL. Questa funzionalità ti consente di generare query SQL direttamente da prompt in linguaggio naturale, sfruttando la potenza dell'AI all'interno del tuo database.

Importante:poiché si tratta di una funzionalità pre-GA, devi registrarti e attivare l'accesso per il tuo progetto Google Cloud, il cluster AlloyDB e il database.

Registrati per l'accesso:compila questo modulo per richiedere l'accesso per il tuo progetto.
Documentazione: puoi scoprire di più su come sfruttare AlloyDB AI Natural Language to SQL nella documentazione ufficiale.

Dopo aver eseguito la registrazione e confermato l'accesso per il tuo progetto, procedi con i seguenti passaggi in AlloyDB Studio.

Accedi ad AlloyDB utilizzando le credenziali che hai creato quando hai creato il cluster:

Nome utente: "postgres"
Database: "store"
Password: "alloydb"

1. Crea l'estensione alloydb_ai_nl. Questa estensione fornisce le funzioni necessarie per le funzionalità di linguaggio naturale di AlloyDB AI.

CREATE EXTENSION alloydb_ai_nl cascade;

2. Crea una configurazione per la tua applicazione. Una configurazione definisce il contesto dello schema che il modello di AI utilizzerà per comprendere il tuo database.

SELECT
 alloydb_ai_nl.g_create_configuration(
   'finn_app_config'        -- configuration_id
 );

3. Registra lo schema / le tabelle con la configurazione. Aggiungi alla configurazione le tabelle e gli schemi specifici con cui interagirà l'agente della tua applicazione.

SELECT alloydb_ai_nl.g_manage_configuration(
   operation => 'register_table_view',
   configuration_id_in => 'finn_app_config',
   table_views_in=>'{public.products, public.products_variants, public.orders, public.orders_items, public.users, public.inventory, public.stores}'
);

4. Genera il contesto per lo schema / le tabelle. Questo passaggio elabora le tabelle registrate per generare il contesto necessario per il modello di AI. Questa procedura può richiedere circa 2-3 minuti.

SELECT alloydb_ai_nl.generate_schema_context(
 'finn_app_config',
 TRUE
);

5. (Facoltativo) Controlla il contesto generato automaticamente per tabelle e colonne specifiche. Puoi esaminare il contesto generato per capire come il modello di AI interpreta lo schema.

SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.inventory';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.name';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.popularity_score';

Nello strumento "tools.yaml" del nostro agente troverai uno strumento chiamato "check-inventory-by-store-brand-category". Questo strumento utilizza la funzionalità di AlloyDB Natural Language to SQL:

Apri un browser web e utilizza l'URL del servizio per aprire l'applicazione: "https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app"

Quindi, utilizza il seguente script nell'interfaccia di chat per testare questa nuova funzionalità:

Ciao Finn!
Qual è la quantità totale di prodotti della categoria Corsa di Salomon disponibili in magazzino nel negozio "Sports Diagonal Mar"?

Per visualizzare la query SQL effettiva generata da AlloyDB AI a partire dall'input in linguaggio naturale, torna ad AlloyDB Studio ed esegui la seguente query:

SELECT
   alloydb_ai_nl.get_sql(
       'finn_app_config',
       'What is the total quantity of category Running products of Salomon in stock at the "Sports Diagonal Mar" store?'
   ) ->> 'sql';

Verrà visualizzata l'istruzione SQL generata da AlloyDB AI.

12. Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo lab, segui questi passaggi:

Nella console Google Cloud, vai alla pagina Gestisci risorse.
Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

13. Complimenti

Complimenti! Hai creato correttamente un'applicazione di AI agentica basata sui dati utilizzando ADK, MCP Toolbox for Databases e AlloyDB per PostgreSQL

Per saperne di più, consulta la documentazione del prodotto: Agent Development Kit, MCP Toolbox per i database e AlloyDB per PostgreSQL.