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 erstellen einen Autonomous Supply Chain Agent (Agent für autonome Lieferketten) 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.
Der Handshake (A2A-Protokoll): Wir ermöglichen die Agent-to-Agent-Kommunikation mithilfe einer standardisierten 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 richten Sie AlloyDB mit Vektoreinbettungen und ScaNN-Indizes ein.
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.
So stellen Sie mit dem AlloyDB Python-Connector eine Verbindung zwischen Agents und AlloyDB her.
Verwendung des A2A-Protokolls für die dynamische Agent-Erkennung

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, prüfen Sie mit dem folgenden Befehl, ob Sie bereits authentifiziert sind und für das Projekt schon Ihre Projekt-ID eingestellt ist:

gcloud auth list

Datenbank einrichten [AlloyDB]

Zuerst müssen wir die Datenbank bereitstellen. Das dauert etwa 15 Minuten.

Klicken Sie auf die Schaltfläche unten, um das AlloyDB-Einrichtungstool in Cloud Shell zu öffnen:

Führen Sie die Einrichtung aus:

Sh run.sh

Öffnen Sie die Einrichtungs-UI über die Webvorschau (Augensymbol 👁️ → Vorschau auf Port 8080).
Geben Sie Ihre Projekt-ID ein, wählen Sie eine Region aus (z.B. „us-central1“) und erstellen Sie ein Datenbankpasswort.

⚠️ SPEICHERN SIE DIESES PASSWORT. Sie benötigen es, wenn Sie vom Einrichtungs-Script dazu aufgefordert werden.

Klicken Sie auf „Bereitstellung starten“ und warten Sie etwa 15 Minuten, bis der Cluster bereitgestellt wird.

Code abrufen

Während AlloyDB bereitgestellt wird (oder sobald die Bereitstellung abgeschlossen ist), öffnen Sie das Codelab-Repository in Cloud Shell:

⚠️ WICHTIG: Wenn Sie auf die Schaltfläche klicken, wird ein Sicherheitsdialogfeld angezeigt. Setzen Sie ein Häkchen in das Kästchen „Repository vertrauen“ und klicken Sie auf „Bestätigen“.

Alternativ können Sie das Repository manuell klonen:

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

cd visual-commerce-gemini-3-alloydb

Projekt festlegen

Prüfen Sie in diesem Cloud Shell-Terminal, ob Ihr Projekt festgelegt ist:

gcloud config set project <YOUR_PROJECT_ID>

Öffentliche IP-Adresse in AlloyDB aktivieren

Wenn die Bereitstellung von AlloyDB abgeschlossen ist, aktivieren Sie die öffentliche IP-Adresse, damit der Python-Connector eine Verbindung von Cloud Shell herstellen kann:

AlloyDB Console aufrufen
Klicken Sie auf Ihren Cluster → klicken Sie auf Ihre primäre Instanz.
Klicken Sie auf „Bearbeiten“.
Scrollen Sie zu „Öffentliche IP-Verbindungen“ und setzen Sie ein Häkchen bei „Öffentliche IP-Adresse aktivieren“.
Klicken Sie auf „Instanz aktualisieren“.

💡 Hinweis: Der AlloyDB Python Connector übernimmt die Authentifizierung und Verschlüsselung. Sie müssen keine autorisierten externen Netzwerke hinzufügen.

Vertex AI-Berechtigungen erteilen

Das AlloyDB-Dienstkonto benötigt Vertex AI-Zugriff zum Generieren von Einbettungen. Führen Sie diesen Befehl im selben Cloud Shell-Fenster aus:

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"

Setup-Skript ausführen

Führen Sie nun das Setupscript aus. Es erkennt Ihre AlloyDB-Instanz automatisch:

sh setup.sh

Funktionsweise des Skripts:

Validiert die gcloud CLI, die Authentifizierung, das Projekt und Python 3
Prüft und aktiviert die erforderlichen APIs (AlloyDB, Vertex AI, Compute, Service Networking)
Aufforderungen für Ihren Gemini API-Schlüssel
Erkennt Ihre AlloyDB-Instanz automatisch und extrahiert Region, Cluster und Instanzname.
Aufforderung zur Eingabe Ihres Datenbankpassworts
Generiert die .env-Konfigurationsdatei
Python-Abhängigkeiten installieren

3. Datenbank einrichten

Das Herzstück unserer Anwendung ist AlloyDB for PostgreSQL. Wir nutzen die leistungsstarken Vektorfähigkeiten und den ScaNN-Index, um semantische Suchvorgänge nahezu in Echtzeit zu ermöglichen. So können unsere Kundenservicemitarbeiter in Millisekunden Inventarabstimmungen in Tausenden von Datensätzen finden.

