Tworzenie autonomicznego łańcucha dostaw za pomocą Gemini 3 Flash i AlloyDB AI

1. Przegląd

Era „czatbotów, które czytają” dobiega końca. Wkraczamy w erę wizji opartej na agentach.

W tym ćwiczeniu z programowania wdrożymy inżynierię deterministycznej AI, czyli praktykę tworzenia systemów AI, które nie zgadują. Standardowe modele AI często „halucynują” (zgadują), gdy są proszone o policzenie elementów na złożonym obrazie. W łańcuchu dostaw zgadywanie jest niebezpieczne. Jeśli AI zgadnie, że masz 12 produktów, a w rzeczywistości masz ich 15, spowoduje to kosztowne błędy.

Stworzymy autonomicznego agenta łańcucha dostaw, który będzie korzystać z nowej pętli Think, Act, Observe w Gemini 3 Flash. Nie tylko obserwuje, ale też bada.

Architektura deterministyczna

Zaczniemy od systemu „ślepego” i „cierpiącego na amnezję”. Będziesz ręcznie „budzić” jego zmysły jeden po drugim:

The Eyes (Vision Agent): udostępniamy Gemini 3 Flash z wykonywaniem kodu. Zamiast przewidywać tokeny, aby odgadnąć liczbę, model pisze kod w języku Python (OpenCV), aby deterministycznie zliczać piksele.
Pamięć (agent dostawcy): włączamy AlloyDB AI z ScaNN (Scalable Nearest Neighbors). Dzięki temu agent może w milisekundach przywołać dokładnego dostawcę części spośród milionów opcji.
Uzgadnianie połączenia (protokół A2A): umożliwiamy komunikację między agentami za pomocą standardowego pliku agent_card.json , dzięki czemu agent Vision może samodzielnie zamawiać towar od agenta dostawcy.

Co utworzysz

Agent wizyjny, który wykonuje „obliczenia wizualne” na podstawie obrazu z kamery.
Agent dostawcy oparty na AlloyDB ScaNN do szybkiego wyszukiwania wektorowego.
Interfejs Control Tower z aktualizacjami WebSocket w czasie rzeczywistym, który umożliwia wizualizację pętli autonomicznej.

Czego się nauczysz

Jak skonfigurować AlloyDB z wektorami dystrybucyjnymi i indeksami ScaNN.
Jak włączyć Agentic Vision w przypadku modelu gemini-3-flash-preview za pomocą interfejsu Gemini API.
Jak wdrożyć wyszukiwanie wektorowe za pomocą operatora <=> (odległość cosinusowa) w AlloyDB.
Jak połączyć agentów z AlloyDB za pomocą oprogramowania sprzęgającego AlloyDB Python.
Jak używać protokołu A2A do dynamicznego wykrywania agentów.

Wymagania

przeglądarka, np. Chrome lub Firefox;
Projekt Google Cloud z włączonymi płatnościami.
Klucz interfejsu Gemini API (bezpłatny poziom dostępny w Google AI Studio) dla agenta Vision.

2. Zanim zaczniesz

Utwórz projekt

W konsoli Google Cloud na stronie selektora projektów wybierz lub utwórz projekt Google Cloud.
Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie włączone są płatności.

Będziesz używać Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud. U góry konsoli Google Cloud kliknij Aktywuj Cloud Shell.

Obraz przycisku aktywowania Cloud Shell

Po połączeniu z Cloud Shell sprawdź, czy uwierzytelnianie zostało już przeprowadzone, a projekt jest już ustawiony na Twój identyfikator projektu, używając tego polecenia:

gcloud auth list

Konfigurowanie bazy danych [AlloyDB]

Najpierw przygotujemy bazę danych. Zajmie to około 15 minut, więc zaczniemy od tego.

Kliknij przycisk poniżej, aby otworzyć narzędzie do konfiguracji AlloyDB w Cloud Shell:

Uruchom konfigurację:

Sh run.sh

Aby otworzyć interfejs konfiguracji, użyj podglądu w przeglądarce (ikona oka 👁️ → Podejrzyj na porcie 8080).
Wpisz identyfikator projektu, wybierz region (np. us-central1) i utwórz hasło do bazy danych.

⚠️ ZAPISZ TO HASŁO – będzie ono potrzebne, gdy skrypt konfiguracji o nie poprosi.

Kliknij Rozpocznij wdrażanie i poczekaj około 15 minut na skonfigurowanie klastra.

