Build an Autonomous Supply Chain with Gemini 3 Flash & AlloyDB AI

1. סקירה כללית

העידן של הצ'אטבוטים שיודעים לקרוא הולך ונגמר. אנחנו נכנסים לעידן של חזון אקטיבי.

ב-Codelab הזה נטמיע הנדסת AI דטרמיניסטית – שיטה לבניית מערכות AI שלא מנחשות. מודלים רגילים של AI לרוב 'ממציאים' תשובות (מנחשים) כשמבקשים מהם לספור פריטים בתמונה מורכבת. בשרשרת אספקה, ניחוש הוא מסוכן. אם AI מנחש שיש לכם 12 פריטים כשבפועל יש לכם 15, הוא יגרום לשגיאות יקרות.

אנחנו נבנה סוכן אוטונומי לניהול שרשרת אספקה באמצעות לולאת חשיבה, פעולה, תצפית חדשה ב-Gemini 3 Flash. הוא לא רק בודק, אלא גם חוקר.

הארכיטקטורה הדטרמיניסטית

נתחיל עם מערכת 'עיוורת' ו'אמנזית'. תצטרכו 'להעיר' את החושים שלו אחד אחרי השני באופן ידני:

17191a91a9c54146.png

  1. ‫The Eyes (סוכן הראייה): אנחנו מפעילים את Gemini 3 Flash עם Code Execution. במקום לחזות טוקנים כדי לנחש מספר, המודל כותב קוד Python ‏ (OpenCV) כדי לספור פיקסלים באופן דטרמיניסטי.
  2. הזיכרון (סוכן הספק): אנחנו מפעילים את AlloyDB AI עם ScaNN (Scalable Nearest Neighbors). כך הסוכן יכול לשלוף את הספק המדויק של חלק מסוים מתוך מיליוני אפשרויות במילי-שניות.
  3. הלחיצת יד (פרוטוקול A2A): אנחנו מאפשרים תקשורת סוכן לסוכן באמצעות קובץ agent_card.json סטנדרטי , שמאפשר לסוכן Vision להזמין מלאי באופן אוטונומי מסוכן הספק.

מה תפַתחו

  • סוכן Vision שמבצע 'מתמטיקה חזותית' בפידים של המצלמה.
  • סוכן ספקים שמבוסס על AlloyDB ScaNN לחיפוש וקטורי במהירות גבוהה.
  • ממשק קצה של Control Tower עם עדכוני WebSocket בזמן אמת להמחשת הלולאה האוטונומית.

מה תלמדו

  • איך מגדירים את AlloyDB עם הטמעות וקטורים ואינדקסים של ScaNN.
  • איך מפעילים את Agentic Vision באמצעות gemini-3-flash-preview באמצעות Gemini API.
  • איך מטמיעים חיפוש וקטורי באמצעות האופרטור <=> (מרחק קוסינוס) ב-AlloyDB.
  • איך מחברים סוכנים ל-AlloyDB באמצעות AlloyDB Python Connector.
  • איך משתמשים בפרוטוקול A2A כדי לגלות סוכנים דינמיים.

דרישות

  • דפדפן, כמו Chrome או Firefox
  • פרויקט ב-Google Cloud שהחיוב בו מופעל.
  • מפתח Gemini API (יש תוכנית בחינם ב-Google AI Studio) בשביל סוכן ה-Vision.

‫2. לפני שמתחילים

יצירת פרויקט

  1. ב-מסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים או יוצרים פרויקט ב-Google Cloud.
  2. מוודאים שהחיוב מופעל בפרויקט ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט.
  1. תשתמשו ב-Cloud Shell, סביבת שורת פקודה שפועלת ב-Google Cloud. לוחצים על 'הפעלת Cloud Shell' בחלק העליון של מסוף Google Cloud.

תמונה של לחצן ההפעלה של Cloud Shell

  1. אחרי שמתחברים ל-Cloud Shell, בודקים שכבר בוצע אימות ושהפרויקט מוגדר למזהה הפרויקט באמצעות הפקודה הבאה:
gcloud auth list

הגדרת מסד נתונים [AlloyDB]

קודם כל, צריך להקצות את מסד הנתונים – התהליך הזה נמשך כ-15 דקות, אז נתחיל איתו.

  1. כדי לפתוח את כלי ההגדרה של AlloyDB ב-Cloud Shell, לוחצים על הלחצן שלמטה:

  1. מריצים את ההגדרה:
Sh run.sh
  1. משתמשים בתצוגה המקדימה באינטרנט (סמל העין 👁️ → תצוגה מקדימה ביציאה 8080) כדי לפתוח את ממשק המשתמש של ההגדרה.
  2. מזינים את מזהה הפרויקט, בוחרים אזור (לדוגמה, us-central1) ויוצרים סיסמה למסד הנתונים.

⚠️ חשוב לשמור את הסיסמה הזו – תצטרכו אותה כשתתבקשו להזין אותה בסקריפט ההגדרה.

  1. לוחצים על Start Deployment (התחלת הפריסה) ומחכים כ-15 דקות עד שהאשכול יוקצה.

קבל את הקוד

בזמן שההקצאה של AlloyDB מתבצעת (או אחרי שהיא מסתיימת), פותחים את מאגר ה-codelab ב-Cloud Shell:

⚠️ חשוב: כשלוחצים על הלחצן, מוצג דו-שיח אבטחה. מסמנים את התיבה 'Trust repo' (הוספת מאגר מהימן) ולוחצים על 'Confirm' (אישור).

אפשרות אחרת היא לשכפל ידנית:

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

cd visual-commerce-gemini-3-alloydb

הגדרת הפרויקט

בטרמינל של Cloud Shell, מוודאים שהפרויקט מוגדר:

gcloud config set project <YOUR_PROJECT_ID>

הפעלת כתובת IP ציבורית ב-AlloyDB

אחרי שהקצאת המשאבים של AlloyDB מסתיימת, מפעילים כתובת IP ציבורית כדי ש-Python Connector יוכל להתחבר מ-Cloud Shell:

  1. עוברים אל AlloyDB Console.
  2. לוחצים על האשכול → לוחצים על המופע הראשי
  3. לוחצים על 'עריכה'.
  4. גוללים אל Public IP Connectivity (קישוריות של כתובת IP ציבורית) ומסמנים את התיבה Enable Public IP (הפעלת כתובת IP ציבורית).
  5. לוחצים על Update Instance (עדכון המכונה).

💡 הערה: מחבר Python של AlloyDB מטפל באימות ובצפנה – אין צורך להוסיף רשתות חיצוניות מורשות.

מתן הרשאות ל-Vertex AI

לחשבון השירות של AlloyDB נדרשת גישה ל-Vertex AI כדי ליצור הטמעות. מריצים את הפקודה הבאה באותו חלון של Cloud Shell:

PROJECT_ID=$(gcloud config get-value project)


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

הרצת סקריפט ההגדרה

עכשיו מריצים את סקריפט ההגדרה – הוא יזהה אוטומטית את מופע AlloyDB:

sh setup.sh

מה הסקריפט עושה:

  • אימות של ה-CLI של gcloud, אימות, פרויקט ו-Python 3
  • בודק ומפעיל את ממשקי ה-API הנדרשים (AlloyDB, ‏ Vertex AI, ‏ Compute, ‏ Service Networking)
  • הנחיות למפתח Gemini API
  • מזהה אוטומטית את מופע AlloyDB ומחלץ את האזור, האשכול ושם המופע
  • מבקש את הסיסמה למסד הנתונים
  • יצירת קובץ התצורה ‎ .env
  • התקנה של יחסי תלות של Python

3. הגדרת מסד נתונים

בליבת האפליקציה שלנו נמצא AlloyDB ל-PostgreSQL. נשתמש ביכולות הווקטוריות המתקדמות שלו ובאינדקס ScaNN כדי לאפשר חיפוש סמנטי כמעט בזמן אמת, וכך הסוכנים שלנו יוכלו למצוא התאמות למלאי מתוך אלפי רשומות במילי-שניות.

בקטע הזה נסביר איך להקצות את הסכמה, להזין נתונים ראשוניים וליצור הטמעות – והכול מ-AlloyDB Studio.

התחברות ל-AlloyDB Studio

  1. עוברים למופע AlloyDB ב-AlloyDB Console.
  2. בתפריט הניווט הימני, לוחצים על AlloyDB Studio.
  3. אימות באמצעות:
  4. שם משתמש: postgres
  5. מסד נתונים: postgres
  6. ‫Password: הסיסמה שהגדרתם במהלך יצירת האשכול