In diesem Abschnitt stellen Sie das Schema und die Seed-Daten bereit und generieren Einbettungen – alles über AlloyDB Studio.

Verbindung zu AlloyDB Studio herstellen

Rufen Sie Ihre AlloyDB-Instanz in der AlloyDB Console auf.
Klicken Sie im linken Navigationsbereich auf AlloyDB Studio.
Authentifizieren mit:
Nutzername: postgres
Datenbank: postgres
Passwort: Das Passwort, das Sie beim Erstellen des Clusters festgelegt haben

Erweiterungen aktivieren

AlloyDB bietet integrierte Erweiterungen für Vektoren und KI. Führen Sie den folgenden SQL-Code in AlloyDB Studio aus:

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: Aktiviert die Funktion „ai.embedding()“ zum direkten Aufrufen von Vertex AI über SQL.
vector:Speichert und fragt 768-dimensionale Vektoreinbettungen ab.
alloydb_scann: Aktiviert den ScaNN-Index von Google für die ultraschnelle Vektorsuche.

Inventartabelle erstellen

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

In der Spalte „part_embedding“ werden 768-dimensionale Vektoren aus „text-embedding-005“ gespeichert. Das ist die Grundlage der semantischen Suche.

Beispieldaten einfügen

Füge 20 Lagerinventarelemente ein:

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

Einbettungsberechtigungen erteilen

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Vektoreinbettungen generieren

Dazu wird die integrierte Funktion „ai.embedding()“ von AlloyDB verwendet, um das Modell „text-embedding-005“ von Vertex AI direkt aus SQL aufzurufen. Es ist kein Python-Code erforderlich:

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

Dadurch werden 768-dimensionale Vektoren generiert, die die semantische Bedeutung des Namens und der Beschreibung jedes Teils erfassen. Der ScaNN-Index verwendet diese für blitzschnelle Ähnlichkeitssuchen. [Dies dauert etwa 3–5 Minuten.]

ScaNN-Index erstellen

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

Prüfen, ob alles funktioniert hat

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

Es sollten 20 Zeilen angezeigt werden, alle mit „has_embedding = true“.

4. Architektur

Bevor wir Codeänderungen vornehmen, sehen wir uns an, wie das System aufgebaut ist. Die Architektur folgt einem progressiven „Erwachen“-Muster:

Der Agent-Stack

Vision Agent (agents/vision-agent/)

agent.py – Kernlogik von Gemini 3 Flash. Sendet Bilder an das Modell, wobei die Codeausführung aktiviert ist, damit es Python (OpenCV) schreibt, um Elemente deterministisch zu zählen.
agent_executor.py: Überbrückt A2A-Protokollanfragen zur Agent-Logik.
main.py: Uvicorn-A2A-Server, der /.well-known/agent-card.json bereitstellt und Anfragen verarbeitet.

Supplier Agent (agents/supplier-agent/)

inventory.py: Stellt über den AlloyDB Python-Connector eine Verbindung zu AlloyDB her (kein Auth-Proxy erforderlich). Enthält die Funktion „find_supplier()“, mit der die ScaNN-Vektorsuche ausgeführt wird.
agent_executor.py: Stellt eine Verbindung zwischen dem A2A-Protokoll und der Logik für die Bestandssuche her.
main.py – Uvicorn-A2A-Server mit Agentenkarte und Health-Endpunkt.

Control Tower (Frontend)

app.py – FastAPI- und WebSocket-Server, der Agents über A2A erkennt, die Pipeline „Vision → Suche → Bestellung“ orchestriert und Echtzeit-Updates an den Browser streamt.

Der A2A-Ablauf

Control Tower liest /.well-known/agent-card.json von jedem Agenten.
Funktionen (Skills, Endpunkte) werden erkannt – keine hartcodierten URLs
Bild wird an Vision Agent gesendet → Anzahl der Artikel + Beschreibung werden abgerufen
Sendet die Beschreibung als Embedding-Anfrage an den Anbieter-Agenten → erhält eine teilweise Übereinstimmung
Bestellung wird autonom aufgegeben

Die AlloyDB-Verbindung

Der Supplier Agent verwendet den AlloyDB Python Connector anstelle des herkömmlichen Auth-Proxys:

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
)

IAM-Authentifizierung, SSL/TLS und Verbindungsrouting werden automatisch verarbeitet. Wenn Sie die Bereitstellung später in Cloud Run vornehmen, ändern Sie einfach „ip_type“ in „PRIVATE“ für den VPC-Zugriff.

5. Schritt 1: Das Gedächtnis (Lieferanten-Agent)