Pobierz kod

Gdy AlloyDB będzie się konfigurować (lub gdy ten proces się zakończy), otwórz repozytorium codelab w Cloud Shell:

⚠️ WAŻNE: po kliknięciu przycisku pojawi się okno dialogowe zabezpieczeń. Zaznacz pole „Zaufaj repozytorium” i kliknij „Potwierdź”.

Możesz też ręcznie sklonować repozytorium:

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

cd visual-commerce-gemini-3-alloydb

Ustawianie projektu

W tym terminalu Cloud Shell sprawdź, czy projekt jest ustawiony:

gcloud config set project <YOUR_PROJECT_ID>

Włączanie publicznego adresu IP w AlloyDB

Po zakończeniu udostępniania AlloyDB włącz publiczny adres IP, aby łącznik Python mógł połączyć się z Cloud Shell:

Otwórz konsolę AlloyDB.
Kliknij klaster → kliknij instancję główną.
Kliknij Edytuj.
Przewiń do sekcji Publiczne połączenie IP i zaznacz opcję Włącz publiczny adres IP.
Kliknij Zaktualizuj instancję.

💡 Uwaga: AlloyDB Python Connector obsługuje uwierzytelnianie i szyfrowanie, więc nie musisz dodawać żadnych autoryzowanych sieci zewnętrznych.

Przyznawanie uprawnień do Vertex AI

Konto usługi AlloyDB potrzebuje dostępu do Vertex AI, aby generować wektory. Uruchom to polecenie w tym samym oknie Cloud Shell:

PROJECT_ID=$(gcloud config get-value project)


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

Uruchamianie skryptu konfiguracji

Teraz uruchom skrypt konfiguracji. Automatycznie wykryje on instancję AlloyDB:

sh setup.sh

Działanie skryptu:

Weryfikuje gcloud CLI, uwierzytelnianie, projekt i Pythona 3.
Sprawdza i włącza wymagane interfejsy API (AlloyDB, Vertex AI, Compute, Service Networking).
Prompty dotyczące klucza interfejsu Gemini API
Automatycznie wykrywa instancję AlloyDB i wyodrębnia region, klaster i nazwę instancji.
prosi o hasło do bazy danych,
Generuje plik konfiguracji .env
Instaluje zależności Pythona

3. Konfiguracja bazy danych

W centrum naszej aplikacji znajduje się AlloyDB for PostgreSQL. Wykorzystamy jego zaawansowane możliwości wektorowe i indeks ScaNN, aby umożliwić wyszukiwanie semantyczne w czasie zbliżonym do rzeczywistego. Dzięki temu nasi agenci będą mogli w milisekundach znajdować pasujące zasoby reklamowe w tysiącach rekordów.

W tej sekcji udostępnisz schemat, dane początkowe i wygenerujesz wektory dystrybucyjne – wszystko w AlloyDB Studio.

Łączenie z AlloyDB Studio

Otwórz instancję AlloyDB w konsoli AlloyDB.
W menu nawigacyjnym po lewej stronie kliknij AlloyDB Studio.
Uwierzytelnij za pomocą:
Nazwa użytkownika: postgres
Baza danych: postgres
Hasło: hasło ustawione podczas tworzenia klastra.

Włącz rozszerzenia

AlloyDB udostępnia wbudowane rozszerzenia do obsługi wektorów i AI. Uruchom ten kod SQL w AlloyDB Studio:

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

google_ml_integration: włącza funkcję ai.embedding() do wywoływania Vertex AI bezpośrednio z SQL.
vector: przechowuje 768-wymiarowe wektory dystrybucyjne i wysyła o nie zapytania.
alloydb_scann: włącza indeks ScaNN od Google, który umożliwia ultraszybkie wyszukiwanie wektorowe.

Tworzenie tabeli zasobów reklamowych

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

Kolumna part_embedding przechowuje 768-wymiarowe wektory z modelu text-embedding-005. To właśnie ta funkcja umożliwia wyszukiwanie semantyczne.

Wstaw przykładowe dane

Wstaw 20 pozycji asortymentu magazynowego:

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

Przyznawanie uprawnień do umieszczania na innych stronach

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Generowanie wektorów dystrybucyjnych

Wykorzystuje to wbudowaną funkcję ai.embedding() AlloyDB, aby wywołać model text-embedding-005 Vertex AI bezpośrednio z SQL – nie jest potrzebny żaden kod w Pythonie:

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

