Membangun Rantai Pasokan yang Mandiri dengan Gemini 3 Flash & AlloyDB AI

1. Ringkasan

Era "Chatbot yang Membaca" akan berakhir. Kita memasuki era Agentic Vision.

Dalam Codelab ini, kita akan menerapkan Rekayasa AI Deterministik—praktik membangun sistem AI yang tidak menebak. Model AI standar sering kali "berhalusinasi" (menebak) saat diminta menghitung item dalam gambar yang kompleks. Dalam supply chain, menebak-nebak itu berbahaya. Jika AI menebak Anda memiliki 12 item padahal Anda sebenarnya memiliki 15 item, hal ini akan memicu error yang merugikan.

Kita akan membangun Agen Supply Chain Otonom yang memanfaatkan loop Berpikir, Bertindak, Mengamati baru di Gemini 3 Flash. Tidak hanya melihat, tetapi juga menyelidiki.

Arsitektur Deterministik

Kita akan mulai dengan sistem "buta" dan "amnesia". Anda akan "membangunkan" indranya satu per satu secara manual:

The Eyes (Agen Vision): Kami mengaktifkan Gemini 3 Flash dengan Eksekusi Kode. Alih-alih memprediksi token untuk menebak angka, model menulis kode Python (OpenCV) untuk menghitung piksel secara deterministik.
Memory (Agen Pemasok): Kami mengaktifkan AlloyDB AI dengan ScaNN (Scalable Nearest Neighbors). Hal ini memungkinkan agen mengingat persis pemasok untuk suatu suku cadang dari jutaan opsi dalam hitungan milidetik.
Handshake (Protokol A2A): Kami mengaktifkan komunikasi Agen-ke-Agen menggunakan agent_card.json standar , sehingga Agen Vision dapat secara mandiri memesan stok dari Agen Pemasok.

Yang akan Anda build

Agen Visi yang melakukan "matematika visual" pada feed kamera.
Agen Pemasok yang didukung oleh ScaNN AlloyDB untuk penelusuran vektor berkecepatan tinggi.
Frontend Control Tower dengan update WebSocket real-time untuk memvisualisasikan loop otonom.

Yang akan Anda pelajari

Cara menyiapkan AlloyDB dengan embedding vektor dan indeks ScaNN.
Cara mengaktifkan Agentic Vision dengan gemini-3-flash-preview menggunakan Gemini API.
Cara menerapkan penelusuran vektor menggunakan operator <=> (jarak kosinus) di AlloyDB.
Cara menghubungkan agen ke AlloyDB menggunakan AlloyDB Python Connector.
Cara menggunakan Protokol A2A untuk penemuan agen dinamis.

Persyaratan

Browser, seperti Chrome atau Firefox
Project Google Cloud yang mengaktifkan penagihan.
Kunci Gemini API (paket gratis tersedia di Google AI Studio) untuk Vision Agent.

2. Sebelum memulai

Membuat project

Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Anda akan menggunakan Cloud Shell, lingkungan command line yang berjalan di Google Cloud. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.

Gambar tombol Activate Cloud Shell

Setelah terhubung ke Cloud Shell, Anda dapat memeriksa bahwa Anda sudah diautentikasi dan project sudah ditetapkan ke project ID Anda menggunakan perintah berikut:

gcloud auth list

Menyiapkan Database [AlloyDB]

Sebelum melakukan hal lain, mari kita siapkan database — proses ini memerlukan waktu sekitar 15 menit, jadi kita akan memulainya terlebih dahulu.

Klik tombol di bawah untuk membuka alat penyiapan AlloyDB di Cloud Shell:

Jalankan penyiapan:

Sh run.sh

Gunakan Pratinjau Web (ikon mata 👁️ → Pratinjau di port 8080) untuk membuka UI penyiapan.
Masukkan Project ID Anda, pilih Region (misalnya, us-central1), dan buat Sandi Database.

⚠️ SIMPAN SANDI INI — Anda akan membutuhkannya saat skrip penyiapan memintanya.

