Crea una catena di fornitura autonoma con Gemini 3 Flash e AlloyDB AI

1. Panoramica

L'era dei "chatbot che leggono" sta per finire. Stiamo entrando nell'era della visione agentica.

In questo codelab implementeremo l'ingegneria dell'AI deterministica, una pratica di creazione di sistemi di AI che non fanno ipotesi. I modelli di AI standard spesso "allucinano" (indovinano) quando viene chiesto di contare gli elementi in un'immagine complessa. In una catena di fornitura, un'ipotesi è pericolosa. Se un'IA stima che tu abbia 12 articoli quando in realtà ne hai 15, si verificano errori costosi.

Creeremo un agente della catena di fornitura autonoma utilizzando il nuovo ciclo Pensa, Agisci, Osserva in Gemini 3 Flash. Non si limita a guardare, ma indaga.

Architettura deterministica

Inizieremo con un sistema "cieco" e "amnesico". Dovrai "risvegliare" manualmente i suoi sensi uno alla volta:

The Eyes (Vision Agent): abbiamo attivato Gemini 3 Flash con Esecuzione del codice. Anziché prevedere i token per indovinare un numero, il modello scrive codice Python (OpenCV) per contare i pixel in modo deterministico.
La memoria (agente fornitore): abilitiamo AlloyDB AI con ScaNN (Scalable Nearest Neighbors). In questo modo, l'agente può richiamare il fornitore esatto di un componente tra milioni di opzioni in pochi millisecondi.
L'handshake (protocollo A2A): attiviamo la comunicazione da agente ad agente utilizzando un file agent_card.json standardizzato , consentendo all'agente Vision di ordinare autonomamente le scorte dall'agente fornitore.

Cosa creerai

Un agente di visione che esegue "matematica visiva" sui feed delle videocamere.
Un agente fornitore supportato da AlloyDB ScaNN per la ricerca vettoriale ad alta velocità.
Un frontend Control Tower con aggiornamenti WebSocket in tempo reale per visualizzare il ciclo autonomo.

Obiettivi didattici

Come configurare AlloyDB con incorporamenti vettoriali e indici ScaNN.
Come attivare Agentic Vision con gemini-3-flash-preview utilizzando l'API Gemini.
Come implementare la ricerca vettoriale utilizzando l'operatore <=> (distanza del coseno) in AlloyDB.
Come connettere gli agenti ad AlloyDB utilizzando il connettore Python di AlloyDB.
Come utilizzare il protocollo A2A per il rilevamento dinamico degli agenti.

Requisiti

Un browser, ad esempio Chrome o Firefox
Un progetto Google Cloud con la fatturazione abilitata.
Una chiave API Gemini (livello senza costi disponibile su Google AI Studio) per l'agente Vision.

2. Prima di iniziare

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

Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.

Immagine del pulsante Attiva 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

Configura database [AlloyDB]

Prima di tutto, eseguiamo il provisioning del database. Questa operazione richiede circa 15 minuti, quindi la avvieremo per prima.

Fai clic sul pulsante di seguito per aprire lo strumento di configurazione di AlloyDB in Cloud Shell:

Esegui la configurazione:

Sh run.sh

Utilizza l'anteprima web (icona a forma di occhio 👁️ → Anteprima sulla porta 8080) per aprire la UI di configurazione.
Inserisci l'ID progetto, seleziona una regione (ad es. us-central1) e crea una password del database.

⚠️ SALVA QUESTA PASSWORD: ti servirà quando lo script di configurazione te la chiederà.

Fai clic su Avvia deployment e attendi circa 15 minuti per il provisioning del cluster.

Richiedi il codice

Mentre AlloyDB esegue il provisioning (o una volta terminato), apri il repository del codelab in Cloud Shell:

⚠️ IMPORTANTE: quando fai clic sul pulsante, viene visualizzata una finestra di dialogo di sicurezza. Seleziona la casella "Trust repo" (Considera attendibile il repository) e fai clic su "Confirm" (Conferma).

In alternativa, clona manualmente:

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

cd visual-commerce-gemini-3-alloydb

Configura il progetto

In questo terminale Cloud Shell, verifica che il progetto sia impostato:

gcloud config set project <YOUR_PROJECT_ID>

Abilita l'IP pubblico su AlloyDB

Una volta completato il provisioning di AlloyDB, abilita l'IP pubblico in modo che Python Connector possa connettersi da Cloud Shell:

