Créer une chaîne d'approvisionnement autonome avec Gemini 3 Flash et AlloyDB AI

1. Présentation

L'ère des "chatbots qui lisent" touche à sa fin. Nous entrons dans l'ère de la vision agentique.

Dans cet atelier de programmation, nous allons implémenter l'ingénierie d'IA déterministe, une pratique qui consiste à créer des systèmes d'IA qui ne devinent pas. Les modèles d'IA standards "hallucinent" (devinent) souvent lorsqu'on leur demande de compter des éléments dans une image complexe. Dans une chaîne d'approvisionnement, une supposition est dangereuse. Si une IA estime que vous avez 12 articles alors que vous en avez 15, cela entraîne des erreurs coûteuses.

Nous allons créer un agent de chaîne d'approvisionnement autonome à l'aide de la nouvelle boucle Penser, Agir, Observer dans Gemini 3 Flash. Elle ne se contente pas de regarder, elle enquête.

Architecture déterministe

Nous allons commencer par un système "aveugle" et "amnésique". Vous allez "éveiller" manuellement ses sens un par un :

1. Les yeux (agent Vision) : nous activons Gemini 3 Flash avec l'exécution de code. Au lieu de prédire des jetons pour deviner un nombre, le modèle écrit du code Python (OpenCV) pour compter les pixels de manière déterministe.
2. Mémoire (agent fournisseur) : nous activons AlloyDB AI avec ScaNN (Scalable Nearest Neighbors). Cela permet à l'agent de retrouver le fournisseur exact d'une pièce parmi des millions d'options en quelques millisecondes.
3. La poignée de main (protocole A2A) : nous activons la communication Agent-to-Agent à l'aide d'un fichier agent_card.json standardisé , ce qui permet à l'agent Vision de commander des stocks de manière autonome auprès de l'agent Fournisseur.

Ce que vous allez faire

• Un agent Vision qui effectue des "calculs visuels" sur les flux de caméras.
• Un agent fournisseur basé sur AlloyDB ScaNN pour une recherche vectorielle à grande vitesse.
• Un frontend Control Tower avec des mises à jour WebSocket en temps réel pour visualiser la boucle autonome.

Points abordés

• Comment activer Agentic Vision avec gemini-3-flash-preview à l'aide de l'API Gemini.
• Découvrez comment implémenter la recherche vectorielle à l'aide de l'opérateur <=> (distance cosinus) dans AlloyDB.
• Découvrez comment faire le pont entre Cloud Shell et AlloyDB à l'aide du proxy d'authentification.

Conditions requises

• Un navigateur tel que Chrome ou Firefox
• Un projet Google Cloud avec facturation activée.
• Une clé API Gemini (niveau sans frais disponible sur Google AI Studio) pour l'agent Vision.

2. Avant de commencer

Créer un projet

1. Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
2. 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.

Pour essayer cet atelier de programmation, vous pouvez utiliser le lien vers l'avoir de facturation de l'essai GCP : https://bit.ly/cvs14-ghj.

Comment utiliser des avoirs à l'aide de ce lien ? Parrainer.

3. Vous allez utiliser Cloud Shell, un environnement de ligne de commande exécuté dans Google Cloud. Cliquez sur "Activer Cloud Shell" en haut de la console Google Cloud.

4. 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

Et voilà !

Vous êtes maintenant prêt pour la configuration en un clic. La section suivante :

• Ouvrir Cloud Shell automatiquement
• Cloner le dépôt
• vous guider tout au long de la configuration dans un tutoriel interactif ;

3. Configuration en un clic dans Cloud Shell

Nous avons simplifié la configuration en un tutoriel guidé dans Cloud Shell. Tout est automatisé : provisionnement de l'infrastructure, configuration d'AlloyDB et du proxy d'authentification, et seeding de la base de données.

Lancer le tutoriel Cloud Shell

⚠️ IMPORTANT : Avant de cliquer, vous verrez une boîte de dialogue de sécurité vous demandant Ouvrir dans Cloud Shell. Cette option s'affiche AVANT le clonage des dépôts.

Vous devez respecter les points suivants :

1. ✅ Cochez la case Trust repo (Faire confiance au dépôt).
2. ✅ Cliquez sur Confirmer.

Sinon, le dépôt ne sera pas cloné.

Prêt à vous lancer ? Cliquez pour ouvrir le projet avec un tutoriel détaillé :