Klik Start Deployment dan tunggu ~15 menit hingga cluster disediakan.

Dapatkan Kode

Saat AlloyDB melakukan penyediaan (atau setelah selesai), buka repo codelab di Cloud Shell:

⚠️ PENTING: Saat mengklik tombol, Anda akan melihat dialog keamanan. Centang kotak "Trust repo" dan klik "Confirm".

Atau, clone secara manual:

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

cd visual-commerce-gemini-3-alloydb

Menetapkan Project Anda

Di terminal Cloud Shell ini, pastikan project Anda sudah disetel:

gcloud config set project <YOUR_PROJECT_ID>

Mengaktifkan IP Publik di AlloyDB

Setelah penyediaan AlloyDB selesai, aktifkan IP Publik agar Konektor Python dapat terhubung dari Cloud Shell:

Buka Konsol AlloyDB
Klik cluster Anda → klik instance utama Anda
Klik Edit
Scroll ke Public IP Connectivity dan centang Enable Public IP
Klik Update Instance

💡 Catatan: Konektor Python AlloyDB menangani autentikasi dan enkripsi — Anda tidak perlu menambahkan jaringan eksternal yang diizinkan.

Memberikan Izin Vertex AI

Akun layanan AlloyDB memerlukan akses Vertex AI untuk membuat embedding. Jalankan perintah ini di jendela Cloud Shell yang sama:

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"

Menjalankan Skrip Penyiapan

Sekarang jalankan skrip penyiapan — skrip ini akan mendeteksi instance AlloyDB Anda secara otomatis:

sh setup.sh

Fungsi skrip:

Memvalidasi gcloud CLI, autentikasi, project, dan Python 3
Memeriksa dan mengaktifkan API yang diperlukan (AlloyDB, Vertex AI, Compute, Service Networking)
Perintah untuk kunci Gemini API Anda
Mendeteksi instance AlloyDB Anda secara otomatis dan mengekstrak nama region, cluster, dan instance
Meminta sandi database Anda
Membuat file konfigurasi .env
Menginstal dependensi Python

3. Penyiapan Database

Di inti aplikasi kami terdapat AlloyDB untuk PostgreSQL. Kami akan menggunakan kemampuan vektornya yang canggih dan indeks ScaNN untuk mengaktifkan penelusuran semantik yang mendekati real-time, sehingga agen kami dapat menemukan kecocokan inventaris di ribuan catatan dalam milidetik.

Di bagian ini, Anda akan menyediakan skema, data awal, dan membuat sematan — semuanya dari AlloyDB Studio.

Menghubungkan ke AlloyDB Studio

Buka instance AlloyDB Anda di Konsol AlloyDB
Klik AlloyDB Studio di navigasi kiri
Lakukan autentikasi dengan:
Username: postgres
Database: postgres
Sandi: Sandi yang Anda tetapkan selama pembuatan cluster

Mengaktifkan Ekstensi

AlloyDB menyediakan ekstensi bawaan untuk vektor dan AI. Jalankan SQL berikut di 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: Mengaktifkan fungsi ai.embedding() untuk memanggil Vertex AI langsung dari SQL.
vector: Menyimpan dan membuat kueri embedding vektor 768 dimensi.
alloydb_scann: Mengaktifkan indeks ScaNN Google untuk penelusuran vektor yang sangat cepat.

Membuat Tabel Inventaris

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

Kolom part_embedding menyimpan vektor 768 dimensi dari text-embedding-005. Inilah yang mendukung penelusuran semantik.

Menyisipkan Data Sampel

Sisipkan 20 item inventaris gudang:

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

Memberikan Izin Penyematan

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Membuat Embedding Vektor

Contoh ini menggunakan fungsi ai.embedding() bawaan AlloyDB untuk memanggil model text-embedding-005 Vertex AI langsung dari SQL — tidak memerlukan kode Python:

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