Generuje to 768-wymiarowe wektory, które odzwierciedlają znaczenie semantyczne nazwy i opisu każdej części. Indeks ScaNN będzie ich używać do błyskawicznego wyszukiwania podobieństw. [Wypełnienie tej ankiety zajmie około 3–5 minut]

Tworzenie indeksu ScaNN

SET scann.allow_blocked_operations = true;

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

Sprawdzanie, czy wszystko działa

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

Powinno być widocznych 20 wierszy, w których kolumna has_embedding ma wartość „true”.

4. Omówienie architektury

Zanim wprowadzisz zmiany w kodzie, dowiedz się, jak jest zbudowany system. Architektura jest zgodna z progresywnym wzorcem „przebudzenia”:

Stos agenta

Vision Agent (agents/vision-agent/)

agent.py – podstawowa logika Gemini 3 Flash. Wysyła obrazy do modelu z włączoną funkcją wykonywania kodu, aby model mógł napisać kod w języku Python (OpenCV) i określić liczbę elementów.
agent_executor.py – łączy żądania protokołu A2A z logiką agenta.
main.py – serwer Uvicorn A2A, który obsługuje plik /.well-known/agent-card.json i żądania.

Agent dostawcy (agents/supplier-agent/)

inventory.py – łączy się z AlloyDB za pomocą oprogramowania sprzęgającego AlloyDB Python (nie wymaga serwera proxy uwierzytelniania). Zawiera funkcję find_supplier(), która wykonuje wyszukiwanie wektorowe ScaNN.
agent_executor.py – łączy protokół A2A z logiką wyszukiwania asortymentu.
main.py – serwer Uvicorn A2A z kartą agenta i punktem końcowym stanu.

Control Tower (frontend/)

app.py – serwer FastAPI + WebSocket, który wykrywa agentów za pomocą A2A, koordynuje potok wizja → wyszukiwanie → zamówienie i przesyła aktualizacje w czasie rzeczywistym do przeglądarki.

Proces A2A

Control Tower odczytuje plik /.well-known/agent-card.json z każdego agenta.
Odkrywa funkcje (umiejętności, punkty końcowe) – bez zakodowanych na stałe adresów URL.
Wysyła obraz do agenta Vision API → otrzymuje liczbę elementów i opis
Wysyła opis jako zapytanie o wektor dystrybucyjny do agenta dostawcy → otrzymuje częściowe dopasowanie
składa zamówienie autonomicznie,

Połączenie AlloyDB

Agent dostawcy używa oprogramowania sprzęgającego AlloyDB Python zamiast tradycyjnego serwera proxy uwierzytelniania:

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
)

Automatycznie obsługuje uwierzytelnianie IAM, SSL/TLS i routing połączeń. Podczas późniejszego wdrażania w Cloud Run po prostu zmień ip_type na „PRIVATE”, aby uzyskać dostęp do VPC.

5. Krok 1. Pamięć (agent dostawcy)

Agent dostawcy zapamiętuje miliony części dzięki AlloyDB ScaNN. Obecnie zawiera on zapytanie zastępcze – „amnezję”, która zwraca pierwszy znaleziony wiersz, niezależnie od tego, czego szukasz.

The Audit: The Amnesiac

Jeśli teraz wyślesz zapytanie do agenta dostawcy, zwróci on losowy wynik. Nie ma pojęcia podobieństwa. Zajmijmy się tym.

Uruchomienie agenta dostawcy

Serwer A2A (main.py) przekazuje zadania do agent_executor.py, który łączy protokół z logiką biznesową w inventory.py.

pkill -f uvicorn #Kill all uvicorn processes

Krok 1. Otwórz katalog agentów

cd agents/supplier-agent

Krok 2. Zainstaluj zależności

pip install -r requirements.txt

Krok 3. Uruchom serwer agenta

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

Polecenie > /dev/null 2>&1 & uruchamia serwer w tle i tłumi dane wyjściowe, aby nie przerywać pracy terminala.

Krok 4. Sprawdź, czy agent działa (odczekaj 2–3 sekundy po uruchomieniu)

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

Oczekiwane dane wyjściowe: JSON z konfiguracją agenta (powinien być zwracany bez błędów)

Rozwiązanie: wdrożenie operatora <=>