הפעלת תוספים

‫AlloyDB מספק תוספים מובנים לווקטורים ול-AI. מריצים את ה-SQL הבא ב-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: הפעלה של הפונקציה ai.embedding()‎ לקריאה ל-Vertex AI ישירות מ-SQL.
  • וקטור: אחסון והצגת שאילתות של הטמעות וקטוריות ב-768 ממדים.
  • ‫alloydb_scann: מפעיל את אינדקס ScaNN של Google לחיפוש וקטורי מהיר במיוחד.

יצירת טבלת המלאי

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 מאוחסנים וקטורים תלת-ממדיים מ-text-embedding-005. זה מה שמפעיל את החיפוש הסמנטי.

הוספת נתונים לדוגמה

הוספת 20 פריטים של מלאי במחסן:

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

מתן הרשאות להטמעה

GRANT EXECUTE ON FUNCTION embedding TO postgres;

יצירת הטמעות וקטוריות

הפונקציה המובנית ai.embedding()‎ של AlloyDB משמשת כדי לקרוא למודל text-embedding-005 של Vertex AI ישירות מ-SQL – אין צורך בקוד Python:

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

הפעולה הזו יוצרת וקטורים של 768 ממדים שמתעדים את המשמעות הסמנטית של השם והתיאור של כל חלק. האינדקס של ScaNN ישתמש בהם לחיפוש דמיון מהיר במיוחד. [מילוי הסקר יימשך כ-3-5 דקות]

יצירת אינדקס 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');

אימות שהכול פעל

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

אמורות להופיע 20 שורות, ובכולן הערך של has_embedding הוא true.

4. הסבר על הארכיטקטורה

לפני שמבצעים שינויים בקוד, כדאי להבין איך המערכת בנויה. הארכיטקטורה פועלת לפי דפוס של 'התעוררות' הדרגתית:

הערמה של הסוכן

‫Vision Agent (agents/vision-agent/)

  • ‫agent.py – לוגיקת הליבה של Gemini 3 Flash. שולח תמונות למודל עם הפעלת Code Execution כדי לכתוב Python ‏ (OpenCV) לספירת פריטים באופן דטרמיניסטי.
  • agent_executor.py – מגשר בין בקשות של פרוטוקול A2A לבין הלוגיקה של הסוכן.
  • main.py – שרת Uvicorn A2A שמציג את ‎ /.well-known/agent-card.json ומטפל בבקשות.

נציג של ספק (agents/supplier-agent/)

  • inventory.py – מתחבר ל-AlloyDB באמצעות AlloyDB Python Connector (אין צורך ב-Auth Proxy). כולל את הפונקציה find_supplier()‎ שמבצעת חיפוש וקטורי ב-ScaNN.
  • agent_executor.py — מגשר בין פרוטוקול A2A לבין לוגיקת חיפוש המלאי.
  • main.py — Uvicorn A2A server with agent card and health endpoint.

‫Control Tower (frontend/)

  • app.py – שרת FastAPI + WebSocket שמגלה סוכנים באמצעות A2A, מתזמן את פייפליין הנתונים של ראייה ← חיפוש ← הזמנה ומזרים עדכונים בזמן אמת לדפדפן.

תהליך העבודה של A2A

  • ‫Control Tower קורא את הקובץ ‎ /.well-known/agent-card.json מכל סוכן
  • מגלה יכולות (מיומנויות, נקודות קצה) – ללא כתובות URL שמוגדרות בהארדקוד
  • התמונה נשלחת לסוכן Vision → מתקבל תיאור + מספר הפריטים
  • שולח תיאור כשאילתת הטמעה לסוכן הספק ← מקבל התאמה חלקית
  • ביצוע הזמנה באופן אוטונומי

החיבור ל-AlloyDB

הספק משתמש בAlloyDB Python Connector במקום ב-Auth Proxy הרגיל:

from google.cloud.alloydbconnector import Connector

connector = Connector()
conn = connector.connect(
    inst_uri,       # Full instance URI
    "pg8000",       # Driver
    user="postgres",
    password=DB_PASS,
    ip_type="PUBLIC",  # Cloud Shell uses Public IP
)

הוא מטפל באופן אוטומטי באימות IAM, ב-SSL/TLS ובניתוב החיבור. כשפורסים ל-Cloud Run מאוחר יותר, פשוט משנים את ip_type ל-PRIVATE כדי לקבל גישה ל-VPC.