Exécuter en un clic

Et ensuite ?

1. Cloud Shell s'ouvre avec le dépôt précloné.
2. Un panneau de tutoriel s'affiche à droite et fournit des instructions détaillées.
3. Vous serez guidé tout au long de la procédure :

• Obtenir votre clé API Gemini (niveau sans frais disponible)
• Définir votre projet GCP dans le terminal
• Exécution de la configuration (vérification des API, activation si nécessaire, provisionnement d'AlloyDB : environ 15 minutes)
• Apporter deux modifications clés au code (activer la vision et la mémoire)
• Créer la fiche de l'agent (protocole A2A)
• Démarrer tous les services

Ce tutoriel est interactif : chaque étape est numérotée et votre progression est suivie.

📌 Automatisé : le script de configuration vérifie l'authentification, les API et la configuration du projet. Il vous invite à agir si un élément requiert votre attention.

💡 Redémarrage sans risque : si la configuration se bloque ou échoue, vous pouvez réexécuter sh setup.sh sans risque. Le script détecte les instances AlloyDB existantes et ignore le provisionnement, en reprenant là où vous vous étiez arrêté.

Autre option : configuration manuelle

Si vous préférez le contrôle manuel :

1. Ouvrez Cloud Shell et vérifiez que votre projet est défini.

gcloud config get-value project

2. Si nécessaire, définissez votre projet.

gcloud config set project YOUR_PROJECT_ID

3. Cloner le dépôt

git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git
cd visual-commerce-gemini-3-alloydb

4. Exécuter la configuration

sh setup.sh

Suivez les instructions de configuration qui s'affichent à l'écran.

Étape suivante : le tutoriel vous guide tout au long des étapes restantes. Une fois l'opération terminée, passez à la section 4 pour comprendre ce qui s'est passé en arrière-plan.

4. En coulisses : proxy d'authentification et seeding de base de données

Remarque : Si vous avez suivi le tutoriel complet sur Cloud Shell, toutes ces étapes ont été automatisées. Cette section explique ce qui s'est passé en coulisses.

Problème : AlloyDB se trouve dans un VPC privé. Cloud Shell se trouve en dehors. La connexion directe est impossible.

Solution : le proxy d'authentification AlloyDB crée un tunnel sécurisé et authentifié par IAM depuis 127.0.0.1:5432 sur Cloud Shell vers votre instance AlloyDB. Si l'adresse IP publique est activée pour votre instance, le proxy l'utilise. Sinon, il se connecte via l'adresse IP privée du VPC.

Ce qu'a fait setup.sh

1. Votre instance AlloyDB (cluster, région, projet) a été détectée automatiquement.
2. Création du fichier .env avec tous les identifiants (GEMINI_API_KEY, DB_PASS, détails AlloyDB)
3. Téléchargement et démarrage du proxy d'authentification (avec --public-ip le cas échéant)
4. Base de données enrichie avec huit exemples de pièces d'inventaire et un index ScaNN

Votre fichier .env est prêt. Toutes les futures exécutions chargeront automatiquement les identifiants.

Vérifier que l'opération a fonctionné

Assurez-vous d'être toujours à la racine du dépôt.

pwd  # Should end with: visual-commerce-gemini-3-alloydb

Vérifier que le proxy d'authentification est en cours d'exécution

ps aux | grep alloydb-auth-proxy

Ce qui a été créé

• Table d'inventaire avec huit parties et des embeddings de 768 dimensions
• Index ScaNN (idx_inventory_scann) pour une recherche vectorielle rapide

Erreurs courantes :

• "DB_PASS not set" (DB_PASS non défini) : réexécutez sh setup.sh pour recréer .env.
• Connexion refusée : le proxy d'authentification peut avoir besoin de plus de temps. Patientez 30 secondes, puis réessayez.
• "Aucune instance trouvée" : vérifiez le déploiement : gcloud alloydb instances list
• Erreur de bus (le proxy d'authentification s'arrête) : corruption du fichier binaire. Correction : rm alloydb-auth-proxy && sh setup.sh

5. Étape 1 : La mémoire (agent fournisseur)

Remarque : Si vous avez suivi le tutoriel Cloud Shell, vous avez déjà modifié ce code. Cette section explique pourquoi c'est important et comment cela fonctionne.

L'agent fournisseur se souvient de millions de pièces à l'aide d'AlloyDB ScaNN. Nous le démarrons en tant que serveur A2A, puis corrigeons la requête vectorielle.

The Audit: The Amnesiac

Si vous interrogez l'agent fournisseur maintenant (avec le code SQL de l'espace réservé), il renvoie la première ligne qu'il trouve, et non la correspondance la plus proche. Il n'a aucune notion de similarité. Il est amnésique.