Vai alla console AlloyDB.
Fai clic sul cluster → fai clic sull'istanza principale
Fai clic su Modifica.
Scorri fino a Connettività IP pubblico e seleziona Abilita IP pubblico.
Fai clic su Aggiorna istanza.

💡 Nota: il connettore Python per AlloyDB gestisce l'autenticazione e la crittografia, quindi non è necessario aggiungere reti esterne autorizzate.

Concedi le autorizzazioni Vertex AI

Per generare incorporamenti, il service account AlloyDB deve avere accesso a Vertex AI. Esegui questo comando nella stessa finestra di Cloud Shell:

PROJECT_ID=$(gcloud config get-value project)


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

Esegui lo script di configurazione

Ora esegui lo script di configurazione, che rileverà automaticamente l'istanza AlloyDB:

sh setup.sh

Cosa fa lo script:

Convalida gcloud CLI, autenticazione, progetto e Python 3
Controlla e abilita le API richieste (AlloyDB, Vertex AI, Compute, Service Networking)
Richiede la chiave API Gemini
Rileva automaticamente l'istanza AlloyDB ed estrae la regione, il cluster e il nome dell'istanza.
Richiede la password del database
Genera il file di configurazione .env
Installa le dipendenze Python

3. Configurazione del database

Al centro della nostra applicazione si trova AlloyDB per PostgreSQL. Utilizzeremo le sue potenti funzionalità vettoriali e l'indice ScaNN per attivare la ricerca semantica quasi in tempo reale, consentendo ai nostri agenti di trovare corrispondenze di inventario in migliaia di record in pochi millisecondi.

In questa sezione, eseguirai il provisioning dello schema, inserirai i dati iniziali e genererai gli embedding, tutto da AlloyDB Studio.

Connettersi ad AlloyDB Studio

Vai all'istanza AlloyDB nella console AlloyDB.
Fai clic su AlloyDB Studio nel riquadro di navigazione a sinistra.
Autentica con:
Nome utente: postgres
Database: postgres
Password: la password che hai impostato durante la creazione del cluster

Attivare le estensioni

AlloyDB fornisce estensioni integrate per vettori e AI. Esegui il seguente SQL in AlloyDB Studio:

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

google_ml_integration: abilita la funzione ai.embedding() per chiamare Vertex AI direttamente da SQL.
vector: archivia ed esegue query su vector embedding a 768 dimensioni.
alloydb_scann: abilita l'indice ScaNN di Google per la ricerca vettoriale ultraveloce.

Creare la tabella dell'inventario

DROP TABLE IF EXISTS inventory;

CREATE TABLE inventory (
    id SERIAL PRIMARY KEY,
    part_name TEXT NOT NULL,
    supplier_name TEXT NOT NULL,
    description TEXT,
    stock_level INT DEFAULT 0,
    part_embedding vector(768)
);

La colonna part_embedding memorizza vettori a 768 dimensioni da text-embedding-005. È questo che alimenta la ricerca semantica.

Inserisci dati di esempio

Inserisci 20 articoli di inventario del magazzino:

INSERT INTO inventory (part_name, supplier_name, description, stock_level) VALUES
('Cardboard Shipping Box Large', 'Packaging Solutions Inc', 'Heavy-duty corrugated cardboard shipping container, 24x18x12 inches', 250),
('Warehouse Storage Container', 'Industrial Supply Co', 'Stackable plastic storage bin with snap-lock lid, blue', 180),
('Product Shipping Boxes', 'Acme Packaging', 'Medium corrugated boxes for warehouse storage, 18x14x10 inches', 320),
('Industrial Widget X-9', 'Acme Corp', 'Heavy-duty industrial coupling for pneumatic systems', 50),
('Precision Bolt M4', 'Global Fasteners Inc', 'Stainless steel M4 allen bolt, 20mm length, grade A2-70', 200),
('Hexagonal Nut M6', 'Metro Supply Co', 'Galvanized steel hex nut M6, DIN 934 standard', 150),
('Phillips Head Screw 3x20', 'Acme Corp', 'Zinc-plated Phillips head wood screw, 3mm x 20mm', 500),
('Wooden Dowel 10mm', 'Craft Materials Ltd', 'Hardwood birch dowel rod, 10mm diameter x 300mm length', 80),
('Rubber Gasket Small', 'SealTech Industries', 'Buna-N rubber gasket, 25mm OD x 15mm ID, oil resistant', 120),
('Spring Tension 5kg', 'Mechanical Parts Co', 'Stainless steel compression spring, 5kg load capacity', 60),
('Bearing 6204', 'Bearings Direct', 'Deep groove ball bearing 6204-2RS, 20x47x14mm sealed', 45),
('Warehouse Shelf Boxes', 'Storage Systems Ltd', 'Standardized warehouse inventory boxes, corrugated, bulk pack', 400),
('Inventory Container Units', 'Supply Chain Pros', 'Modular stackable storage units for warehouse racking', 95),
('Aluminum Extrusion Bar', 'MetalWorks International', 'T-slot aluminum extrusion 20x20mm profile, 1 meter length', 110),
('Cable Tie Pack 200mm', 'ElectroParts Depot', 'Nylon cable ties, 200mm x 4.8mm, UV resistant black, pack of 100', 600),
('Hydraulic Hose 1/2 inch', 'FluidPower Systems', 'High-pressure hydraulic hose, 1/2 inch ID, 3000 PSI rated', 35),
('Safety Goggles Clear', 'WorkSafe Equipment Co', 'ANSI Z87.1 rated clear safety goggles, anti-fog coating', 275),
('Packing Tape Industrial', 'Packaging Solutions Inc', 'Heavy-duty polypropylene packing tape, 48mm x 100m, clear', 450),
('Stainless Steel Sheet 1mm', 'MetalWorks International', '304 stainless steel sheet, 1mm thickness, 300x300mm', 70),
('Silicone Sealant Tube', 'SealTech Industries', 'Industrial-grade RTV silicone sealant, 300ml cartridge, grey', 190);

Concedere le autorizzazioni di incorporamento

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Genera vector embedding

Utilizza la funzione ai.embedding() integrata di AlloyDB per chiamare il modello text-embedding-005 di Vertex AI direttamente da SQL, senza bisogno di codice Python:

UPDATE inventory
SET part_embedding = ai.embedding(
    'text-embedding-005',
    part_name || '. ' || description
)::vector
WHERE part_embedding IS NULL;

In questo modo vengono generati vettori a 768 dimensioni che acquisiscono il significato semantico del nome e della descrizione di ogni parte. L'indice ScaNN li utilizzerà per una ricerca di similarità fulminea. [Il completamento dell'operazione richiede circa 3-5 minuti]

Crea l'indice ScaNN

SET scann.allow_blocked_operations = true;

CREATE INDEX IF NOT EXISTS idx_inventory_scann
ON inventory USING scann (part_embedding cosine)
WITH (num_leaves=5, quantizer='sq8');

Verificare che tutto funzioni

SELECT part_name, supplier_name, stock_level,
       (part_embedding IS NOT NULL) as has_embedding
FROM inventory
ORDER BY id;

Dovresti vedere 20 righe, tutte con has_embedding = true.

4. Informazioni sull'architettura

Prima di apportare modifiche al codice, vediamo come è costruito il sistema. L'architettura segue un pattern di "risveglio" progressivo:

Lo stack dell'agente

Vision Agent (agents/vision-agent/)

agent.py: logica principale di Gemini 3 Flash. Invia immagini al modello con l'esecuzione di codice abilitata, in modo che scriva Python (OpenCV) per contare gli elementi in modo deterministico.
agent_executor.py: collega le richieste del protocollo A2A alla logica dell'agente.
main.py: server Uvicorn A2A che pubblica /.well-known/agent-card.json e gestisce le richieste.

Agente fornitore (agenti/supplier-agent/)

inventory.py: si connette ad AlloyDB tramite il connettore Python AlloyDB (non è necessario il proxy di autenticazione). Contiene la funzione find_supplier() che esegue la ricerca vettoriale ScaNN.
agent_executor.py: collega il protocollo A2A alla logica di ricerca dell'inventario.
main.py: server Uvicorn A2A con scheda dell'agente ed endpoint di integrità.

Control Tower (frontend/)

app.py: server FastAPI + WebSocket che rileva gli agenti tramite A2A, coordina la pipeline visione → ricerca → ordine e trasmette aggiornamenti in tempo reale al browser.

Il flusso A2A