5. שלב 1: הזיכרון (סוכן הספק)

סוכן הספק זוכר מיליוני חלקים באמצעות AlloyDB ScaNN. בשלב הזה, הוא מגיע עם שאילתת placeholder – שאילתה ששוכחת את מה שחיפשתם ומחזירה את השורה הראשונה שהיא מוצאת.

הביקורת: אמנזיה

אם תשאלו את סוכן הספקים שאילתה עכשיו, הוא יחזיר תוצאה אקראית. אין לו מושג של דמיון. יחד נפתור את זה.

הפעלת הסוכן לספקים

שרת ה-A2A‏ (main.py) מעביר את הפעולה אל agent_executor.py, שמגשר בין הפרוטוקול לבין הלוגיקה העסקית ב-inventory.py.

pkill -f uvicorn #Kill all uvicorn processes

שלב 1: עוברים לספריית הסוכנים

cd agents/supplier-agent

שלב 2: התקנת יחסי תלות

pip install -r requirements.txt

שלב 3: הפעלת שרת הסוכן

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

הפקודה > /dev/null 2>&1 & מריצה את השרת ברקע ומונעת את הפלט כדי שלא יפריע ל-Terminal.

שלב 4: מוודאים שהסוכן פועל (מחכים 2-3 שניות אחרי ההפעלה)

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

הפלט הצפוי: קובץ JSON עם הגדרות הסוכן (הפעולה אמורה להסתיים ללא שגיאות)

הפתרון: הטמעה של האופרטור <=>

פותחים את הקובץ agents/supplier-agent/inventory.py ומחפשים את הפונקציה find_supplier() בשורה 60-70. יוצג לכם ה-placeholder:

# TODO: Replace this placeholder query with ScaNN vector search

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

מחליפים את שתי השורות האלה בשורות הבאות:

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

מה זה אומר:

  • ‫<=> הוא אופרטור המרחק הקוסינוסי ב-PostgreSQL
  • ‫ORDER BY part_embedding <=> %s::vector מוצא את ההתאמה הקרובה ביותר (המרחק הכי קטן = המשמעות הסמנטית הכי קרובה)
  • ‫%s::vector מבצע המרה של מערך ההטמעה לסוג הווקטור של PostgreSQL
  • האינדקס של ScaNN מאיץ את השאילתה הזו באופן אוטומטי.

שלב 4: שומרים את הקובץ (Ctrl+S או Cmd+S)

הנציג ישתמש עכשיו בחיפוש סמנטי במקום להחזיר תוצאות אקראיות.

אימות

בודקים את הגילוי של A2A ואת המלאי:

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

צפוי: הקובץ agent-card.json מחזיר את כרטיס הסוכן. קטע הקוד ב-Python מחזיר חלק וספק מהנתונים הראשוניים.

6. שלב 2: העיניים (סוכן הראייה)

אפשר לגשת למסד הנתונים, אבל בואו נשתמש ב-Gemini 3 Flash כדי להעיר את העיניים. סוכן ה-Vision מבצע 'מתמטיקה ויזואלית' באמצעות הפעלת קוד.

הביקורת: ההזיה

אם שואלים מודל רגיל רב-אופני: "כמה קופסאות יש בתמונה המבולגנת הזו?", המודל מעבד את התמונה כצילום מסך סטטי ומנחש.

  • המודל אומר: "אני רואה בערך 12 תיבות".
  • במציאות: יש 15 תיבות.
  • תוצאה: כשל בשרשרת האספקה.

הפתרון: הפעלת לולאת החשיבה, הפעולה והתצפית

אנחנו מפעילים את Code Execution (הרצת קוד) ואת ThinkingConfig (הגדרות חשיבה) כדי שהמודל יכתוב קוד Python ‏(OpenCV) לספירה דטרמיניסטית.

  1. פותחים את הקובץ agents/vision-agent/agent.py .
  2. מחפשים את הקטע GenerateContentConfig (בסביבות שורות 68-78).
  3. מסירים את ההערה משני הבלוקים: thinking_config=types.ThinkingConfig(...) ו-tools=[types.Tool(code_execution=...)].
  4. הלקוח כבר מוגדר להשתמש ב-GEMINI_API_KEY מהסביבה.