Hal ini menghasilkan vektor 768 dimensi yang menangkap makna semantik dari nama dan deskripsi setiap suku cadang. Indeks ScaNN akan menggunakan indeks ini untuk penelusuran kemiripan yang sangat cepat. [Survei ini akan memakan waktu sekitar 3-5 menit]

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

Memverifikasi Semuanya Berfungsi

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

Anda akan melihat 20 baris, semuanya dengan has_embedding = true.

4. Memahami Arsitektur

Sebelum melakukan perubahan kode, mari pahami cara sistem dibuat. Arsitektur ini mengikuti pola "pengaktifan" progresif:

Stack Agen

Vision Agent (agents/vision-agent/)

agent.py — Logika inti Gemini 3 Flash. Mengirim gambar ke model dengan Eksekusi Kode diaktifkan sehingga model menulis Python (OpenCV) untuk menghitung item secara deterministik.
agent_executor.py — Menjembatani permintaan protokol A2A ke logika agen.
main.py — Server A2A Uvicorn yang menampilkan /.well-known/agent-card.json dan menangani permintaan.

Agen Pemasok (agents/supplier-agent/)

inventory.py — Terhubung ke AlloyDB melalui AlloyDB Python Connector (tidak memerlukan Proxy Auth). Berisi fungsi find_supplier() yang melakukan penelusuran vektor ScaNN.
agent_executor.py — Menjembatani protokol A2A ke logika penelusuran inventaris.
main.py — Server A2A Uvicorn dengan kartu agen dan endpoint kesehatan.

Control Tower (frontend/)

app.py — Server FastAPI + WebSocket yang menemukan agen melalui A2A, mengatur pipeline vision → penelusuran → pemesanan, dan melakukan streaming update real-time ke browser.

Alur A2A

Control Tower membaca /.well-known/agent-card.json dari setiap agen
Menemukan kemampuan (keterampilan, endpoint) — tanpa URL hardcode
Mengirim gambar ke Agen Vision → mendapatkan jumlah item + deskripsi
Mengirim deskripsi sebagai kueri penyematan ke Agen Pemasok → mendapatkan kecocokan sebagian
Melakukan pemesanan secara mandiri

Koneksi AlloyDB

Agen Supplier menggunakan AlloyDB Python Connector, bukan Proxy Auth tradisional:

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
)

Opsi ini menangani autentikasi IAM, SSL/TLS, dan perutean koneksi secara otomatis. Saat men-deploy ke Cloud Run nanti, cukup ubah ip_type menjadi "PRIVATE" untuk akses VPC.

5. Langkah 1: The Memory (Agen Pemasok)

Agen Pemasok mengingat jutaan suku cadang menggunakan ScaNN AlloyDB. Saat ini, aplikasi ini dilengkapi dengan kueri placeholder — amnesia yang menampilkan baris pertama yang ditemukannya, terlepas dari apa yang Anda telusuri.

The Audit: The Amnesiac

Jika Anda mengkueri Agen Pemasok sekarang, agen tersebut akan menampilkan hasil acak. Tidak memiliki konsep kesamaan. Ayo perbaiki.

Mulai Agen Pemasok

Server A2A (main.py) mendelegasikan ke agent_executor.py, yang menjembatani protokol ke logika bisnis di inventory.py.

pkill -f uvicorn #Kill all uvicorn processes

Langkah 1: Buka direktori agen

cd agents/supplier-agent

Langkah 2: Instal dependensi

pip install -r requirements.txt

Langkah 3: Mulai server agen

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

> /dev/null 2>&1 & menjalankan server di latar belakang dan menekan output sehingga tidak mengganggu terminal Anda.

Langkah 4: Pastikan agen berjalan (tunggu 2-3 detik setelah memulai)

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

Output yang Diharapkan: JSON dengan konfigurasi agen (harus ditampilkan tanpa error)

Perbaikan: Menerapkan Operator <=>

Buka agents/supplier-agent/inventory.py dan temukan fungsi find_supplier() di sekitar baris 60-70. Anda akan melihat placeholder:

# TODO: Replace this placeholder query with ScaNN vector search

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

