Autonome Lieferkette mit Gemini 3 Flash und AlloyDB AI erstellen

1. Übersicht

Die Ära der „Chatbots, die lesen“ geht zu Ende. Wir befinden uns im Zeitalter von Agentic Vision.

In diesem Codelab implementieren wir Deterministic AI Engineering – eine Methode zum Erstellen von KI-Systemen, die nicht raten. Standard-KI-Modelle „halluzinieren“ (raten) oft, wenn sie aufgefordert werden, Elemente in einem komplexen Bild zu zählen. In einer Lieferkette ist eine Schätzung gefährlich. Wenn eine KI schätzt, dass Sie 12 Artikel haben, obwohl es 15 sind, führt das zu kostspieligen Fehlern.

Wir entwickeln einen Autonomous Supply Chain Agent (Autonomen Supply Chain-Agenten) mit dem neuen Think, Act, Observe-Zyklus (Denken, Handeln, Beobachten) in Gemini 3 Flash. Sie sieht nicht nur, sondern untersucht.

Die deterministische Architektur

Wir beginnen mit einem „blinden“ und „amnesischen“ System. Sie müssen die Sinne des Geräts manuell einzeln „erwecken“:

The Eyes (Vision Agent): Wir aktivieren Gemini 3 Flash mit Codeausführung. Anstatt Tokens vorherzusagen, um eine Zahl zu schätzen, schreibt das Modell Python-Code (OpenCV), um Pixel deterministisch zu zählen.
Der Speicher (Lieferanten-Agent): Wir aktivieren AlloyDB AI mit ScaNN (Scalable Nearest Neighbors). So kann der Kundenservicemitarbeiter in Millisekunden den genauen Lieferanten für ein Teil aus Millionen von Optionen abrufen.
Handshake (A2A-Protokoll): Wir ermöglichen die Agent-to-Agent-Kommunikation über eine standardisierte agent_card.json , sodass der Vision Agent autonom Lagerbestände beim Supplier Agent bestellen kann.

Aufgaben

Ein Vision Agent, der „visuelle Mathematik“ auf Kamerastreams anwendet.
Ein Lieferanten-Agent, der von AlloyDB ScaNN für die schnelle Vektorsuche unterstützt wird.
Ein Control Tower-Frontend mit WebSocket-Updates in Echtzeit zur Visualisierung des autonomen Ablaufs.

Lerninhalte

So aktivieren Sie Agentic Vision mit gemini-3-flash-preview über die Gemini API.
So implementieren Sie die Vektorsuche mit dem Operator <=> (Kosinusdistanz) in AlloyDB.
Cloud Shell über den Auth-Proxy mit AlloyDB verbinden

Voraussetzungen

Ein Browser, z. B. Chrome oder Firefox
Google Cloud-Projekt mit aktivierter Abrechnungsfunktion.
Ein Gemini API-Schlüssel (kostenloses Kontingent in Google AI Studio verfügbar) für den Vision-Agent.

2. Hinweis

Projekt erstellen

Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

Sie verwenden Cloud Shell, eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird. Klicken Sie oben in der Google Cloud Console auf „Cloud Shell aktivieren“.

Bild der Schaltfläche „Cloud Shell aktivieren“

Sobald die Verbindung mit der Cloud Shell hergestellt ist, können Sie mit dem folgenden Befehl prüfen, ob Sie bereits authentifiziert sind und für das Projekt schon Ihre Projekt-ID eingestellt ist:

gcloud auth list

Geschafft!

Sie können jetzt mit der Einrichtung per Mausklick fortfahren. Im nächsten Abschnitt wird Folgendes behandelt:

Cloud Shell automatisch öffnen
Repository klonen
Sie in einer interaktiven Anleitung durch die gesamte Einrichtung führen

3. Ein-Klick-Einrichtung in Cloud Shell

