Gemini 3 Flash ve AlloyDB AI ile bağımsız bir tedarik zinciri oluşturma

1. Genel Bakış

Okuyan Chatbotlar" dönemi sona eriyor. Temsilci tabanlı vizyon çağına giriyoruz.

Bu Codelab'de, tahmin yürütmeyen yapay zeka sistemleri oluşturma uygulaması olan Belirleyici Yapay Zeka Mühendisliği'ni uygulayacağız. Standart yapay zeka modelleri, karmaşık bir resimdeki öğeleri saymaları istendiğinde genellikle "halüsinasyon" (tahmin) yapar. Tedarik zincirinde tahmin yapmak tehlikelidir. Yapay zeka, 15 öğeniz olduğu halde 12 öğeniz olduğunu tahmin ederse maliyetli hatalara yol açar.

Gemini 3 Flash'taki yeni Düşün, Hareket Et, Gözlemle döngüsünü kullanarak Otonom Tedarik Zinciri Temsilcisi oluşturacağız. Sadece bakmaz, araştırır.

Deterministik Mimari

"Kör" ve "hafızasız" bir sistemle başlayacağız. Duyularını tek tek manuel olarak "uyandıracaksınız":

17191a91a9c54146.png

  1. The Eyes (Vision Agent): Kod Yürütme ile Gemini 3 Flash'i etkinleştiriyoruz. Model, bir sayıyı tahmin etmek için jetonları tahmin etmek yerine pikselleri deterministik olarak saymak için Python kodu (OpenCV) yazar.
  2. Bellek (Tedarikçi Aracısı): ScaNN (Ölçeklenebilir En Yakın Komşular) ile AlloyDB AI'yı etkinleştiriyoruz. Bu sayede aracı, milyonlarca seçenek arasından bir parçanın tam tedarikçisini milisaniyeler içinde hatırlayabilir.
  3. El Sıkışma (A2A Protokolü): Standartlaştırılmış bir agent_card.json kullanarak Temsilciden Temsilciye iletişimi etkinleştiririz. Bu sayede Vision Agent , tedarikçi temsilcisinden bağımsız olarak stok siparişi verebilir.

Ne oluşturacaksınız?

  • Kamera feed'lerinde "görsel matematik" işlemleri yapan bir Vision Agent.
  • Yüksek hızlı vektör araması için AlloyDB ScaNN tarafından desteklenen bir Tedarikçi Aracısı.
  • Özerk döngüyü görselleştirmek için gerçek zamanlı WebSocket güncellemeleri içeren bir Control Tower ön ucu.

Neler öğreneceksiniz?

  • AlloyDB'yi vektör yerleştirmeleri ve ScaNN dizinleriyle ayarlama
  • Gemini API'yi kullanarak gemini-3-flash-preview ile Agentic Vision'ı etkinleştirme
  • AlloyDB'de <=> (kosinüs uzaklığı) operatörünü kullanarak vektör aramayı uygulama.
  • AlloyDB Python Bağlayıcısı'nı kullanarak aracıları AlloyDB'ye bağlama
  • Dinamik aracı keşfi için A2A protokolünü kullanma.