קובץ: 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)]
)

למה הערך thinking_level הוא MINIMAL?

למשימה הזו (ספירת פריטים באמצעות הפעלת קוד), התשובה 'מינימלית' מספקת נימוק מספיק לתכנון הסקריפט ולאימות הספירה. השימוש בערך 'גבוה' יוסיף חביון של פי 2 עד פי 3 בלי לשפר את הדיוק במשימות דטרמיניסטיות. אופטימיזציה של העלות והביצועים – התאמת עומק הנימוקים למורכבות המשימה.

אופטימיזציה של עלות וביצועים היא מיומנות חשובה בהנדסת AI לייצור: התאמת עומק הנימוקים למורכבות המשימה.

הפעלת הסוכן החכם של Vision

‫🔄 בדיקת הנתיב: אם אתם עדיין בתיקייה agents/supplier-agent/, קודם צריך לחזור לתיקיית הבסיס של המאגר באמצעות הפקודה cd ../..

שלב 1: עוברים לספרייה של סוכן הראייה

cd agents/vision-agent

שלב 2: התקנת יחסי תלות

pip install -r requirements.txt

שלב 3: מפעילים את השרת של סוכן הראייה

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

הפקודה > /dev/null 2>&1 & מריצה את השרת ברקע ומונעת את הפלט כדי שלא יפריע ל-Terminal.

אימות

בדיקת גילוי של A2A:

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

התוצאה הצפויה: קובץ JSON עם שם הסוכן והכישורים שלו. בשלב 8 תבדקו את הספירה בפועל באמצעות ראייה ממוחשבת בממשק המשתמש של Control Tower.

dc9bc53007336472.png

7. שלב 3: לחיצת היד (כרטיס סוכן A2A)

הסוכן רואה את הבעיה (Vision) ויודע מי הספק (Memory). פרוטוקול A2A מאפשר גילוי דינמי – הקצה הקדמי לומד איך לתקשר עם כל סוכן על ידי קריאת הכרטיס שלו.

‫A2A לעומת ממשקי REST API רגילים

Aspect

REST מסורתי

פרוטוקול A2A

Endpoint Discovery

כתובות URL שמוגדרות בהגדרות

דינמי דרך ‎ /.well-known/agent-card.json

תיאור היכולת

מאמרי עזרה של ה-API (למשתמשים)

מיומנויות (קריאות למכונה)

Integration

קוד ידני לכל שירות

התאמה סמנטית: "אני צריך לחפש מלאי" → גילוי מיומנות

נוסף סוכן חדש

עדכון ההגדרות של כל הלקוחות

אין צורך בהגדרה – המכשיר מתגלה אוטומטית

יתרון בעולם האמיתי: במיקרו-שירות מסורתי, אם מוסיפים סוכן לוגיסטיקה שלישי, צריך לעדכן את הקוד של מגדל הבקרה עם כתובת ה-URL וחוזה ה-API שלו. בעזרת A2A, ‏ Control Tower מגלה את האפליקציה באופן אוטומטי ומבין את היכולות שלה באמצעות תיאורי מיומנויות בשפה טבעית.

זו הסיבה לכך ש-A2A מאפשרת הרכבת סוכנים בשיטת Plug-and-Play – התבנית האדריכלית למערכות אוטונומיות.

יצירת כרטיס הסוכן

‫🔄 בדיקת הנתיב: אם אתם עדיין ב-agents/vision-agent/, קודם צריך לחזור אל שורש המאגר באמצעות cd ../..

כרטיס הנציג כבר נכלל בנתיב agents/supplier-agent/agent_card.json. פותחים את הקובץ ובודקים:

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

אתם יכולים להתאים אישית את השם, התיאור או הדוגמאות כך שיתאימו לתרחיש השימוש שלכם.

מפעילים מחדש את הספק כדי לטעון את הכרטיס:

שלב 1: מפסיקים את הסוכן הפועל

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

שלב 2: ניווט לספריית הסוכנים

cd agents/supplier-agent

שלב 3: מפעילים מחדש את הסוכן

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

הפקודה ‎> /dev/null 2>&1 &‎ מריצה את השרת ברקע ומונעת את הפלט כדי שלא יפריע ל-Terminal.

שלב 4: מאמתים את כרטיס הסוכן החדש (מחכים 2-3 שניות אחרי ההתחלה)

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

