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 kesalahan yang merugikan.

Kita akan membangun Agen Rantai Pasokan 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:

1. The Eyes (Agen Vision): Kami mengaktifkan Gemini 3 Flash dengan Eksekusi Kode. Daripada memprediksi token untuk menebak angka, model menulis kode Python (OpenCV) untuk menghitung piksel secara deterministik.
2. 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.
3. The Handshake (A2A Protocol): Kami mengaktifkan komunikasi Agent-to-Agent menggunakan agent_card.json standar , sehingga Vision Agent dapat secara mandiri memesan stok dari Supplier Agent.

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 mengaktifkan Agentic Vision dengan gemini-3-flash-preview menggunakan Gemini API.
• Cara menerapkan penelusuran vektor menggunakan operator <=> (jarak kosinus) di AlloyDB.
• Cara menghubungkan Cloud Shell ke AlloyDB menggunakan Proxy Auth.

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

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

Untuk mencoba codelab ini, Anda dapat menggunakan Link Kredit Penagihan Uji Coba GCP: https://bit.ly/cvs14-ghj

Bagaimana cara menukarkan kredit menggunakan link ini? Merujuk.

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

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

Selesai!

Sekarang Anda siap untuk penyiapan sekali klik. Bagian berikutnya akan:

• Membuka Cloud Shell secara otomatis
• Melakukan cloning repositori
• Memandu Anda melakukan seluruh penyiapan dalam tutorial interaktif

3. Penyiapan Sekali Klik di Cloud Shell

Kami telah menyederhanakan penyiapan menjadi tutorial Cloud Shell terpandu. Semuanya bersifat otomatis: penyediaan infrastruktur, penyiapan AlloyDB, konfigurasi Auth Proxy, dan pengisian database.

Tutorial Meluncurkan Cloud Shell

⚠️ PENTING - Sebelum mengklik: Saat mengklik tombol di bawah, Anda akan melihat dialog keamanan yang menanyakan "Open in Cloud Shell". Tindakan ini muncul SEBELUM repositori di-clone.

Anda harus:

1. ✅ Centang kotak: "Trust repo"
2. ✅ Klik "Konfirmasi"

Tanpa ini, repositori tidak akan di-clone.

Sudah siap? Klik untuk membuka project dengan tutorial langkah demi langkah:

Satu Klik & Jalankan

Proses selanjutnya:

1. Cloud Shell akan terbuka dengan repositori yang sudah di-clone
2. Panel tutorial akan muncul di sebelah kanan dengan petunjuk langkah demi langkah
3. Anda akan dipandu dalam:

• Mendapatkan kunci Gemini API Anda (tersedia paket gratis)
• Menetapkan project GCP di terminal
• Menjalankan penyiapan (memeriksa API, mengaktifkan jika diperlukan, menyediakan AlloyDB: ~15 menit)
• Membuat 2 perubahan kode utama (mengaktifkan penglihatan + memori)
• Membuat kartu agen (protokol A2A)
• Memulai semua layanan

Tutorial ini bersifat interaktif—setiap langkah diberi nomor dan melacak progres Anda.

📌 Otomatis: Skrip penyiapan memeriksa autentikasi, API, dan konfigurasi project. Fitur ini akan meminta Anda untuk meninjau jika ada hal yang perlu diperhatikan.

💡 Aman untuk Memulai Ulang: Jika penyiapan macet atau gagal, Anda dapat menjalankan ulang sh setup.sh dengan aman. Skrip mendeteksi instance AlloyDB yang ada dan melewati penyediaan, melanjutkan dari tempat Anda berhenti.

Alternatif: Penyiapan Manual

Jika Anda lebih memilih kontrol manual:

1. Buka Cloud Shell dan verifikasi project Anda telah disetel

gcloud config get-value project

2. Jika perlu, tetapkan project Anda

gcloud config set project YOUR_PROJECT_ID

3. Melakukan cloning repositori

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

4. Menjalankan penyiapan

sh setup.sh

Ikuti petunjuk di layar dari skrip penyiapan.

Langkah Berikutnya: Tutorial ini akan memandu Anda menyelesaikan langkah-langkah lainnya. Setelah selesai, lanjutkan ke Bagian 4 untuk memahami apa yang terjadi di balik layar

4. Di Balik Layar: Proxy Auth & Pengisian Database

