Cette page a été traduite par l'API Cloud Translation.

Créer un assistant d'IA pour un agent de magasin de sport avec l'ADK, MCP Toolbox et AlloyDB

1. Introduction

Objectifs de l'atelier

Dans cet atelier de programmation, vous allez apprendre à créer un assistant IA pour une boutique d'articles de sport. Cette application d'IA pour les agents de nouvelle génération, optimisée par ADK, MCP Toolbox et AlloyDB, aidera les utilisateurs à effectuer diverses tâches, y compris :

Rechercher des produits en langage naturel
Trouver des magasins à proximité pour acheter les produits recommandés.
Passer de nouvelles commandes.
Vérifier l'état des commandes existantes.
Mise à jour des commandes avec les modes de livraison préférés.

Points abordés

Provisionnement et remplissage d'une base de données AlloyDB pour PostgreSQL.
Configurer la boîte à outils MCP pour les bases de données avec votre instance AlloyDB pour PostgreSQL.
Concevoir et développer un agent d'IA à l'aide de l'Agent Development Kit (ADK) pour répondre aux questions sur les magasins de sport.
Tester votre agent et MCP Toolbox for Databases dans un environnement cloud.
Exploiter les fonctionnalités de requête avancées d'AlloyDB pour les réponses intelligentes des agents.

Prérequis

Pour suivre cet atelier de programmation, vous aurez besoin :

Un navigateur Web Chrome.
Un compte Gmail
Projet Google Cloud avec facturation activée

Cet atelier de programmation s'adresse aux développeurs de tous niveaux, y compris aux débutants.

2. Avant de commencer

Cette section vous guide à travers la configuration initiale requise dans votre projet Google Cloud avant de pouvoir commencer à créer l'assistant IA Sports Shop Agent.

Créer un projet

Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet .
Activez Cloud Shell en cliquant sur ce lien. Vous pouvez basculer entre le terminal Cloud Shell (pour exécuter des commandes cloud) et l'éditeur (pour créer des projets) en cliquant sur le bouton correspondant dans Cloud Shell.

Une fois connecté à Cloud Shell, vérifiez que vous êtes déjà authentifié et que le projet est défini sur votre ID de projet à l'aide de la commande suivante :

gcloud auth list

Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet.

gcloud config list project

Définissez la variable PROJECT_ID à l'aide de la commande suivante :

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

Activez les API suivantes en exécutant les commandes suivantes :

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

3. Créer l'instance AlloyDB

Dans cette section, vous allez configurer votre cluster et votre instance de base de données AlloyDB, et configurer la mise en réseau et les autorisations nécessaires pour votre agent d'IA.

Tout d'abord, exécutez la commande suivante dans votre terminal Cloud Shell pour créer le cluster AlloyDB :

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

AlloyDB s'appuie sur la connectivité par adresse IP privée pour un accès sécurisé et performant. Vous devez allouer une plage d'adresses IP privées dans votre VPC pour que Google puisse l'utiliser pour la connexion d'appairage de services à l'infrastructure de mise en réseau des services gérés par Google. Exécutez la commande suivante :

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

Créez ensuite la connexion d'appairage de services VPC. Cela permet à votre réseau de cloud privé virtuel (VPC) Google Cloud de communiquer de manière sécurisée et privée avec les services gérés de Google, y compris AlloyDB. Exécutez la commande suivante :

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

Créez maintenant l'instance principale dans votre cluster AlloyDB. Il s'agit du point de terminaison de la base de données auquel vos applications se connecteront. Exécutez la commande suivante pour créer une instance 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

Remarque : La création de l'instance peut prendre environ 10 minutes. Veuillez attendre la fin de cette opération avant de continuer.

Activer l'intégration à Vertex AI

Pour permettre à votre instance AlloyDB d'effectuer des requêtes de recherche vectorielle (essentielles pour les fonctionnalités d'IA telles que la recherche sémantique) et d'appeler des modèles déployés dans Vertex AI, vous devez accorder des autorisations Vertex AI à l'agent de service AlloyDB.

Commencez par récupérer le numéro de votre projet Google Cloud, car il est requis pour l'association IAM.

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

Accordez ensuite à Vertex AI l'autorisation d'accéder à l'agent de service AlloyDB :

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