Otwórz plik agents/supplier-agent/inventory.py i znajdź funkcję find_supplier() w wierszach 60–70. Zobaczysz symbol zastępczy:

# TODO: Replace this placeholder query with ScaNN vector search

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

Zastąp te 2 wiersze tymi:

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

Co to robi:

<=> to operator odległości cosinusowej w PostgreSQL.
ORDER BY part_embedding <=> %s::vector znajduje najbliższe dopasowanie (najmniejsza odległość = najbliższe znaczenie semantyczne).
%s::vector przekształca tablicę wektorów dystrybucyjnych na typ wektora PostgreSQL.
Indeks ScaNN automatycznie przyspiesza to zapytanie.

Krok 4. Zapisz plik (Ctrl+S lub Cmd+S)

Agent będzie teraz używać wyszukiwania semantycznego zamiast zwracać losowe wyniki.

Weryfikacja

Sprawdź wykrywanie A2A i zasoby reklamowe:

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

Oczekiwano: plik agent-card.json zwraca kartę agenta. Fragment kodu w Pythonie zwraca część i dostawcę z danych początkowych.

6. Krok 2. Oczy (Vision Agent)

Baza danych jest dostępna, więc użyjmy Gemini 3 Flash, aby otworzyć oczy. Agent Vision wykonuje „obliczenia wizualne” za pomocą wykonywania kodu.

Audyt: halucynacje

Jeśli zapytasz standardowy model multimodalny: „Ile pudełek jest na tym nieuporządkowanym obrazie?”, przetworzy on obraz jako statyczną migawkę i spróbuje zgadnąć.

Model mówi: „Widzę około 12 pudełek”.
Rzeczywistość: jest 15 pudełek.
Wynik: awaria łańcucha dostaw.

Rozwiązanie: pobudzenie pętli myślenie–działanie–obserwacja

Włączamy wykonywanie kodu i konfigurację myślenia, aby model pisał kod w Pythonie (OpenCV) i dokonywał deterministycznego zliczania.

Otwórz plik agents/vision-agent/agent.py .
Znajdź sekcję GenerateContentConfig (w okolicach wierszy 68–78).
Usuń znaczniki komentarza z bloku thinking_config=types.ThinkingConfig(...) i tools=[types.Tool(code_execution=...)].
Klient jest już skonfigurowany do używania klucza GEMINI_API_KEY ze środowiska.

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

Dlaczego thinking_level="MINIMAL"?

W przypadku tego zadania (zliczania elementów za pomocą wykonania kodu) poziom „MINIMAL” zapewnia wystarczające rozumowanie do zaplanowania skryptu i zweryfikowania liczby. Ustawienie „WYSOKA” zwiększy opóźnienie 2–3-krotnie, ale nie poprawi dokładności w przypadku zadań deterministycznych. Optymalizacja kosztów i wydajności – dopasowywanie głębokości rozumowania do złożoności zadania.

Optymalizacja kosztów i wydajności to kluczowa umiejętność w inżynierii AI w środowisku produkcyjnym: dopasowywanie głębokości rozumowania do złożoności zadania.

Uruchamianie agenta Vision

🔄 Sprawdź ścieżkę: jeśli nadal jesteś w folderze agents/supplier-agent/, najpierw wróć do głównego katalogu repozytorium za pomocą polecenia cd ../..

Krok 1. Otwórz katalog agentów wizyjnych

cd agents/vision-agent

Krok 2. Zainstaluj zależności

pip install -r requirements.txt

Krok 3. Uruchom serwer agenta wizyjnego

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

Polecenie > /dev/null 2>&1 & uruchamia serwer w tle i tłumi dane wyjściowe, aby nie przerywać pracy terminala.

Weryfikacja

Testowanie wykrywania A2A:

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

Oczekiwano: plik JSON z nazwą agenta i jego umiejętnościami. W kroku 8 przetestujesz rzeczywiste zliczanie za pomocą interfejsu Control Tower.

7. Krok 3. Uścisk dłoni (karta agenta A2A)

Agent widzi problem (Vision) i zna dostawcę (Memory). Protokół A2A umożliwia dynamiczne wykrywanie – interfejs uczy się komunikować z każdym agentem, odczytując jego kartę.

A2A a tradycyjne interfejsy API REST