Şartlar

  • Chrome veya Firefox gibi bir tarayıcı
  • Faturalandırmanın etkin olduğu bir Google Cloud projesi.
  • Vision Agent için Gemini API anahtarı (Google AI Studio'da ücretsiz katman mevcuttur).

2. Başlamadan önce

Proje oluşturma

  1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.
  1. Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.

Cloud Shell&#39;i etkinleştir düğmesinin resmi

  1. Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulandığını ve projenin proje kimliğinize ayarlandığını kontrol edin:
gcloud auth list

Veritabanı Kurulumu [AlloyDB]

Her şeyden önce veritabanını hazırlayalım. Bu işlem yaklaşık 15 dakika sürer.

  1. AlloyDB kurulum aracını Cloud Shell'de açmak için aşağıdaki düğmeyi tıklayın:

  1. Kurulumu çalıştırın:
Sh run.sh
  1. Kurulum kullanıcı arayüzünü açmak için web önizlemesini (göz simgesi 👁️ → 8080 numaralı bağlantı noktasında önizle) kullanın.
  2. Proje kimliğinizi girin, bir bölge (ör. us-central1) seçin ve veritabanı şifresi oluşturun.

⚠️ BU ŞİFREYİ KAYDEDİN. Kurulum komut dosyası istediğinde bu şifreye ihtiyacınız olacaktır.

  1. Dağıtımı Başlat'ı tıklayın ve kümenin sağlanması için yaklaşık 15 dakika bekleyin.

Kodu Al

AlloyDB'nin sağlama işlemi devam ederken (veya tamamlandıktan sonra) Cloud Shell'de codelab deposunu açın:

⚠️ ÖNEMLİ: Düğmeyi tıkladığınızda bir güvenlik iletişim kutusu görürsünüz. "Depoya güven" kutusunu işaretleyin ve "Onayla"yı tıklayın.

Alternatif olarak, manuel olarak klonlayın:

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

cd visual-commerce-gemini-3-alloydb

Projenizi ayarlama

Bu Cloud Shell terminalinde projenizin ayarlandığını onaylayın:

gcloud config set project <YOUR_PROJECT_ID>

AlloyDB'de genel IP'yi etkinleştirme

AlloyDB sağlama işlemi tamamlandıktan sonra Python bağlayıcısının Cloud Shell'den bağlanabilmesi için genel IP'yi etkinleştirin:

  1. AlloyDB Console'a gidin.
  2. Kümenizi → birincil örneğinizi tıklayın.
  3. Düzenle'yi tıklayın.
  4. Genel IP Bağlantısı'na gidin ve Genel IP'yi Etkinleştir'i işaretleyin.
  5. Örneği Güncelle'yi tıklayın.

💡 Not: AlloyDB Python Bağlayıcısı, kimlik doğrulama ve şifreleme işlemlerini gerçekleştirir. Yetkili harici ağ eklemeniz gerekmez.

Vertex AI İzinleri Verme

AlloyDB hizmet hesabının, yerleştirmeler oluşturmak için Vertex AI erişimine ihtiyacı vardır. Aynı Cloud Shell penceresinde şunu çalıştırın:

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"

Kurulum komut dosyasını çalıştırma

Şimdi kurulum komut dosyasını çalıştırın. Bu komut dosyası, AlloyDB örneğinizi otomatik olarak algılar:

sh setup.sh

Komut dosyasının yaptığı işlemler:

  • gcloud CLI, kimlik doğrulama, proje ve Python 3'ü doğrular.
  • Gerekli API'leri (AlloyDB, Vertex AI, Compute, Service Networking) kontrol eder ve etkinleştirir.
  • Gemini API anahtarınız için istemler
  • AlloyDB örneğinizi otomatik olarak algılar ve bölge, küme ve örnek adını ayıklar.
  • Veritabanı şifrenizi istiyor
  • .env yapılandırma dosyasını oluşturur.
  • Python bağımlılıklarını yükler.

3. Veritabanı kurulumu

Uygulamamızın temelinde PostgreSQL için AlloyDB yer alıyor. Neredeyse anlık semantik arama sağlamak için bu hizmetin güçlü vektör özelliklerinden ve ScaNN dizininden yararlanacağız. Böylece, temsilcilerimiz binlerce kayıt arasında milisaniyeler içinde envanter eşleşmeleri bulabilecek.

Bu bölümde, şemayı sağlama, verileri doldurma ve yerleştirmeler oluşturma işlemlerini AlloyDB Studio'dan yapacaksınız.

AlloyDB Studio'ya bağlanma

  1. AlloyDB Console'da AlloyDB örneğinize gidin.
  2. Soldaki gezinme panelinde AlloyDB Studio'yu tıklayın.
  3. Kimlik doğrulama yöntemi:
  4. Kullanıcı adı: postgres
  5. Veritabanı: postgres
  6. Şifre: Küme oluşturma sırasında belirlediğiniz şifre

Uzantıları etkinleştirme

AlloyDB, vektörler ve yapay zeka için yerleşik uzantılar sağlar. AlloyDB Studio'da aşağıdaki SQL'i çalıştırın:

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: Vertex AI'ı doğrudan SQL'den çağırmak için ai.embedding() işlevini etkinleştirir.
  • vector: 768 boyutlu vektör yerleştirmelerini depolar ve sorgular.
  • alloydb_scann: Google'ın ScaNN dizinini etkinleştirerek ultra hızlı vektör araması yapılmasını sağlar.

Envanter tablosunu oluşturma

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

part_embedding sütununda, text-embedding-005'ten elde edilen 768 boyutlu vektörler saklanır. Semantik arama bu şekilde çalışır.

Örnek Veri Ekleme

20 depo envanter öğesi ekleyin:

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

Yerleştirme İzinleri Verme

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Vektör yerleştirmeleri oluşturma

Bu işlemde, Vertex AI'ın text-embedding-005 modelini doğrudan SQL'den çağırmak için AlloyDB'nin yerleşik ai.embedding() işlevi kullanılır. Python kodu gerekmez:

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

Bu işlem, her parçanın adının ve açıklamasının anlamsal anlamını yakalayan 768 boyutlu vektörler oluşturur. ScaNN dizini, ışık hızında benzerlik araması için bunları kullanır. [Bu işlem yaklaşık 3-5 dakika sürecektir]

ScaNN dizinini oluşturma

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

Her şeyin çalıştığını doğrulama

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

20 satır görmeniz gerekir. Bu satırların tümünde has_embedding = true olmalıdır.

4. Mimarinin Anlaşılması

Kodda değişiklik yapmadan önce sistemin nasıl oluşturulduğunu anlayalım. Mimari, aşamalı bir "uyanış" modelini izler:

The Agent Stack

Vision Agent (agents/vision-agent/)

  • agent.py: Temel Gemini 3 Flash mantığı. Öğeleri deterministik olarak saymak için Python (OpenCV) yazması amacıyla, kod yürütme etkinleştirilmiş şekilde modele resimler gönderir.
  • agent_executor.py: A2A protokolü isteklerini aracı mantığına bağlar.
  • main.py: /.well-known/agent-card.json dosyasını sunan ve istekleri işleyen Uvicorn A2A sunucusu.

Tedarikçi Aracısı (agents/supplier-agent/)

  • inventory.py: AlloyDB Python Bağlayıcısı aracılığıyla AlloyDB'ye bağlanır (Auth Proxy gerekmez). ScaNN vektör araması gerçekleştiren find_supplier() işlevini içerir.
  • agent_executor.py: A2A protokolünü envanter arama mantığına bağlar.
  • main.py: Aracı kartı ve sağlık uç noktası içeren Uvicorn A2A sunucusu.

Control Tower (ön uç)

  • app.py: A2A aracılığıyla aracıları keşfeden, vision → search → order işlem hattını düzenleyen ve tarayıcıya gerçek zamanlı güncellemeler yayınlayan FastAPI + WebSocket sunucusu.

A2A akışı

  • Control Tower, her temsilciden /.well-known/agent-card.json dosyasını okur.
  • Özellikleri (beceriler, uç noktalar) keşfeder. Sabit kodlanmış URL'ler yoktur.
  • Resmi Vision Agent'a gönderir → öğe sayısı ve açıklaması alınır
  • Açıklamayı tedarikçi temsilcisine yerleştirme sorgusu olarak gönderir → kısmi eşleşme alır
  • Bağımsız olarak sipariş verme

AlloyDB Bağlantısı

Tedarikçi Aracısı, geleneksel Auth Proxy yerine AlloyDB Python Bağlayıcısı'nı kullanır:

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
)