Activer les adresses IP publiques

En préparation des étapes suivantes, nous allons activer la connectivité à l'adresse IP publique dans notre instance AlloyDB.

Dans la console, accédez au champ de recherche en haut au centre de l'écran et saisissez "alloydb". Ensuite, modifiez la section "Connectivité à l'adresse IP publique" et accédez-y. Cochez la case "Activer les adresses IP publiques" et saisissez l'adresse IP de votre machine Cloud Shell.

Pour obtenir l'adresse IP de votre machine Cloud Shell, accédez au terminal Cloud Shell et saisissez la commande "ifconfig | grep -A 1 eth0". Dans le résultat, remplacez les deux derniers chiffres par 0.0 avec une taille de masque "/16". Par exemple, il ressemblerait à "XX.XX.0.0/16", où XX sont des nombres.

Collez cette adresse IP dans la zone de texte "Réseaux" de la section "Réseaux externes autorisés" de la page de modification de l'instance.

Remarque : L'opération de mise à jour peut prendre jusqu'à trois minutes.

4. Charger la base de données

Créer la base de données du magasin

Il est maintenant temps de créer votre base de données et de charger les données initiales de votre magasin de sport.

Pour permettre à psql de se connecter à votre instance AlloyDB privée depuis Cloud Shell, vous utiliserez le proxy d'authentification AlloyDB. Cet utilitaire sécurise votre connexion à la base de données. (Consultez Proxy d'authentification AlloyDB.)

Téléchargez le proxy d'authentification AlloyDB à l'aide de la commande suivante :

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

Rendez-le exécutable :

chmod +x alloydb-auth-proxy

Exécutez cette commande dans votre première fenêtre de terminal Cloud Shell. Le proxy s'exécutera en arrière-plan et transférera les connexions.

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

Important : Laissez cette fenêtre de terminal ouverte et le proxy en cours d'exécution. Ne la fermez pas.

Ouvrez une nouvelle fenêtre de terminal dans Cloud Shell (cliquez sur l'icône + à côté de l'onglet "Terminal Cloud Shell" en haut).

Connectez-vous à l'instance AlloyDB à l'aide de psql :

psql -h 127.0.0.1 -U postgres

Remarque : Lorsque vous y êtes invité, saisissez le mot de passe que vous avez défini pour l'utilisateur postgres lors de la création du cluster (si vous suivez directement la documentation, le mot de passe est alloydb).

Créez ensuite la base de données du magasin pour notre application (exécutez les commandes une par une) :

CREATE DATABASE store;
\c store
exit

Code source

Clonez maintenant le dépôt de code source de l'atelier de programmation. Avant de cloner, assurez-vous d'être dans votre répertoire de base ou dans un emplacement approprié, puis exécutez la commande suivante :

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

Insérer des données dans la base de données

Accédez au dossier data du projet cloné pour accéder au fichier de vidage de la base de données.

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

Importez ensuite l'ensemble de données exemple dans votre base de données store à l'aide du fichier store_backup.sql du dépôt.

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

Remarque : Vous pouvez voir des messages d'AVERTISSEMENT et d'ERREUR lors de cette importation, que vous pouvez ignorer en toute sécurité pour cet atelier de programmation. Elles concernent souvent des autorisations ou des objets qui existent déjà si le fichier dump contient un schéma complet. Vous trouverez des AVERTISSEMENTS et des ERREURS que vous pouvez ignorer.

5. Configurer le service d'autorisation

Dans cette section, vous allez configurer le service d'autorisation pour votre application. Ce service est essentiel pour sécuriser l'accès et protéger votre agent d'IA contre les failles d'injection de requêtes.

Vous allez d'abord ajouter un exemple d'utilisateur à la table users de votre base de données store. Cet utilisateur sera utilisé pour l'authentification dans votre application.

Accédez à la console et à AlloyDB, sélectionnez l'instance principale, puis AlloyDB Studio :

Lorsque vous y êtes invité, connectez-vous à AlloyDB Studio à l'aide des identifiants que vous avez créés lors de la configuration du cluster :

Nom d'utilisateur : "postgres"
Base de données : "store"
Mot de passe : "alloydb"