Wir haben die Einrichtung in einer geführten Cloud Shell-Anleitung vereinfacht. Alles ist automatisiert: Infrastrukturbereitstellung, AlloyDB-Einrichtung, Auth-Proxy-Konfiguration und Datenbank-Seeding.

Cloud Shell-Anleitung starten

⚠️ WICHTIG:Wenn Sie auf die Schaltfläche unten klicken, wird ein Sicherheitsdialogfeld mit der Frage In Cloud Shell öffnen angezeigt. Dies wird VOR dem Klonen des Repositorys angezeigt.

Die folgenden Anforderungen müssen erfüllt sein:

✅ Setzen Sie ein Häkchen in das Kästchen Trust repo (Repository vertrauen).
✅ Klicken Sie auf Bestätigen.

Andernfalls wird das Repository nicht geklont.

Bereit? Klicken Sie, um das Projekt mit einer Schritt-für-Schritt-Anleitung zu öffnen:

So geht es weiter:

Cloud Shell wird mit dem vorab geklonten Repository geöffnet.
Rechts wird ein Bereich mit einer Schritt-für-Schritt-Anleitung angezeigt.
Sie werden durch die folgenden Schritte geführt:

Gemini API-Schlüssel abrufen (kostenlose Stufe verfügbar)
GCP-Projekt im Terminal festlegen
Einrichtung ausführen (APIs werden geprüft und bei Bedarf aktiviert, AlloyDB wird bereitgestellt: ca. 15 Minuten)
Zwei wichtige Codeänderungen vornehmen (Vision + Memory aktivieren)
Agent-Karte erstellen (A2A-Protokoll)
Alle Dienste starten

Die Anleitung ist interaktiv. Jeder Schritt ist nummeriert und Ihr Fortschritt wird verfolgt.

Alternative: Manuelle Einrichtung

Wenn Sie die manuelle Steuerung bevorzugen:

Cloud Shell öffnen und prüfen, ob Ihr Projekt festgelegt ist

gcloud config get-value project

Bei Bedarf Projekt festlegen

gcloud config set project YOUR_PROJECT_ID

Repository klonen

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

Einrichtung ausführen

sh setup.sh

Folgen Sie der Anleitung auf dem Bildschirm, die vom Einrichtungs-Script angezeigt wird.

Nächste Schritte:In der Anleitung werden Sie durch die verbleibenden Schritte geführt. Fahren Sie nach Abschluss mit Abschnitt 4 fort, um zu erfahren, was im Hintergrund passiert ist.

4. Hinter den Kulissen: Auth-Proxy und Datenbank-Seeding

Das Problem: AlloyDB befindet sich in einer privaten VPC. Cloud Shell befindet sich außerhalb. Eine direkte Verbindung ist nicht möglich.

Lösung:Der AlloyDB Auth-Proxy erstellt einen sicheren, IAM-authentifizierten Tunnel von 127.0.0.1:5432 in Cloud Shell zu Ihrer AlloyDB-Instanz. Wenn für Ihre Instanz eine öffentliche IP-Adresse aktiviert ist, verwendet der Proxy diese. Andernfalls stellt er eine Verbindung über die private IP-Adresse des VPC her.

Was hat „setup.sh“ gemacht?

Ihre AlloyDB-Instanz (Cluster, Region, Projekt) wurde automatisch erkannt.
.env mit allen Anmeldedaten erstellt (GEMINI_API_KEY, DB_PASS, AlloyDB-Details)
Auth-Proxy heruntergeladen und gestartet (mit –public-ip, falls zutreffend)
Datenbank mit 8 Beispielinventarteilen und ScaNN-Index gefüllt

Ihre .env-Datei ist bereit. Bei allen zukünftigen Ausführungen werden Anmeldedaten automatisch geladen.

Funktionsweise prüfen

Achten Sie darauf, dass Sie sich noch im Stammverzeichnis des Repositorys befinden.

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

Prüfen, ob der Auth-Proxy ausgeführt wird

ps aux | grep alloydb-auth-proxy