Bu, IAM kimlik doğrulama, SSL/TLS ve bağlantı yönlendirmeyi otomatik olarak işler. Daha sonra Cloud Run'a dağıtım yaparken VPC erişimi için ip_type değerini "PRIVATE" olarak değiştirmeniz yeterlidir.

5. 1. adım: Bellek (Tedarikçi Temsilcisi)

Tedarikçi Aracısı, AlloyDB ScaNN'yi kullanarak milyonlarca parçayı hatırlar. Şu anda, ne aradığınızdan bağımsız olarak bulduğu ilk satırı döndüren bir amnezi arama sorgusuyla birlikte gelir.

The Audit: The Amnesiac

Tedarikçi aracısını şu anda sorgularsanız rastgele bir sonuç döndürür. Benzerlik kavramı yoktur. Gelin bu sorunu çözelim.

Tedarikçi Temsilcisi'ni başlatma

A2A sunucusu (main.py), protokolü inventory.py'deki iş mantığına bağlayan agent_executor.py'ye yetki verir.

pkill -f uvicorn #Kill all uvicorn processes

1. adım: Aracı dizinine gidin

cd agents/supplier-agent

2. adım: Bağımlılıkları yükleyin

pip install -r requirements.txt

3. adım: Aracı sunucusunu başlatın

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