Dans l'éditeur SQL, exécutez une instruction INSERT pour ajouter votre utilisateur à la base de données. Modifiez le nom, le prénom et l'adresse e-mail.

Important :

Conservez l'EMPLACEMENT tel qu'il figure dans l'exemple.
Utilisez la même adresse e-mail que celle que vous utilisez pour vous inscrire dans la console Google Cloud.

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');

Ensuite, vous devez configurer l'écran de consentement OAuth pour votre projet. Cet écran s'affiche lorsque votre application demande l'accès au compte Google des utilisateurs. Il définit la marque de votre application.

Dans la console, accédez à "API et services", "Consentement Google OAuth" :

Fournissez les informations suivantes pour créer la marque de votre application :

Nom de l'application : "Sports Shopping Agent AI"
Adresse e-mail d'assistance utilisateur : "YOUR_EMAIL"
Audience : "Externe"
Coordonnées : "YOUR_EMAIL"

Vous allez maintenant créer l'ID client OAuth que votre application frontend utilisera pour valider l'identité de l'utilisateur auprès de Google.

Tout d'abord, assurez-vous d'avoir votre numéro de projet Google Cloud. Cette étape est nécessaire pour configurer correctement les URI de redirection. Exécutez la commande suivante dans un terminal Cloud Shell :

Si votre variable PROJECT_ID n'est pas définie dans cette fenêtre de terminal Cloud Shell, exécutez la commande suivante :

export PROJECT_ID=[YOUR_PROJECT_ID]

Obtenez ensuite le PROJECT_NUMBER à l'aide de la commande suivante :

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

Accédez ensuite à "API et services" > "Identifiants" > "Créer des identifiants" > "ID client OAuth".

Utilisez les informations suivantes pour créer les identifiants :

Type d'application : "Application Web"
Nom : "Sports Shopping Agent AI App"

Origines JavaScript autorisées :

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

URI de redirection autorisés :

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

Remarque : L'URL https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app est l'URL de déploiement attendue pour votre application frontend, qui sera configurée plus tard dans cet atelier de programmation. Veillez à remplacer [VOTRE_NUMÉRO_DE_PROJET] par le numéro que vous avez copié.

Important : Une fois le client OAuth créé, un pop-up affichera son ID client OAuth et, parfois, un code secret client. Conservez votre ID client OAuth dans un endroit sûr, car vous en aurez besoin à une étape ultérieure lors de la configuration de votre interface utilisateur.

6. Configuration de MCP Toolbox for Databases

Toolbox se situe entre le framework d'orchestration de votre application et votre base de données. Il fournit un plan de contrôle utilisé pour modifier, distribuer ou appeler des outils. Il simplifie la gestion de vos outils en vous offrant un emplacement centralisé pour les stocker et les mettre à jour. Vous pouvez ainsi partager des outils entre les agents et les applications, et les mettre à jour sans nécessairement redéployer votre application.

Étant donné qu'AlloyDB est l'une des bases de données compatibles avec MCP Toolbox for Databases et que nous l'avons déjà provisionnée dans la section précédente, configurons Toolbox.

Vous allez d'abord configurer le serveur MCP Toolbox en local dans votre environnement Cloud Shell pour vérifier son fonctionnement.

Dans votre terminal Cloud Shell, accédez au dossier toolbox situé dans le dépôt de votre projet cloné :

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

Exécutez les commandes suivantes pour télécharger le binaire de la boîte à outils et lui accorder des autorisations d'exécution :

# 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

Remarque : La version 0.7.0 est spécifiée ici. Pour les environnements de production, vérifiez toujours la dernière version stable sur la page des versions de la boîte à outils et utilisez-la.

Accédez à l'éditeur Cloud Shell (vous pouvez passer du terminal à l'éditeur en cliquant sur l'icône de l'éditeur).

Dans le même répertoire sports-agent-adk-mcp-alloydb/src/toolbox, vous trouverez un fichier nommé tools.yaml. Ouvrez ce fichier et remplacez les espaces réservés par votre ID client OAuth et votre ID de projet Google Cloud des étapes précédentes.

Comprendre tools.yaml