הפלט הצפוי: קובץ JSON עם השם, התיאור והכישורים שלכם.

dd352ca2e7e6109a.png

8. שלב 4: Control Tower

הפעלת חזית העורף של Control Tower באמצעות FastAPI + WebSockets. הוא מגלה סוכנים באמצעות A2A ומנהל את הלולאה המלאה עם עדכונים בזמן אמת.

הפעלת כל השירותים

הדרך הכי קלה להפעיל את כל השירותים:

מוודאים שאתם נמצאים בתיקיית השורש של המאגר

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

לאחר מכן,

sh run.sh

הפקודה היחידה הזו מפעילה:

  • סוכן Vision ביציאה 8081
  • סוכן הספק ביציאה 8082
  • ‫Control Tower ביציאה 8080

מחכים כ-10 שניות עד שכל השירותים יאותחלו.

בדיקת המערכת

כדי לגשת ל-Control Tower:

  1. בסרגל הכלים של Cloud Shell, לוחצים על הלחצן Web Preview (תצוגה מקדימה של אתר) (סמל העין 👁️).
  2. בוחרים באפשרות תצוגה מקדימה ביציאה 8080.
  3. לוח הבקרה של Control Tower ייפתח בכרטיסייה חדשה

הפעלת ההדגמה:

  1. בפינה הימנית העליונה: מצב החיבור (נקודה ירוקה עם הכיתוב 'בשידור חי'), מתג למצב הדגמה או אוטומטי ואמצעי בקרה של האודיו
  2. המרכז: אזור העריכה הראשי של תהליך העבודה עם העלאת תמונות והמחשה ויזואלית של הניתוח
  3. חלוניות צדדיות (מופיעות במהלך הניתוח): ציר זמן של תהליך העבודה (מימין), מעקב אחר ההתקדמות ותצוגת קוד (משמאל)

אפשרות 1: התחלה מהירה (מומלץ)

  1. בדף הבית יופיע הקטע תחילת עבודה מהירה עם תמונות לדוגמה
  2. לוחצים על תמונה לדוגמה כדי להתחיל את הניתוח באופן אוטומטי.
  3. צפייה בתהליך העבודה האוטונומי (כ-30 עד 45 שניות)

אפשרות 2: העלאה של תמונה משלכם

  1. כדי להעלות תמונה של מחסן או מדף (PNG,‏ JPG, עד 10MB), אפשר לגרור ולשחרר או ללחוץ כדי לעיין
  2. לוחצים על Initiate Autonomous Workflow (הפעלת תהליך עבודה אוטונומי).
  3. התבוננות בצינור עיבוד הנתונים בן 4 השלבים

מה קורה:

  1. גילוי סוכנים: מודלים של פרוטוקול A2A מציגים כרטיסים של סוכן Vision וסוכן ספק עם הכישורים ונקודות הקצה שלהם
  2. ניתוח תמונות: Gemini 3 Flash יוצר ומריץ קוד Python ‏ (OpenCV) כדי לספור פריטים. סרגל ההתקדמות מציג שלבי משנה. תיבות תוחמות מוצגות על פריטים שזוהו. התג של התוצאה מציג את הכיתוב '✓ קוד מאומת' או '~ משוער'
  3. התאמה בין ספקים: אנימציה של חיפוש וקטורים ב-AlloyDB ScaNN. שאילתת חיפוש מוצגת (למשל, 'קופסאות מתכת לתעשייה'). בכרטיס התוצאה מוצגים החלק התואם, הספק וציון רמת הביטחון
  4. ההזמנה בוצעה: כרטיס קבלה עם מזהה הזמנה, כמות ופרטים

טיפ: כדי להשהות את ההצגה בכל שלב, מומלץ להשאיר את מצב ההדגמה מופעל (בפינה השמאלית העליונה). במצב AUTO, תהליך העבודה פועל ברציפות.

1a031c4fd407a183.png

What Just Happened

מגדל הפיקוח השתמש בפרוטוקול A2A כדי לגלות את שני הסוכנים באמצעות ‎ /.well-known/agent-card.json, תזמן את ניתוח הראייה (Gemini 3 Flash עם הרצת קוד), ביצע חיפוש וקטורי (AlloyDB ScaNN) וביצע הזמנה אוטונומית – והכול עם עדכוני WebSocket בזמן אמת. כל סוכן חושף את היכולות שלו באמצעות תקן A2A, מה שמאפשר הרכבה של פלאגין ללא ערכות SDK בהתאמה אישית. מידע נוסף: פרוטוקול A2A