> /dev/null 2>&1 & komutu, sunucuyu arka planda çalıştırır ve çıkışı bastırarak terminalinizi kesintiye uğratmaz.

4. adım: Temsilcinin çalıştığını doğrulayın (başlattıktan sonra 2-3 saniye bekleyin)

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

Beklenen Çıkış: Aracı yapılandırması içeren JSON (hatasız döndürülmelidir)

Çözüm: <=> operatörünü uygulama

agents/supplier-agent/inventory.py dosyasını açın ve 60-70. satırlar civarında find_supplier() işlevini bulun. Yer tutucuyu görürsünüz:

# TODO: Replace this placeholder query with ScaNN vector search

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

Bu iki satırı şununla değiştirin:

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

Bu özellik ne işe yarar?

  • <=>, PostgreSQL'deki kosinüs uzaklığı operatörüdür.
  • ORDER BY part_embedding <=> %s::vector, en yakın eşleşmeyi (en düşük mesafe = en yakın anlamsal anlam) bulur.
  • %s::vector, yerleştirme dizinizi PostgreSQL'in vektör türüne dönüştürür.
  • ScaNN dizini bu sorguyu otomatik olarak hızlandırır.

4. adım: Dosyayı kaydedin (Ctrl+S veya Cmd+S)

Artık rastgele sonuçlar döndürmek yerine semantik arama kullanacak.

Doğrulama

A2A keşfini ve envanteri test edin:

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

44500cdeeca3cee8.png

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

Beklenen: agent-card.json, temsilci kartını döndürür. Python snippet'i, başlangıç verilerinden bir parça ve tedarikçi döndürür.

6. 2. adım: Gözler (Vision Agent)

Veritabanına erişilebilirken Gemini 3 Flash'ı kullanarak gözleri uyandıralım. Vision Agent, Code Execution aracılığıyla "görsel matematik" işlemleri gerçekleştirir.

Denetim: Halüsinasyon

Standart bir çok formatlı modele "Bu dağınık resimde kaç kutu var?" diye sorarsanız resmi statik bir anlık görüntü olarak işler ve tahminde bulunur.

  • Modelin yanıtı: "Yaklaşık 12 kutu görüyorum."
  • Gerçeklik: 15 kutu var.
  • Sonuç: Tedarik zinciri hatası.

Çözüm: Düşünme-Eyleme Geçme-Gözlemleme Döngüsünü Uyandırma

Modelin deterministik olarak sayması için Kod Yürütme ve ThinkingConfig'i etkinleştiriyoruz.

  1. Open agents/vision-agent/agent.py dosyasını açın .
  2. GenerateContentConfig bölümünü (68-78. satırlar civarında) bulun.
  3. Hem thinking_config=types.ThinkingConfig(...) bloğunun hem de tools=[types.Tool(code_execution=...)]. satırının açıklamasını iptal edin.
  4. İstemci, ortamdan GEMINI_API_KEY'nizi kullanacak şekilde zaten yapılandırılmış.

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

Neden thinking_level="MINIMAL"?

Bu görev (kod yürütme yoluyla öğeleri sayma) için "MINIMAL" (MİNİMAL), komut dosyasını planlamak ve sayımı doğrulamak için yeterli gerekçeyi sunar. "YÜKSEK" ayarını kullanmak, deterministik görevlerde doğruluğu artırmadan 2-3 kat gecikmeye neden olur. Maliyet-Performans Optimizasyonu: Muhakeme derinliğini görev karmaşıklığıyla eşleştirin.