Ganti kedua baris tersebut dengan:

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

Fungsinya:

<=> adalah operator jarak kosinus di PostgreSQL
ORDER BY part_embedding <=> %s::vector menemukan kecocokan terdekat (jarak terendah = makna semantik terdekat)
%s::vector mentransmisikan array embedding Anda ke jenis vektor PostgreSQL
Indeks ScaNN otomatis mempercepat kueri ini.

Langkah 4: Simpan file (Ctrl+S atau Cmd+S)

Sekarang agen akan menggunakan penelusuran semantik, bukan menampilkan hasil acak.

Verifikasi

Uji penemuan A2A dan inventaris:

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

Diharapkan: agent-card.json menampilkan kartu agen. Cuplikan Python menampilkan suku cadang dan supplier dari data yang di-seed.

6. Langkah 2: Mata (Agen Visi)

Saat database dapat diakses, mari kita buka mata menggunakan Gemini 3 Flash. Agen Visi melakukan "matematika visual" melalui Eksekusi Kode.

Audit: Halusinasi

Jika Anda bertanya kepada model multimodal standar "Berapa banyak kotak dalam gambar yang berantakan ini?", model tersebut akan memproses gambar sebagai snapshot statis dan menebak.

Model mengatakan: "Saya melihat sekitar 12 kotak".
Kenyataannya: Ada 15 kotak.
Hasil: Kegagalan supply chain.

Solusi: Membangkitkan Loop Berpikir-Bertindak-Mengamati

Kami mengaktifkan Eksekusi Kode dan ThinkingConfig sehingga model menulis Python (OpenCV) untuk menghitung secara deterministik.

Buka agents/vision-agent/agent.py .
Temukan bagian GenerateContentConfig (sekitar baris 68-78).
Batalkan komentar pada blok thinking_config=types.ThinkingConfig(...) dan tools=[types.Tool(code_execution=...)].
Klien sudah dikonfigurasi untuk menggunakan GEMINI_API_KEY Anda dari lingkungan.

File: agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="MINIMAL",  # Valid: "MINIMAL", "LOW", "MEDIUM", "HIGH"
        include_thoughts=False    # Set to True for debugging
    ),
    # CODELAB STEP 2: Uncomment to enable code execution
    tools=[types.Tool(code_execution=types.ToolCodeExecution)]
)

Mengapa thinking_level="MINIMAL"?

Untuk tugas ini (menghitung item melalui eksekusi kode), "MINIMAL" memberikan alasan yang cukup untuk merencanakan skrip dan memverifikasi jumlahnya. Menggunakan "TINGGI" akan menambahkan latensi 2-3x tanpa meningkatkan akurasi untuk tugas deterministik. Pengoptimalan Biaya-Performa — sesuaikan kedalaman penalaran dengan kompleksitas tugas.

Pengoptimalan Performa Biaya adalah keterampilan utama untuk engineering AI produksi: sesuaikan kedalaman penalaran dengan kompleksitas tugas.

Mulai Agen Vision

🔄 Pemeriksaan Jalur: Jika Anda masih berada di agents/supplier-agent/, kembali dulu ke root repo dengan cd ../..

Langkah 1: Buka direktori agen vision

cd agents/vision-agent

Langkah 2: Instal dependensi

pip install -r requirements.txt

Langkah 3: Mulai server agen penglihatan

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

> /dev/null 2>&1 & menjalankan server di latar belakang dan menekan output sehingga tidak mengganggu terminal Anda.

Verifikasi

Pengujian penemuan A2A:

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

Diharapkan: JSON dengan nama dan keterampilan agen. Anda akan menguji penghitungan visi sebenarnya dengan UI Control Tower di Langkah 8.

7. Langkah 3: Handshake (Kartu Agen A2A)

Agen kami melihat masalahnya (Penglihatan) dan mengetahui pemasoknya (Memori). Protokol A2A memungkinkan penemuan dinamis—frontend mempelajari cara berkomunikasi dengan setiap agen dengan membaca kartunya.