Aspekt	Tradycyjny interfejs REST	Protokół A2A
Wykrywanie punktów końcowych	Adresy URL zakodowane na stałe w konfiguracji	Dynamiczne za pomocą pliku /.well-known/agent-card.json
Opis funkcji	Dokumentacja interfejsu API (dla ludzi)	Umiejętności (czytelne dla komputera)
Integracja	Ręczny kod na usługę	Dopasowanie semantyczne: „Potrzebuję wyszukiwania zasobów reklamowych” → wykrywa umiejętność
Dodano nowego agenta	Aktualizowanie konfiguracji wszystkich klientów	Brak konieczności konfigurowania – automatyczne wykrywanie

Praktyczne zastosowanie: w tradycyjnej mikroserwisowej architekturze, jeśli dodasz trzeciego „agenta logistycznego”, musisz zaktualizować kod wieży kontrolnej, podając jego adres URL i kontrakt API. Dzięki A2A wieża kontrolna automatycznie wykrywa usługę i rozumie jej możliwości na podstawie opisów umiejętności w języku naturalnym.

Dlatego A2A umożliwia komponowanie agentów typu plug-and-play, czyli wzorzec architektury systemów autonomicznych.

Tworzenie karty agenta

🔄 Sprawdź ścieżkę: jeśli nadal jesteś w folderze agents/vision-agent/, najpierw wróć do katalogu głównego repozytorium za pomocą polecenia cd ../..

Karta agenta jest już dostępna w pliku agents/supplier-agent/agent_card.json. Otwórz go i sprawdź:

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

Możesz dostosować nazwę, opis lub przykłady do swojego przypadku użycia.

Uruchom ponownie agenta dostawcy, aby załadować kartę:

Krok 1. Zatrzymaj działającego agenta

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

Krok 2. Przejdź do katalogu agentów

cd agents/supplier-agent

Krok 3. Ponownie uruchom agenta

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

Polecenie > /dev/null 2>&1 & uruchamia serwer w tle i tłumi dane wyjściowe, aby nie przerywać pracy terminala.

Krok 4. Sprawdź nową kartę agenta (odczekaj 2–3 sekundy po rozpoczęciu)

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

Oczekiwane dane wyjściowe: plik JSON z wypełnionymi informacjami o Twoim imieniu i nazwisku, opisie i umiejętnościach.

8. Krok 4. Centrum sterowania

Uruchom interfejs Control Tower za pomocą FastAPI i WebSockets. Wykrywa agentów za pomocą A2A i koordynuje pełną pętlę z aktualizacjami w czasie rzeczywistym.

Uruchom wszystkie usługi

Najłatwiejszy sposób uruchomienia wszystkich usług:

Sprawdź, czy jesteś w katalogu głównym repozytorium.

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

Następnie:

sh run.sh

To pojedyncze polecenie rozpoczyna:

Agent Vision na porcie 8081
Agent dostawcy na porcie 8082
Control Tower na porcie 8080

Poczekaj około 10 sekund, aż wszystkie usługi zostaną zainicjowane.

Testowanie systemu

Otwórz Control Tower:

Na pasku narzędzi Cloud Shell kliknij przycisk Podgląd w przeglądarce (ikona oka 👁️).
Wybierz „Podejrzyj na porcie 8080”.
Panel Control Tower otworzy się w nowej karcie.

Uruchomienie wersji demonstracyjnej:

Prawy górny róg: stan połączenia (zielona kropka „Na żywo”), przełącznik trybu DEMO/AUTO i elementy sterujące dźwiękiem.
Środek: główny obszar roboczy przepływu pracy z przesyłaniem obrazów i wizualizacją analizy.
Panele boczne (wyświetlane podczas analizy): oś czasu przepływu pracy (po lewej), śledzenie postępów i przeglądarka kodu (po prawej).

Opcja 1. Szybki start (zalecane)

Na stronie głównej zobaczysz sekcję „Szybki start” z przykładowymi obrazami.
Kliknij dowolny przykładowy obraz, aby automatycznie rozpocząć analizę.
Obserwuj autonomiczny przepływ pracy (ok. 30–45 sekund)

Opcja 2. Prześlij własne

Przeciągnij i upuść obraz magazynu lub półki (PNG, JPG, maks. 10 MB) albo kliknij, aby go wyszukać.
Kliknij „Initiate Autonomous Workflow” (Uruchom autonomiczny proces).
Obserwowanie 4-etapowego potoku

Co się stanie:

Wykrywanie agentów: w oknach modalnych protokołu A2A wyświetlają się karty agenta Vision i agenta dostawcy z ich umiejętnościami i punktami końcowymi.
Analiza obrazu: Gemini 3 Flash generuje i wykonuje kod w Pythonie (OpenCV), aby zliczać elementy. Pasek postępu pokazuje podetapy. Ramki ograniczające nakładane na wykryte elementy. Plakietka wyniku wyświetla „✓ Zweryfikowano kodem” lub „~ Szacunkowo”.
Dopasowanie dostawcy: animacja wyszukiwania wektorowego ScaNN w AlloyDB. Wyświetlane wyszukiwane hasło (np. „metalowe skrzynki przemysłowe”). Karta wyników zawiera dopasowaną część, dostawcę i wskaźnik ufności.
Złożono zamówienie: karta z potwierdzeniem zawierająca identyfikator zamówienia, ilość i szczegóły

Wskazówka: aby wstrzymywać prezentację na każdym etapie, włącz tryb DEMO (w prawym górnym rogu). W trybie AUTO przepływ pracy jest uruchamiany w sposób ciągły.

Co się właśnie stało

Control Tower używał protokołu A2A do wykrywania obu agentów za pomocą pliku /.well-known/agent-card.json, koordynował analizę obrazu (Gemini 3 Flash z wykonywaniem kodu), przeprowadzał wyszukiwanie wektorowe (AlloyDB ScaNN) i składał autonomiczne zamówienie – wszystko to z aktualizacjami w czasie rzeczywistym za pomocą WebSocket. Każdy agent udostępnia swoje możliwości za pomocą standardu A2A, co umożliwia kompozycję typu plug-and-play bez niestandardowych pakietów SDK. Więcej informacji: protokół A2A

Rozwiązywanie problemów

Błędy związane ze ścieżką:

„No such file or directory” (Brak takiego pliku lub katalogu) podczas wykonywania poleceń: nie znajdujesz się w katalogu głównym repozytorium.

# Check where you are
pwd

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

Błędy usługi:

„Adres jest już używany”: procesy z poprzednich uruchomień są nadal aktywne.

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

Usługi nie uruchamiają się: sprawdź, czy porty są zajęte:

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

„Odmowa połączenia” z AlloyDB: sprawdź, czy publiczny adres IP jest włączony w instancji AlloyDB.

9. 🎁 Bonus: wdrażanie w Cloud Run

Opcjonalnie – wszystko działa lokalnie. Jeśli jednak chcesz udostępnić swoją kreację za pomocą publicznego adresu URL:

# From repo root
sh deploy/deploy.sh

Co się stanie:

Odczytuje konfigurację z pliku .env
Prosi o podanie imienia i nazwiska (wyświetlanego w wdrożonej aplikacji).
wdraża wszystkie 3 usługi jako jeden kontener Cloud Run;
Przyznaje role uprawnień do dostępu do AlloyDB
Zwraca adres URL do udostępniania

Użytkownicy, którzy otworzą Twój adres URL, zobaczą wyskakujące okienko:

10. Czyszczenie

Aby uniknąć obciążenia konta opłatami, usuń wszystkie zasoby za pomocą automatycznego skryptu czyszczącego:

# From repo root
sh deploy/cleanup.sh

Bezpiecznie usuwa:

klaster AlloyDB (główny czynnik kosztowy);
usługi Cloud Run (jeśli zostały wdrożone);
Powiązane konta usługi

Przed usunięciem czegokolwiek skrypt poprosi o potwierdzenie.

11. Źródła i dodatkowe informacje

Wszystkie twierdzenia techniczne w tym ćwiczeniu są weryfikowane na podstawie oficjalnej dokumentacji Google Cloud i AI od Google.

Oficjalna dokumentacja

Gemini 3 Flash:

Code Execution API: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
Przewodnik dla deweloperów: https://ai.google.dev/gemini-api/docs/gemini-3
Dokumentacja modelu: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
Karta modelu: https://deepmind.google/models/gemini/flash/

AlloyDB AI i ScaNN:

Testy wydajności ScaNN: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
Informacje o indeksie ScaNN: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
Szczegółowe informacje o AlloyDB AI: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
Sprawdzone metody dostrajania: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
Dokumentacja AlloyDB: https://cloud.google.com/alloydb/docs

Zestaw narzędzi MCP dla baz danych (podejście alternatywne):

Zestaw narzędzi MCP: https://googleapis.github.io/genai-toolbox/getting-started/introduction/