Maliyet-Performans Optimizasyonu, üretimde yapay zeka mühendisliği için önemli bir beceridir: Muhakeme derinliğini görev karmaşıklığıyla eşleştirin.

Vision Agent'ı başlatma

🔄 Yol Kontrolü: Hâlâ agents/supplier-agent/ dizinindeyseniz önce cd ../.. komutuyla depo köküne geri dönün.

1. adım: Vision aracısı dizinine gidin

cd agents/vision-agent

2. adım: Bağımlılıkları yükleyin

pip install -r requirements.txt

3. adım: Vision Agent sunucusunu başlatın

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

> /dev/null 2>&1 & komutu, sunucuyu arka planda çalıştırır ve çıkışı bastırarak terminalinizi kesintiye uğratmaz.

Doğrulama

A2A keşfini test etme:

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

Beklenen: Temsilci adı ve becerilerini içeren JSON. 8. adımda, Kontrol Kulesi kullanıcı arayüzü ile gerçek görüntü sayımını test edeceksiniz.

dc9bc53007336472.png

7. 3. adım: El sıkışma (A2A Agent Card)

Ajanımız sorunu görüyor (Vision) ve tedarikçiyi biliyor (Memory). A2A protokolü, dinamik keşfe olanak tanır. Ön uç, kartını okuyarak her bir aracıyla nasıl iletişim kuracağını öğrenir.

A2A ve geleneksel REST API'leri

Aspect

Geleneksel REST

A2A Protokolü

Uç nokta keşfi

Yapılandırmadaki sabit kodlu URL'ler

/.well-known/agent-card.json üzerinden dinamik

Özellik Açıklaması

API belgeleri (insanlar için)

Beceriler (makine tarafından okunabilir)

Entegrasyon

Hizmet başına manuel kod

Anlamsal eşleşme: "Envanter araması yapmam gerekiyor" → beceriyi keşfeder

Yeni Temsilci Eklendi

Tüm istemcilerin yapılandırmalarını güncelleme

Sıfır yapılandırma: otomatik olarak keşfedilir

Gerçek Dünyadaki Faydası: Geleneksel bir mikro hizmette üçüncü bir "Lojistik Acentesi" eklediğinizde, Kontrol Kulesi'nin kodunu URL'si ve API sözleşmesiyle güncellemeniz gerekir. A2A ile Control Tower, bunu otomatik olarak keşfeder ve doğal dil beceri açıklamaları aracılığıyla yeteneklerini anlar.

Bu nedenle A2A, Plug-and-Play Agent Composition'ı (otonom sistemler için mimari kalıp) etkinleştirir.

Aracı kartını oluşturma

🔄 Yol Kontrolü: Hâlâ agents/vision-agent/ dizinindeyseniz önce cd ../.. komutuyla depo köküne geri dönün.

Aracı kartı, agents/supplier-agent/agent_card.json adresinde zaten yer alıyor. E-postayı açıp şunları inceleyin:

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

Adı, açıklamayı veya örnekleri kullanım alanınıza uyacak şekilde özelleştirebilirsiniz.

Kartı yüklemek için Tedarikçi Aracısı'nı yeniden başlatın:

1. adım: Çalışan aracıyı durdurun

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

2. adım: Aracı dizinine gidin

cd agents/supplier-agent

3. adım: Aracıyı tekrar başlatın

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

> /dev/null 2>&1 & komutu, sunucuyu arka planda çalıştırır ve çıkışı bastırarak terminalinizi kesintiye uğratmaz.

4. adım: Yeni temsilci kartını doğrulayın (başlattıktan sonra 2-3 saniye bekleyin)

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

Beklenen Çıkış: Doldurulmuş adınız, açıklamanız ve becerilerinizle ilgili JSON.

dd352ca2e7e6109a.png

8. 4. adım: Kontrol Kulesi

Control Tower ön ucunu FastAPI + WebSockets ile çalıştırın. A2A aracılığıyla aracıları keşfeder ve gerçek zamanlı güncellemelerle tüm döngüyü düzenler.

Tüm Hizmetleri Başlat

