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 עם הרצת קוד. במקום לחזות טוקנים כדי לנחש מספר, המודל כותב קוד Python ‏ (OpenCV) כדי לספור פיקסלים באופן דטרמיניסטי.
  2. הזיכרון (סוכן הספק): אנחנו מפעילים את AlloyDB AI עם ScaNN (Scalable Nearest Neighbors). כך הסוכן יכול לשלוף את הספק המדויק של חלק מסוים מתוך מיליוני אפשרויות במילי-שניות.
  3. הלחיצת יד (פרוטוקול A2A): אנחנו מאפשרים תקשורת סוכן לסוכן באמצעות קובץ agent_card.json סטנדרטי , שמאפשר לסוכן Vision להזמין מלאי באופן אוטונומי מסוכן הספק.

מה תפַתחו

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

מה תלמדו

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

דרישות

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

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

יצירת פרויקט

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

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

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

זהו!

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

  • פתיחה אוטומטית של Cloud Shell
  • שכפול המאגר
  • מדריך אינטראקטיבי שיעזור לכם להגדיר את הכל

3. הגדרה בלחיצה אחת ב-Cloud Shell

פישטנו את ההגדרה והפכנו אותה להדרכה מודרכת ב-Cloud Shell. הכול אוטומטי: הקצאת תשתית, הגדרת AlloyDB, הגדרת שרת Proxy לאימות וזריעת נתונים במסד הנתונים.

הפעלת מדריך Cloud Shell

⚠️ חשוב – לפני שלוחצים: כשלוחצים על הלחצן שלמטה, מוצג דו-שיח אבטחה עם השאלה "פתיחה ב-Cloud Shell". ההודעה הזו מופיעה לפני שיבוט המאגר.

פעולות שצריך לבצע:

  1. ‫✅ מסמנים את התיבה: Trust repo (מאגר מהימן)
  2. ‫✅ לוחצים על אישור.

אם לא תעשו את זה, המאגר לא ישוכפל.

מוכנים? כדי לפתוח את הפרויקט עם מדריך מפורט:

מה השלב הבא:

  1. ‫Cloud Shell נפתח עם שיבוט מראש של המאגר
  2. בצד שמאל תופיע חלונית הדרכה עם הוראות מפורטות
  3. אנחנו נדריך אתכם בתהליך הבא:
  • קבלת מפתח Gemini API (יש אפשרות לשימוש בחינם)
  • הגדרת פרויקט GCP בטרמינל
  • הפעלת ההגדרה (בדיקת ממשקי API, הפעלה אם צריך, הקצאת AlloyDB: כ-15 דקות)
  • ביצוע 2 שינויים בקוד המפתח (הפעלת ראייה + זיכרון)
  • יצירת כרטיס הסוכן (פרוטוקול A2A)
  • הפעלת כל השירותים

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

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

אם אתם מעדיפים לשלוט בהגדרות באופן ידני:

  1. פותחים את Cloud Shell ומוודאים שהפרויקט מוגדר
gcloud config get-value project
  1. במידת הצורך, מגדירים את הפרויקט.
gcloud config set project YOUR_PROJECT_ID
  1. שכפול המאגר
git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git
cd visual-commerce-gemini-3-alloydb
  1. הרצת ההגדרה
sh setup.sh

פועלים לפי ההוראות במסך מתוך סקריפט ההגדרה.

מה השלב הבא: במדריך מוסבר מהם השלבים הבאים. אחרי שמסיימים, ממשיכים אל קטע 4 כדי להבין מה קרה מאחורי הקלעים.

4. מאחורי הקלעים: שרת proxy לאימות ואיכלוס מסד נתונים

הבעיה: AlloyDB נמצא בתוך VPC פרטי. ‫Cloud Shell נמצא מחוץ לזה. אי אפשר להתחבר ישירות.

הפתרון: AlloyDB Auth Proxy יוצר מנהרה מאובטחת עם אימות IAM מ-127.0.0.1:5432 ב-Cloud Shell למופע AlloyDB. אם במכונה שלכם מופעלת כתובת IP ציבורית, ה-proxy משתמש בה. אחרת, הוא מתחבר דרך כתובת ה-IP הפרטית של ה-VPC.