Démarrer l'agent fournisseur

Le serveur A2A (main.py) délègue à agent_executor.py, qui fait le lien entre le protocole et la logique métier dans inventory.py.

💡 Conseil de dépannage : Si vous recevez des erreurs "adresse déjà utilisée", arrêtez les processus existants et réessayez :

pkill -f uvicorn #Kill all uvicorn processes

Étape 1 : Accédez au répertoire d'agents.

cd agents/supplier-agent

Étape 2 : Installez les dépendances

pip install -r requirements.txt

Étape 3 : Démarrez le serveur de l'agent

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

> /dev/null 2>&1 & exécute le serveur en arrière-plan et supprime la sortie pour ne pas interrompre votre terminal.

Étape 4 : Vérifiez que l'agent est en cours d'exécution (attendez deux à trois secondes après le démarrage).

curl http://localhost:8082/.well-known/agent-card.json

Résultat attendu : JSON avec la configuration de l'agent (doit être renvoyé sans erreur)

Embeddings sémantiques réels

Lors de la configuration, la base de données a été initialisée avec de véritables embeddings sémantiques générés à l'aide du modèle text-embedding-005 du SDK Google Gen AI. Cela permet d'assurer une correspondance précise de la similarité, et non des vecteurs aléatoires. Le processus d'amorçage prend environ 10 secondes pour 13 éléments échantillons. Il utilise la génération d'embeddings parallèles pour créer des vecteurs de 768 dimensions significatifs qui capturent la signification sémantique de chaque partie.

Détour AlloyDB : pourquoi ScaNN ?

Remarque : La recherche vectorielle standard (HNSW) est gourmande en mémoire. Lorsque votre inventaire atteint 100 millions de pièces, l'index devient trop volumineux pour la RAM. ScaNN (Scalable Nearest Neighbors) utilise la quantification vectorielle. Il compresse les vecteurs pour que l'index tienne dans le cache L2 du processeur. Il est donc jusqu'à 10 fois plus rapide que l'index HNSW standard.

Solution : implémenter l'opérateur <=>

L'agent est fourni avec une requête de substitution. Nous devons activer la recherche vectorielle ScaNN.

Étape 1 : Ouvrez le fichier d'inventaire

cd agents/supplier-agent

Étape 2 : Recherchez le TODO dans inventory.py

Recherchez la fonction find_supplier() vers les lignes 47 à 60. Cette page vous indique les informations suivantes :

# ============================================================
# CODELAB STEP 1: Implement ScaNN Vector Search
# ============================================================
# TODO: Replace this placeholder query with ScaNN vector search

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

Étape 3 : Remplacez le code SQL de l'espace réservé par la recherche vectorielle ScaNN

Supprimez ces deux lignes :

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

Remplacez-les par :

sql = """
SELECT part_name, supplier_name
FROM inventory
ORDER BY part_embedding <=> %s::vector
LIMIT 1;
"""
cursor.execute(sql, (embedding_vector,))

À quoi sert le script ?

• <=> est l'opérateur de distance cosinus dans PostgreSQL.
• ORDER BY part_embedding <=> %s::vector trouve la correspondance la plus proche (distance la plus faible = signification sémantique la plus proche).
• %s::vector convertit votre tableau d'embedding au type vectoriel de PostgreSQL.
• LIMIT 1 ne renvoie que la correspondance la plus proche.
• L'index ScaNN accélère automatiquement cette requête.

Étape 4 : Enregistrez le fichier (Ctrl+S ou Cmd+S).

L'agent utilise désormais la recherche sémantique au lieu de renvoyer des résultats aléatoires.

Validation

Testez la découverte A2A et l'inventaire :

curl http://localhost:8082/.well-known/agent-card.json

python3 -c "
from inventory import find_supplier
import json
vec = [0.1]*768
r = find_supplier(vec)
if r:
    result = {'part': r[0], 'supplier': r[1]}
    if len(r) > 2:
        result['distance'] = float(r[2]) if r[2] else None
    print(json.dumps(result))