Tüm hizmetleri başlatmanın en kolay yolu:

Depo kök dizininde olduğunuzu doğrulayın

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

Ardından:

sh run.sh

Bu tek komut şunları başlatır:

  • 8081 bağlantı noktasındaki Vision Agent
  • 8082 numaralı bağlantı noktasında tedarikçi aracısı
  • 8080 numaralı bağlantı noktasında Control Tower

Tüm hizmetlerin başlatılması için yaklaşık 10 saniye bekleyin.

Sistemi Test Etme

Kontrol Kulesi'ne erişme:

  1. Cloud Shell araç çubuğunda Web Önizlemesi düğmesini (göz simgesi 👁️) tıklayın.
  2. "8080 numaralı bağlantı noktasında önizle"yi seçin.
  3. Control Tower kontrol paneli yeni bir sekmede açılır.

Demoyu Çalıştırma:

  1. Sağ üst: Bağlantı durumu (yeşil "Canlı" nokta), DEMO/AUTO modu açma/kapatma düğmesi ve ses kontrolleri
  2. Merkez: Resim yükleme ve analiz görselleştirmesi içeren ana iş akışı tuvali
  3. Yan paneller (analiz sırasında görünür): İş akışı zaman çizelgesi (sol), ilerleme durumu takibi ve kod görüntüleyici (sağ)

1. seçenek: Hızlı Başlangıç (Önerilir)

  1. Ana sayfada, örnek resimlerin yer aldığı "Hızlı başlangıç" bölümünü görürsünüz.
  2. Analizi otomatik olarak başlatmak için herhangi bir örnek resmi tıklayın.
  3. Otonom iş akışını izleyin (~30-45 saniye).

2. seçenek: Kendi öğenizi yükleme

  1. Bir depo/raf resmi (PNG, JPG, en fazla 10 MB) sürükleyip bırakın veya göz atmak için tıklayın.
  2. "Initiate Autonomous Workflow" (Bağımsız İş Akışı Başlat) seçeneğini tıklayın.
  3. 4 aşamalı ardışık düzeni inceleyin

Ne olur?

  1. Temsilci Keşfi: A2A protokolü modallarında, Vision Agent ve Supplier Agent kartları becerileri ve uç noktalarıyla birlikte gösterilir.
  2. Görsel Analizi: Gemini 3 Flash, öğeleri saymak için Python kodu (OpenCV) oluşturur ve yürütür. İlerleme çubuğunda alt adımlar gösterilir. Sınırlayıcı kutular, algılanan öğelerin üzerine yerleştirilir. Sonuç rozetinde "✓ Kod Doğrulandı" veya "~ Tahmini" gösterilir.
  3. Tedarikçi Eşleştirme: AlloyDB ScaNN vektör arama animasyonu. Arama sorgusu gösterimleri (ör. "endüstriyel metal kutular") Sonuç kartında eşleşen parça, tedarikçi ve güven puanı gösterilir.
  4. Sipariş Verildi: Sipariş kimliği, miktar ve ayrıntıların yer aldığı makbuz kartı

İpucu: Sunularda her aşamada duraklatmak için DEMO modunu (sağ üstte) açık tutun. AUTO modunda iş akışı sürekli olarak çalışır.

1a031c4fd407a183.png

What Just Happened

Kontrol kulesi, her iki aracı da /.well-known/agent-card.json üzerinden keşfetmek için A2A protokolünü kullandı, kod yürütme özellikli Gemini 3 Flash ile görsel analizini düzenledi, vektör araması (AlloyDB ScaNN) gerçekleştirdi ve bağımsız bir sipariş verdi. Tüm bunlar, anlık WebSocket güncellemeleriyle yapıldı. Her aracı, A2A standardı aracılığıyla özelliklerini kullanıma sunar. Bu sayede, özel SDK'lar olmadan tak ve çalıştır bileşenleri oluşturulabilir. Daha fazla bilgi: A2A Protokolü

Sorun giderme

Yolla İlgili Hatalar:

  • Komutlar çalıştırılırken "No such file or directory" hatası: Depo kökünde değilsiniz.
# Check where you are
pwd

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