Was wurde erstellt?

Inventartabelle mit 8 Teilen und 768-dimensionalen Einbettungen
ScaNN-Index (idx_inventory_scann) für die schnelle Vektorsuche

5. Schritt 1: Das Memory (Supplier Agent)

Der Lieferanten-Agent merkt sich Millionen von Teilen mithilfe von AlloyDB ScaNN. Wir starten ihn als A2A-Server und korrigieren dann die Vektoranfrage.

Das Audit: Der Amnesiker

Wenn Sie den Lieferanten-Agenten jetzt mit dem Platzhalter-SQL abfragen, wird die erste gefundene Zeile zurückgegeben, nicht die beste Übereinstimmung. Es gibt kein Konzept der Ähnlichkeit. Es ist ein Amnesiac.

Lieferanten-Agent starten

Der A2A-Server (main.py) delegiert an agent_executor.py, die das Protokoll mit der Geschäftslogik in inventory.py verbindet.

pkill -f uvicorn #Kill all uvicorn processes

Schritt 1: Agent-Verzeichnis aufrufen

cd agents/supplier-agent

Schritt 2: Abhängigkeiten installieren

pip install -r requirements.txt

Schritt 3: Agent-Server starten

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

Mit > /dev/null 2>&1 & wird der Server im Hintergrund ausgeführt und die Ausgabe unterdrückt, damit Ihr Terminal nicht unterbrochen wird.

Schritt 4: Prüfen, ob der Agent ausgeführt wird (2–3 Sekunden nach dem Start warten)

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

Erwartete Ausgabe:JSON mit der Agent-Konfiguration (sollte ohne Fehler zurückgegeben werden)

Echte semantische Einbettungen

Bei der Einrichtung wurde die Datenbank mit realen semantischen Einbettungen gefüllt, die mit dem Modell „text-embedding-005“ des Google Gen AI SDK generiert wurden. So wird eine genaue Ähnlichkeitsübereinstimmung sichergestellt und nicht zufällige Vektoren. Der Seed-Prozess dauert etwa 10 Sekunden für 13 Beispielelemente. Dabei werden parallele Einbettungen generiert, um aussagekräftige 768-dimensionale Vektoren zu erstellen, die die semantische Bedeutung der einzelnen Teile erfassen.

AlloyDB-Exkurs: Warum ScaNN?

Die Lösung: Implementieren des Operators <=>

Der KI‑Agent wird mit einer Platzhalterabfrage ausgeliefert. Wir müssen die ScaNN-Vektorsuche aktivieren.

Schritt 1: Inventardatei öffnen

cd agents/supplier-agent

Schritt 2: TODO in inventory.py suchen

Suchen Sie in den Zeilen 47 bis 60 nach der Funktion „find_supplier()“. Sie sehen hier Folgendes:

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

Schritt 3: Platzhalter-SQL durch ScaNN-Vektorsuche ersetzen

Löschen Sie diese beiden Zeilen:

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

Ersetzen Sie sie durch:

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

Was passiert dabei?

<=> ist der Operator für Kosinusdistanz in PostgreSQL.
Mit ORDER BY part_embedding <=> %s::vector wird die nächstgelegene Übereinstimmung (geringste Distanz = ähnlichste semantische Bedeutung) gefunden.
%s::vector wandelt Ihr Einbettungs-Array in den PostgreSQL-Vektortyp um.
LIMIT 1 gibt nur die beste Übereinstimmung zurück.
Der ScaNN-Index beschleunigt diese Abfrage automatisch.

Schritt 4: Datei speichern (Strg + S oder Cmd + S)

Der Agent verwendet jetzt die semantische Suche, anstatt zufällige Ergebnisse zurückzugeben.

Bestätigung

A2A-Erkennung und Inventar testen:

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

Erwartet:agent-card.json gibt die Agentenkarte zurück. Das Python-Snippet gibt ein Teil und einen Lieferanten aus den Ausgangsdaten zurück.