Control Tower legge /.well-known/agent-card.json da ogni agente
Rileva le funzionalità (skill, endpoint) senza URL hardcoded
Invia l'immagine all'agente Vision → riceve il conteggio e la descrizione degli articoli
Invia la descrizione come query di incorporamento all'agente fornitore → ottiene una corrispondenza parziale
Effettua ordini in autonomia

La connessione AlloyDB

L'agente fornitore utilizza il connettore Python AlloyDB anziché il proxy di autenticazione tradizionale:

from google.cloud.alloydbconnector import Connector

connector = Connector()
conn = connector.connect(
    inst_uri,       # Full instance URI
    "pg8000",       # Driver
    user="postgres",
    password=DB_PASS,
    ip_type="PUBLIC",  # Cloud Shell uses Public IP
)

Gestisce automaticamente l'autenticazione IAM, SSL/TLS e il routing delle connessioni. Quando esegui il deployment su Cloud Run in un secondo momento, modifica semplicemente ip_type in "PRIVATE" per l'accesso VPC.

5. Passaggio 1: la memoria (agente fornitore)

L'agente fornitore ricorda milioni di parti utilizzando AlloyDB ScaNN. Al momento, viene fornito con una query segnaposto, ovvero una query che restituisce la prima riga che trova, indipendentemente da ciò che cerchi.

Il controllo: l'amnesico

Se esegui una query sull'agente fornitore ora, viene restituito un risultato casuale. Non ha alcun concetto di somiglianza. Risolviamo il problema.

Avvia l'agente fornitore

Il server A2A (main.py) delega l'esecuzione ad agent_executor.py, che collega il protocollo alla logica di business in inventory.py.

pkill -f uvicorn #Kill all uvicorn processes

Passaggio 1: vai alla directory degli agenti

cd agents/supplier-agent

Passaggio 2: installa le dipendenze

pip install -r requirements.txt

Passaggio 3: avvia il server dell'agente

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

> /dev/null 2>&1 & esegue il server in background e sopprime l'output in modo che non interrompa il terminale.

Passaggio 4: verifica che l'agente sia in esecuzione (attendi 2-3 secondi dopo l'avvio)

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

Output previsto: JSON con la configurazione dell'agente (deve essere restituito senza errori)

La soluzione: implementare l'operatore <=>

Apri agents/supplier-agent/inventory.py e trova la funzione find_supplier() intorno alle righe 60-70. Vedrai il segnaposto:

# TODO: Replace this placeholder query with ScaNN vector search

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

Sostituisci queste due righe con:

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

Cosa fa:

<=> è l'operatore di distanza del coseno in PostgreSQL
ORDER BY part_embedding <=> %s::vector trova la corrispondenza più vicina (distanza più breve = significato semantico più vicino)
%s::vector esegue il cast dell'array di incorporamento al tipo di vettore di PostgreSQL
L'indice ScaNN accelera automaticamente questa query.

Passaggio 4: salva il file (Ctrl+S o Cmd+S)

L'agente ora utilizzerà la ricerca semantica anziché restituire risultati casuali.

Verifica

Testa il rilevamento A2A e l'inventario:

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

Previsto:agent-card.json restituisce la scheda dell'agente. Lo snippet Python restituisce una parte e un fornitore dai dati iniziali.

6. Passaggio 2: gli occhi (agente di visione)

Mentre il database è accessibile, riattiviamo gli occhi utilizzando Gemini 3 Flash. L'agente Vision esegue "calcoli visivi" tramite l'esecuzione del codice.

Il controllo: l'allucinazione

Se chiedi a un modello multimodale standard "Quante scatole ci sono in questa immagine disordinata?", elabora l'immagine come un'istantanea statica e fa una stima.

Il modello dice: "Vedo circa 12 scatole".
Realtà: ci sono 15 scatole.
Risultato: errore della catena di fornitura.

La soluzione: risvegliare il ciclo di pensiero-azione-osservazione

Attiviamo Code Execution e ThinkingConfig in modo che il modello scriva Python (OpenCV) per eseguire il conteggio in modo deterministico.

Apri agents/vision-agent/agent.py .
Trova la sezione GenerateContentConfig (circa le righe 68-78).
Rimuovi il commento dal blocco thinking_config=types.ThinkingConfig(...) e da tools=[types.Tool(code_execution=...)].
Il client è già configurato per utilizzare la tua GEMINI_API_KEY dall'ambiente.

File: agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="MINIMAL",  # 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)]
)