else:
    print('No result found')
"

Résultat attendu : agent-card.json renvoie la carte de l'agent. L'extrait de code Python renvoie une pièce et un fournisseur à partir des données initiales.

Erreurs courantes :

• "Fichier ou répertoire inexistant" : vous n'êtes pas à la racine du dépôt. Exécutez la commande cd pour revenir au répertoire personnel, puis cd visual-commerce-gemini-3-alloydb, ou utilisez pwd pour trouver votre emplacement.
• Port 8082 in use (Port 8082 utilisé) : arrêtez le processus existant : lsof -ti:8082 | xargs kill -9
• ModuleNotFoundError : installez les dépendances : pip install -r requirements.txt
• Échec de la connexion à la base de données : assurez-vous que le proxy d'authentification est toujours en cours d'exécution.
• Le script de validation échoue : vérifiez que l'amorçage s'est terminé correctement à l'étape 4.

6. Étape 2 : Les yeux (agent Vision)

Remarque : Si vous avez suivi le tutoriel Cloud Shell, vous avez déjà activé l'exécution de code. Cette section explique l'architecture et pourquoi cette approche élimine les hallucinations.

Bien que la base de données soit accessible, réveillons les yeux à l'aide de Gemini 3 Flash. L'agent Vision effectue des "calculs visuels" via l'exécution de code. Le serveur A2A (main.py) délègue à agent_executor.py, qui appelle agent.py pour l'analyse Gemini.

L'audit : l'hallucination

Si vous demandez à un modèle multimodal standard "Combien de boîtes y a-t-il sur cette image désordonnée ?", il traite l'image comme un instantané statique et fait une estimation.

• Le modèle répond : "Je vois environ 12 boîtes."
• Réalité : il y a 15 boîtes.
• Résultat : Échec de la chaîne d'approvisionnement.

La solution : réveiller la boucle Réfléchir-Agir-Observer

Nous activons Code Execution et ThinkingConfig pour que le modèle écrive du code Python (OpenCV) afin d'effectuer un comptage déterministe.

1. Ouvrez agents/vision-agent/agent.py .
2. Accédez à la section GenerateContentConfig.
3. Décommentez le bloc thinking_config=types.ThinkingConfig(...) et tools=[types.Tool(code_execution=...)] .
4. Le client est déjà configuré pour utiliser votre GEMINI_API_KEY à partir de l'environnement.

Remarque : thinking_level="LOW" équilibre la vitesse et la précision. Valeurs valides : "MINIMAL", "LOW", "MEDIUM", "HIGH". Nécessite google-genai>=1.56.0.

Remarque sur l'architecture : L'agent Vision utilise l'API Gemini (clé API), tandis que l'agent Fournisseur utilise les embeddings Vertex AI (identifiants GCP). Cette approche hybride permet de simplifier le composant Vision tout en conservant les fonctionnalités de base de données de niveau entreprise.

Fichier : agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="LOW",  # Valid: "MINIMAL", "LOW", "MEDIUM", "HIGH"
        include_thoughts=False    # Set to True for debugging
    ),
    # CODELAB STEP 2: Uncomment to enable code execution
    tools=[types.Tool(code_execution=types.ToolCodeExecution)]
)

Pourquoi thinking_level="LOW" ?