6. Schritt 2: Die Augen (Vision Agent)

Während die Datenbank zugänglich ist, lassen Sie uns die Augen mit Gemini 3 Flash zum Leben erwecken. Der Vision-Agent führt über die Codeausführung „visuelle Mathematik“ durch. Der A2A-Server (main.py) delegiert an agent_executor.py, die agent.py für die Gemini-Analyse aufruft.

Das Audit: Die Halluzination

Wenn Sie ein Standardmodell für multimodale Anfragen fragen: „Wie viele Kisten sind auf diesem unordentlichen Bild zu sehen?“, wird das Bild als statische Momentaufnahme verarbeitet und das Modell gibt eine Schätzung ab.

Modell: „Ich sehe etwa 12 Kästen.“
Realität: Es gibt 15 Kästchen.
Ergebnis: Fehler in der Lieferkette.

Die Lösung: Denken-Handeln-Beobachten-Schleife reaktivieren

Wir aktivieren Code Execution (Codeausführung) und ThinkingConfig (Denkkonfiguration), damit das Modell Python (OpenCV) schreibt, um deterministisch zu zählen.

Öffnen Sie „agents/vision-agent/agent.py“.
Suchen Sie nach dem Abschnitt „GenerateContentConfig“.
Entfernen Sie die Kommentarzeichen für den Block thinking_config=types.ThinkingConfig(...) und tools=[types.Tool(code_execution=...)] .
Der Client ist bereits so konfiguriert, dass er Ihren GEMINI_API_KEY aus der Umgebung verwendet.

Datei: 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)]
)

Warum thinking_level="LOW"?

Für diese spezielle Aufgabe (Zählen von Elementen über die Codeausführung) bietet „LOW“ ein ausreichendes Budget für die Begründung, um:

Struktur des Python-Skripts planen
Entscheiden, welcher Ansatz für die Bildverarbeitung verwendet werden soll
Prüfen, ob die Anzahl mit der Anzahl der Begrenzungsrahmen übereinstimmt