A2A vs. REST API Tradisional

Aspek	REST tradisional	A2A Protocol
Penemuan Endpoint	URL yang di-hardcode dalam konfigurasi	Dinamis melalui /.well-known/agent-card.json
Deskripsi Kemampuan	Dokumen API (untuk manusia)	Keterampilan (dapat dibaca mesin)
Integrasi	Kode manual per layanan	Pencocokan semantik: "Saya perlu penelusuran inventaris" → menemukan skill
Agen Baru Ditambahkan	Memperbarui konfigurasi semua klien	Konfigurasi nol—ditemukan secara otomatis

Manfaat di Dunia Nyata: Dalam microservice tradisional, jika Anda menambahkan "Agen Logistik" ketiga, Anda harus memperbarui kode Control Tower dengan URL dan kontrak API-nya. Dengan A2A, Control Tower akan menemukannya secara otomatis dan memahami kemampuannya melalui deskripsi kemampuan natural language.

Itulah sebabnya A2A memungkinkan Komposisi Agen Plug-and-Play—pola arsitektur untuk sistem otonom.

Membuat Kartu Agen

🔄 Pemeriksaan Jalur: Jika Anda masih berada di agents/vision-agent/, kembali ke root repo terlebih dahulu dengan cd ../..

Kartu agen sudah disertakan di agents/supplier-agent/agent_card.json. Buka dan tinjau:

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

Jangan ragu untuk menyesuaikan nama, deskripsi, atau contoh agar sesuai dengan kasus penggunaan Anda.

Mulai ulang Agen Pemasok untuk memuat kartu:

Langkah 1: Hentikan agen yang sedang berjalan

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

Langkah 2: Buka direktori agen

cd agents/supplier-agent

Langkah 3: Mulai ulang agen

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

> /dev/null 2>&1 & menjalankan server di latar belakang dan menekan output sehingga tidak mengganggu terminal Anda.

Langkah 4: Verifikasi kartu agen baru (tunggu 2-3 detik setelah memulai)

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

Output yang Diharapkan: JSON dengan nama, deskripsi, dan keterampilan Anda yang telah diisi.

8. Langkah 4: Menara Pengontrol

Jalankan frontend Control Tower dengan FastAPI + WebSockets. Agent Engine menemukan agen melalui A2A dan mengatur seluruh loop dengan pembaruan real-time.

Mulai Semua Layanan

Cara termudah untuk memulai semua layanan:

Verifikasi bahwa Anda berada di root repo

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

Lalu:

sh run.sh

Satu perintah ini memulai:

Vision Agent di port 8081
Supplier Agent di port 8082
Control Tower di port 8080

Tunggu ~10 detik hingga semua layanan diinisialisasi.

Menguji Sistem

Akses Control Tower:

Klik tombol Web Preview (ikon mata 👁️) di toolbar Cloud Shell
Pilih "Preview on port 8080"
Dasbor Control Tower akan terbuka di tab baru

Jalankan Demo:

Kanan atas: Status koneksi (titik "Live" hijau), tombol mode DEMO/AUTO, dan kontrol audio
Tengah: Kanvas alur kerja utama dengan upload gambar dan visualisasi analisis
Panel samping (muncul selama analisis): Linimasa alur kerja (kiri), pelacakan progres, dan penampil kode (kanan)

Opsi 1: Mulai Cepat (Direkomendasikan)

Di halaman beranda, Anda akan melihat bagian "Mulai cepat" dengan contoh gambar
Klik gambar contoh untuk memulai analisis secara otomatis
Tonton alur kerja otonom (~30-45 detik)

Opsi 2: Upload Milik Anda

Tarik lalu lepas gambar gudang/rak (PNG, JPG, hingga 10 MB) atau klik untuk menjelajah
Klik "Initiate Autonomous Workflow"
Mengamati pipeline 4 tahap

Yang Terjadi:

Penemuan Agen: Modal protokol A2A menampilkan kartu Agen Visi dan Agen Pemasok dengan keterampilan dan endpoint-nya
Analisis Visual: Gemini 3 Flash membuat dan mengeksekusi kode Python (OpenCV) untuk menghitung item. Status progres menampilkan sub-langkah. Overlay kotak pembatas pada item yang terdeteksi. Badge hasil menampilkan "✓ Diverifikasi Kode" atau "~ Diperkirakan"
Pencocokan Pemasok: Animasi penelusuran vektor ScaNN AlloyDB. Kueri penelusuran ditampilkan (misalnya, "kotak logam industri"). Kartu hasil menampilkan kecocokan suku cadang, supplier, dan skor keyakinan
Pesanan Ditempatkan: Kartu tanda terima dengan ID pesanan, jumlah, dan detail

Tips: Aktifkan mode DEMO (kanan atas) untuk menjeda di setiap tahap presentasi. Dalam mode AUTO, alur kerja berjalan terus-menerus.

Apa yang Baru Saja Terjadi

Control Tower menggunakan Protokol A2A untuk menemukan kedua agen melalui /.well-known/agent-card.json, mengatur analisis visi (Gemini 3 Flash dengan eksekusi kode), melakukan penelusuran vektor (ScaNN AlloyDB), dan melakukan pesanan secara mandiri—semuanya dengan update WebSocket real-time. Setiap agen mengekspos kemampuannya melalui standar A2A, sehingga memungkinkan komposisi plug-and-play tanpa SDK kustom. Pelajari lebih lanjut: A2A Protocol

Pemecahan masalah

Error Terkait Jalur:

"No such file or directory" saat menjalankan perintah: Anda tidak berada di root repo.

# Check where you are
pwd

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

Error Layanan:

"Address already in use": Proses dari eksekusi sebelumnya masih aktif.

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

Layanan tidak dimulai: Periksa apakah port sedang digunakan:

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

"Connection refused" ke AlloyDB: Verifikasi bahwa IP Publik diaktifkan di instance AlloyDB Anda

9. 🎁 Bonus: Men-deploy ke Cloud Run

Opsional — Semuanya berfungsi secara lokal. Namun, jika Anda ingin membagikan kreasi Anda dengan URL publik:

# From repo root
sh deploy/deploy.sh

Yang terjadi:

Membaca konfigurasi .env Anda
Meminta nama Anda (ditampilkan di aplikasi yang di-deploy)
Men-deploy ketiga layanan sebagai satu container Cloud Run
Memberikan peran IAM untuk akses AlloyDB
Menghasilkan URL yang dapat dibagikan

Pengunjung yang membuka URL Anda akan melihat pop-up:

10. Pembersihan

Untuk menghindari timbulnya biaya, hancurkan semua resource dengan skrip pembersihan otomatis:

# From repo root
sh deploy/cleanup.sh

Tindakan ini akan menghapus dengan aman:

Cluster AlloyDB (faktor utama biaya)
Layanan Cloud Run (jika di-deploy)
Akun layanan terkait

Skrip akan meminta konfirmasi sebelum menghapus apa pun.

11. Referensi & Bacaan Lebih Lanjut

Semua klaim teknis dalam codelab ini diverifikasi dari dokumentasi resmi Google Cloud dan Google AI.

Dokumentasi Resmi

Gemini 3 Flash:

Code Execution API: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
Panduan Developer: https://ai.google.dev/gemini-api/docs/gemini-3
Dokumentasi Model: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
Kartu Model: https://deepmind.google/models/gemini/flash/

AlloyDB AI & ScaNN:

Benchmark Performa ScaNN: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
Memahami Indeks ScaNN: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
Mengenal AlloyDB AI Lebih Dalam: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
Praktik Terbaik untuk Penyesuaian: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
Dokumentasi AlloyDB: https://cloud.google.com/alloydb/docs

MCP Toolbox for Databases (pendekatan alternatif):

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

Informasi Harga:

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

Klaim Performa Terverifikasi