Perché thinking_level="MINIMAL"?

Per questa attività (conteggio degli elementi tramite l'esecuzione del codice), "MINIMAL" fornisce un ragionamento sufficiente per pianificare lo script e verificare il conteggio. L'utilizzo di "ALTA" aggiungerebbe una latenza 2-3 volte superiore senza migliorare la precisione per le attività deterministiche. Ottimizzazione del rapporto costi/prestazioni: adatta la profondità del ragionamento alla complessità dell'attività.

L'ottimizzazione del rapporto costo/rendimento è una competenza chiave per l'ingegneria dell'AI di produzione: adatta la profondità del ragionamento alla complessità dell'attività.

Avvia l'agente Vision

🔄 Controllo del percorso: se ti trovi ancora in agents/supplier-agent/, torna prima alla radice del repository con cd ../..

Passaggio 1: vai alla directory degli agenti di visione

cd agents/vision-agent

Passaggio 2: installa le dipendenze

pip install -r requirements.txt

Passaggio 3: avvia il server dell'agente di visione

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

> /dev/null 2>&1 & esegue il server in background e sopprime l'output in modo che non interrompa il terminale.

Verifica

Test A2A discovery:

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

Previsto:JSON con nome e competenze dell'agente. Nel passaggio 8 testerai il conteggio effettivo della visione con l'interfaccia utente della torre di controllo.

7. Passaggio 3: l'handshake (scheda agente A2A)

Il nostro agente vede il problema (Vision) e conosce il fornitore (Memory). Il protocollo A2A consente il rilevamento dinamico: il frontend impara a comunicare con ogni agente leggendo la sua scheda.

API REST tradizionali e A2A

Aspetto	REST tradizionale	Protocollo A2A
Endpoint Discovery	URL hardcoded nella configurazione	Dinamico tramite /.well-known/agent-card.json
Descrizione della funzionalità	Documentazione dell'API (per gli utenti)	Competenze (leggibili da una macchina)
Integrazione	Codice manuale per servizio	Corrispondenza semantica: "Ho bisogno di cercare nell'inventario" → scopre l'abilità
Nuovo agente aggiunto	Aggiorna le configurazioni di tutti i clienti	Configurazione zero: rilevamento automatico

Vantaggio nel mondo reale:in un microservizio tradizionale, se aggiungi un terzo "agente logistico", devi aggiornare il codice di Control Tower con il relativo URL e il contratto API. Con A2A, Control Tower lo rileva automaticamente e ne comprende le funzionalità tramite descrizioni delle competenze in linguaggio naturale.

Per questo motivo, A2A consente la composizione di agenti plug-and-play, il pattern architetturale per i sistemi autonomi.

Crea la scheda dell'agente

🔄 Controllo del percorso: se ti trovi ancora in agents/vision-agent/, torna prima alla radice del repository con cd ../..

La scheda dell'agente è già inclusa in agents/supplier-agent/agent_card.json. Apri e controlla:

{
  "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?"]
  }]
}

Puoi personalizzare il nome, la descrizione o gli esempi in base al tuo caso d'uso.

Riavvia l'agente fornitore per caricare la carta:

Passaggio 1: arresta l'agente in esecuzione

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

Passaggio 2: vai alla directory degli agenti

cd agents/supplier-agent

Passaggio 3: avvia di nuovo l'agente

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

> /dev/null 2>&1 & esegue il server in background e sopprime l'output in modo che non interrompa il terminale.

Passaggio 4: verifica la nuova scheda dell'agente (attendi 2-3 secondi dopo l'avvio)

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

Output previsto:JSON con nome, descrizione e competenze compilati.

8. Passaggio 4: la torre di controllo

Esegui il frontend di Control Tower con FastAPI + WebSocket. Rileva gli agenti tramite A2A e orchestra l'intero ciclo con aggiornamenti in tempo reale.

Avvia tutti i servizi

Il modo più semplice per avviare tutti i servizi:

Verificare di trovarsi nella root del repository

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

A questo punto:

sh run.sh

Questo singolo comando inizia:

Agente Vision sulla porta 8081
Agente fornitore sulla porta 8082
Control Tower sulla porta 8080

Attendi circa 10 secondi per l'inizializzazione di tutti i servizi.

Testare il sistema

Accedere alla Control Tower:

Fai clic sul pulsante Anteprima web (icona a forma di occhio 👁️) nella barra degli strumenti di Cloud Shell.
Seleziona "Anteprima sulla porta 8080".
La dashboard Control Tower si aprirà in una nuova scheda

Esegui la demo:

In alto a destra:stato della connessione (punto verde "Live"), pulsante di attivazione/disattivazione della modalità DEMO/AUTO e controlli audio
Centro: canvas principale del workflow con caricamento delle immagini e visualizzazione dell'analisi
Riquadri laterali (visualizzati durante l'analisi): cronologia del workflow (a sinistra), monitoraggio dell'avanzamento e visualizzatore di codice (a destra)

Opzione 1: avvio rapido (consigliata)

Nella home page, vedrai una sezione "Guida rapida" con immagini di esempio.
Fai clic su una delle immagini di esempio per avviare automaticamente l'analisi.
Guarda il flusso di lavoro autonomo (circa 30-45 secondi)

Opzione 2: carica il tuo

Trascina un'immagine del magazzino/dello scaffale (PNG, JPG, fino a 10 MB) o fai clic per sfogliare
Fai clic su "Initiate Autonomous Workflow" (Avvia flusso di lavoro autonomo).
Osserva la pipeline in quattro fasi

Cosa succede:

Rilevamento degli agenti:le finestre modali del protocollo A2A mostrano le schede dell'agente Vision e dell'agente fornitore con le relative competenze ed endpoint
Analisi della visione:Gemini 3 Flash genera ed esegue codice Python (OpenCV) per contare gli elementi. La barra di avanzamento mostra i passaggi secondari. I riquadri di delimitazione si sovrappongono agli elementi rilevati. Il badge del risultato mostra "✓ Verificato dal codice" o "~ Stimato"
Corrispondenza fornitori:animazione della ricerca vettoriale ScaNN di AlloyDB. Query di ricerca visualizzate (ad es. "scatole metalliche industriali"). La scheda dei risultati mostra il componente corrispondente, il fornitore e il punteggio di affidabilità
Ordine effettuato:scheda della ricevuta con ID ordine, quantità e dettagli

Suggerimento: mantieni attiva la modalità DEMO (in alto a destra) per mettere in pausa ogni fase delle presentazioni. In modalità AUTO, il flusso di lavoro viene eseguito continuamente.

Che cosa è successo

Control Tower ha utilizzato il protocollo A2A per rilevare entrambi gli agenti tramite /.well-known/agent-card.json, ha orchestrato l'analisi della visione (Gemini 3 Flash con esecuzione di codice), ha eseguito la ricerca vettoriale (AlloyDB ScaNN) e ha effettuato un ordine autonomo, il tutto con aggiornamenti WebSocket in tempo reale. Ogni agente espone le proprie funzionalità tramite lo standard A2A, consentendo la composizione plug-and-play senza SDK personalizzati. Scopri di più: Protocollo A2A

Risoluzione dei problemi

Errori relativi al percorso:

"Nessun file o directory corrispondente" durante l'esecuzione dei comandi: non ti trovi nella radice del repository.

# Check where you are
pwd

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

Errori del servizio:

"Indirizzo già in uso": i processi delle esecuzioni precedenti sono ancora attivi.

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

Servizi non avviati: controlla se le porte sono occupate:

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

"Connection refused" (Connessione rifiutata) ad AlloyDB: verifica che l'IP pubblico sia abilitato nell'istanza AlloyDB

9. 🎁 Bonus: esegui il deployment in Cloud Run

Facoltativo: tutto funziona a livello locale. Se invece vuoi condividere la tua creazione con un URL pubblico:

# From repo root
sh deploy/deploy.sh

Cosa succede:

Legge la configurazione .env
Chiede il tuo nome (mostrato nell'app di cui è stato eseguito il deployment)
Esegue il deployment di tutti e tre i servizi come un unico container Cloud Run
Concede ruoli IAM per l'accesso ad AlloyDB
Restituisce un URL condivisibile

I visitatori che aprono il tuo URL vedranno un popup:

10. Esegui la pulizia

Per evitare addebiti, elimina tutte le risorse con lo script di pulizia automatica:

# From repo root
sh deploy/cleanup.sh

Questa operazione rimuove in modo sicuro:

Cluster AlloyDB (il principale fattore di costo)
Servizi Cloud Run (se di cui è stato eseguito il deployment)
Service account associati

Lo script chiederà la conferma prima di eliminare qualsiasi elemento.

11. Riferimenti e ulteriori letture

Tutte le affermazioni tecniche in questo codelab sono verificate dalla documentazione ufficiale di Google Cloud e Google AI.

Documentazione ufficiale

Gemini 3 Flash:

API Code Execution: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
Guida per gli sviluppatori: https://ai.google.dev/gemini-api/docs/gemini-3
Documentazione del modello: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
Scheda del modello: https://deepmind.google/models/gemini/flash/

AlloyDB AI e ScaNN:

Benchmark delle prestazioni di ScaNN: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
Informazioni sull'indice ScaNN: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
Approfondimento su AlloyDB AI: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
Best practice per l'ottimizzazione: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
Documentazione di AlloyDB: https://cloud.google.com/alloydb/docs

MCP Toolbox for Databases (approccio alternativo):

MCP Toolbox: https://googleapis.github.io/genai-toolbox/getting-started/introduction/

Informazioni sui prezzi:

Prezzi dell'API Gemini: https://ai.google.dev/gemini-api/docs/pricing
Prezzi di AlloyDB: https://cloud.google.com/alloydb/pricing
Prezzi di Vertex AI: https://cloud.google.com/vertex-ai/pricing

Dichiarazioni di rendimento verificate

Funzionalità	Richiedi	Origine
ScaNN e HNSW (con filtro)	10 volte più veloce	Blog di Google Cloud (verificato)
ScaNN e HNSW (standard)	4 volte più veloce	Blog di Google Cloud (verificato)
Footprint della memoria di ScaNN	3-4 volte più piccolo	Blog di Google Cloud (verificato)
Tempo di compilazione dell'indice ScaNN	8 volte più veloce	Blog di Google Cloud (verificato)
Timeout esecuzione codice	Massimo 30 secondi	Documenti Google Cloud (verificati)
I/O di file di esecuzione del codice	Non supportata	Documenti Google Cloud (verificati)
Comportamento di Temperature=0	Output deterministico	Verificata con community

Risorse aggiuntive

Protocollo Agent-to-Agent (A2A):

A2A standardizza l'individuazione e la comunicazione degli agenti
Schede Agente pubblicate su /.well-known/agent-card.json
Standard emergente per la collaborazione tra agenti autonomi

ScaNN Research:

Basato su 12 anni di Google Research
Alimenta la Ricerca Google e YouTube su miliardi di scale
Rilasciata per la disponibilità generale: ottobre 2024
Il primo indice vettoriale PostgreSQL adatto a milioni o miliardi di vettori

12. Modalità Sfida: migliora le tue competenze agentiche

Hai creato una catena di fornitura autonoma funzionante. Pronto a fare di più? Queste sfide applicano i pattern che hai imparato a nuovi problemi.

Sfida 1: ricerca basata su immagini (embedding multimodali)

Flusso attuale: l'agente Vision conta gli articoli → genera una query di testo → l'agente fornitore incorpora il testo → esegue la ricerca in AlloyDB

Sfida:ignora completamente il testo e invia l'immagine ritagliata direttamente all'agente del fornitore.

Suggerimenti:

L'esecuzione del codice dell'agente di visione artificiale può ritagliare singoli elementi dall'immagine della mensola
Il modello multimodalembedding@001 di Vertex AI può incorporare direttamente le immagini
Modifica inventory.py per accettare i byte dell'immagine anziché il testo
Aggiorna la descrizione della skill A2A per indicare "Accetta: immagine/jpeg o testo"

Perché è importante:la ricerca visiva è più precisa per le parti con aspetti complessi (variazioni di colore, danni, differenze di imballaggio).

Sfida 2: osservabilità: fiducia attraverso la trasparenza

Stato attuale: il sistema funziona, ma non puoi vedere "sotto il cofano"

Sfida: esamina i log delle query di AlloyDB per dimostrare che la ricerca vettoriale è in esecuzione.

Passaggi:

Query Insights è abilitato per impostazione predefinita su AlloyDB. Per verificare, esegui:

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

Eseguire una ricerca di fornitori tramite l'interfaccia utente
Visualizza l'SQL effettivo eseguito:

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

Output previsto: vedrai la query ORDER BY part_embedding <=> $1::vector LIMIT 1 esatta con il tempo di esecuzione.

Perché è importante:l'osservabilità rafforza la fiducia. Quando gli stakeholder chiedono "Come prende le decisioni questo agente?", puoi mostrare loro il piano di query, non solo l'output.

Sfida 3: composizione multi-agente

Sfida:aggiungi un terzo agente (agente logistico) che calcola i costi di spedizione in base alla posizione del magazzino e al peso dell'articolo.

Architettura:

Output dell'agente Vision: conteggio degli articoli
Output dell'agente fornitore: sede del fornitore
Agente logistico (NOVITÀ) input: destinazione, peso → output: costo di spedizione + ETA

Suggerimento: il protocollo A2A rende questa operazione banale: crea una nuova scheda dell'agente con un'abilità calculate_shipping. La torre di controllo lo rileverà automaticamente.

Pattern di apprendimento: si tratta del fulcro dell'architettura orientata agli agenti, ovvero sistemi complessi creati a partire da piccoli specialisti componibili.

13. Conclusione

Hai eseguito correttamente la transizione dall'AI generativa all'AI agentica.

Cosa abbiamo creato:

Visione:abbiamo sostituito "ipotesi" con Esecuzione del codice (Gemini 3 Flash tramite chiave API).
Memoria:abbiamo sostituito "ricerca lenta" con AlloyDB ScaNN (tramite GCP).
Azione:abbiamo sostituito "Integrazione API" con il protocollo A2A.

Vantaggi dell'architettura ibrida:

Questo codelab ha dimostrato un approccio ibrido:

Agente Vision: utilizza l'API Gemini (chiave API) - livello semplice e senza costi disponibile, non è richiesta la fatturazione Google Cloud
Agente fornitore:utilizza GCP (Vertex AI + AlloyDB) di livello enterprise e pronto per la conformità

Questa è l'architettura dell'economia autonoma. Il codice è tuo.

Passaggi successivi

Ottieni la tua chiave API Gemini (livello senza costi disponibile)
Esplora la documentazione dell'API Gemini
Consulta la documentazione di AlloyDB AI
Esplorare l'esecuzione di codice di Gemini

Crea una catena di fornitura autonoma con Gemini 3 Flash e AlloyDB AI Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

1. Panoramica

Architettura deterministica

Cosa creerai

Obiettivi didattici

Requisiti

2. Prima di iniziare

Crea un progetto

Configura database [AlloyDB]

Richiedi il codice

Configura il progetto

Abilita l'IP pubblico su AlloyDB

Concedi le autorizzazioni Vertex AI

Esegui lo script di configurazione

3. Configurazione del database

Connettersi ad AlloyDB Studio

Attivare le estensioni

Creare la tabella dell'inventario

La colonna part_embedding memorizza vettori a 768 dimensioni da text-embedding-005. È questo che alimenta la ricerca semantica.

Inserisci dati di esempio

Concedere le autorizzazioni di incorporamento

Genera vector embedding

Crea l'indice ScaNN

Verificare che tutto funzioni

4. Informazioni sull'architettura

Lo stack dell'agente

Vision Agent (agents/vision-agent/)

Agente fornitore (agenti/supplier-agent/)

Control Tower (frontend/)

Il flusso A2A

La connessione AlloyDB

5. Passaggio 1: la memoria (agente fornitore)

Il controllo: l'amnesico

Avvia l'agente fornitore

La soluzione: implementare l'operatore <=>

Verifica

6. Passaggio 2: gli occhi (agente di visione)

Il controllo: l'allucinazione

La soluzione: risvegliare il ciclo di pensiero-azione-osservazione

Avvia l'agente Vision

Verifica

7. Passaggio 3: l'handshake (scheda agente A2A)

API REST tradizionali e A2A

Crea la scheda dell'agente

8. Passaggio 4: la torre di controllo

Avvia tutti i servizi

Testare il sistema

Che cosa è successo

Risoluzione dei problemi

9. 🎁 Bonus: esegui il deployment in Cloud Run

10. Esegui la pulizia

11. Riferimenti e ulteriori letture

Documentazione ufficiale

Risorse aggiuntive

12. Modalità Sfida: migliora le tue competenze agentiche

Sfida 1: ricerca basata su immagini (embedding multimodali)

Sfida 2: osservabilità: fiducia attraverso la trasparenza

Sfida 3: composizione multi-agente

13. Conclusione

Crea una catena di fornitura autonoma con Gemini 3 Flash e AlloyDB AI