פתרון בעיות

שגיאות שקשורות לנתיב:

  • הודעת השגיאה No such file or directory (אין קובץ או ספרייה בשם הזה) מופיעה כשמריצים פקודות: אתם לא נמצאים בתיקיית הבסיס של המאגר.
# Check where you are
pwd

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

שגיאות בשירות:

  • ‫"Address already in use" (הכתובת כבר נמצאת בשימוש): תהליכים מהרצות קודמות עדיין פעילים.
# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents
  • השירותים לא מופעלים: בודקים אם הפורטים תפוסים:
# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent
  • הודעת השגיאה 'החיבור נדחה' ב-AlloyDB: צריך לוודא שכתובת ה-IP הציבורית מופעלת במופע AlloyDB

9. 🎁 בונוס: פריסה ב-Cloud Run

אופציונלי – הכל פועל באופן מקומי! אבל אם רוצים לשתף את היצירה באמצעות כתובת URL ציבורית:

# From repo root
sh deploy/deploy.sh

מה קורה:

  1. קריאה של ההגדרה האישית שלכם בקובץ ‎ .env
  2. מבקש את השם שלכם (שמוצג באפליקציה שנפרסה)
  3. פריסת כל 3 השירותים כקונטיינר יחיד של Cloud Run
  4. מעניק תפקידי IAM לגישה ל-AlloyDB
  5. הפונקציה מחזירה כתובת URL שניתן לשתף

מבקרים שיפתחו את כתובת ה-URL יראו חלון קופץ:

10. הסרת המשאבים

כדי להימנע מחיובים, צריך להשמיד את כל המשאבים באמצעות סקריפט הניקוי האוטומטי:

# From repo root
sh deploy/cleanup.sh

הפעולה הזו מסירה בבטחה את:

  • אשכול AlloyDB (הגורם העיקרי לעלויות)
  • שירותי Cloud Run (אם הם נפרסו)
  • חשבונות שירות משויכים

הסקריפט יבקש אישור לפני מחיקת משהו.

11. חומרי עזר וקריאה נוספת

כל הטענות הטכניות ב-codelab הזה אומתו ממסמכי עזרה רשמיים של Google Cloud ו-Google AI.

מאמרי עזרה רשמיים

‫Gemini 3 Flash:

‫AlloyDB AI ו-ScaNN:

‫MCP Toolbox for Databases (גישה חלופית):

פרטי תמחור:

טענות מאומתות לגבי ביצועים

תכונה

תביעה

מקור

‫ScaNN לעומת HNSW (מסונן)

מהיר פי 10

הבלוג של Google Cloud (מאומת)

‫ScaNN לעומת HNSW (רגיל)

מהיר פי 4

הבלוג של Google Cloud (מאומת)

הזיכרון שבשימוש ב-ScaNN

קטן פי 3-4

הבלוג של Google Cloud (מאומת)

משך זמן של תהליך build של אינדקס ScaNN

מהיר פי 8

הבלוג של Google Cloud (מאומת)

הזמן שהוקצב להרצת הקוד פג

‫30 שניות לכל היותר

מסמכים של Google Cloud (מאומתים)

קלט/פלט של קובץ בהרצת קוד

לא נתמך

מסמכים של Google Cloud (מאומתים)

התנהגות כש-Temperature=0

פלט דטרמיניסטי

אומת על ידי הקהילה

מקורות מידע נוספים

פרוטוקול Agent-to-Agent (A2A):

  • תקן A2A מאפשר לגלות סוכנים ולתקשר איתם בצורה אחידה
  • כרטיסי נציגים שמוצגים ב-/.well-known/agent-card.json
  • תקן חדש לשיתוף פעולה בין סוכנים אוטונומיים

ScaNN Research:

  • על סמך 12 שנים של צוות המחקר של Google
  • מפעיל את חיפוש Google ואת YouTube בהיקף של מיליארדים
  • הושק בזמינות לכלל המשתמשים (GA): אוקטובר 2024
  • אינדקס וקטורי ראשון של PostgreSQL שמתאים למיליון עד מיליארד וקטורים