Les sources représentent vos différentes sources de données avec lesquelles un outil peut interagir. Une source représente une source de données avec laquelle un outil peut interagir. Vous pouvez définir des sources sous forme de mappage dans la section "sources" de votre fichier tools.yaml. En règle générale, une configuration de source contient toutes les informations nécessaires pour se connecter à la base de données et interagir avec elle.

Les outils définissent les actions qu'un agent peut effectuer, comme lire et écrire dans une source. Un outil représente une action que votre agent peut effectuer, comme exécuter une instruction SQL. Vous pouvez définir des outils sous forme de mappage dans la section "tools" de votre fichier tools.yaml. En règle générale, un outil a besoin d'une source pour agir.

Pour en savoir plus sur la configuration de votre fichier tools.yaml, consultez cette documentation.

Exécutons le serveur MCP Toolbox for Databases

Exécutez la commande suivante (à partir du dossier mcp-toolbox) pour démarrer le serveur :

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

Si vous ouvrez le serveur en mode Aperçu Web dans le cloud, vous devriez voir le serveur Toolbox en cours d'exécution avec tous les outils de notre application.

Par défaut, le serveur MCP Toolbox s'exécute sur le port 5000. Utilisons Cloud Shell pour tester cela.

Cliquez sur "Aperçu sur le Web" dans Cloud Shell, comme indiqué ci-dessous :

Cliquez sur "Change port" (Modifier le port), définissez le port sur 5000 comme indiqué ci-dessous, puis cliquez sur "Change and Preview" (Modifier et prévisualiser).

Vous devriez obtenir le résultat suivant :

La boîte à outils MCP pour les bases de données décrit un SDK Python qui vous permet de valider et de tester les outils. Pour en savoir plus, cliquez ici. Nous allons passer cette étape et passer directement au kit de développement d'agent (ADK) dans la section suivante, qui utilisera ces outils.

Déployons notre boîte à outils sur Cloud Run

Pour rendre votre serveur Toolbox accessible en tant que point de terminaison public pouvant être intégré à d'autres applications et à votre agent d'IA, vous le déploierez sur Cloud Run. Pour obtenir des instructions détaillées sur l'hébergement de la boîte à outils sur Cloud Run, cliquez ici.

Revenez au terminal Cloud Shell et accédez au dossier de la boîte à outils :

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

Assurez-vous que la variable d'environnement PROJECT_ID est définie sur l'ID de votre projet Google Cloud.

export PROJECT_ID=$PROJECT_ID

Ensuite, vérifiez que les services Google Cloud suivants sont activés dans le projet.

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

Créons un compte de service distinct qui servira d'identité pour le service Toolbox que nous allons déployer sur Google Cloud Run. Nous nous assurons également que ce compte de service dispose des rôles appropriés, c'est-à-dire qu'il peut accéder à Secret Manager et communiquer avec 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'

Vous allez ensuite importer le fichier tools.yaml en tant que secret. Comme nous devons installer la boîte à outils dans Cloud Run, nous allons utiliser la dernière image de conteneur pour la boîte à outils et la définir dans la variable IMAGE.

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

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

Enfin, déployez votre serveur Toolbox sur Cloud Run à l'aide de la commande suivante. Cette commande conteneurise votre application, configure le compte de service, injecte le secret et l'expose publiquement :

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

Cela devrait lancer le processus de déploiement du serveur Toolbox avec notre fichier tools.yaml configuré sur Cloud Run. Si le déploiement réussit, un message semblable à celui-ci s'affiche :

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

Vous pouvez maintenant accéder à l'URL du service listée ci-dessus dans le navigateur. Le message "Hello World" que nous avons vu précédemment doit s'afficher. Vous pouvez également accéder à l'URL suivante pour voir les outils disponibles :

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

Vous pouvez également accéder à Cloud Run depuis la console Google Cloud. Le service Toolbox sera alors disponible dans la liste des services Cloud Run.

7. Agent créé sur ADK

Dans cette section, vous allez déployer votre agent d'IA, qui est conçu à l'aide du kit de développement d'agents (ADK), sur Cloud Run.

Tout d'abord, activez les API nécessaires dans votre projet pour créer et déployer votre agent sur Cloud Run, et pour interagir avec Artifact Registry et Cloud Storage. Exécutez la commande suivante dans votre terminal Cloud Shell :

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