Informacje o cenach:

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

Zweryfikowane deklaracje dotyczące skuteczności

Funkcja	Wykorzystaj	Źródło
ScaNN a HNSW (filtrowane)	10 razy szybciej	Blog Google Cloud (zweryfikowany)
ScaNN a HNSW (standard)	4 razy szybciej	Blog Google Cloud (zweryfikowany)
Wykorzystanie pamięci przez ScaNN	3–4 razy mniejszy	Blog Google Cloud (zweryfikowany)
Czas kompilacji indeksu ScaNN	8 razy szybciej	Blog Google Cloud (zweryfikowany)
Limit czasu wykonania kodu	Maksymalnie 30 sekund	Dokumenty Google Cloud (zweryfikowane)
Wykonywanie kodu w przypadku wejścia/wyjścia plików	Nieobsługiwane	Dokumentacja Google Cloud (zweryfikowana)
Działanie przy wartości Temperature=0	Deterministyczne dane wyjściowe	Zweryfikowane przez społeczność

Dodatkowe materiały

Protokół Agent-to-Agent (A2A):

A2A standaryzuje wykrywanie agentów i komunikację z nimi
Karty agentów wyświetlane w /.well-known/agent-card.json
Nowy standard współpracy autonomicznych agentów

ScaNN Research:

Na podstawie 12 lat badań zespołu ds. badań Google
Umożliwia wyszukiwanie w wyszukiwarce Google i YouTube na ogromną skalę
Ogólna dostępność: październik 2024 r.
Pierwszy indeks wektorowy PostgreSQL odpowiedni dla milionów i miliardów wektorów

12. Tryb wyzwania: rozwijaj umiejętności agentowe

Udało Ci się zbudować działający autonomiczny łańcuch dostaw. Chcesz iść dalej? Te wyzwania pozwalają zastosować poznane wzorce do nowych problemów.

Zadanie 1. Wyszukiwanie na podstawie obrazu (multimodalne wektory dystrybucyjne)

Obecny przepływ: agent Vision zlicza produkty → generuje zapytanie tekstowe → agent dostawcy osadza tekst → wyszukuje w AlloyDB

Wyzwanie: całkowite pominięcie tekstu – wysłanie przyciętego obrazu bezpośrednio do agenta dostawcy.

Wskazówki:

Wykonywanie kodu przez Vision Agent może przycinać poszczególne produkty ze zdjęcia półki.
Model multimodalembedding@001 w Vertex AI może bezpośrednio osadzać obrazy.
Zmiana pliku inventory.py, aby akceptował bajty obrazu zamiast tekstu
Zaktualizuj opis umiejętności A2A, aby wskazać „Akceptuje: obraz/jpeg lub tekst”.

Dlaczego to jest ważne: wyszukiwanie wizualne jest dokładniejsze w przypadku części o złożonym wyglądzie (różnice w kolorze, uszkodzenia, różnice w opakowaniu).

Wyzwanie 2: Dostrzegalność – zaufanie dzięki przejrzystości

Obecny stan: system działa, ale nie widać „pod maską”.

Wyzwanie: sprawdź dzienniki zapytań AlloyDB, aby potwierdzić, że wyszukiwanie wektorowe jest wykonywane.

Instrukcje:

Statystyki zapytań są domyślnie włączone w AlloyDB. Aby to sprawdzić, uruchom:

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

Przeprowadzanie wyszukiwania dostawców w interfejsie
Wyświetl rzeczywiste wykonane zapytanie SQL:

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

Oczekiwane dane wyjściowe: zobaczysz dokładne zapytanie ORDER BY part_embedding <=> $1::vector LIMIT 1 wraz z czasem wykonania.

Dlaczego to jest ważne: dostrzegalność buduje zaufanie. Gdy interesariusze zapytają: „Jak ten agent podejmuje decyzje?”, możesz pokazać im plan zapytania, a nie tylko dane wyjściowe.

Wyzwanie 3. Kompozycja wieloagentowa

Wyzwanie: dodaj trzeciego agenta (Logistics Agent), który oblicza koszty dostawy na podstawie lokalizacji magazynu i wagi produktu.

Architektura:

Dane wyjściowe agenta Vision: liczba elementów
Dane wyjściowe agenta dostawcy: lokalizacja dostawcy
Dane wejściowe agenta logistycznego (NOWOŚĆ): miejsce docelowe, waga → dane wyjściowe: koszt dostawy + szacowany czas dostawy