Der Lieferanten-Agent merkt sich Millionen von Teilen mithilfe von AlloyDB ScaNN. Derzeit wird sie mit einer Platzhalterabfrage ausgeliefert – einer amnesischen Abfrage, die die erste gefundene Zeile zurückgibt, unabhängig davon, wonach Sie suchen.

Das Audit: Der Amnesiker

Wenn Sie den Supplier Agent jetzt abfragen, wird ein zufälliges Ergebnis zurückgegeben. Es gibt kein Konzept der Ähnlichkeit. Das sollte nicht sein.

Lieferanten-Agent starten

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

pkill -f uvicorn #Kill all uvicorn processes

Schritt 1: Agentenverzeichnis 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)

Die Lösung: Implementieren des Operators <=>

Öffnen Sie „agents/supplier-agent/inventory.py“ und suchen Sie die Funktion „find_supplier()“ in den Zeilen 60–70. Der Platzhalter wird angezeigt:

# TODO: Replace this placeholder query with ScaNN vector search

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

Ersetzen Sie diese beiden Zeilen durch:

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

Was passiert dabei?

<=> ist der Operator für Kosinusdistanz in PostgreSQL.
ORDER BY part_embedding <=> %s::vector findet die nächstgelegene Übereinstimmung (geringste Distanz = ähnlichste semantische Bedeutung).
%s::vector wandelt Ihr Einbettungs-Array in den Vektortyp von PostgreSQL um.
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.

Häufige Fehler:

„Datei oder Verzeichnis nicht vorhanden“: Sie befinden sich nicht im Stammverzeichnis des Repositorys. Führen Sie „cd“ aus, um zum Home-Verzeichnis zu wechseln, und dann „cd visual-commerce-gemini-3-alloydb“. Alternativ können Sie mit „pwd“ herausfinden, wo Sie sich gerade befinden.
Port 8082 wird verwendet: Beenden Sie den vorhandenen Prozess: lsof -ti:8082 | xargs kill -9
ModuleNotFoundError: Installieren Sie die Abhängigkeiten: pip install -r requirements.txt
Database connection failed (Datenbankverbindung fehlgeschlagen): Prüfen Sie Ihre .env-Datei und füllen Sie ALLOYDB_REGION, ALLOYDB_CLUSTER und ALLOYDB_INSTANCE aus.
Verbindung abgelehnt:Prüfen Sie, ob die öffentliche IP-Adresse für Ihre AlloyDB-Instanz aktiviert ist.
Bestätigungsskript schlägt fehl:Prüfen Sie, ob der Seed in Schritt 4 erfolgreich abgeschlossen wurde.

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“ aus.

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 aktivieren

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

Öffnen Sie „agents/vision-agent/agent.py“.
Suchen Sie den Abschnitt „GenerateContentConfig“ (etwa Zeile 68–78).
Entfernen Sie die Kommentarzeichen sowohl aus dem Block „thinking_config=types.ThinkingConfig(...)“ als auch aus „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="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)]
)

Warum thinking_level=„MINIMAL“?

Für diese Aufgabe (Zählen von Elementen durch Ausführen von Code) bietet „MINIMAL“ genügend Begründung, um das Skript zu planen und die Anzahl zu überprüfen. Bei Verwendung von „HIGH“ würde die Latenz um das 2- bis 3‑Fache erhöht, ohne die Genauigkeit für deterministische Aufgaben zu verbessern. Kosten-Leistungs-Optimierung: Passen Sie die Tiefe der Argumentation an die Komplexität der Aufgabe an.

Die Optimierung von Kosten und Leistung ist eine wichtige Fähigkeit für die Entwicklung von KI für die 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 dem Namen des Agents und den Skills. 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	Manuelle Eingabe des Codes 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-Agent-Zusammensetzung – das Architekturmuster für autonome Systeme.

Agent-Karte erstellen

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

Die Agentenkarte ist bereits in agents/supplier-agent/agent_card.json enthalten. Öffnen Sie sie und prüfen Sie Folgendes:

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

Sie können den Namen, die Beschreibung oder die Beispiele an Ihren Anwendungsfall anpassen.

Starten Sie den Lieferanten-Agent neu, um die Karte zu laden:

Schritt 1: Laufenden Agent beenden

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

Schritt 2: Zum Agentenverzeichnis 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 Agent-Karte überprüfen (2–3 Sekunden nach dem Start warten)

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