Nous allons ensuite attribuer les autorisations nécessaires au compte de service Compute par défaut dans notre projet. Pour commencer, exécutez la commande suivante dans votre terminal Cloud Shell afin d'obtenir le PROJECT_NUMBER :

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

Attribuez des autorisations au compte de service Compute par défaut :

# 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"

Connecter notre agent à des outils

Nous allons connecter notre agent aux outils. Dans le contexte de l'ADK, un outil représente une fonctionnalité spécifique fournie à un agent d'IA, lui permettant d'effectuer des actions et d'interagir avec le monde au-delà de ses capacités de génération de texte et de raisonnement de base.

Dans notre cas, nous allons équiper notre agent avec les outils que nous avons configurés dans MCP Toolbox for Databases.

À l'aide de l'éditeur Cloud Shell, accédez à sports-agent-adk-mcp-alloydb/src/backend/ et modifiez le fichier "finn_agent.py" avec le code suivant. Notez que nous utilisons l'URL du service Cloud Run à partir du serveur MCP ToolBox déployé à l'étape précédente :

Déployer notre agent sur Cloud Run

Enfin, vous déploierez votre agent d'IA configuré sur Cloud Run, ce qui le rendra accessible via un point de terminaison HTTP.

Commencez par créer un dépôt Docker dans Artifact Registry pour stocker les images de conteneur de votre agent. Exécutez la commande suivante dans Cloud Shell :

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

Ensuite, créez l'image Docker pour votre agent à l'aide de Cloud Build. Exécutez cette commande à partir du répertoire racine de votre projet cloné (sports-agent-adk-mcp-alloydb/) :

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

Déployez maintenant le service d'agent. Cette commande crée un service Cloud Run, extrait l'image d'Artifact Registry et configure les variables d'environnement.

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"

Remarque : Nous définissons dynamiquement les variables d'environnement, y compris GOOGLE_CLOUD_PROJECT (à l'aide de la variable shell $PROJECT_ID).

Vous devriez obtenir un résultat semblable à celui-ci, indiquant que votre agent a bien été déployé :

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

Enfin, testez votre agent en exécutant la commande curl suivante à partir de votre terminal Cloud Shell :

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

Vous obtiendrez un résultat semblable à celui-ci :

"Bonjour ! Je suis Finn, votre assistant d'achat sportif basé sur l'IA. Je peux vous aider à trouver des produits, des équipements et du matériel de sport. Que puis-je faire pour vous ?"

À ce stade, vous avez validé le déploiement d'AlloyDB, de MCP Toolbox et de votre agent créé à l'aide de l'ADK.

8. Déployer l'interface

Dans cette section, vous allez déployer l'interface utilisateur conversationnelle de votre assistant IA sur Cloud Run. Cette interface est développée à l'aide de React et de JavaScript.

Avant de déployer l'application, vous devez mettre à jour le code source du frontend avec les URL de votre agent déployé et votre ID client OAuth.

À l'aide de l'éditeur Cloud Shell, accédez à sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ et ouvrez le fichier Home.jsx. Vous devrez mettre à jour l'espace réservé pour l'URL du service Cloud Run de votre agent. Remplacez-la ensuite par l'URL du service Cloud Run de votre agent à l'étape précédente (par exemple, https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app).

Accédez ensuite à sports-agent-adk-mcp-alloydb/src/frontend/src/components/ et ouvrez le fichier GoogleSignInButton.jsx. Vous allez mettre à jour ce fichier avec l'ID client OAuth que vous avez obtenu dans la section "Configuration du service d'autorisation" :

Déployer l'interface sur Cloud Run

Maintenant que votre application frontend est configurée, vous pouvez la déployer sur Cloud Run.

Exécutez la commande suivante dans un terminal Cloud Shell à partir du répertoire racine (sports-agent-adk-mcp-alloydb/) pour créer un dépôt Docker dans Artifact Registry pour vos images d'interface.

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

Ensuite, créez l'image Docker pour votre application d'interface à l'aide de Cloud Build. Exécutez cette commande à partir du répertoire racine de votre projet :

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