Catatan: Jika Anda menggunakan tutorial Cloud Shell lengkap, semua ini akan otomatis. Bagian ini menjelaskan apa yang terjadi di balik layar.

Masalahnya: AlloyDB berada di dalam VPC Pribadi. Cloud Shell berada di luarnya. Koneksi langsung tidak mungkin dilakukan.

Perbaikan: Proxy Auth AlloyDB membuat tunnel yang aman dan diautentikasi IAM dari 127.0.0.1:5432 di Cloud Shell ke instance AlloyDB Anda. Jika instance Anda mengaktifkan IP Publik, proxy akan menggunakannya; jika tidak, proxy akan terhubung melalui IP pribadi VPC.

Tindakan yang Dilakukan setup.sh

1. Mendeteksi instance AlloyDB Anda secara otomatis (cluster, region, project)
2. Membuat .env dengan semua kredensial (GEMINI_API_KEY, DB_PASS, detail AlloyDB)
3. Mendownload dan memulai Proxy Auth (dengan –public-ip jika berlaku)
4. Mengisi database dengan 8 bagian inventaris contoh + indeks ScaNN

File .env Anda sudah siap. Semua proses berikutnya akan memuat kredensial secara otomatis.

Memverifikasi Keberhasilannya

Pastikan Anda masih berada di root repo

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

Memeriksa apakah Auth Proxy sedang berjalan

ps aux | grep alloydb-auth-proxy

Yang Dibuat

• tabel inventaris dengan 8 bagian dan embedding 768 dimensi
• Indeks ScaNN (idx_inventory_scann) untuk penelusuran vektor yang cepat

Error Umum:

• "DB_PASS tidak ditetapkan": Jalankan ulang sh setup.sh untuk membuat ulang .env.
• "Connection refused": Proxy Auth mungkin memerlukan waktu lebih lama. Tunggu 30 detik, lalu coba lagi.
• "No instance found": Verifikasi deployment: gcloud alloydb instances list
• "Error bus" (Proxy Auth berhenti): Kerusakan biner. Perbaikan: rm alloydb-auth-proxy && sh setup.sh

5. Langkah 1: The Memory (Agen Pemasok)

Catatan: Jika Anda menggunakan tutorial Cloud Shell, Anda sudah melakukan perubahan kode ini. Bagian ini menjelaskan mengapa hal ini penting dan cara kerjanya.

Agen Pemasok mengingat jutaan suku cadang menggunakan ScaNN AlloyDB. Kita memulainya sebagai server A2A, lalu memperbaiki kueri vektor.

Audit: Amnesia

Jika Anda mengkueri Agen Pemasok sekarang (dengan SQL placeholder), agen akan menampilkan baris pertama yang ditemukannya, bukan kecocokan terdekat. Tidak memiliki konsep kesamaan. Dia adalah seorang amnesia.

Mulai Agen Pemasok

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

💡 Tips Pemecahan Masalah: Jika Anda mendapatkan error "alamat sudah digunakan", hentikan proses yang ada dan coba lagi:

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

Embedding Semantik Nyata

Selama penyiapan, database diisi dengan embedding semantik asli yang dihasilkan melalui model text-embedding-005 Google Gen AI SDK. Hal ini memastikan pencocokan kemiripan yang akurat - bukan vektor acak. Proses penanaman memerlukan waktu sekitar 10 detik untuk 13 item contoh menggunakan pembuatan embedding paralel untuk membuat vektor 768 dimensi yang bermakna yang menangkap makna semantik setiap bagian.

Penyimpangan AlloyDB: Mengapa ScaNN?

Catatan: Standard Vector Search (HNSW) membutuhkan banyak memori. Saat inventaris Anda bertambah hingga 100 juta suku cadang, indeks menjadi terlalu besar untuk RAM. ScaNN (Scalable Nearest Neighbors) menggunakan Vector Quantization. Vektor dikompresi sehingga indeks sesuai dengan Cache L2 CPU. Hal ini membuatnya 10x lebih cepat daripada HNSW standar.

Perbaikan: Menerapkan Operator <=>

Agen ini dilengkapi dengan kueri placeholder. Kita perlu mengaktifkan penelusuran vektor ScaNN.

Langkah 1: Buka file inventaris

cd agents/supplier-agent

Langkah 2: Temukan TODO di inventory.py