Wskazówka: protokół A2A ułatwia to zadanie – utwórz nową kartę agenta z umiejętnością calculate_shipping. Wieża kontrolna wykryje go automatycznie.

Wzorzec, którego się uczysz: to podstawa architektury zorientowanej na agentów – złożonych systemów zbudowanych z małych, kompozycyjnych specjalistów.

13. Podsumowanie

Udało Ci się przejść z generatywnej AI na AI z agentami.

Co stworzyliśmy:

Vision: zastąpiliśmy „zgadywanie” wykonywaniem kodu (Gemini 3 Flash za pomocą klucza API).
Pamięć: zastąpiliśmy „wolne wyszukiwanie” AlloyDB ScaNN (za pomocą GCP).
Działanie: zastąpiliśmy „Integrację interfejsu API” protokołem A2A.

Zalety architektury hybrydowej:

W tym ćwiczeniu pokazaliśmy podejście hybrydowe:

Agent Vision: korzysta z Gemini API (klucz interfejsu API) – dostępny jest prosty, bezpłatny poziom, nie wymaga rozliczeń GCP.
Agent dostawcy: korzysta z GCP (Vertex AI + AlloyDB) – rozwiązanie klasy korporacyjnej, zgodne z przepisami.

To jest architektura autonomicznej gospodarki. Kod jest Twój.

Następne kroki

Uzyskaj klucz interfejsu Gemini API (dostępny jest bezpłatny poziom)
Zapoznaj się z dokumentacją interfejsu Gemini API
Zapoznaj się z dokumentacją AlloyDB AI
Poznaj wykonywanie kodu w Gemini

Tworzenie autonomicznego łańcucha dostaw za pomocą Gemini 3 Flash i AlloyDB AI Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

1. Przegląd

Architektura deterministyczna

Co utworzysz

Czego się nauczysz

Wymagania

2. Zanim zaczniesz

Utwórz projekt

Konfigurowanie bazy danych [AlloyDB]

Pobierz kod

Ustawianie projektu

Włączanie publicznego adresu IP w AlloyDB

Przyznawanie uprawnień do Vertex AI

Uruchamianie skryptu konfiguracji

3. Konfiguracja bazy danych

Łączenie z AlloyDB Studio

Włącz rozszerzenia

Tworzenie tabeli zasobów reklamowych

Kolumna part_embedding przechowuje 768-wymiarowe wektory z modelu text-embedding-005. To właśnie ta funkcja umożliwia wyszukiwanie semantyczne.

Wstaw przykładowe dane

Przyznawanie uprawnień do umieszczania na innych stronach

Generowanie wektorów dystrybucyjnych

Tworzenie indeksu ScaNN

Sprawdzanie, czy wszystko działa

4. Omówienie architektury

Stos agenta

Vision Agent (agents/vision-agent/)

Agent dostawcy (agents/supplier-agent/)

Control Tower (frontend/)

Proces A2A

Połączenie AlloyDB

5. Krok 1. Pamięć (agent dostawcy)

The Audit: The Amnesiac

Uruchomienie agenta dostawcy

Rozwiązanie: wdrożenie operatora <=>

Weryfikacja

6. Krok 2. Oczy (Vision Agent)

Audyt: halucynacje

Rozwiązanie: pobudzenie pętli myślenie–działanie–obserwacja

Uruchamianie agenta Vision

Weryfikacja

7. Krok 3. Uścisk dłoni (karta agenta A2A)

A2A a tradycyjne interfejsy API REST

Tworzenie karty agenta

8. Krok 4. Centrum sterowania

Uruchom wszystkie usługi

Testowanie systemu

Co się właśnie stało

Rozwiązywanie problemów

9. 🎁 Bonus: wdrażanie w Cloud Run

10. Czyszczenie

11. Źródła i dodatkowe informacje

Oficjalna dokumentacja

Dodatkowe materiały

12. Tryb wyzwania: rozwijaj umiejętności agentowe

Zadanie 1. Wyszukiwanie na podstawie obrazu (multimodalne wektory dystrybucyjne)

Wyzwanie 2: Dostrzegalność – zaufanie dzięki przejrzystości

Wyzwanie 3. Kompozycja wieloagentowa

13. Podsumowanie

Tworzenie autonomicznego łańcucha dostaw za pomocą Gemini 3 Flash i AlloyDB AI