Enfin, nous allons déployer le frontend sur Cloud Run à l'aide de la commande suivante :

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

Vous devriez obtenir un résultat semblable à celui-ci, indiquant que votre frontend a bien été déployé :

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

Ouvrez votre navigateur Web et utilisez l'URL du service de l'étape précédente pour ouvrir l'application que vous venez de déployer, optimisée par votre agent d'IA.

9. Exécuter notre agent

Votre assistant IA Finn, l'agent de la boutique de sport, est désormais entièrement déployé et prêt à vous aider pour vos achats.

Ouvrez votre navigateur Web et accédez à l'URL du service de votre application frontend de l'étape précédente. L'URL doit respecter le format suivant : https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Une fois le frontend chargé, cliquez sur le bouton en haut à droite (généralement intitulé "Se connecter" ou une invite similaire) pour vous authentifier à l'aide de vos identifiants Google. Cette action utilisera la configuration OAuth que vous avez définie précédemment.

Une fois l'authentification réussie, vous pouvez interagir avec Finn. Cliquez sur le bouton "Acheter maintenant" pour commencer votre expérience d'achat conversationnelle.

Utilisez le script suivant pour tester les différentes fonctionnalités de votre agent d'IA. Copiez et collez ces requêtes dans l'interface de chat, une par une :

Bonjour Finn !
Je cherche des chaussures de course pour un ultra-trail
Dis-m'en plus sur Ultra Glide
Ajoute des Ultra Glide, taille 40, couleur rouge/gris à ma liste de courses
Affiche ma liste de courses
Trouver des magasins à proximité
Veuillez passer une commande en utilisant ma liste de courses pour le magasin Sports Diagonal Mar
Vérifier l'état de mes commandes
Veuillez lister les modes de livraison pour le magasin Sports Diagonal Mar.
Modifier le mode de livraison de ma commande [YOUR_ORDER_NUMBER] pour la livraison express
Vérifier l'état de mes commandes
Merci Finn !

Pour une démonstration visuelle de l'agent Finn déployé et de ses capacités, regardez la vidéo ci-dessous :

Démonstration d'un assistant IA pour agent sportif optimisé par AlloyDB

10. Résultats

Après avoir exécuté le script précédent, vous avez validé l'intégration complète de votre agent ADK, sa connexion à AlloyDB et son utilisation de la boîte à outils MCP. Cette section met en avant les principales fonctionnalités que vous avez implémentées.

Service d'autorisation

La boîte à outils MCP pour les bases de données permet de fédérer un service d'autorisation (plus précisément, Google Sign-In dans cet atelier de programmation) pour authentifier les utilisateurs dans votre application. Avec MCP Toolbox, votre ID client OAuth permet de valider l'identité de l'utilisateur lorsqu'un outil est appelé.

Ce mécanisme d'authentification robuste constitue une excellente solution pour protéger votre application agentique contre l'injection de code dans les requêtes, un type d'attaque dans lequel une entrée malveillante tente de contourner ou de manipuler le comportement prévu de l'agent. Pour en savoir plus, consultez l'article Wikipédia sur l'injection de requêtes .

Dans cette application, cette technique est utilisée lorsqu'un utilisateur demande à "vérifier l'état de ses commandes" ou à "afficher sa liste de courses". L'agent est conçu pour n'afficher que les commandes appartenant à l'utilisateur authentifié, ce qui empêche tout accès non autorisé aux informations sur les commandes.

Vector Search

Votre application agentive utilise AlloyDB pour PostgreSQL pour fournir des fonctionnalités de requête avancées, en particulier grâce à la recherche vectorielle. AlloyDB permet de générer des embeddings en ligne directement dans la base de données à l'aide de fonctions SQL.

Cette fonctionnalité puissante permet à l'agent de traduire l'entrée en langage naturel d'un utilisateur en une représentation numérique intégrée. Il peut ensuite exécuter une recherche de similarités dans votre catalogue de produits (ou d'autres données pertinentes) en fonction de ces embeddings, ce qui permet d'obtenir des résultats de recherche très pertinents.

Dans votre application, vous pouvez tester cette technique en demandant à Finn : "Je cherche des chaussures de course pour un ultra-trail".

