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 supply chain, 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 supply chain autonomo 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 abilitato Gemini 3 Flash con l'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): abilitiamo 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 "calcoli visivi" 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 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 collegare Cloud Shell ad AlloyDB utilizzando il proxy di autenticazione.

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

È tutto.

Ora puoi procedere con la configurazione con un clic. Nella sezione successiva:

Aprire Cloud Shell automaticamente
Clona il repository
Guidarti nell'intera configurazione in un tutorial interattivo

3. Configurazione con un clic in Cloud Shell

Abbiamo semplificato la configurazione in un tutorial guidato di Cloud Shell. Tutto è automatizzato: provisioning dell'infrastruttura, configurazione di AlloyDB, configurazione del proxy di autenticazione e seeding del database.

Avvia il tutorial di Cloud Shell

⚠️ IMPORTANTE - Prima di fare clic:quando fai clic sul pulsante qui sotto, vedrai una finestra di dialogo di sicurezza che chiede "Apri in Cloud Shell". Questo viene visualizzato PRIMA dei cloni del repository.

Devi:

✅ Seleziona la casella "Trust repo".
✅ Fai clic su "Conferma".

Senza questo passaggio, il repository non verrà clonato.

È tutto pronto? Fai clic per aprire il progetto con un tutorial passo passo:

Cosa accade a questo punto:

Cloud Shell si apre con il repository pre-clonato
A destra viene visualizzato un riquadro del tutorial con istruzioni passo passo.
Ti guideremo attraverso:

Ottenere la chiave API Gemini (livello senza costi disponibile)
Impostazione del progetto GCP nel terminale
Esecuzione della configurazione (controlla le API, le abilita se necessario, esegue il provisioning di AlloyDB: circa 15 minuti)
Esecuzione di due modifiche al codice chiave (attivazione di visione e memoria)
Creazione della scheda dell'agente (protocollo A2A)
Avvio di tutti i servizi

Il tutorial è interattivo: ogni passaggio è numerato e tiene traccia dei tuoi progressi.

Alternativa: configurazione manuale

Se preferisci il controllo manuale:

Apri Cloud Shell e verifica che il progetto sia impostato

gcloud config get-value project

Se necessario, imposta il progetto

gcloud config set project YOUR_PROJECT_ID

Clona il repository

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

Esegui configurazione

sh setup.sh

Segui le istruzioni sullo schermo dello script di configurazione.

Passaggi successivi: il tutorial ti guida attraverso i passaggi rimanenti. Una volta completata, continua con la Sezione 4 per capire cosa è successo internamente.

4. Dietro le quinte: proxy di autenticazione e seeding del database

Il problema: AlloyDB si trova all'interno di un VPC privato. Cloud Shell si trova al di fuori. La connessione diretta è impossibile.

La soluzione:il proxy di autenticazione AlloyDB crea un tunnel sicuro autenticato da IAM da 127.0.0.1:5432 su Cloud Shell all'istanza AlloyDB. Se l'IP pubblico è abilitato per l'istanza, il proxy lo utilizza; in caso contrario, si connette tramite l'IP privato del VPC.

Cosa ha fatto setup.sh

Rilevamento automatico dell'istanza AlloyDB (cluster, regione, progetto)
È stato creato il file .env con tutte le credenziali (GEMINI_API_KEY, DB_PASS, dettagli di AlloyDB)
Scaricato e avviato il proxy di autenticazione (con –public-ip, se applicabile)
È stato eseguito il seeding del database con 8 parti di inventario di esempio + indice ScaNN

Il file .env è pronto. Tutte le esecuzioni future caricano automaticamente le credenziali.

Verifica che abbia funzionato

Assicurati di trovarti ancora nella radice del repository

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

Verifica che Auth Proxy sia in esecuzione

ps aux | grep alloydb-auth-proxy

Cosa è stato creato

Tabella dell'inventario con 8 parti e incorporamenti a 768 dimensioni
Indice ScaNN (idx_inventory_scann) per la ricerca vettoriale rapida

5. Passaggio 1: la memoria (agente fornitore)

L'agente fornitore ricorda milioni di parti utilizzando AlloyDB ScaNN. Lo avviamo come server A2A, quindi correggiamo la query vettoriale.

The Audit: The Amnesiac

Se esegui una query sull'agente fornitore ora (con il segnaposto SQL), viene restituita la prima riga trovata, non la corrispondenza più vicina. Non ha alcun concetto di somiglianza. È un'amnesica.

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)

Embedding semantici reali