Fitur	Klaim	Sumber
ScaNN vs. HNSW (difilter)	10x lebih cepat	Blog Google Cloud (terverifikasi)
ScaNN vs HNSW (standar)	4x lebih cepat	Blog Google Cloud (terverifikasi)
Jejak memori ScaNN	3-4x lebih kecil	Blog Google Cloud (terverifikasi)
Waktu build indeks ScaNN	8x lebih cepat	Blog Google Cloud (terverifikasi)
Waktu tunggu eksekusi kode	Maksimum 30 detik	Dokumen Google Cloud (terverifikasi)
I/O file eksekusi kode	Tidak didukung	Dokumen Google Cloud (terverifikasi)
Perilaku Temperature=0	Output deterministik	Diverifikasi oleh komunitas

Referensi Tambahan

Protokol Agent-to-Agent (A2A):

A2A menstandardisasi penemuan dan komunikasi agen
Kartu agen yang ditayangkan di /.well-known/agent-card.json
Standar baru untuk kolaborasi agen otonom

Riset ScaNN:

Berdasarkan 12 tahun Riset Google
Mendukung Google Penelusuran dan YouTube dalam skala miliaran
Dirilis untuk ketersediaan umum: Oktober 2024
Indeks vektor PostgreSQL pertama yang cocok untuk vektor dalam jumlah jutaan hingga miliaran

12. Mode Tantangan: Tingkatkan Keterampilan Agentik Anda

Anda telah membangun supply chain otonom yang berfungsi. Siap untuk melangkah lebih jauh? Tantangan ini menerapkan pola yang telah Anda pelajari ke masalah baru.

Tantangan 1: Penelusuran Berbasis Gambar (Embedding Multimodal)

Alur Saat Ini: Agen Vision menghitung item → membuat kueri teks → Agen Supplier menyematkan teks → menelusuri AlloyDB

Tantangan: Lewati teks sepenuhnya—kirim gambar yang dipangkas langsung ke Agen Pemasok.

Petunjuk:

Eksekusi kode Vision Agent dapat memangkas item individual dari gambar rak
Model multimodalembedding@001 Vertex AI dapat menyematkan gambar secara langsung
Ubah inventory.py untuk menerima byte gambar, bukan teks
Perbarui deskripsi skill A2A untuk menunjukkan "Menerima: image/jpeg atau text"

Mengapa Hal Ini Penting: Penelusuran visual lebih akurat untuk suku cadang dengan tampilan yang kompleks (variasi warna, kerusakan, perbedaan kemasan).

Tantangan 2: Observabilitas—Kepercayaan Melalui Transparansi

Status Saat Ini: Sistem berfungsi, tetapi Anda tidak dapat melihat "di balik layar"

Tantangan: Periksa log kueri AlloyDB untuk membuktikan bahwa penelusuran vektor sedang dijalankan.

Langkah-langkah:

Insight kueri diaktifkan secara default di AlloyDB. Untuk memverifikasi, jalankan:

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

Menjalankan penelusuran pemasok melalui UI
Melihat SQL yang sebenarnya dijalankan:

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

Output yang Diharapkan: Anda akan melihat kueri ORDER BY part_embedding <=> $1::vector LIMIT 1 yang tepat dengan waktu eksekusi.

Mengapa Hal Ini Penting: Observabilitas membangun kepercayaan. Saat pemangku kepentingan bertanya "Bagaimana agen ini membuat keputusan?", Anda dapat menunjukkan rencana kueri, bukan hanya outputnya.

Tantangan 3: Komposisi Multi-Agen

Tantangan: Tambahkan agen ketiga (Agen Logistik) yang menghitung biaya pengiriman berdasarkan lokasi gudang dan berat item.

Arsitektur:

Output Vision Agent: jumlah item
Output Agen Pemasok: lokasi pemasok
Input Agen Logistik (BARU): tujuan, berat → output: biaya pengiriman + perkiraan waktu pengiriman

Petunjuk: Protokol A2A membuat hal ini menjadi mudah—buat kartu agen baru dengan kemampuan calculate_shipping. Control Tower akan menemukannya secara otomatis.