Erwartete Ausgabe:JSON mit Ihrem ausgefüllten 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 starten Sie alle Dienste am einfachsten:

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:

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 den 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 (~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. Begrenzungsrahmen werden über erkannte Elemente gelegt. Das Ergebnis-Badge zeigt „✓ Code-Verified“ (✓ Code-verifiziert) oder „~ Estimated“ (~ Geschätzt) an.
Supplier Match:Animation der AlloyDB ScaNN-Vektorsuche. Suchanfrage wird angezeigt (z.B. „Metallboxen für die Industrie“). 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 Agents über /.well-known/agent-card.json zu erkennen, die Bildanalyse (Gemini 3 Flash mit Codeausführung) zu orchestrieren, die Vektorsuche (AlloyDB ScaNN) durchzuführen und eine autonome Bestellung aufzugeben – alles mit WebSocket-Updates in Echtzeit. Jeder Agent stellt seine Funktionen über den A2A-Standard zur Verfügung, sodass eine Plug-and-Play-Zusammenstellung 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 die öffentliche IP-Adresse für Ihre AlloyDB-Instanz aktiviert ist.

9. 🎁 Bonus: In Cloud Run bereitstellen

Optional: Alles funktioniert lokal. Wenn Sie Ihre Kreation über eine öffentliche URL teilen möchten, gehen Sie so vor:

# From repo root
sh deploy/deploy.sh

Was passiert?

Liest Ihre .env-Konfiguration
Fragt nach Ihrem Namen (wird in der bereitgestellten App angezeigt)
Stellt alle drei Dienste als einzelnen Cloud Run-Container bereit
IAM-Rollen für den AlloyDB-Zugriff gewähren
Gibt eine freigebbare URL aus

Besucher, die Ihre URL öffnen, sehen ein Pop-up:

10. Bereinigen

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

# From repo root
sh deploy/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.

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

MCP Toolbox for Databases (alternativer Ansatz):

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

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 für die 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 Erkennung und Kommunikation von Agenten
Agentenkarten, die bei /.well-known/agent-card.json angezeigt werden
Neuer Standard für die Zusammenarbeit autonomer KI-Agenten

ScaNN Research:

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

12. 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:Vision Agent zählt Artikel → generiert Textanfrage → Supplier Agent bettet Text ein → sucht in 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-Komposition

Herausforderung:Fügen Sie einen dritten Agenten (Logistics Agent) hinzu, der die Versandkosten anhand des Lagerstandorts und des Artikelgewichts 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

Tipp:Das A2A-Protokoll macht das 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.

13. 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 Hybridansatz 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

Autonome Lieferkette mit Gemini 3 Flash und AlloyDB AI erstellen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

1. Übersicht

Die deterministische Architektur

Aufgaben

Lerninhalte

Voraussetzungen

2. Hinweis

Projekt erstellen

Datenbank einrichten [AlloyDB]

Code abrufen

Projekt festlegen

Öffentliche IP-Adresse in AlloyDB aktivieren

Vertex AI-Berechtigungen erteilen

Setup-Skript ausführen

3. Datenbank einrichten

Verbindung zu AlloyDB Studio herstellen

Erweiterungen aktivieren

Inventartabelle erstellen

In der Spalte „part_embedding“ werden 768-dimensionale Vektoren aus „text-embedding-005“ gespeichert. Das ist die Grundlage der semantischen Suche.

Beispieldaten einfügen

Einbettungsberechtigungen erteilen

Vektoreinbettungen generieren

ScaNN-Index erstellen

Prüfen, ob alles funktioniert hat

4. Architektur

Der Agent-Stack

Vision Agent (agents/vision-agent/)

Supplier Agent (agents/supplier-agent/)

Control Tower (Frontend)

Der A2A-Ablauf

Die AlloyDB-Verbindung

5. Schritt 1: Das Gedächtnis (Lieferanten-Agent)

Das Audit: Der Amnesiker

Lieferanten-Agent starten

Die Lösung: Implementieren des Operators <=>

Bestätigung

6. Schritt 2: Die Augen (Vision Agent)

Das Audit: Die Halluzination

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

Vision Agent starten

Bestätigung

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

A2A im Vergleich zu herkömmlichen REST APIs

Agent-Karte erstellen

8. Schritt 4: Der Kontrollturm

Alle Dienste starten

System testen

Was ist gerade passiert?

Fehlerbehebung

9. 🎁 Bonus: In Cloud Run bereitstellen

10. Bereinigen

11. Referenzen und weitere Materialien

Offizielle Dokumentation

Zusätzliche Ressourcen

12. Herausforderungsmodus: Agentic Skills verbessern

Herausforderung 1: Bildbasierte Suche (multimodale Einbettungen)

Herausforderung 2: Beobachtbarkeit – Vertrauen durch Transparenz

Herausforderung 3: Multi-Agent-Komposition

13. Fazit

Autonome Lieferkette mit Gemini 3 Flash und AlloyDB AI erstellen