Bei deterministischen Aufgaben würde die Verwendung von „HIGH“ die Latenz und die Kosten um das 2- bis 3‑Fache erhöhen, ohne die Genauigkeit zu verbessern. Reservieren Sie „HOCH“ für komplexe mehrstufige Problemlösungen (z.B. „Analysiere diese Unterbrechung der Lieferkette und schlage drei alternative Lieferanten mit Begründung vor.“

Kosten-Leistungs-Optimierung ist eine wichtige Fähigkeit für die KI-Entwicklung in der Produktion: Die Tiefe der Schlussfolgerungen muss an die Komplexität der Aufgabe angepasst werden.

Vision Agent starten

🔄 Pfad prüfen: Wenn Sie sich noch in agents/supplier-agent/ befinden, kehren Sie zuerst mit cd ../.. zum Stammverzeichnis des Repositorys zurück.

Schritt 1: Verzeichnis des Vision-Agents aufrufen

cd agents/vision-agent

Schritt 2: Abhängigkeiten installieren

pip install -r requirements.txt

Schritt 3: Vision-Agent-Server starten

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

Mit > /dev/null 2>&1 & wird der Server im Hintergrund ausgeführt und die Ausgabe unterdrückt, damit Ihr Terminal nicht unterbrochen wird.

Bestätigung

A2A-Erkennung testen:

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

Erwartet:JSON mit Agentennamen und ‑kompetenzen. Im Schritt 8 testen Sie die tatsächliche Zählung von Besuchen mit der Control Tower-Benutzeroberfläche.

7. Schritt 3: Der Handshake (A2A-Agentenkarte)

Unser KI-Agent sieht das Problem (Vision) und kennt den Lieferanten (Memory). Das A2A-Protokoll ermöglicht die dynamische Erkennung: Das Frontend erfährt, wie es mit den einzelnen Agents kommunizieren muss, indem es die jeweilige Karte liest.

A2A im Vergleich zu herkömmlichen REST APIs

Aspekt	Traditionelles REST	A2A-Protokoll
Endpoint Discovery	Fest codierte URLs in der Konfiguration	Dynamisch über /.well-known/agent-card.json
Beschreibung der Funktion	API-Dokumentation (für Menschen)	Kompetenzen (maschinenlesbar)
Integration	Manueller Code pro Dienst	Semantikmatching: „Ich brauche die Inventarsuche“ → Skill wird erkannt
Neuer KI-Agent hinzugefügt	Konfigurationen aller Clients aktualisieren	Keine Konfiguration erforderlich – automatische Erkennung

Praxisbezug:Wenn Sie in einem herkömmlichen Microservice einen dritten „Logistics Agent“ hinzufügen, müssen Sie den Code des Control Towers mit seiner URL und seinem API-Vertrag aktualisieren. Bei A2A wird der Control Tower automatisch erkannt und seine Funktionen werden durch Beschreibungen in natürlicher Sprache verstanden.

Aus diesem Grund ermöglicht A2A die Plug-and-Play-Agentenzusammenstellung – das Architekturmuster für autonome Systeme.

Lösung: Agent-Karte erstellen

Wir müssen definieren, was der Lieferanten-Agent tun kann.

Kopieren Sie „agents/supplier-agent/agent_card_skeleton.json“ nach „agents/supplier-agent/agent_card.json“.
Bearbeiten Sie die Datei, um Platzhalter zu ersetzen:

Vorher (Skelett):

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

Nachher (nach Ihren Änderungen):

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

Starten Sie den Supplier Agent neu, damit die neue Karte geladen wird:

Schritt 1: Laufenden Agent beenden

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

Schritt 2: Zum Agent-Verzeichnis wechseln

cd agents/supplier-agent

Schritt 3: Agent neu starten

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

Mit > /dev/null 2>&1 & wird der Server im Hintergrund ausgeführt und die Ausgabe unterdrückt, damit Ihr Terminal nicht unterbrochen wird.

Schritt 4: Neue Kundenservice-Karte bestätigen (2–3 Sekunden nach dem Start warten)

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

Erwartete Ausgabe:JSON mit Ihrem Namen, Ihrer Beschreibung und Ihren Skills.

8. Schritt 4: Der Kontrollturm

Control Tower-Frontend mit FastAPI + WebSockets ausführen Es erkennt Agents über A2A und orchestriert den gesamten Ablauf mit Echtzeit-Updates.

Alle Dienste starten

So kannst du alle Dienste am einfachsten starten:

Prüfen, ob Sie sich im Stammverzeichnis des Repositorys befinden

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

Danach geht es so weiter:

sh run.sh

Mit diesem einzelnen Befehl wird Folgendes gestartet:

AlloyDB Auth-Proxy (falls nicht ausgeführt)
Vision Agent auf Port 8081
Supplier Agent auf Port 8082
Control Tower auf Port 8080

Warten Sie etwa 10 Sekunden, bis alle Dienste initialisiert wurden.

System testen

Auf Control Tower zugreifen:

Klicken Sie in der Cloud Shell-Symbolleiste auf die Schaltfläche Webvorschau (Augensymbol 👁️).
Wählen Sie Vorschau auf Port 8080 aus.
Das Control Tower-Dashboard wird in einem neuen Tab geöffnet.

Demo ausführen:

Rechts oben:Verbindungsstatus (grüner Punkt „Live“), Umschalter für DEMO-/AUTO-Modus und Audio-Steuerelemente
Center: Hauptarbeitsbereich mit Bild-Upload und Visualisierung der Analyse
Seitenleisten (werden während der Analyse angezeigt): Workflow-Zeitachse (links), Fortschrittsverfolgung und Code-Viewer (rechts)

Option 1: Schnellstart (empfohlen)

Auf der Startseite sehen Sie den Bereich Schnellstart mit Beispielbildern.
Klicken Sie auf ein beliebiges Beispielbild, um die Analyse automatisch zu starten.
Autonomen Workflow ansehen (ca. 30–45 Sekunden)

Option 2: Eigene hochladen

Ziehen Sie ein Bild von einem Lager oder Regal (PNG, JPG, bis zu 10 MB) per Drag-and-drop hierher oder klicken Sie, um es zu suchen.
Klicken Sie auf Autonomen Workflow starten.
4‑stufige Pipeline beobachten

Was passiert?

Agentenerkennung:In A2A-Protokollmodulen werden Vision Agent- und Supplier Agent-Karten mit ihren Fähigkeiten und Endpunkten angezeigt.
Bildanalyse:Gemini 3 Flash generiert und führt Python-Code (OpenCV) aus, um Elemente zu zählen. Die Fortschrittsanzeige zeigt die einzelnen Schritte an. Begrenzungsrahmen werden über erkannte Elemente gelegt. Im Ergebnislogo wird „✓ Code-Verified“ (✓ Code-verifiziert) oder „~ Estimated“ (~ Geschätzt) angezeigt.
Supplier Match:Animation der AlloyDB ScaNN-Vektorsuche. Suchanfrage-Displays (z.B. „industrielle Metallboxen“). Auf der Ergebnis-Card werden das übereinstimmende Teil, der Lieferant und der Konfidenzwert angezeigt.
Bestellung aufgegeben:Belegkarte mit Bestell-ID, Menge und Details

Tipp: Lassen Sie den DEMO-Modus (oben rechts) aktiviert, um bei Präsentationen in jeder Phase zu pausieren. Im AUTO-Modus wird der Workflow kontinuierlich ausgeführt.

Was ist gerade passiert?

Der Control Tower hat das A2A-Protokoll verwendet, um beide Agenten über /.well-known/agent-card.json zu erkennen, die Bildanalyse (Gemini 3 Flash mit Codeausführung) orchestriert, die Vektorsuche (AlloyDB ScaNN) durchgeführt und eine autonome Bestellung aufgegeben – alles mit WebSocket-Updates in Echtzeit. Jeder Agent stellt seine Funktionen über den A2A-Standard zur Verfügung, sodass eine Plug-and-Play-Zusammensetzung ohne benutzerdefinierte SDKs möglich ist. Weitere Informationen: A2A-Protokoll

Fehlerbehebung

Pfadbezogene Fehler:

Beim Ausführen von Befehlen wird die Meldung No such file or directory (Datei oder Verzeichnis nicht vorhanden) angezeigt: Sie befinden sich nicht im Stammverzeichnis des Repositorys.

# Check where you are
pwd

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

Dienstfehler:

Adresse wird bereits verwendet: Prozesse aus vorherigen Ausführungen sind noch aktiv.

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

Dienste werden nicht gestartet: Prüfen Sie, ob Ports belegt sind:

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

„Connection refused“ für AlloyDB:Prüfen Sie, ob der Auth-Proxy ausgeführt wird:

ps aux | grep alloydb-auth-proxy

AlloyDB-Verbindungsprobleme:

Wenn Sie die Meldung „Verbindung zum Server unter 127.0.0.1, Port 5432 fehlgeschlagen“ sehen:

Wenn die Verbindung zum Server unter 127.0.0.1, Port 5432, fehlgeschlagen ist:

Auth-Proxy prüfen:ps aux | grep alloydb-auth-proxy
Öffentliche IP-Adresse aktivieren:gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
Für die lokale Entwicklung (nicht Cloud Shell):
Problem: Cloud Shell funktioniert automatisch, aber für lokale Computer sind autorisierte Netzwerke erforderlich
Lösung: Führen Sie „sh setup.sh“ noch einmal aus und wählen Sie bei Aufforderung Option 1 (0.0.0.0/0 autorisieren) aus.
Sicherheitshinweis: Auch bei 0.0.0.0/0 ist für die Verbindung Folgendes erforderlich:
Gültige GCP-Anmeldedaten (Standardanmeldedaten für Anwendungen)
Passwort für Datenbank
mTLS-Verschlüsselung (wird vom Auth-Proxy verarbeitet)

9. Bereinigen

So vermeiden Sie Gebühren: Zerstören Sie alle Ressourcen mit dem automatischen Bereinigungsscript:

# From repo root
sh cleanup.sh

Dadurch werden folgende Elemente sicher entfernt:

AlloyDB-Cluster (der primäre Kostentreiber)
Cloud Run-Dienste (falls bereitgestellt)
Verknüpfte Dienstkonten

Das Skript fordert Sie zur Bestätigung auf, bevor etwas gelöscht wird.

10. Referenzen und weitere Materialien

Alle technischen Behauptungen in diesem Codelab werden anhand der offiziellen Google Cloud- und Google AI-Dokumentation überprüft.

Offizielle Dokumentation

Gemini 3 Flash:

Code Execution API: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
Entwicklerleitfaden: https://ai.google.dev/gemini-api/docs/gemini-3
Modelldokumentation: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
Modellkarte: https://deepmind.google/models/gemini/flash/

AlloyDB AI und ScaNN:

ScaNN-Leistungsbenchmarks: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
ScaNN-Index: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
AlloyDB AI – Detaillierte Informationen: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
Best Practices für das Tuning: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
AlloyDB-Dokumentation: https://cloud.google.com/alloydb/docs

Preisinformationen:

Gemini API-Preise: https://ai.google.dev/gemini-api/docs/pricing
AlloyDB-Preise: https://cloud.google.com/alloydb/pricing
Vertex AI – Preise: https://cloud.google.com/vertex-ai/pricing

Bestätigte Leistungsangaben

Feature	Anspruch	Quelle
ScaNN im Vergleich zu HNSW (gefiltert)	10-mal schneller	Google Cloud-Blog (bestätigt)
ScaNN im Vergleich zu HNSW (Standard)	4-mal schneller	Google Cloud-Blog (bestätigt)
ScaNN-Speicherbedarf	3- bis 4-mal kleiner	Google Cloud-Blog (bestätigt)
ScaNN-Index-Erstellungszeit	8-mal schneller	Google Cloud-Blog (bestätigt)
Zeitüberschreitung bei der Codeausführung	Maximal 30 Sekunden	Google Cloud-Dokumente (bestätigt)
Datei-E/A bei der Codeausführung	Nicht unterstützt	Google Cloud-Dokumente (bestätigt)
Verhalten bei „Temperatur=0“	Deterministische Ausgabe	Von der Community überprüft

Zusätzliche Ressourcen

Agent-to-Agent-Protokoll (A2A):

A2A standardisiert die Agentenerkennung und ‑kommunikation
Agentenkarten, die bei /.well-known/agent-card.json angezeigt werden
Neuer Standard für die Zusammenarbeit autonomer KI-Agenten

ScaNN-Forschung:

Basierend auf 12 Jahren Google-Forschung
Grundlage für die Google Suche und YouTube mit Milliarden von Nutzern
Allgemeine Verfügbarkeit: Oktober 2024
Erster PostgreSQL-Vektorindex, der für Millionen bis Milliarden von Vektoren geeignet ist

11. Herausforderungsmodus: Agentic Skills verbessern

Sie haben eine funktionierende autonome Lieferkette aufgebaut. Bereit für den nächsten Schritt? In diesen Challenges werden die Muster, die Sie gelernt haben, auf neue Probleme angewendet.

Herausforderung 1: Bildbasierte Suche (multimodale Einbettungen)

Aktueller Ablauf:Der Vision-Agent zählt Elemente → generiert eine Textanfrage → der Supplier-Agent bettet Text ein → durchsucht AlloyDB

Herausforderung:Lassen Sie den Text weg und senden Sie das zugeschnittene Bild direkt an den Kundenservicemitarbeiter des Lieferanten.

Hinweise:

Bei der Codeausführung des Vision-Agents können einzelne Elemente aus dem Regalbild herausgeschnitten werden.
Das Modell „multimodalembedding@001“ von Vertex AI kann Bilder direkt einbetten.
inventory.py so ändern, dass Bild-Bytes anstelle von Text akzeptiert werden
A2A-Skill-Beschreibung aktualisieren, um „Akzeptiert: image/jpeg oder Text“ anzugeben

Warum ist das wichtig? Die visuelle Suche ist genauer für Teile mit komplexen Erscheinungsbildern (Farbabweichungen, Schäden, Verpackungsunterschiede).

Herausforderung 2: Beobachtbarkeit – Vertrauen durch Transparenz

Aktueller Zustand:Das System funktioniert, aber Sie können nicht sehen, was im Hintergrund passiert.

Herausforderung:Untersuchen Sie die Abfragelogs von AlloyDB, um nachzuweisen, dass die Vektorsuche ausgeführt wird.

Schritte:

Query Insights sind in AlloyDB standardmäßig aktiviert. Führen Sie zur Überprüfung Folgendes aus:

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

Lieferantensuche über die Benutzeroberfläche ausführen
So sehen Sie den tatsächlich ausgeführten SQL-Code:

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

Erwartete Ausgabe:Sie sehen die genaue Abfrage ORDER BY part_embedding <=> $1::vector LIMIT 1 mit der Ausführungszeit.

Warum das wichtig ist:Observability schafft Vertrauen. Wenn Stakeholder fragen, wie dieser Agent Entscheidungen trifft, können Sie ihnen nicht nur die Ausgabe, sondern auch den Abfrageplan zeigen.

Herausforderung 3: Multi-Agent Composition

Herausforderung:Fügen Sie einen dritten Agenten (Logistics Agent) hinzu, der die Versandkosten basierend auf dem Lagerstandort und dem Artikelgewicht berechnet.

Architektur:

Vision Agent-Ausgaben: Anzahl der Elemente
Ausgaben des Anbieter-Agents: Standort des Anbieters
Logistik-Agent (NEU): Eingaben: Zielort, Gewicht → Ausgaben: Versandkosten + voraussichtliche Ankunftszeit

Hinweis:Das A2A-Protokoll macht dies ganz einfach. Erstellen Sie eine neue Agentenkarte mit dem Skill „calculate_shipping“. Der Control Tower erkennt sie automatisch.

Muster, das Sie lernen: Dies ist der Kern der agentenorientierten Architektur – komplexe Systeme, die aus kleinen, zusammensetzbaren Spezialisten bestehen.

12. Fazit

Sie haben erfolgreich von Generative AI zu Agentic AI gewechselt.

Was wir entwickelt haben:

Vision:Wir haben „raten“ durch Codeausführung (Gemini 3 Flash über API-Schlüssel) ersetzt.
Arbeitsspeicher:Wir haben „langsame Suche“ durch AlloyDB ScaNN (über GCP) ersetzt.
Aktion:Wir haben „API-Integration“ durch das A2A-Protokoll ersetzt.

Vorteile der Hybridarchitektur:

In diesem Codelab wurde ein hybrider Ansatz vorgestellt:

Vision Agent:Verwendet die Gemini API (API-Schlüssel) – einfach, kostenloses Kontingent verfügbar, keine GCP-Abrechnung erforderlich
Lieferanten-Agent:Nutzt GCP (Vertex AI + AlloyDB) – für Unternehmen geeignet, Compliance-konform

Das ist die Architektur der autonomen Wirtschaft. Der Code gehört Ihnen.

Nächste Schritte

Gemini API-Schlüssel abrufen (kostenlose Stufe verfügbar)
Gemini API-Dokumentation ansehen
AlloyDB AI-Dokumentation ansehen
Codeausführung in Gemini kennenlernen