Hizmet Hataları:

  • "Adres zaten kullanılıyor": Önceki çalıştırmalardan kalan işlemler hâlâ etkin.
# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents
  • Hizmetler başlatılmıyor: Bağlantı noktalarının kullanılıp kullanılmadığını kontrol edin:
# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent
  • AlloyDB'ye "Bağlantı reddedildi": AlloyDB örneğinizde genel IP'nin etkinleştirildiğini doğrulayın.

9. 🎁 Bonus: Cloud Run'a dağıtma

İsteğe bağlı: Her şey yerel olarak çalışır. Ancak oluşturduğunuz içeriği herkese açık bir URL ile paylaşmak isterseniz:

# From repo root
sh deploy/deploy.sh

Ne olur?

  1. .env yapılandırmanızı okur.
  2. Adınızı ister (Dağıtılan uygulamada gösterilir)
  3. 3 hizmetin tümünü tek bir Cloud Run container'ı olarak dağıtır.
  4. AlloyDB erişimi için IAM rolleri verir.
  5. Paylaşılabilir bir URL çıkışı verir.

URL'nizi açan ziyaretçiler aşağıdaki pop-up'ı görür:

10. Temizleme

Ücretlendirilmemek için otomatik temizleme komut dosyasıyla tüm kaynakları yok edin:

# From repo root
sh deploy/cleanup.sh

Bu işlem aşağıdakileri güvenli bir şekilde kaldırır:

  • AlloyDB kümesi (birincil maliyet sürücüsü)
  • Cloud Run hizmetleri (dağıtılmışsa)
  • İlişkili hizmet hesapları

Komut dosyası, herhangi bir şeyi silmeden önce onay ister.

11. Referanslar ve Ek Okuma Materyalleri

Bu codelab'deki tüm teknik iddialar, resmi Google Cloud ve Google AI belgelerinden doğrulanmıştır.

Resmi Belgeler

Gemini 3 Flash:

AlloyDB AI ve ScaNN:

Veritabanları için MCP Araç Kutusu (alternatif yaklaşım):

Fiyatlandırma bilgileri:

Doğrulanmış Performans İddiaları

Özellik

Kullan

Kaynak

ScaNN ve HNSW karşılaştırması (filtrelenmiş)

10 kat daha hızlı

Google Cloud Blogu (doğrulanmış)

ScaNN ve HNSW (standart) karşılaştırması

4 kat daha hızlı

Google Cloud Blogu (doğrulanmış)

ScaNN bellekte kaplanan yer

3-4 kat daha küçük

Google Cloud Blogu (doğrulanmış)

ScaNN dizini derleme süresi

8 kat daha hızlı

Google Cloud Blogu (doğrulanmış)

Kod yürütme zaman aşımı

Maksimum 30 saniye

Google Cloud Dokümanları (doğrulanmış)

Kod yürütme dosyası G/Ç

Desteklenmiyor

Google Cloud Dokümanları (doğrulanmış)

Sıcaklık=0 davranışı

Belirleyici çıkış

Topluluk tarafından doğrulanmış

Ek Kaynaklar

Temsilciden Temsilciye (A2A) Protokolü:

  • A2A, aracı keşfini ve iletişimi standartlaştırır
  • /.well-known/agent-card.json konumunda gösterilen aracı kartları
  • Otonom aracıların ortak çalışması için gelişmekte olan standart

ScaNN Araştırması:

  • 12 yıllık Google Research verilerine dayalıdır.
  • Milyarlarca ölçekte Google Arama ve YouTube'u destekler
  • Genel kullanıma sunulma tarihi: Ekim 2024
  • Milyonlarca ila milyarlarca vektör için uygun ilk PostgreSQL vektör dizini

12. Meydan Okuma Modu: Agentic Becerilerinizi Geliştirin

Çalışan bir otonom tedarik zinciri oluşturdunuz. Daha da ileri gitmeye hazır mısınız? Bu zorluklar, öğrendiğiniz kalıpları yeni sorunlara uygulamanızı sağlar.

1. Görev: Resme Dayalı Arama (Çok Formatlı Yerleştirmeler)