Durante la configurazione, il database è stato inizializzato con incorporamenti semantici reali generati tramite il modello text-embedding-005 dell'SDK Google Gen AI. In questo modo, la corrispondenza di similarità è precisa e non si basa su vettori casuali. Il processo di seeding richiede circa 10 secondi per 13 elementi di esempio utilizzando la generazione di incorporamenti paralleli per creare vettori significativi a 768 dimensioni che acquisiscono il significato semantico di ogni parte.

Deviazione di AlloyDB: perché ScaNN?

La soluzione: implementare l'operatore <=>

L'agente viene fornito con una query segnaposto. Dobbiamo attivare la ricerca vettoriale ScaNN.

Passaggio 1: apri il file di inventario

cd agents/supplier-agent

Passaggio 2: trova il TODO in inventory.py

Cerca la funzione find_supplier() intorno alle righe 47-60. Visualizzerai:

# ============================================================
# 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)

Passaggio 3: sostituisci il segnaposto SQL con la ricerca vettoriale ScaNN

Elimina queste due righe:

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

e sostituiscili con:

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

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
LIMIT 1 restituisce solo la corrispondenza più vicina
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 server A2A (main.py) delega l'esecuzione ad agent_executor.py, che chiama agent.py per l'analisi di Gemini.

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.
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="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)]
)

Perché thinking_level="LOW"?

Per questa attività specifica (conteggio degli elementi tramite l'esecuzione del codice), "BASSO" fornisce un budget di ragionamento sufficiente per:

Pianificare la struttura dello script Python
Decidere quale approccio di elaborazione delle immagini utilizzare
Verifica che il conteggio corrisponda al numero di riquadri di delimitazione

L'utilizzo di "HIGH" aggiungerebbe una latenza e un costo 2-3 volte superiori senza migliorare l'accuratezza per le attività deterministiche. Riserva "ALTA" per il ragionamento complesso in più fasi (ad es. "Analizza questa interruzione della catena di fornitura e consiglia tre fornitori alternativi con motivazione".

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 dell'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.

La soluzione: crea la scheda dell'agente

Dobbiamo definire cosa può fare l'agente fornitore.

Copia agents/supplier-agent/agent_card_skeleton.json in agents/supplier-agent/agent_card.json.
Modifica il file per sostituire i segnaposto:

Prima (scheletro):

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

Dopo (le tue modifiche):

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

Riavvia l'agente fornitore in modo che carichi la nuova 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:

Proxy di autenticazione AlloyDB (se non in esecuzione)
Agente Vision sulla porta 8081
Supplier Agent 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 flusso di lavoro con caricamento delle immagini e visualizzazione dell'analisi
Pannelli laterali (visualizzati durante l'analisi): cronologia del flusso di lavoro (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 "✓ Codice verificato" o "~ Stimato"
Corrispondenza fornitori:animazione della ricerca vettoriale ScaNN di AlloyDB. Visualizzazioni delle query di ricerca (ad es. "industrial metal boxes"). 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" ad AlloyDB: verifica che il proxy di autenticazione sia in esecuzione:

ps aux | grep alloydb-auth-proxy

Problemi di connessione ad AlloyDB:

Se visualizzi il messaggio Connessione al server 127.0.0.1, porta 5432 non riuscita:

Se visualizzi il messaggio "Connessione al server 127.0.0.1, porta 5432 non riuscita":

Controlla il proxy di autenticazione: ps aux | grep alloydb-auth-proxy
Verifica che l'IP pubblico sia abilitato: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
Per lo sviluppo locale (non Cloud Shell):
Problema: Cloud Shell funziona automaticamente, ma le macchine locali hanno bisogno di reti autorizzate
Soluzione: esegui di nuovo lo script setup.sh e scegli l'opzione 1 (autorizza 0.0.0.0/0) quando richiesto
Nota sulla sicurezza: anche con 0.0.0.0/0, la connessione richiede:
Credenziali Google Cloud valide (credenziali predefinite dell'applicazione)
Password database
Crittografia mTLS (gestita dal proxy di autenticazione)

9. Esegui la pulizia

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

# From repo root
sh cleanup.sh

Vengono rimossi 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.

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

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 (filtrati)	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 creazione 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 con temperatura=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

Ricerca ScaNN:

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

11. Modalità Sfida: migliora le tue competenze di agente

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

Soluzione: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 striscia
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: ispeziona 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à crea 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:è il fulcro dell'architettura orientata agli agenti, ovvero sistemi complessi creati a partire da piccoli specialisti componibili.

12. 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 la "ricerca lenta" con AlloyDB ScaNN (tramite Google Cloud).
Azione:abbiamo sostituito "Integrazione API" con il protocollo A2A.

Vantaggi dell'architettura ibrida:

Questo codelab ha dimostrato un approccio ibrido:

Agente di visione: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