Fonctionnalités géospatiales (PostGIS)

AlloyDB pour PostgreSQL est 100 % compatible avec les fonctionnalités PostgreSQL standards. Dans cette application, nous utilisons l'extension PostgreSQL populaire PostGIS pour fournir des fonctionnalités de localisation géospatiale à l'agent.

Lorsque vous demandez à l'agent "Trouve des magasins près de moi", il exécute un outil qui utilise les index PostGIS de la base de données pour localiser efficacement les magasins les plus proches de l'emplacement spécifié ou déduit de l'utilisateur.

11. (Facultatif) Tester la fonctionnalité de langage naturel vers SQL d'AlloyDB AI

Cette section présente une fonctionnalité avancée en pré-GA d'AlloyDB pour PostgreSQL : Langage naturel vers SQL. Cette fonctionnalité vous permet de générer des requêtes SQL directement à partir de requêtes en langage naturel, en exploitant la puissance de l'IA dans votre base de données.

Important : Comme il s'agit d'une fonctionnalité en pré-GA, vous devez vous inscrire et activer l'accès pour votre projet Google Cloud, votre cluster AlloyDB et votre base de données.

S'inscrire pour y accéder : veuillez remplir ce formulaire pour demander l'accès à votre projet.
Documentation : pour en savoir plus sur l'utilisation d'AlloyDB AI Natural Language to SQL, consultez la documentation officielle.

Une fois que vous vous êtes inscrit et que vous avez confirmé l'accès à votre projet, suivez les étapes ci-dessous dans AlloyDB Studio.

Connectez-vous à AlloyDB à l'aide des identifiants que vous avez créés lors de la création du cluster :

Nom d'utilisateur : "postgres"
Base de données : "store"
Mot de passe : "alloydb"

1) Créez l'extension alloydb_ai_nl. Cette extension fournit les fonctions nécessaires aux fonctionnalités de langage naturel AlloyDB/AI.

CREATE EXTENSION alloydb_ai_nl cascade;

2) Créez une configuration pour votre application. Une configuration définit le contexte de schéma que le modèle d'IA utilisera pour comprendre votre base de données.

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

3) Enregistrez le schéma / les tables avec la configuration. Ajoutez à la configuration les tables et les schémas spécifiques avec lesquels l'agent de votre application interagira.

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) Générez le contexte pour le schéma / les tables. Cette étape traite les tables enregistrées pour générer le contexte nécessaire au modèle d'IA. Cette opération peut prendre environ 2 à 3 minutes.

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

5) Vérifiez le contexte généré automatiquement pour des tables et des colonnes spécifiques (facultatif). Vous pouvez inspecter le contexte généré pour comprendre comment le modèle d'IA interprète votre schéma.

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';

Vous trouverez un outil appelé "check-inventory-by-store-brand-category" dans le fichier "tools.yaml" de notre agent. Cet outil utilise AlloyDB Natural Language to SQL :

Ouvrez un navigateur Web et utilisez l'URL du service pour ouvrir l'application : "https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app".

Ensuite, utilisez le script suivant dans l'interface de chat pour tester cette nouvelle fonctionnalité :

Bonjour Finn !
Quelle est la quantité totale de produits de la catégorie "Running" de Salomon en stock dans le magasin "Sports Diagonal Mar" ?

Pour afficher la requête SQL réelle qu'AlloyDB AI a générée à partir de votre saisie en langage naturel, revenez à AlloyDB Studio et exécutez la requête suivante :

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';

L'instruction SQL générée par AlloyDB AI s'affiche.

12. Effectuer un nettoyage

Pour éviter que les ressources utilisées dans cet atelier soient facturées sur votre compte Google Cloud, procédez comme suit :

Dans la console Google Cloud, accédez à la page Gérer les ressources.
Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur "Supprimer".
Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur "Arrêter" pour supprimer le projet.

13. Félicitations

Félicitations ! Vous avez créé une application d'IA agentive axée sur les données à l'aide de l'ADK, de MCP Toolbox for Databases et d'AlloyDB pour PostgreSQL.

Pour en savoir plus, consultez la documentation produit : Kit de développement d'agents, Boîte à outils MCP pour les bases de données et AlloyDB pour PostgreSQL.