Cari fungsi find_supplier() di sekitar baris 47-60. Anda akan melihat:

# ============================================================
# CODELAB STEP 1: Implement ScaNN Vector Search
# ============================================================
# TODO: Replace this placeholder query with ScaNN vector search

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

Langkah 3: Ganti SQL placeholder dengan penelusuran vektor ScaNN

Hapus kedua baris ini:

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

Lalu ganti dengan:

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

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
• LIMIT 1 hanya menampilkan kecocokan terdekat
• 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')
"

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

Error Umum:

• "Tidak ada file atau direktori tersebut": Anda tidak berada di root repo. Jalankan cd untuk kembali ke direktori utama, lalu cd visual-commerce-gemini-3-alloydb, atau gunakan pwd untuk menemukan lokasi Anda.
• Port 8082 sedang digunakan: Hentikan proses yang ada: lsof -ti:8082 | xargs kill -9
• ModuleNotFoundError: Instal dependensi: pip install -r requirements.txt
• Database connection failed: Pastikan Proxy Auth masih berjalan
• Skrip verifikasi gagal: Periksa apakah penyiapan berhasil diselesaikan di Langkah 4

6. Langkah 2: Mata (Agen Visi)

Catatan: Jika Anda menggunakan tutorial Cloud Shell, Anda sudah mengaktifkan Eksekusi Kode. Bagian ini menjelaskan arsitektur dan alasan pendekatan ini menghilangkan halusinasi.

Saat database dapat diakses, mari kita buka mata menggunakan Gemini 3 Flash. Agen Vision melakukan "matematika visual" melalui Eksekusi Kode. Server A2A (main.py) mendelegasikan ke agent_executor.py, yang memanggil agent.py untuk analisis Gemini.

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 Siklus Berpikir-Bertindak-Mengamati

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

1. Buka agents/vision-agent/agent.py .
2. Temukan bagian GenerateContentConfig.
3. Hapus tanda komentar pada blok thinking_config=types.ThinkingConfig(...) dan tools=[types.Tool(code_execution=...)] .
4. Klien sudah dikonfigurasi untuk menggunakan GEMINI_API_KEY Anda dari lingkungan.

Tips: thinking_level="LOW" menyeimbangkan kecepatan dan akurasi. Nilai yang valid: "MINIMAL", "LOW", "MEDIUM", "HIGH". Memerlukan google-genai>=1.56.0.

Catatan Arsitektur: Vision Agent menggunakan Gemini API (kunci API), sedangkan Supplier Agent menggunakan embedding Vertex AI (kredensial GCP). Pendekatan hibrida ini menjaga komponen visi tetap sederhana sekaligus mempertahankan fitur database tingkat perusahaan.

File: agents/vision-agent/agent.py

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

Mengapa thinking_level="LOW"?

Untuk tugas khusus ini (menghitung item melalui eksekusi kode), "RENDAH" memberikan anggaran penalaran yang memadai untuk:

• Merencanakan struktur skrip Python
• Menentukan pendekatan pemrosesan gambar yang akan digunakan
• Pastikan jumlahnya sama dengan jumlah kotak pembatas