Pola yang Anda Pelajari: Ini adalah inti dari Arsitektur Berorientasi Agen—sistem kompleks yang dibangun dari spesialis kecil yang dapat dikomposisikan.

13. Kesimpulan

Anda telah berhasil beralih dari AI Generatif ke AI Agentik.

Yang kami bangun:

Vision: Kami mengganti "menebak" dengan Eksekusi Kode (Gemini 3 Flash melalui kunci API).
Memori: Kami mengganti "penelusuran lambat" dengan ScaNN AlloyDB (melalui GCP).
Tindakan: Kami mengganti "integrasi API" dengan Protokol A2A.

Manfaat Arsitektur Hybrid:

Codelab ini menunjukkan pendekatan hybrid:

Agen Vision: Menggunakan Gemini API (kunci API) - tersedia tingkat sederhana dan gratis, tidak memerlukan penagihan GCP
Agen Pemasok: Menggunakan GCP (Vertex AI + AlloyDB) - tingkat perusahaan, siap untuk kepatuhan

Inilah arsitektur ekonomi otonom. Kode tersebut dapat Anda simpan.

Langkah Berikutnya

Dapatkan Kunci Gemini API Anda (tersedia tingkat gratis)
Mempelajari Dokumentasi Gemini API
Baca Dokumentasi AI AlloyDB
Menjelajahi Eksekusi Kode Gemini

Membangun Rantai Pasokan yang Mandiri dengan Gemini 3 Flash & AlloyDB AI Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

1. Ringkasan

Arsitektur Deterministik

Yang akan Anda build

Yang akan Anda pelajari

Persyaratan

2. Sebelum memulai

Membuat project

Menyiapkan Database [AlloyDB]

Dapatkan Kode

Menetapkan Project Anda

Mengaktifkan IP Publik di AlloyDB

Memberikan Izin Vertex AI

Menjalankan Skrip Penyiapan

3. Penyiapan Database

Menghubungkan ke AlloyDB Studio

Mengaktifkan Ekstensi

Membuat Tabel Inventaris

Kolom part_embedding menyimpan vektor 768 dimensi dari text-embedding-005. Inilah yang mendukung penelusuran semantik.

Menyisipkan Data Sampel

Memberikan Izin Penyematan

Membuat Embedding Vektor

Membuat Indeks ScaNN

Memverifikasi Semuanya Berfungsi

4. Memahami Arsitektur

Stack Agen

Vision Agent (agents/vision-agent/)

Agen Pemasok (agents/supplier-agent/)

Control Tower (frontend/)

Alur A2A

Koneksi AlloyDB

5. Langkah 1: The Memory (Agen Pemasok)

The Audit: The Amnesiac

Mulai Agen Pemasok

Perbaikan: Menerapkan Operator <=>

Verifikasi

6. Langkah 2: Mata (Agen Visi)

Audit: Halusinasi

Solusi: Membangkitkan Loop Berpikir-Bertindak-Mengamati

Mulai Agen Vision

Verifikasi

7. Langkah 3: Handshake (Kartu Agen A2A)

A2A vs. REST API Tradisional

Membuat Kartu Agen

8. Langkah 4: Menara Pengontrol

Mulai Semua Layanan

Menguji Sistem

Apa yang Baru Saja Terjadi

Pemecahan masalah

9. 🎁 Bonus: Men-deploy ke Cloud Run

10. Pembersihan

11. Referensi & Bacaan Lebih Lanjut

Dokumentasi Resmi

Referensi Tambahan

12. Mode Tantangan: Tingkatkan Keterampilan Agentik Anda

Tantangan 1: Penelusuran Berbasis Gambar (Embedding Multimodal)

Tantangan 2: Observabilitas—Kepercayaan Melalui Transparansi

Tantangan 3: Komposisi Multi-Agen

13. Kesimpulan

Membangun Rantai Pasokan yang Mandiri dengan Gemini 3 Flash & AlloyDB AI