Mevcut akış: Vision Agent öğeleri sayar → metin sorgusu oluşturur → Supplier Agent metni yerleştirir → AlloyDB'de arama yapar

Görev: Metni tamamen atlayın. Kırpılmış resmi doğrudan tedarikçi temsilcisine gönderin.

İpuçları:

  1. Vision Agent'ın kod yürütme özelliği, raftaki resimden tek tek öğeleri kırpabilir.
  2. Vertex AI'ın multimodalembedding@001 modeli, görüntüleri doğrudan yerleştirebilir.
  3. inventory.py dosyasını metin yerine görüntü baytlarını kabul edecek şekilde değiştirin.
  4. A2A beceri açıklamasını "Kabul eder: image/jpeg veya text" şeklinde güncelleyin.

Neden Önemli? Görsel arama, karmaşık görünümlere (renk varyasyonları, hasar, ambalaj farklılıkları) sahip parçalar için daha doğrudur.

2. zorluk: Gözlemlenebilirlik: Şeffaflık sayesinde güven

Mevcut Durum: Sistem çalışıyor ancak "kaputun altını" göremiyorsunuz.

Zorluk: Vektör aramasının yürütüldüğünü kanıtlamak için AlloyDB'nin sorgu günlüklerini inceleyin.

Adımlar:

  • Sorgu analizleri, AlloyDB'de varsayılan olarak etkindir. Doğrulamak için şunu çalıştırın:
gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"
  • Kullanıcı arayüzü üzerinden tedarikçi araması yapma
  • Yürütülen gerçek SQL'i görüntüleyin:
gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

Beklenen Çıktı: Yürütme süresiyle birlikte tam ORDER BY part_embedding <=> $1::vector LIMIT 1 sorgusunu görürsünüz.

Bu Neden Önemli? Gözlemlenebilirlik güven oluşturur. Paydaşlar "Bu aracı nasıl karar veriyor?" diye sorduğunda onlara yalnızca çıkışı değil, sorgu planını da gösterebilirsiniz.

3. zorluk: Çoklu ajan kompozisyonu

Sorun: Kargo maliyetlerini depo konumuna ve öğe ağırlığına göre hesaplayan üçüncü bir aracı (Lojistik Aracı) ekleyin.

Mimari:

  • Vision Agent çıkışları: öğe sayısı
  • Tedarikçi temsilcisi çıkışları: tedarikçi konumu
  • Lojistik Ajanı (YENİ) girişleri: hedef, ağırlık → çıkışları: kargo maliyeti + tahmini varış zamanı

İpucu: A2A protokolü bu işlemi kolaylaştırır. calculate_shipping becerisine sahip yeni bir aracı kartı oluşturun. Kontrol Kulesi, cihazı otomatik olarak keşfeder.

Öğrendiğiniz Kalıp: Bu, Agent-Oriented Architecture'ın (Aracı Odaklı Mimari) temelini oluşturur. Bu mimari, küçük ve birleştirilebilir uzmanlardan oluşturulmuş karmaşık sistemleri ifade eder.

13. Sonuç

Üretken yapay zeka'dan ajan tabanlı yapay zeka'ya başarıyla geçiş yaptınız.

Geliştirdiğimiz özellikler:

  • Vision: "Tahmin etme" yerine Kod Yürütme (API anahtarı aracılığıyla Gemini 3 Flash) özelliğini ekledik.
  • Bellek: "Yavaş arama" yerine AlloyDB ScaNN (GCP üzerinden) kullanmaya başladık.
  • İşlem: "API entegrasyonu" ifadesini A2A Protokolü ile değiştirdik.

Karma mimarinin avantajları:

Bu codelab'de hibrit bir yaklaşım gösterilmiştir:

  • Vision Agent: Gemini API'yi (API anahtarı) kullanır. Basit ve ücretsiz katman mevcuttur. GCP faturalandırması gerekmez.
  • Tedarikçi Temsilcisi: GCP'yi (Vertex AI + AlloyDB) kullanır. Kurumsal düzeyde ve uyumluluğa hazırdır.

Bu, otonom ekonominin mimarisidir. Kod size aittir.

Sonraki Adımlar