מה קרה במהלך ההגדרה של setup.sh

  1. המכונה שלכם ב-AlloyDB זוהתה אוטומטית (אשכול, אזור, פרויקט)
  2. נוצר הקובץ .env עם כל פרטי הכניסה (GEMINI_API_KEY, ‏ DB_PASS, פרטים של AlloyDB)
  3. הורדה והפעלה של שרת ה-Proxy לאימות (עם ‎–public-ip אם רלוונטי)
  4. הוספנו למסד הנתונים 8 חלקים לדוגמה של מלאי + אינדקס ScaNN

קובץ ‎ .env מוכן. כל ההרצות העתידיות יטענו את פרטי הכניסה באופן אוטומטי.

אימות הפעולה

מוודאים שאתם עדיין בתיקיית הבסיס של המאגר

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

בדיקה אם שרת ה-Proxy לאימות פועל

ps aux | grep alloydb-auth-proxy

מה נוצר

  • טבלת מלאי עם 8 חלקים והטמעות ב-768 ממדים
  • אינדקס ScaNN ‏ (idx_inventory_scann) לחיפוש מהיר של וקטורים

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

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

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

אם תריצו עכשיו שאילתה על סוכן הספק (עם ה-SQL של ה-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 עם הגדרות הנציג (הפלט צריך להיות ללא שגיאות)

Real Semantic Embeddings

במהלך ההגדרה, מסד הנתונים אוכלס בהטמעות סמנטיות אמיתיות שנוצרו באמצעות מודל text-embedding-005 של Google Gen AI SDK. כך אפשר לוודא שההתאמה בין הווקטורים תהיה מדויקת ולא אקראית. תהליך ה-seed לוקח בערך 10 שניות ל-13 פריטים לדוגמה, באמצעות יצירת הטמעה מקבילה כדי ליצור וקטורים משמעותיים של 768 ממדים שמבטאים את המשמעות הסמנטית של כל חלק.

‫AlloyDB Detour: למה ScaNN?

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

הנציג נשלח עם שאילתת placeholder. צריך להפעיל את חיפוש הווקטורים של ScaNN.

שלב 1: פותחים את קובץ המלאי

cd agents/supplier-agent

שלב 2: מאתרים את הערך TODO בקובץ inventory.py

מחפשים את הפונקציה find_supplier() בשורות 47-60. הפרטים שמוצגים הם:

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

שלב 3: מחליפים את ה-SQL של ה-placeholder בחיפוש וקטורי של ScaNN

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

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

ומחליפים אותן ב:

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

מה זה אומר:

  • ‫<=> הוא אופרטור המרחק הקוסינוסי ב-PostgreSQL
  • ‫ORDER BY part_embedding <=> %s::vector מוצא את ההתאמה הקרובה ביותר (המרחק הכי קטן = המשמעות הסמנטית הכי קרובה)
  • ‫‎%s::vector ממיר את מערך ההטמעה לסוג הווקטור של PostgreSQL
  • ‫LIMIT 1 מחזירה רק את ההתאמה הכי קרובה
  • האינדקס של 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 מבצע 'מתמטיקה ויזואלית' באמצעות הפעלת קוד. שרת ה-A2A‏ (main.py) מעביר את הפעולה אל agent_executor.py, שקורא ל-agent.py לצורך ניתוח Gemini.

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

אם שואלים מודל רגיל מרובה-מוֹדָלִים "כמה תיבות יש בתמונה המבולגנת הזו?", המודל מעבד את התמונה כתמונה סטטית ומנחש.

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

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

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

  1. פותחים את הקובץ agents/vision-agent/agent.py .
  2. מחפשים את הקטע GenerateContentConfig.
  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="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)]
)

למה thinking_level="LOW"?

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

  • תכנון המבנה של סקריפט Python
  • החלטה באיזו גישה לעיבוד תמונות להשתמש
  • מוודאים שהספירה תואמת למספר תיבות התוחמות