12. מצב אתגר: התקדמות לשלב הבא במיומנויות סוכנים

יצרת שרשרת אספקה אוטונומית שפועלת. מוכנים להתקדם? האתגרים האלה מאפשרים לכם ליישם את הדפוסים שלמדתם על בעיות חדשות.

אתגר 1: חיפוש מבוסס-תמונה (הטמעות מולטי-מודאליות)

התהליך הנוכחי: סוכן Vision סופר פריטים ← יוצר שאילתת טקסט ← סוכן הספק מטמיע טקסט ← מחפש ב-AlloyDB

אתגר: לעקוף את הטקסט לחלוטין – לשלוח את התמונה החתוכה ישירות לסוכן הספק.

הערות:

  1. הסוכן Vision יכול לחתוך פריטים בודדים מתמונת המדף
  2. מודל multimodalembedding@001 של Vertex AI יכול להטמיע תמונות ישירות
  3. שינוי הקובץ inventory.py כך שיקבל בייטים של תמונה במקום טקסט
  4. עדכון התיאור של מיומנות A2A כדי לציין 'הקבלה: image/jpeg או text'

למה זה חשוב: חיפוש חזותי מדויק יותר כשמדובר בחלקים עם מראה מורכב (וריאציות של צבעים, נזק, הבדלים באריזה).

אתגר 2: יכולת צפייה – אמון באמצעות שקיפות

מצב נוכחי: המערכת פועלת, אבל אי אפשר לראות את מה שקורה מאחורי הקלעים

אתגר: בודקים את יומני השאילתות של AlloyDB כדי לוודא שהחיפוש הווקטורי מתבצע.

השלבים:

  • התובנות לגבי שאילתות מופעלות כברירת מחדל ב-AlloyDB. כדי לאמת, מריצים את הפקודה:
gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"
  • הפעלת חיפוש ספקים דרך ממשק המשתמש
  • צפייה ב-SQL בפועל שהופעל:
gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

פלט צפוי: תוצג השאילתה המדויקת ORDER BY part_embedding <=> $1::vector LIMIT 1 עם זמן הביצוע.

למה זה חשוב: יכולת התבוננות יוצרת אמון. כשבעלי עניין שואלים "איך הסוכן הזה מקבל החלטות?", אתם יכולים להראות להם את תוכנית השאילתה, ולא רק את הפלט.

אתגר 3: שילוב של כמה סוכנים

אתגר: להוסיף סוכן שלישי (סוכן לוגיסטיקה) שמחשב את עלויות המשלוח על סמך מיקום המחסן ומשקל הפריט.

ארכיטקטורה:

  • הפלט של סוכן הראייה: מספר הפריטים
  • התפוקות של סוכן הספק: מיקום הספק
  • סוכן לוגיסטיקה (חדש) – קלט: יעד, משקל ← פלט: עלות משלוח + זמן הגעה משוער

הערה: פרוטוקול A2A מאפשר לעשות את זה בקלות – יוצרים כרטיס סוכן חדש עם מיומנות calculate_shipping. ה-Control Tower יגלה אותו באופן אוטומטי.

הדפוס שאתם לומדים: זהו הבסיס של ארכיטקטורה מבוססת-סוכנים – מערכות מורכבות שמורכבות ממומחים קטנים וניתנים להרכבה.

13. סיכום

המעבר מ-AI גנרטיבי ל-AI מבוסס-סוכן בוצע בהצלחה.

מה בנינו:

  • Vision: החלפנו את הניחוש בהפעלת קוד (Gemini 3 Flash באמצעות מפתח API).
  • זיכרון: החלפנו את 'חיפוש איטי' ב-AlloyDB ScaNN (דרך GCP).
  • פעולה: החלפנו את האפשרות 'שילוב API' בפרוטוקול A2A.

היתרונות של ארכיטקטורה היברידית:

בשיעור הזה הודגמה גישה היברידית:

  • ‫Vision Agent: משתמש ב-Gemini API (מפתח API) – יש רמה פשוטה וחינמית, לא נדרש חיוב ב-GCP
  • סוכן ספקים: משתמש ב-GCP‏ (Vertex AI + AlloyDB) – מוכן לשימוש ברמת הארגון ועומד בדרישות התאימות

זו הארכיטקטורה של הכלכלה האוטונומית. הקוד הוא שלכם.

השלבים הבאים