Menggunakan "TINGGI" akan menambah latensi dan biaya 2-3x tanpa meningkatkan akurasi untuk tugas deterministik. Cadangkan "TINGGI" untuk penalaran multi-langkah yang kompleks (misalnya, Analisis gangguan supply chain ini dan rekomendasikan 3 pemasok alternatif beserta alasannya").

Pengoptimalan Performa Biaya adalah keterampilan utama untuk rekayasa 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.

Error Umum:

• "No such file or directory": Anda tidak berada di root repo. Gunakan cd ../.. untuk kembali ke root repo, atau periksa lokasi Anda dengan pwd.
• Port 8081 sedang digunakan: Hentikan proses yang ada: lsof -ti:8081 | xargs kill -9
• GEMINI_API_KEY tidak disetel: Periksa apakah file .env ada di root repo dengan perintah cat .env | grep GEMINI_API_KEY
• Kunci API tidak valid: Pastikan kunci Anda sudah benar dan belum habis masa berlakunya
• google-genai tidak ditemukan: Instal dependensi: pip install -r requirements.txt

7. Langkah 3: Handshake (Kartu Agen A2A)

Catatan: Jika Anda menggunakan tutorial Cloud Shell, Anda sudah membuat kartu agen ini. Bagian ini menjelaskan protokol A2A dan alasan protokol ini memungkinkan komposisi agen plug-and-play.

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 bahasa alami.

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

Solusi: Buat Kartu Agen

Kita perlu menentukan apa yang dapat dilakukan Agen Pemasok.

1. Salin agents/supplier-agent/agent_card_skeleton.json ke agents/supplier-agent/agent_card.json.
2. Edit file untuk mengganti placeholder:

Sebelum (kerangka):

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

Setelah (hasil edit Anda):

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

3. Mulai ulang Agen Pemasok agar kartu baru dimuat:

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

Catatan: Jika Anda menggunakan tutorial Cloud Shell, layanan Anda sudah berjalan. Buka bagian "Uji Sistem" di bawah untuk mengakses Control Tower dan menyaksikan alur kerja otonom beraksi.

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:

• Proxy Auth AlloyDB (jika tidak berjalan)
• Vision Agent di port 8081
• Supplier Agent di port 8082
• Control Tower di port 8080

Tunggu ~10 detik hingga semua layanan diinisialisasi.

💡 Tips Pemecahan Masalah: Jika run.sh gagal dengan error "address already in use":

Hentikan semua layanan, lalu coba lagi

pkill -f uvicorn

sh run.sh

Hal ini terjadi jika layanan masih berjalan dari upaya sebelumnya.

Menguji Sistem

Akses Control Tower:

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

Catatan: Frontend menggunakan WebSockets real-time untuk update agen langsung. Anda akan melihat kartu agen diperbarui saat mereka berpikir, menganalisis, dan bertindak—tidak perlu memuat ulang halaman.

Jalankan Demo:

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

Opsi 1: Mulai Cepat (Direkomendasikan)

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

Opsi 2: Upload Milik Anda

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

Yang Terjadi:

1. Penemuan Agen: Modal protokol A2A menampilkan kartu Agen Visi dan Agen Pemasok dengan keterampilan dan endpoint-nya
2. Analisis Visi: 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 "✓ Terverifikasi Kode" atau "~ Diperkirakan"
3. Pencocokan Pemasok: Animasi penelusuran vektor ScaNN AlloyDB. Tampilan kueri penelusuran (misalnya, "kotak logam industri"). Kartu hasil menampilkan kecocokan suku cadang, supplier, dan skor keyakinan
4. 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 (AlloyDB ScaNN), 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:

• "Tidak ada file atau direktori tersebut" 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 Proxy Auth sedang berjalan:

ps aux | grep alloydb-auth-proxy

Masalah Koneksi AlloyDB:

Jika Anda melihat koneksi ke server di 127.0.0.1, port 5432 gagal:

Jika Anda melihat koneksi ke server di 127.0.0.1, port 5432 gagal:

1. Periksa Proxy Auth: ps aux | grep alloydb-auth-proxy
2. Verifikasi IP Publik diaktifkan: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
3. Untuk pengembangan lokal (bukan Cloud Shell):
4. Masalah: Cloud Shell berfungsi secara otomatis, tetapi mesin lokal memerlukan jaringan yang diberi otorisasi
5. Solusi: Jalankan kembali penyiapan sh setup.sh dan pilih opsi 1 (authorize 0.0.0.0/0) saat diminta
6. Catatan Keamanan: Meskipun dengan 0.0.0.0/0, koneksi memerlukan:
7. Kredensial GCP yang valid (Kredensial Default Aplikasi)
8. Sandi database
9. Enkripsi mTLS (ditangani oleh Proxy Auth)

9. Pembersihan

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

# From repo root
sh cleanup.sh

Tindakan ini akan menghapus dengan aman:

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

Skrip akan meminta konfirmasi sebelum menghapus apa pun.

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

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)
Batas waktu eksekusi kode	Maksimum 30 detik	Dokumen Google Cloud (terverifikasi)
Eksekusi kode I/O file	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 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

11. Mode Tantangan: Tingkatkan Keterampilan Agentik Anda

Anda telah membangun rantai pasokan 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:

1. Eksekusi kode Vision Agent dapat memangkas item individual dari gambar rak
2. Model multimodalembedding@001 Vertex AI dapat menyematkan gambar secara langsung
3. Ubah inventory.py untuk menerima byte gambar, bukan teks
4. 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 composable kecil.

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