שימוש בערך 'גבוה' יוסיף פי 2 עד פי 3 זמן אחזור ועלות, בלי לשפר את הדיוק במשימות דטרמיניסטיות. מומלץ להשתמש בערך 'גבוהה' להסקת מסקנות מורכבת ורב-שלבית (למשל, "תנתח את השיבוש הזה בשרשרת האספקה ותמליץ על 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 מאפשר גילוי דינמי – הקצה הקדמי לומד איך לתקשר עם כל סוכן על ידי קריאת הכרטיס שלו.

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

Aspect

REST מסורתי

פרוטוקול A2A

Endpoint Discovery

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

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

תיאור היכולת

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

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

Integration

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

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

נוסף סוכן חדש

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

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

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

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

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

צריך להגדיר מה סוכן הספק יכול לעשות.

  1. מעתיקים את הקובץ agents/supplier-agent/agent_card_skeleton.json אל agents/supplier-agent/agent_card.json.
  2. עורכים את הקובץ כדי להחליף את הפלייס-הולדרים:

לפני (skeleton):

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

אחרי (העריכות שלכם):

{
  "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. מפעילים מחדש את הסוכן של הספק כדי שהכרטיס החדש ייטען:

שלב 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

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

  • שרת proxy לאימות ב-AlloyDB (אם הוא לא פועל)
  • סוכן 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 מציגים כרטיסים של סוכן הראייה וסוכן הספק עם הכישורים ונקודות הקצה שלהם
  2. ניתוח תמונות: Gemini 3 Flash יוצר ומריץ קוד Python ‏ (OpenCV) כדי לספור פריטים. סרגל ההתקדמות מציג שלבי משנה. תיבות תוחמות מוצגות בשכבת-על על פריטים שזוהו. התג של התוצאה מציג את הכיתוב '✓ קוד מאומת' או '~ משוער'
  3. התאמה בין ספקים: אנימציה של חיפוש וקטורים ב-AlloyDB ScaNN. הצגת שאילתת חיפוש (למשל, ‫"industrial metal boxes"). בכרטיס התוצאה מוצגים החלק התואם, הספק וציון רמת הביטחון
  4. הזמנה שבוצעה: כרטיס קבלה עם מזהה ההזמנה, הכמות והפרטים

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

1a031c4fd407a183.png

What Just Happened

‫Control Tower השתמש בפרוטוקול 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: צריך לוודא ש-Auth Proxy פועל:
ps aux | grep alloydb-auth-proxy

בעיות בחיבור ל-AlloyDB:

אם מופיעה השגיאה 'החיבור לשרת בכתובת 127.0.0.1, יציאה 5432 נכשל':

אם מופיעה השגיאה 'החיבור לשרת בכתובת 127.0.0.1, יציאה 5432 נכשל':

  1. בודקים את שרת ה-proxy לאימות: ps aux | grep alloydb-auth-proxy
  2. אימות של כתובת IP ציבורית: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
  3. לפיתוח מקומי (לא Cloud Shell):
  4. הבעיה: Cloud Shell פועל באופן אוטומטי, אבל במכונות מקומיות נדרשות רשתות מורשות
  5. פתרון: מריצים מחדש את הפקודה sh setup.sh ובוחרים באפשרות 1 (הרשאה 0.0.0.0/0) כשמוצגת הבקשה
  6. הערה בנושא אבטחה: גם אם משתמשים ב-0.0.0.0/0, החיבור דורש:
  7. פרטי כניסה תקפים ל-GCP ‏ (Application Default Credentials)
  8. סיסמה למסד הנתונים
  9. הצפנת mTLS (שרת ה-proxy ל-Auth מטפל בזה)

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

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

# From repo root
sh cleanup.sh

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

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

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

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

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

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

‫Gemini 3 Flash:

‫AlloyDB AI ו-ScaNN:

פרטי תמחור:

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

תכונה

תביעה

מקור

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

מהיר פי 10

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

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

מהיר פי 4

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

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

קטן פי 3-4

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

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

מהיר פי 8

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

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

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

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

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

לא נתמך

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

התנהגות כשמגדירים את הטמפרטורה כ-0

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

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

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

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

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

ScaNN Research:

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

11. מצב אתגר: שיפור המיומנויות של סוכנים

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

אתגר 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: שילוב של כמה סוכנים

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

ארכיטקטורה:

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

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

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

12. סיכום

המעבר שלך מ-AI גנרטיבי ל-AI מבוסס-סוכנים הסתיים בהצלחה.

מה בנינו:

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

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

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

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

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

השלבים הבאים