Pour cette tâche spécifique (compter des éléments via l'exécution de code), le niveau "FAIBLE" fournit un budget de raisonnement suffisant pour :

• Planifier la structure du script Python
• Choisir l'approche de traitement d'image à utiliser
• Vérifiez que le nombre correspond à celui des cadres de délimitation.

Si vous choisissez "ÉLEVÉE", la latence et les coûts seront multipliés par deux ou trois, sans améliorer la précision des tâches déterministes. Réservez le niveau "ÉLEVÉ" pour les raisonnements complexes en plusieurs étapes (par exemple, "Analyse cette perturbation de la chaîne d'approvisionnement et recommande trois fournisseurs alternatifs en justifiant ton choix.")

L'optimisation du rapport coût/performances est une compétence clé pour l'ingénierie de l'IA de production : elle permet d'adapter la profondeur du raisonnement à la complexité de la tâche.

Démarrer l'agent Vision

🔄 Vérification du chemin d'accès : si vous êtes toujours dans agents/supplier-agent/, revenez d'abord à la racine du dépôt avec cd ../..

Étape 1 : Accédez au répertoire des agents Vision

cd agents/vision-agent

Étape 2 : Installez les dépendances

pip install -r requirements.txt

Étape 3 : Démarrez le serveur de l'agent Vision

uvicorn main:app --host 0.0.0.0 --port 8081 > /dev/null 2>&1 &

> /dev/null 2>&1 & exécute le serveur en arrière-plan et supprime la sortie pour ne pas interrompre votre terminal.

Validation

Test de la découverte A2A :

curl http://localhost:8081/.well-known/agent-card.json

Résultat attendu : JSON avec le nom et les compétences de l'agent. Vous testerez le comptage de vision réel avec l'interface utilisateur de la tour de contrôle à l'étape 8.

Erreurs courantes :

• Aucun fichier ni répertoire de ce type : vous n'êtes pas à la racine du dépôt. Utilisez cd ../.. pour revenir à la racine du dépôt ou vérifiez votre emplacement avec pwd.
• Port 8081 en cours d'utilisation : arrêtez le processus existant : lsof -ti:8081 | xargs kill -9
• GEMINI_API_KEY non défini : vérifiez que votre fichier .env existe dans la racine du dépôt avec cat .env | grep GEMINI_API_KEY
• Clé API non valide : vérifiez que votre clé est correcte et qu'elle n'a pas expiré.
• google-genai introuvable : installez les dépendances : pip install -r requirements.txt

7. Étape 3 : La poignée de main (carte d'agent A2A)

Remarque : Si vous avez suivi le tutoriel Cloud Shell, vous avez déjà créé cette fiche d'agent. Cette section explique le protocole A2A et pourquoi il permet la composition d'agents plug-and-play.

Notre agent voit le problème (Vision) et connaît le fournisseur (Mémoire). Le protocole A2A permet la découverte dynamique : le frontend apprend à communiquer avec chaque agent en lisant sa carte.

A2A vs API REST traditionnelles

Aspect	REST traditionnel	Protocole A2A
Découverte des points de terminaison	URL codées en dur dans la configuration	Dynamique via /.well-known/agent-card.json
Description de la fonctionnalité	Documentation de l'API (pour les humains)	Compétences (lisibles par une machine)
Intégration	Code manuel par service	Correspondance sémantique : "J'ai besoin d'une recherche d'inventaire" → découverte de la skill
Nouvel agent ajouté	Mettre à jour les configurations de tous les clients	Aucune configuration requise : découverte automatique

Avantage concret : dans un microservice traditionnel, si vous ajoutez un troisième "agent logistique", vous devez mettre à jour le code de la tour de contrôle avec son URL et son contrat d'API. Avec A2A, la Control Tower le découvre automatiquement et comprend ses capacités grâce à des descriptions de compétences en langage naturel.

C'est pourquoi A2A permet la composition d'agents plug-and-play, le modèle architectural pour les systèmes autonomes.

Solution : créer la fiche de l'agent

Nous devons définir ce que l'agent fournisseur peut faire.

1. Copiez agents/supplier-agent/agent_card_skeleton.json dans agents/supplier-agent/agent_card.json.
2. Modifiez le fichier pour remplacer les espaces réservés :

Avant (squelette) :

{
  "name": "___FILL: agent-name ___",
  "description": "___FILL: what-this-agent-does ___"
}

Après (vos modifications) :

{
  "name": "Acme Supplier Agent",
  "description": "Autonomous fulfillment for industrial parts via AlloyDB ScaNN.",
  "version": "1.0.0",
  "skills": [{
    "id": "search_inventory",
    "name": "Search Inventory",
    "description": "Searches the warehouse database for semantic matches using AlloyDB ScaNN vector search.",
    "tags": ["inventory", "search", "alloydb"],
    "examples": ["Find stock for Industrial Widget X-9", "Who supplies ball bearings?"]
  }]
}

3. Redémarrez l'agent fournisseur pour qu'il charge la nouvelle carte :

Étape 1 : Arrêtez l'agent en cours d'exécution

pkill -f "uvicorn main:app.*8082"

Étape 2 : Accédez au répertoire d'agents

cd agents/supplier-agent

Étape 3 : Redémarrez l'agent

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

> /dev/null 2>&1 & exécute le serveur en arrière-plan et supprime la sortie pour ne pas interrompre votre terminal.

Étape 4 : Vérifiez la nouvelle fiche d'agent (attendez deux à trois secondes après le démarrage).

curl http://localhost:8082/.well-known/agent-card.json

Résultat attendu : JSON avec votre nom, votre description et vos compétences renseignés.

8. Étape 4 : La tour de contrôle

Remarque : Si vous avez suivi le tutoriel Cloud Shell, vos services sont déjà en cours d'exécution. Passez à la section "Tester le système" ci-dessous pour accéder à la Control Tower et observer le workflow autonome en action.

Exécutez l'interface utilisateur Control Tower avec FastAPI et WebSockets. Il découvre les agents via A2A et orchestre la boucle complète avec des mises à jour en temps réel.

Démarrer tous les services

La méthode la plus simple pour démarrer tous les services :

Vérifier que vous êtes à la racine du dépôt

pwd  # Should end with: visual-commerce-gemini-3-alloydb

Ensuite,

sh run.sh

Cette commande unique démarre :

• Proxy d'authentification AlloyDB (s'il n'est pas en cours d'exécution)
• Agent Vision sur le port 8081
• Agent fournisseur sur le port 8082
• Control Tower sur le port 8080

Attendez environ 10 secondes que tous les services s'initialisent.

💡 Conseil de dépannage : Si run.sh échoue avec des erreurs address already in use (adresse déjà utilisée) :

Arrêtez tous les services et réessayez

pkill -f uvicorn

sh run.sh

Cela se produit si des services sont toujours en cours d'exécution à la suite d'une tentative précédente.

Tester le système

Accéder à Control Tower :

1. Cliquez sur le bouton Aperçu sur le Web (icône en forme d'œil 👁️) dans la barre d'outils Cloud Shell.
2. Sélectionnez Prévisualiser sur le port 8080.
3. Le tableau de bord Control Tower s'ouvre dans un nouvel onglet.

Remarque : Le frontend utilise des WebSockets en temps réel pour les mises à jour des agents en direct. Vous verrez les fiches des agents se mettre à jour au fur et à mesure qu'ils réfléchissent, analysent et agissent, sans avoir besoin d'actualiser la page.

Exécuter la démo :

1. En haut à droite : état de la connexion (point vert "En ligne"), bouton bascule du mode DÉMO/AUTO et commandes audio
2. Centre : canevas principal du workflow avec importation d'images et visualisation de l'analyse
3. Panneaux latéraux (qui s'affichent pendant l'analyse) : chronologie du workflow (à gauche), suivi de la progression et visionneuse de code (à droite)

Option 1 : Démarrage rapide (recommandé)

1. Sur la page d'accueil, vous trouverez une section Démarrage rapide avec des exemples d'images.
2. Cliquez sur une image exemple pour lancer automatiquement l'analyse.
3. Observez le workflow autonome (environ 30 à 45 secondes).

Option 2 : Importer votre propre fichier

1. Glissez-déposez une image d'entrepôt/d'étagère (PNG, JPG, jusqu'à 10 Mo) ou cliquez pour parcourir.
2. Cliquez sur Initiate Autonomous Workflow (Lancer le workflow autonome).
3. Observer le pipeline en quatre étapes

Ce qui se passe :

1. Découverte d'agents : les modaux du protocole A2A affichent les cartes de l'agent Vision et de l'agent Fournisseur avec leurs compétences et leurs points de terminaison.
2. Analyse de vision : Gemini 3 Flash génère et exécute du code Python (OpenCV) pour compter les éléments. La barre de progression affiche les sous-étapes. Des cadres de délimitation sont superposés aux éléments détectés. Le badge de résultat indique "✓ Code vérifié" ou "~ Estimation".
3. Supplier Match : animation de la recherche vectorielle ScaNN AlloyDB. Affichages de requêtes de recherche (par exemple, "boîtes métalliques industrielles"). La fiche de résultat indique la pièce correspondante, le fournisseur et le score de confiance.
4. Commande passée : carte de reçu avec l'ID de commande, la quantité et les détails

Conseil : Laissez le mode DÉMO activé (en haut à droite) pour mettre en pause chaque étape lors des présentations. En mode AUTO, le workflow s'exécute en continu.

Que s'est-il passé ?

La tour de contrôle a utilisé le protocole A2A pour découvrir les deux agents via /.well-known/agent-card.json, orchestrer l'analyse de vision (Gemini 3 Flash avec exécution de code), effectuer une recherche vectorielle (AlloyDB ScaNN) et passer une commande autonome, le tout avec des mises à jour WebSocket en temps réel. Chaque agent expose ses capacités via la norme A2A, ce qui permet une composition plug-and-play sans SDK personnalisés. En savoir plus : Protocole A2A

Dépannage

Erreurs liées au chemin d'accès :

• L'erreur No such file or directory (Fichier ou répertoire inexistant) s'affiche lorsque vous exécutez des commandes : vous n'êtes pas à la racine du dépôt.

# Check where you are
pwd

# If you're lost, navigate to home and back to repo
cd
cd visual-commerce-gemini-3-alloydb

Erreurs de service :

• "Adresse déjà utilisée" : les processus des exécutions précédentes sont toujours actifs.

# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents

• Les services ne démarrent pas : vérifiez si les ports sont occupés :

# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent

• "Connexion refusée" à AlloyDB : vérifiez que le proxy d'authentification est en cours d'exécution :

ps aux | grep alloydb-auth-proxy

Problèmes de connexion AlloyDB :

Si le message "Échec de la connexion au serveur 127.0.0.1, port 5432" s'affiche :

Si le message "Échec de la connexion au serveur 127.0.0.1, port 5432" s'affiche :

1. Vérifier le proxy d'authentification : ps aux | grep alloydb-auth-proxy
2. Vérifiez que l'adresse IP publique est activée : gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
3. Pour le développement local (pas Cloud Shell) :
4. Problème : Cloud Shell fonctionne automatiquement, mais les machines locales ont besoin de réseaux autorisés.
5. Solution : réexécutez sh setup.sh et choisissez l'option 1 (autoriser 0.0.0.0/0) lorsque vous y êtes invité.
6. Remarque sur la sécurité : Même avec 0.0.0.0/0, la connexion nécessite :
7. Identifiants GCP valides (identifiants par défaut de l'application)
8. Mot de passe de la base de données
9. Chiffrement mTLS (géré par le proxy d'authentification)

9. Nettoyage

Pour éviter des frais, détruisez toutes les ressources à l'aide du script de nettoyage automatique :

# From repo root
sh cleanup.sh

Les éléments suivants sont supprimés de manière sécurisée :

• Cluster AlloyDB (principal facteur de coût)
• Services Cloud Run (si déployés)
• Comptes de service associés

Le script vous demandera de confirmer l'opération avant de supprimer quoi que ce soit.

10. Références et lectures complémentaires

Toutes les affirmations techniques de cet atelier de programmation sont vérifiées à partir de la documentation officielle de Google Cloud et de Google IA.

Documentation officielle

Gemini 3 Flash :

• API Code Execution : https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
• Guide du développeur : https://ai.google.dev/gemini-api/docs/gemini-3
• Documentation sur le modèle : https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
• Fiche du modèle : https://deepmind.google/models/gemini/flash/

AlloyDB AI et ScaNN :

• Benchmarks de performances ScaNN : https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
• Comprendre l'index ScaNN : https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
• Présentation détaillée d'AlloyDB/AI : https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
• Bonnes pratiques pour le réglage : https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
• Documentation AlloyDB : https://cloud.google.com/alloydb/docs

Informations tarifaires :

• Tarifs de l'API Gemini : https://ai.google.dev/gemini-api/docs/pricing
• Tarifs AlloyDB : https://cloud.google.com/alloydb/pricing
• Tarification de Vertex AI : https://cloud.google.com/vertex-ai/pricing

Affirmations vérifiées sur les performances

Fonctionnalité	Demander	Source
ScaNN vs HNSW (filtré)	10 fois plus rapide	Blog Google Cloud (validé)
ScaNN vs HNSW (standard)	4 fois plus rapide	Blog Google Cloud (validé)
Espace mémoire utilisé par ScaNN	3 à 4 fois plus petit	Blog Google Cloud (validé)
Temps de création d'un index ScaNN	8 fois plus rapide	Blog Google Cloud (validé)
Délai d'exécution du code	30 secondes maximum	Documentation Google Cloud (vérifiée)
E/S de fichier d'exécution de code	Non compatible	Documentation Google Cloud (vérifiée)
Comportement avec une température de 0	Résultat déterministe	Validé par la communauté

Autres ressources

Protocole Agent-to-Agent (A2A) :

• A2A normalise la découverte et la communication des agents
• Cartes d'agent diffusées sur /.well-known/agent-card.json
• Norme émergente pour la collaboration entre agents autonomes

Recherche ScaNN :

• Basé sur 12 ans de recherche Google
• Alimente la recherche Google et YouTube à l'échelle du milliard
• Disponibilité générale : octobre 2024
• Premier index vectoriel PostgreSQL adapté aux millions à milliards de vecteurs

11. Mode Défi : améliorez vos compétences d'agent

Vous avez créé une chaîne d'approvisionnement autonome fonctionnelle. Prêt à aller plus loin ? Ces défis appliquent les modèles que vous avez appris à de nouveaux problèmes.

Défi 1 : Recherche basée sur des images (embeddings multimodaux)

Flux actuel : l'agent Vision compte les articles → génère une requête textuelle → l'agent Fournisseur intègre le texte → effectue une recherche dans AlloyDB

Défi : contournez complètement le texte et envoyez l'image recadrée directement à l'agent fournisseur.

Conseils :

1. L'exécution de code de l'agent Vision peut recadrer des éléments individuels à partir de l'image de l'étagère.
2. Le modèle multimodalembedding@001 de Vertex AI peut intégrer directement des images.
3. Modifier inventory.py pour accepter les octets d'image au lieu du texte
4. Mise à jour de la description de la compétence A2A pour indiquer "Accepte : image/jpeg ou texte"

Pourquoi est-ce important ? La recherche visuelle est plus précise pour les pièces à l'apparence complexe (variations de couleur, dommages, différences d'emballage).

Défi 2 : Observabilité – Confiance grâce à la transparence

État actuel : le système fonctionne, mais vous ne pouvez pas voir "sous le capot"

Défi : Inspectez les journaux de requêtes d'AlloyDB pour prouver que la recherche vectorielle est en cours d'exécution.

Étapes :

• Les insights sur les requêtes sont activés par défaut sur AlloyDB. Pour le vérifier, exécutez la commande suivante :

gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"

• Effectuer une recherche de fournisseurs dans l'UI
• Affichez le code SQL réellement exécuté :

gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

Résultat attendu : Vous verrez la requête ORDER BY part_embedding <= > $1::vector LIMIT 1 exacte avec le temps d'exécution.

Pourquoi est-ce important ? L'observabilité renforce la confiance. Lorsque les parties prenantes demandent "Comment cet agent prend-il des décisions ?", vous pouvez leur montrer le plan de requête, et pas seulement le résultat.

Défi 3 : Composition multi-agents

Défi : ajoutez un troisième agent (agent logistique) qui calcule les frais de port en fonction de l'emplacement de l'entrepôt et du poids de l'article.

Architecture :

• Sorties de l'agent Vision : nombre d'articles
• Sorties de l'agent fournisseur : emplacement du fournisseur
• Entrées de l'agent de logistique (NOUVEAU) : destination, poids → sorties : frais de port + heure d'arrivée estimée

Conseil : Le protocole A2A facilite cette tâche. Créez une carte d'agent avec une compétence calculate_shipping. La Control Tower le détectera automatiquement.

Schéma d'apprentissage : il s'agit du cœur de l'architecture orientée agent, qui consiste à créer des systèmes complexes à partir de petits spécialistes composables.

12. Conclusion

Vous êtes bien passé de l'IA générative à l'IA agentique.

Ce que nous avons créé :

• Vision : nous avons remplacé la "devinette" par l'exécution de code (Gemini 3 Flash via clé API).
• Mémoire : nous avons remplacé "recherche lente" par AlloyDB ScaNN (via GCP).
• Action : nous avons remplacé "Intégration de l'API" par le protocole A2A.

Avantages de l'architecture hybride :

Cet atelier de programmation a présenté une approche hybride :

• Agent Vision : utilise l'API Gemini (clé API), niveau simple et sans frais disponible, aucune facturation GCP requise
• Agent fournisseur : utilise GCP (Vertex AI + AlloyDB), conforme et adapté aux entreprises

Voici l'architecture de l'économie autonome. Vous pouvez conserver le code.

Étapes suivantes

• Obtenez votre clé API Gemini (niveau sans frais disponible)
• Consulter la documentation de l'API Gemini
• Consulter la documentation AlloyDB AI
• Découvrir l'exécution de code Gemini