1. מבוא

1. האתגר
במצבי חירום, כדי לתאם בין ניצולים עם כישורים, משאבים וצרכים שונים במקומות שונים, נדרשות יכולות חכמות של ניהול נתונים וחיפוש. בסדנה הזו תלמדו איך לבנות מערכת AI בסביבת ייצור שמשלבת:
- 🗄️ מסד נתונים של גרפים (Spanner): אחסון קשרים מורכבים בין השורדים, הכישורים והמשאבים
- 🔍 חיפוש מבוסס-AI: חיפוש משולב של מילות מפתח וחיפוש סמנטי באמצעות הטמעות
- 📸 עיבוד מולטי-מודאלי: חילוץ נתונים מובְנים מתמונות, מטקסט ומסרטונים
- 🤖 תזמור של כמה סוכנים: תיאום בין סוכנים ייעודיים לתהליכי עבודה מורכבים
- 🧠 זיכרון לטווח ארוך: התאמה אישית עם בנק זיכרון Vertex AI

2. מה תפתחו
מסד נתונים של תרשים רשת ניצולים עם:
- 🗺️ תרשים אינטראקטיבי בתלת-ממד של הקשרים בין הניצולים
- 🔍 חיפוש חכם (מילת מפתח, סמנטי והיברידי)
- 📸 תהליך העלאה מולטי-מודאלי (חילוץ ישויות מתמונות או מסרטונים)
- 🤖 מערכת מרובת סוכנים (MAS) לניהול משימות מורכבות
- 🧠 שילוב Memory Bank לאינטראקציות בהתאמה אישית
3. טכנולוגיות ליבה
רכיב | טכנולוגיה | מטרה |
מסד נתונים | Cloud Spanner Graph | אחסון צמתים (שורדים, יכולות) וקצוות (קשרים) |
חיפוש מבוסס-AI | Gemini והטמעות | הבנה סמנטית + חיפוש דמיון |
Agent Framework | ADK (ערכה לפיתוח סוכנים) | תזמור תהליכי עבודה מבוססי-AI |
זיכרון | Vertex AI Memory Bank | אחסון לטווח ארוך של העדפות המשתמשים |
Frontend | React + Three.js | המחשה של תרשים תלת-ממדי אינטראקטיבי |
2. 🛠️ הכנת הסביבה (אפשר לדלג אם אתם בסדנה)
חלק ראשון: הפעלת החשבון לחיוב
כדי להריץ את ה-Codelab הזה, צריך חשבון לחיוב עם קרדיט. כדי להתחיל, השתמשו בקרדיטים מהבאנר שבחלק העליון של ה-Codelab הזה. אם כבר יש לכם חשבון לחיוב, אתם יכולים לדלג על השלב הזה.
חלק שני: סביבה פתוחה
- 👉 לוחצים על הקישור הזה כדי לעבור ישירות אל Cloud Shell Editor.
- 👉 אם תתבקשו לאשר בשלב כלשהו היום, לחצו על אישור כדי להמשיך.

- 👉 אם הטרמינל לא מופיע בתחתית המסך, פותחים אותו:
- לוחצים על הצגה.
- לוחצים על Terminal (מסוף).

- 👉💻 בטרמינל, מריצים את הפקודה הבאה כדי לוודא שכבר אומתתם ושהפרויקט מוגדר למזהה הפרויקט שלכם:
gcloud auth list - 👉💻 משכפלים את פרויקט ה-bootstrap מ-GitHub:
git clone https://github.com/gca-americas/way-back-home.git
חלק שלישי: יצירת פרויקט חדש
👉💻 בטרמינל, הופכים את הסקריפט init לקובץ הפעלה ומריצים אותו:
cd ~/way-back-home/level_2
./init.sh
3. 🛠️ הגדרת הסביבה
1. פתיחת Cloud Shell
בטרמינל של Cloud Shell Editor, אם הטרמינל לא מופיע בתחתית המסך, פותחים אותו:
- לוחצים על הצגה.
- לוחצים על Terminal (מסוף).

2. הגדרת הפרויקט
👉💻 בטרמינל, מגדירים את מזהה הפרויקט:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 מפעילים את ממשקי ה-API הנדרשים (זה לוקח בערך 2-3 דקות):
gcloud services enable compute.googleapis.com \
aiplatform.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
spanner.googleapis.com \
storage.googleapis.com
3. הרצת סקריפט ההגדרות
👉💻 מריצים את סקריפט ההגדרות:
cd ~/way-back-home/level_2
./setup.sh
הפעולה הזו תיצור בשבילכם .env. ב-Cloud Shell, פותחים את הפרויקט way_back_home. בתיקייה level_2, אפשר לראות שנוצר בשבילך הקובץ .env. אם לא מוצאים אותו, אפשר ללחוץ על View -> Toggle Hidden File כדי לראות אותו. 
4. טעינת נתונים לדוגמה
👉💻 עוברים לקצה העורפי ומתקינים את יחסי התלות:
cd ~/way-back-home/level_2/backend
uv sync
👉💻 טוענים את הנתונים הראשוניים של הניצולים:
uv run python ~/way-back-home/level_2/backend/setup_data.py
הפעולה הזו יוצרת:
- מכונת Spanner (
survivor-network) - מסד נתונים (
graph-db) - כל טבלאות הצמתים והקצוות
- תרשימי מאפיינים לשאילתות הפלט המצופה:
============================================================
SUCCESS! Database setup complete.
============================================================
Instance: survivor-network
Database: graph-db
Graph: SurvivorGraph
Access your database at:
https://console.cloud.google.com/spanner/instances/survivor-network/databases/graph-db?project=waybackhome
אם תלחצו על הקישור אחרי Access your database at בפלט, תוכלו לפתוח את Spanner במסוף Google Cloud.

Spanner יופיע במסוף Google Cloud.

4. 🚀 המחשה חזותית של נתוני תרשים ב-Spanner Studio
במדריך הזה נסביר איך להציג את נתוני התרשים של Survivor Network ולבצע בהם פעולות ישירות במסוף Google Cloud באמצעות Spanner Studio. זו דרך מצוינת לאמת את הנתונים ולהבין את מבנה התרשים לפני שיוצרים את סוכן ה-AI.
1. גישה ל-Spanner Studio
- בשלב האחרון, חשוב ללחוץ על הקישור ולפתוח את Spanner Studio.

2. הסבר על מבנה התרשים (התמונה הכוללת)
אפשר לחשוב על קבוצת הנתונים של Survivor Network כחידת היגיון או כמצב משחק:
ישות | תפקיד במערכת | אנלוגיה |
Survivors | הסוכנים/השחקנים | שחקנים |
ביומות | איפה הם נמצאים | אזורים במפה |
מיומנויות | מה הם יכולים לעשות | פעולות שניתן לבצע |
צרכים | מה חסר להם (משברים) | קווסטים/משימות |
מקורות מידע | פריטים שנמצאו בעולם | שלל |
המטרה: התפקיד של סוכן ה-AI הוא לקשר בין מיומנויות (פתרונות) לבין צרכים (בעיות), תוך התחשבות בביומות (אילוצי מיקום).
🔗 קצוות (קשרים):
-
SurvivorInBiome: מעקב אחר מיקום SurvivorHasSkill: מלאי של יכולותSurvivorHasNeed: רשימת הבעיות הפעילות-
SurvivorFoundResource: מלאי של פריטים -
SurvivorCanHelp: קשר משוער (ה-AI מחשב את זה!)
3. שליחת שאילתות לתרשים
נריץ כמה שאילתות כדי לראות את "הסיפור" שמאחורי הנתונים.
ב-Spanner Graph משתמשים ב-GQL (Graph Query Language). כדי להריץ שאילתה, משתמשים ב-GRAPH SurvivorNetwork ואחריו בתבנית ההתאמה.
👉 שאילתה 1: רשימת התלמידים הגלובלית (מי נמצא איפה?) זה הבסיס – הבנת המיקום היא קריטית לפעולות חילוץ.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[:SurvivorInBiome]->(b:Biomes)
RETURN TO_JSON(result) AS json_result
התוצאה אמורה להיראות כך: 
👉 שאילתה 2: מטריצת המיומנויות (יכולות) עכשיו, כשאתם יודעים איפה כולם נמצאים, אתם יכולים לגלות מה הם יכולים לעשות.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasSkill]->(k:Skills)
RETURN TO_JSON(result) AS json_result
התוצאה אמורה להיראות כך: 
👉 שאילתה 3: מי נמצא במשבר? ("לוח המשימות") כאן אפשר לראות את השורדים שזקוקים לעזרה ואת מה שהם צריכים.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasNeed]->(n:Needs)
RETURN TO_JSON(result) AS json_result
התוצאה אמורה להיראות כך: 
🔎 [אופציונלי] שידוכים – מי יכול לעזור למי?
כאן הגרף הופך לכלי חזק! השאילתה הזו מוצאת שורדים שיש להם מיומנויות שיכולות לענות על הצרכים של שורדים אחרים.
GRAPH SurvivorNetwork
MATCH result = (helper:Survivors)-[:SurvivorHasSkill]->(skill:Skills)-[:SkillTreatsNeed]->(need:Needs)<-[:SurvivorHasNeed]-(helpee:Survivors)
RETURN TO_JSON(result) AS json_result
התוצאה אמורה להיראות כך: 
aside positive מה השאילתה הזו עושה:
במקום להציג רק את "First Aid treats burns" (שברור מהסכימה), השאילתה הזו מוצאת:
- ד"ר אלנה פרוסט (שיש לה הכשרה רפואית) ← יכולה לטפל ← בקפטן טנאקה (שיש לו כוויות)
- דוד כהן (שיש לו ערכת עזרה ראשונה) → יכול לטפל ב-→ סגן פארק (שיש לו נקע בקרסול)
למה זה חשוב:
מה סוכן ה-AI יעשה:
כשמשתמש שואל "מי יכול לטפל בכוויות?", הסוכן:
- הרצת שאילתת גרף דומה
- התשובה: "לד"ר פרוסט יש הכשרה רפואית והוא יכול לעזור לקפטן טנאקה"
- המשתמש לא צריך לדעת על טבלאות או קשרים ביניים.
5. 🚀 הטמעות מבוססות-AI ב-Spanner
1. למה כדאי להשתמש בהטמעות? (אין פעולה, לקריאה בלבד)
במצב הישרדות, הזמן הוא קריטי. כשניצול מדווח על מקרה חירום, כמו I need someone who can treat burns או Looking for a medic, הוא לא יכול לבזבז זמן בניחוש השמות המדויקים של המיומנויות במסד הנתונים.
תרחיש אמיתי: שורד: Captain Tanaka has burns—we need medical help NOW!
חיפוש מסורתי של מילת המפתח "חובש" ← 0 תוצאות ❌
חיפוש סמנטי עם הטמעות ← מוצא את "הכשרה רפואית", "עזרה ראשונה" ✅
זה בדיוק מה שהסוכנים צריכים: חיפוש חכם, דמוי אנוש שמבין את הכוונה, ולא רק מילות מפתח.
2. יצירת מודל הטמעה

עכשיו ניצור מודל שממיר טקסט להטמעות באמצעות text-embedding-004 של Google.
👉 ב-Spanner Studio, מריצים את ה-SQL הזה (מחליפים את $YOUR_PROJECT_ID במזהה הפרויקט):
‼️ בעורך של Cloud Shell, פותחים את File -> Open Folder -> way-back-home/level_2 כדי לראות את כל הפרויקט.

👉 כדי להריץ את השאילתה ב-Spanner Studio, מעתיקים ומדביקים את השאילתה הבאה ולוחצים על Run:
CREATE OR REPLACE MODEL TextEmbeddings
INPUT(content STRING(MAX))
OUTPUT(embeddings STRUCT<values ARRAY<FLOAT32>>)
REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004'
);
מה קורה בעקבות הפעולה הזו:
- יוצרת מודל וירטואלי ב-Spanner (משקלי המודל לא מאוחסנים באופן מקומי)
- מפנה אל
text-embedding-004של Google ב-Vertex AI - מגדיר את החוזה: הקלט הוא טקסט, הפלט הוא מערך של מספרים ממשיים עם 768 ממדים
למה "אפשרויות מרחוק"?
- Spanner לא מריץ את המודל בעצמו
- הוא שולח קריאה ל-Vertex AI דרך API כשמשתמשים ב-
ML.PREDICT - Zero-ETL: לא צריך לייצא נתונים ל-Python, לעבד אותם ולייבא אותם מחדש
לוחצים על הלחצן Run. אם הפעולה תצליח, התוצאה תיראה כך:

3. הוספת עמודת הטמעה
👉 מוסיפים עמודה לאחסון הטמעות:
ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;
לוחצים על הלחצן Run. אם הפעולה תצליח, התוצאה תיראה כך:

4. יצירת הטמעות
👉 משתמשים ב-AI כדי ליצור הטמעות וקטורים לכל מיומנות:
UPDATE Skills
SET skill_embedding = (
SELECT embeddings.values
FROM ML.PREDICT(
MODEL TextEmbeddings,
(SELECT name AS content)
)
)
WHERE skill_embedding IS NULL;
לוחצים על הלחצן Run. אם הפעולה תצליח, התוצאה תיראה כך:

מה קורה: כל שם של מיומנות (למשל, "עזרה ראשונה") מומר לווקטור של 768 ממדים שמייצג את המשמעות הסמנטית שלו.
5. אימות ההטמעות
👉 בודקים שנוצרו הטמעות:
SELECT
skill_id,
name,
ARRAY_LENGTH(skill_embedding) AS embedding_dimensions
FROM Skills
LIMIT 5;
הפלט המצופה:

6. בדיקת החיפוש הסמנטי
עכשיו נבדוק את תרחיש השימוש המדויק מהתרחיש שלנו: חיפוש מיומנויות רפואיות באמצעות המונח "חובש".
👉 חיפוש מיומנויות שדומות ל "חובש":
WITH query_embedding AS (
SELECT embeddings.values AS val
FROM ML.PREDICT(MODEL TextEmbeddings, (SELECT "medic" AS content))
)
SELECT
s.name AS skill_name,
s.category,
COSINE_DISTANCE(s.skill_embedding, (SELECT val FROM query_embedding)) AS distance
FROM Skills AS s
WHERE s.skill_embedding IS NOT NULL
ORDER BY distance ASC
LIMIT 10;
- ממיר את מונח החיפוש של המשתמש "רופא" להטמעה
- מאחסן אותו בטבלה הזמנית
query_embedding
התוצאות הצפויות (מרחק קטן יותר = דמיון רב יותר):

7. יצירת מודל Gemini לניתוח נתונים

👉 יוצרים הפניה למודל AI גנרטיבי (מחליפים את $YOUR_PROJECT_ID במזהה הפרויקט):
CREATE OR REPLACE MODEL GeminiPro
INPUT(prompt STRING(MAX))
OUTPUT(content STRING(MAX))
REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-pro',
default_batch_size = 1
);
ההבדל ממודל הטמעות:
- הטמעות: טקסט ← וקטור (לחיפוש דמיון)
- Gemini: טקסט ← טקסט דינמי מבוסס-AI (להסקת מסקנות או ניתוח)

8. איך משתמשים ב-Gemini לניתוח תאימות
👉 מנתחים זוגות של שורדים כדי לבדוק אם הם מתאימים למשימה:
WITH PairData AS (
SELECT
s1.name AS Name_A,
s2.name AS Name_B,
CONCAT(
"Assess compatibility of these two survivors for a resource-gathering mission. ",
"Survivor 1: ", s1.name, ". ",
"Survivor 2: ", s2.name, ". ",
"Give a score from 1-10 and a 1-sentence reason."
) AS prompt
FROM Survivors s1
JOIN Survivors s2 ON s1.survivor_id < s2.survivor_id
LIMIT 1
)
SELECT
Name_A,
Name_B,
content AS ai_assessment
FROM ML.PREDICT(
MODEL GeminiPro,
(SELECT Name_A, Name_B, prompt FROM PairData)
);
הפלט המצופה:
Name_A | Name_B | ai_assessment
----------------|-------------------|----------------
"David Chen" | "Dr. Elena Frost" | "**Score: 9/10** Their compatibility is extremely high as David's practical, hands-on scavenging skills are perfectly complemented by Dr. Frost's specialized knowledge to identify critical medical supplies and avoid biological hazards."
6. 🚀 יצירת סוכן Graph RAG עם חיפוש היברידי
1. סקירה כללית של ארכיטקטורת המערכת
בקטע הזה נבנה מערכת חיפוש בכמה שיטות שנותנת לנציג גמישות לטפל בסוגים שונים של שאילתות. המערכת מורכבת משלוש שכבות: שכבת הנציג, שכבת הכלים ושכבת השירות.

למה שלוש שכבות?
- הפרדת תחומי האחריות: הנציג מתמקד בכוונת המשתמש, הכלים מתמקדים בממשק והשירות מתמקד בהטמעה
- גמישות: הנציג יכול לאלץ שיטות ספציפיות או לאפשר ל-AI לנתב באופן אוטומטי
- אופטימיזציה: אפשר לדלג על ניתוח AI יקר כשהשיטה ידועה
בקטע הזה, תטמיעו בעיקר חיפוש סמנטי (RAG) – חיפוש תוצאות לפי משמעות ולא רק לפי מילות מפתח. בהמשך נסביר איך החיפוש ההיברידי משלב כמה שיטות.
2. הטמעת שירות RAG
👉💻 בטרמינל, פותחים את הקובץ ב-Cloud Shell Editor באמצעות הפקודה:
cloudshell edit ~/way-back-home/level_2/backend/services/hybrid_search_service.py
מאתרים את התגובה # TODO: REPLACE_SQL
מחליפים את כל השורה הזו בקוד הבא:
# This is your working query from the successful run!
sql = """
WITH query_embedding AS (
SELECT embeddings.values AS val
FROM ML.PREDICT(
MODEL TextEmbeddings,
(SELECT @query AS content)
)
)
SELECT
s.survivor_id,
s.name AS survivor_name,
s.biome,
sk.skill_id,
sk.name AS skill_name,
sk.category,
COSINE_DISTANCE(
sk.skill_embedding,
(SELECT val FROM query_embedding)
) AS distance
FROM Survivors s
JOIN SurvivorHasSkill shs ON s.survivor_id = shs.survivor_id
JOIN Skills sk ON shs.skill_id = sk.skill_id
WHERE sk.skill_embedding IS NOT NULL
ORDER BY distance ASC
LIMIT @limit
"""
3. הגדרת כלי החיפוש הסמנטי
👉💻 בטרמינל, פותחים את הקובץ ב-Cloud Shell Editor באמצעות הפקודה:
cloudshell edit ~/way-back-home/level_2/backend/agent/tools/hybrid_search_tools.py
ב-hybrid_search_tools.py, מאתרים את התגובה # TODO: REPLACE_SEMANTIC_SEARCH_TOOL
👉מחליפים את כל השורה הזו בקוד הבא:
async def semantic_search(query: str, limit: int = 10) -> str:
"""
Force semantic (RAG) search using embeddings.
Use this when you specifically want to find things by MEANING,
not just matching keywords. Great for:
- Finding conceptually similar items
- Handling vague or abstract queries
- When exact terms are unknown
Example: "healing abilities" will find "first aid", "surgery",
"herbalism" even though no keywords match exactly.
Args:
query: What you're looking for (describe the concept)
limit: Maximum results
Returns:
Semantically similar results ranked by relevance
"""
try:
service = _get_service()
result = service.smart_search(
query,
force_method=SearchMethod.RAG,
limit=limit
)
return _format_results(
result["results"],
result["analysis"],
show_analysis=True
)
except Exception as e:
return f"Error in semantic search: {str(e)}"
כשהנציג משתמש ב:
- שאילתות שמבקשות דמיון ("מצא משהו דומה ל-X")
- שאילתות קונספטואליות ("יכולות ריפוי")
- כשהבנת המשמעות היא קריטית
4. מדריך לקבלת החלטות של הסוכן (הוראות)
בהגדרת הסוכן, מעתיקים ומדביקים את החלק שקשור לחיפוש הסמנטי בהוראה.
👉💻 בטרמינל, פותחים את הקובץ ב-Cloud Shell Editor באמצעות הפקודה:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
הנציג משתמש בהוראה הזו כדי לבחור את הכלי המתאים:
👉בקובץ agent.py, מאתרים את ההערה # TODO: REPLACE_SEARCH_LOGIC, Replace this whole line ומחליפים אותה בקוד הבא:
- `semantic_search`: Force RAG/embedding search
Use for: "Find similar to X", conceptual queries, unknown terminology
Example: "Find skills related to healing"
👉מאתרים את ההערה # TODO: ADD_SEARCH_TOOLReplace this whole line ומחליפים אותה בקוד הבא:
semantic_search, # Force RAG
5. איך פועל החיפוש ההיברידי (לקריאה בלבד, לא נדרשת פעולה)
בשלבים 2 עד 4, הטמעתם חיפוש סמנטי (RAG), שיטת החיפוש העיקרית שמוצאת תוצאות לפי משמעות. אבל אולי שמתם לב שהמערכת נקראת "חיפוש משולב". ככה זה עובד:
איך פועל מיזוג היברידי:
בקובץ way-back-home/level_2/backend/services/hybrid_search_service.py, כשמתבצעת קריאה ל-hybrid_search(), השירות מריץ את שני החיפושים וממזג את התוצאות:
# Location: backend/services/hybrid_search_service.py
rank_kw = keyword_ranks.get(surv_id, float('inf'))
rank_rag = rag_ranks.get(surv_id, float('inf'))
rrf_score = 0.0
if rank_kw != float('inf'):
rrf_score += 1.0 / (K + rank_kw)
if rank_rag != float('inf'):
rrf_score += 1.0 / (K + rank_rag)
combined_score = rrf_score
ב-Codelab הזה הטמעתם את רכיב החיפוש הסמנטי (RAG), שהוא הבסיס. שיטות החיפוש לפי מילות מפתח והחיפוש ההיברידי כבר מוטמעות בשירות, והנציג יכול להשתמש בכל שלוש השיטות.
מעולה! סיימתם להגדיר את סוכן Graph RAG עם חיפוש היברידי.
7. 🚀 בדיקת הסוכן באמצעות ADK Web
הדרך הכי קלה לבדוק את הנציג היא באמצעות הפקודה adk web, שמפעילה את הנציג עם ממשק צ'אט מובנה.
1. הפעלת הסוכן
👉💻 עוברים לספריית הקצה העורפי (שבה מוגדר הנציג) ומפעילים את ממשק האינטרנט:
cd ~/way-back-home/level_2/backend
uv run adk web
הפקודה הזו מפעילה את הנציג שמוגדר ב-
agent/agent.py
ופותח ממשק אינטרנט לבדיקה.
👉 פותחים את כתובת ה-URL:
הפקודה תוציא כתובת URL מקומית (בדרך כלל http://127.0.0.1:8000 או משהו דומה). פותחים את הקישור בדפדפן.

אחרי שלוחצים על כתובת ה-URL, מופיע ממשק המשתמש של ADK באינטרנט. חשוב לבחור את הנציג בפינה הימנית העליונה.

2. בדיקת יכולות החיפוש
הסוכן מתוכנן לנתב את השאילתות שלכם בצורה חכמה. כדי לראות שיטות חיפוש שונות בפעולה, נסו להזין את הקלטים הבאים בחלון הצ'אט.
🧬 א. Graph RAG (חיפוש סמנטי)
הוא מוצא פריטים על סמך המשמעות והקונספט, גם אם מילות המפתח לא תואמות.
שאילתות לבדיקה: (אפשר לבחור כל אחת מהאפשרויות הבאות)
Who can help with injuries?
What abilities are related to survival?
מה צריך לחפש:
- ההסבר צריך לכלול את המונחים סמנטי או RAG.
- אמורים להופיע תוצאות שקשורות מבחינה רעיונית (למשל, "ניתוח" כשמבקשים "עזרה ראשונה").
- התוצאות יכללו את הסמל 🧬.
🔀 ב. חיפוש היברידי
משלב מסננים של מילות מפתח עם הבנה סמנטית של שאילתות מורכבות.
שאילתות לבדיקה: (אפשר לבחור כל אחת מהאפשרויות הבאות)
Find someone who can fly a plane in the volcanic area
Who has healing abilities in the FOSSILIZED?
Who has healing abilities in the mountains?
מה צריך לחפש:
- ההסבר צריך להתייחס לחיפוש היברידי.
- התוצאות צריכות להתאים לשני הקריטריונים (הקונספט + המיקום או הקטגוריה).
- תוצאות שנמצאו בשתי השיטות יופיעו עם הסמל 🔀 וידורגו במקום הכי גבוה.
👉💻 בסיום הבדיקה, מסיימים את התהליך על ידי לחיצה על Ctrl+C בשורת הפקודה.
8. 🚀 הפעלת האפליקציה המלאה
סקירה כללית על ארכיטקטורת Full Stack

הוספת SessionService ו-Runner
👉💻 בטרמינל, פותחים את הקובץ chat.py ב-Cloud Shell Editor באמצעות הפקודה הבאה (לפני שממשיכים, חשוב לוודא שהקשתם על Ctrl+C כדי לסיים את התהליך הקודם):
cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py
👉בקובץ chat.py, מאתרים את ההערה # TODO: REPLACE_INMEMORY_SERVICES, Replace this whole line ומחליפים אותה בקוד הבא:
session_service = InMemorySessionService()
memory_service = InMemoryMemoryService()
👉בקובץ chat.py, מאתרים את ההערה # TODO: REPLACE_RUNNER, Replace this whole line ומחליפים אותה בקוד הבא:
runner = Runner(
agent=root_agent,
session_service=session_service,
memory_service=memory_service,
app_name="survivor-network"
)
1. להגשת הבקשה
אם הטרמינל הקודם עדיין פועל, מסיימים אותו על ידי הקשה על Ctrl+C.
👉💻 הפעלת האפליקציה:
cd ~/way-back-home/level_2/
./start_app.sh
כשה-backend יתחיל לפעול, תראו את ההודעה Local: http://localhost:5173/" כמו בדוגמה הבאה: 
👉 לוחצים על Local: http://localhost:5173/ בטרמינל.

2. בדיקת החיפוש הסמנטי
שאילתה:
Find skills similar to healing

מה קורה:
- הסוכן מזהה בקשה לדמיון
- יוצר הטמעה של "ריפוי"
- משתמש במרחק קוסינוס כדי למצוא מיומנויות דומות מבחינה סמנטית
- התוצאה: עזרה ראשונה (למרות שהשמות לא תואמים ל"ריפוי")
3. בדיקת החיפוש המשולב
שאילתה:
Find medical skills in the mountains
מה קורה:
- רכיב מילת מפתח: סינון לפי
category='medical' - רכיב סמנטי: הטמעת המונח "רפואי" ודירוג לפי דמיון
- מיזוג: שילוב של התוצאות, תוך מתן עדיפות לתוצאות שנמצאו בשתי השיטות 🔀
שאילתה (אופציונלי):
Who is good at survival and in the forest?
מה קורה:
- מילת המפתח נמצאה ב:
biome='forest' - חיפושים סמנטיים: מיומנויות שדומות ל "הישרדות"
- היברידית – שילוב של שתי השיטות כדי לקבל את התוצאות הכי טובות
👉💻 כשמסיימים את הבדיקה, מסיימים אותה בטרמינל על ידי לחיצה על Ctrl+C.
4. (!ONLY FOR WORKSHOP ATTENDEE) Update your location
👉💻 מריצים את הסקריפט להשלמה:
cd ~/way-back-home/level_2
./set_level_2.sh
עכשיו פותחים את waybackhome.dev, והמיקום יתעדכן. כל הכבוד, סיימת את רמה 2!

9. ☕️ [אופציונלי] צינור עיבוד נתונים מולטימודלי (לקריאה בלבד) – שכבת הכלים
למה אנחנו צריכים צינור עיבוד נתונים מולטי-מודאלי?
רשת ההישרדות היא לא רק טקסט. הניצולים בשטח שולחים נתונים לא מובְנים ישירות דרך הצ'אט:
- 📸 תמונות: תמונות של משאבים, מפגעים או ציוד
- 🎥 סרטונים: דיווחי סטטוס או שידורי SOS
- 📄 טקסט: הערות או יומנים מהשטח
אילו קבצים אנחנו מעבדים?
בניגוד לשלב הקודם שבו חיפשנו בנתונים קיימים, כאן אנחנו מעבדים קבצים שהמשתמשים העלו. הממשק של chat.py מטפל בקבצים מצורפים באופן דינמי:
מקור | תוכן | יעד |
קובץ מצורף של משתמש | תמונה/סרטון/טקסט | מידע שצריך להוסיף לתרשים |
הקשר השיחה | "הנה תמונה של הציוד" | כוונה ופרטים נוספים |
הגישה המתוכננת: צינור עיבוד נתונים של סוכנים ברצף
אנחנו משתמשים בסוכן רציף (multimedia_agent.py) שמקשר בין סוכנים ייעודיים:

הוא מוגדר ב-backend/agent/multimedia_agent.py בתור SequentialAgent.
שכבת הכלים מספקת את היכולות שהנציגים יכולים להפעיל. הכלים מטפלים ב "איך" – העלאת קבצים, חילוץ ישויות ושמירה במסד הנתונים.
1. פתיחת קובץ הכלים
👉💻 פותחים את הקובץ level_2/backend/agent/tools/extraction_tools.py או מקלידים את הפקודה הבאה בטרמינל. פותחים טרמינל חדש. בטרמינל, פותחים את הקובץ ב-Cloud Shell Editor:
cloudshell edit ~/way-back-home/level_2/backend/agent/tools/extraction_tools.py
2. הטמעת הכלי upload_media
הכלי הזה מעלה קובץ מקומי ל-Google Cloud Storage.
👉 ב-def upload_media(file_path: str, survivor_id: Optional[str] = None) -> Dict[str, Any]:, הקוד הבא מראה איך להעלות קבצים ל-GCS ולזהות את הסוג שלהם:
"""
Upload media file to GCS and detect its type.
Args:
file_path: Path to the local file
survivor_id: Optional survivor ID to associate with upload
Returns:
Dict with gcs_uri, media_type, and status
"""
try:
if not file_path:
return {"status": "error", "error": "No file path provided"}
# Strip quotes if present
file_path = file_path.strip().strip("'").strip('"')
if not os.path.exists(file_path):
return {"status": "error", "error": f"File not found: {file_path}"}
gcs_uri, media_type, signed_url = gcs_service.upload_file(file_path, survivor_id)
return {
"status": "success",
"gcs_uri": gcs_uri,
"signed_url": signed_url,
"media_type": media_type.value,
"file_name": os.path.basename(file_path),
"survivor_id": survivor_id
}
except Exception as e:
logger.error(f"Upload failed: {e}")
return {"status": "error", "error": str(e)}
3. הטמעת כלי extract_from_media
הכלי הזה הוא נתב – הוא בודק את ה-media_type ומנתב אותו למחלץ הנכון (טקסט, תמונה או סרטון).
👉 ב-async def extract_from_media(gcs_uri: str, media_type: str, signed_url: Optional[str] = None) -> Dict[str, Any]:, הקוד הבא מראה איך לחלץ ישויות וקשרים ממדיה שהועלתה.
"""
Extract entities and relationships from uploaded media.
Args:
gcs_uri: GCS URI of the uploaded file
media_type: Type of media (text/image/video)
signed_url: Optional signed URL for public/temporary access
Returns:
Dict with extraction results
"""
try:
if not gcs_uri:
return {"status": "error", "error": "No GCS URI provided"}
# Select appropriate extractor
if media_type == MediaType.TEXT.value or media_type == "text":
result = await text_extractor.extract(gcs_uri)
elif media_type == MediaType.IMAGE.value or media_type == "image":
result = await image_extractor.extract(gcs_uri)
elif media_type == MediaType.VIDEO.value or media_type == "video":
result = await video_extractor.extract(gcs_uri)
else:
return {"status": "error", "error": f"Unsupported media type: {media_type}"}
# Inject signed URL into broadcast info if present
if signed_url:
if not result.broadcast_info:
result.broadcast_info = {}
result.broadcast_info['thumbnail_url'] = signed_url
return {
"status": "success",
"extraction_result": result.to_dict(), # Return valid JSON dict instead of object
"summary": result.summary,
"entities_count": len(result.entities),
"relationships_count": len(result.relationships),
"entities": [e.to_dict() for e in result.entities],
"relationships": [r.to_dict() for r in result.relationships]
}
except Exception as e:
logger.error(f"Extraction failed: {e}")
return {"status": "error", "error": str(e)}
פרטי הטמעה עיקריים:
- קלט מולטי-מודאלי: אנחנו מעבירים גם את פרומפט טקסטואלי (
_get_extraction_prompt()) וגם את אובייקט התמונה אלgenerate_content. - פלט מובנה:
response_mime_type="application/json"מבטיח שה-LLM יחזיר JSON תקין, וזה קריטי לצינור עיבוד הנתונים. - קישור ישויות חזותיות: ההנחיה כוללת ישויות מוכרות כדי ש-Gemini יוכל לזהות דמויות ספציפיות.
4. הטמעת כלי אחד (save_to_spanner)
הכלי הזה שומר את הישויות והקשרים שחולצו במסד הנתונים של Spanner Graph.
👉 ב-def save_to_spanner(extraction_result: Any, survivor_id: Optional[str] = None) -> Dict[str, Any]:, הקוד הבא מראה איך לשמור ישויות וקשרים שחולצו במסד הנתונים של Spanner Graph.
"""
Save extracted entities and relationships to Spanner Graph DB.
Args:
extraction_result: ExtractionResult object (or dict from previous step if passed as dict)
survivor_id: Optional survivor ID to associate with the broadcast
Returns:
Dict with save statistics
"""
try:
# Handle if extraction_result is passed as the wrapper dict from extract_from_media
result_obj = extraction_result
if isinstance(extraction_result, dict) and 'extraction_result' in extraction_result:
result_obj = extraction_result['extraction_result']
# If result_obj is a dict (from to_dict()), reconstruct it
if isinstance(result_obj, dict):
from extractors.base_extractor import ExtractionResult
result_obj = ExtractionResult.from_dict(result_obj)
if not result_obj:
return {"status": "error", "error": "No extraction result provided"}
stats = spanner_service.save_extraction_result(result_obj, survivor_id)
return {
"status": "success",
"entities_created": stats['entities_created'],
"entities_existing": stats['entities_found_existing'],
"relationships_created": stats['relationships_created'],
"broadcast_id": stats['broadcast_id'],
"errors": stats['errors'] if stats['errors'] else None
}
except Exception as e:
logger.error(f"Spanner save failed: {e}")
return {"status": "error", "error": str(e)}
כשאנחנו נותנים לסוכנים כלים ברמה גבוהה, אנחנו מבטיחים את תקינות הנתונים תוך ניצול יכולות החשיבה של הסוכן.
5. עדכון שירות GCS
ה-GCSService מטפל בהעלאת הקובץ בפועל ל-Google Cloud Storage.
👉💻 פותחים את הקובץ level_2/backend/services/gcs_service.py, או מקלידים בטרמינל כדי לפתוח את הקובץ ב-Cloud Shell Editor:
cloudshell edit ~/way-back-home/level_2/backend/services/gcs_service.py
👉 ב-def upload_file(self, file_path: str, survivor_id: Optional[str] = None) -> Tuple[str, MediaType, str]:, הקוד הבא מראה איך לשמור ישויות וקשרים שחולצו במסד הנתונים של Spanner Graph.
blob = self.bucket.blob(blob_name)
blob.upload_from_filename(file_path)
הפשטת התהליך הזה לשירות מאפשרת לנציג לפעול בלי לדעת על קטגוריות GCS, שמות של אובייקטים גדולים או יצירת כתובות URL חתומות. הוא רק מבקש "להעלות".
6. למה Agentic Workflow עדיף על גישות מסורתיות?
היתרון של סוכני AI:
תכונה | צינור עיבוד נתונים באצווה | מונחה אירועים | Agentic Workflows |
מורכבות | נמוכה (סקריפט אחד) | גבוה (יותר מ-5 שירותים) | נמוכה (קובץ Python אחד: |
ניהול מצב | משתנים גלובליים | קשיח (מנותק) | מנוהל במרוכז (מצב הסוכן) |
טיפול בשגיאות | קריסות | יומנים שקטים | אינטראקטיבי ("לא הצלחתי לקרוא את הקובץ הזה") |
משוב ממשתמשים | הדפסות במסוף | נדרשת דגימה | מיידי (חלק מהצ'אט) |
יכולת הסתגלות | לוגיקה קבועה | פונקציות קשיחות | חכם (ה-LLM מחליט מה השלב הבא) |
מודעות להקשר | ללא | ללא | מלא (יודע את כוונת המשתמש) |
למה זה חשוב: באמצעות multimedia_agent.py (סוכן SequentialAgent עם 4 סוכני משנה: העלאה ← חילוץ ← שמירה ← סיכום), אנחנו מחליפים תשתית מורכבת וסקריפטים שבירים בלוגיקה חכמה של אפליקציה לשיחות.
10. ☕️ [אופציונלי] צינור עיבוד נתונים מולטימודלי (לקריאה בלבד) – שכבת הסוכן
שכבת הסוכנים מגדירה את האינטליגנציה – סוכנים שמשתמשים בכלים כדי לבצע משימות. לכל סוכן יש תפקיד ספציפי והוא מעביר את ההקשר לסוכן הבא. בהמשך מופיעה דיאגרמת ארכיטקטורה של מערכת עם כמה סוכנים.

1. פתיחת קובץ הסוכן
👉💻 פותחים את הקובץ level_2/backend/agent/multimedia_agent.py או מקלידים את הפקודה הבאה בטרמינל. פותחים טרמינל חדש. בטרמינל, פותחים את הקובץ ב-Cloud Shell Editor:
cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py
2. הגדרת סוכן ההעלאה
הנציג הזה מחלץ נתיב קובץ מההודעה של המשתמש ומעלה אותו ל-GCS.
👉בקובץ multimedia_agent.py, באמצעות הקוד הבא, נוצר upload_agent שמעלה ל-GCS:
upload_agent = LlmAgent(
name="UploadAgent",
model="gemini-2.5-flash",
instruction="""Extract the file path from the user's message and upload it.
Use `upload_media(file_path, survivor_id)` to upload the file.
The survivor_id is optional - include it if the user mentions a specific survivor (e.g., "survivor Sarah" -> "Sarah").
If the user provides a path like "/path/to/file", use that.
Return the upload result with gcs_uri and media_type.""",
tools=[upload_media],
output_key="upload_result"
)
3. הגדרת סוכן החילוץ
הסוכן הזה "רואה" את המדיה שהועלתה ומחלץ נתונים מובְנים באמצעות Gemini Vision.
👉בקובץ multimedia_agent.py, עם הקוד הבא, הוא יוצר את extraction_agent שמחלץ מידע מהמדיה שהועלתה:
extraction_agent = LlmAgent(
name="ExtractionAgent",
model="gemini-2.5-flash",
instruction="""Extract information from the uploaded media.
Previous step result: {upload_result}
Use `extract_from_media(gcs_uri, media_type, signed_url)` with the values from the upload result.
The gcs_uri is in upload_result['gcs_uri'], media_type in upload_result['media_type'], and signed_url in upload_result['signed_url'].
Return the extraction results including entities and relationships found.""",
tools=[extract_from_media],
output_key="extraction_result"
)
שימו לב איך instruction מפנה אל {upload_result} – ככה המצב מועבר בין סוכנים ב-ADK.
4. הגדרת הסוכן של Spanner
הסוכן הזה שומר את הישויות והקשרים שחולצו במסד הנתונים של התרשים.
👉בקובץ multimedia_agent.py, עם הקוד הבא, הוא יוצר את spanner_agent ששומר את המידע שחולץ במסד הנתונים:
spanner_agent = LlmAgent(
name="SpannerAgent",
model="gemini-2.5-flash",
instruction="""Save the extracted information to the database.
Upload result: {upload_result}
Extraction result: {extraction_result}
Use `save_to_spanner(extraction_result, survivor_id)` to save to Spanner.
Pass the WHOLE `extraction_result` object/dict from the previous step.
Include survivor_id if it was provided in the upload step.
Return the save statistics.""",
tools=[save_to_spanner],
output_key="spanner_result"
)
הסוכן הזה מקבל הקשר משני השלבים הקודמים (upload_result ו-extraction_result).
5. הגדרת הסוכן המסכם
הנציג הזה מסכם את התוצאות מכל השלבים הקודמים לתשובה ידידותית למשתמש.
👉בקובץ multimedia_agent.py, הקוד הבא מגדיר את ההנחיה ל-summary_agent שמסכמת את התוצאה:
USE_MEMORY_BANK = os.getenv("USE_MEMORY_BANK", "false").lower() == "true"
save_msg = "6. Mention that the data is also being synced to the memory bank." if USE_MEMORY_BANK else ""
summary_instruction = f"""Provide a user-friendly summary of the media processing.
Upload: {{upload_result}}
Extraction: {{extraction_result}}
Database: {{spanner_result}}
Summarize:
1. What file was processed (name and type)
2. Key information extracted (survivors, skills, needs, resources found) - list names and counts
3. Relationships identified
4. What was saved to the database (broadcast ID, number of entities)
5. Any issues encountered
{save_msg}
Be concise but informative."""
הסוכן הזה לא צריך כלים – הוא פשוט קורא את ההקשר המשותף ויוצר סיכום ברור למשתמש.
🧠 סיכום הארכיטקטורה
שכבה | קובץ | אחריות |
כלים |
| איך — מעלים, מחלצים ושומרים |
Agent |
| מה – תזמון צינור עיבוד הנתונים |
11. 🚀 פייפליין נתונים מולטי-מודאלי – תזמור
הליבה של המערכת החדשה שלנו היא MultimediaExtractionPipeline שמוגדרת ב-backend/agent/multimedia_agent.py. הוא משתמש בתבנית Sequential Agent מ-ADK (ערכה לפיתוח סוכנים).
1. למה כדאי להשתמש במודעות ברצף?
עיבוד של העלאה הוא שרשרת תלות לינארית:
- אי אפשר לחלץ נתונים לפני שיש לכם את הקובץ (העלאה).
- אי אפשר לשמור נתונים לפני שמחלצים אותם (חילוץ).
- אי אפשר לסכם עד שיש תוצאות (שמירה).
SequentialAgent הוא פתרון מושלם לזה. הוא מעביר את הפלט של סוכן אחד כהקשר או כקלט לסוכן הבא.
2. הגדרת הסוכן
בואו נראה איך הצינור נבנה בתחתית של multimedia_agent.py: 👉💻 בטרמינל, פותחים את הקובץ ב-Cloud Shell Editor על ידי הרצת הפקודה:
cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py
הוא מקבל קלט משני השלבים הקודמים. מאתרים את התגובה # TODO: REPLACE_ORCHESTRATION. מחליפים את כל השורה הזו בקוד הבא:
sub_agents=[upload_agent, extraction_agent, spanner_agent, summary_agent]
3. חיבור ל-Root Agent
👉💻 בטרמינל, פותחים את הקובץ ב-Cloud Shell Editor באמצעות הפקודה:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
מאתרים את התגובה # TODO: REPLACE_ADD_SUBAGENT. מחליפים את כל השורה הזו בקוד הבא:
sub_agents=[multimedia_agent],
האובייקט היחיד הזה מאגד למעשה ארבעה "מומחים" לישות אחת שאפשר לקרוא לה.
4. זרימת נתונים בין סוכנים
כל נציג שומר את הפלט שלו בהקשר משותף, שנציגים אחרים יכולים לגשת אליו:

5. פותחים את האפליקציה (מדלגים על השלב הזה אם האפליקציה עדיין פועלת).
👉💻 הפעלת האפליקציה:
cd ~/way-back-home/level_2/
./start_app.sh
👉 לוחצים על Local: http://localhost:5173/ בטרמינל.
6. העלאת תמונה לבדיקה
👉 בממשק הצ'אט, בוחרים אחת מהתמונות שכאן ומעלים אותה לממשק:
בממשק הצ'אט, מסבירים לנציג את ההקשר הספציפי:
Here is the survivor note
ואז לצרף את התמונה כאן.


👉💻 בטרמינל, בסיום הבדיקה, לוחצים על "Ctrl+C" כדי לסיים את התהליך.
6. אימות של העלאה ממספר מקורות בקטגוריית GCS
- פותחים את מסוף Google Cloud Storage.
- בוחרים באפשרות "קטגוריה" ב-Cloud Storage

- בוחרים את הקטגוריה ולוחצים על
media.

- כאן אפשר לראות את התמונה שהעלית.

7. אימות ההעלאה המולטי-מודאלית ב-Spanner (אופציונלי)
למטה מוצג פלט לדוגמה בממשק המשתמש של test_photo1.
- פותחים את Spanner במסוף Google Cloud.
- בוחרים את המכונה:
Survivor Network - בוחרים את מסד הנתונים:
graph-db - בסרגל הצד שמימין, לוחצים על Spanner Studio.
👉 ב-Spanner Studio, שולחים שאילתה על הנתונים החדשים:
SELECT
s.name AS Survivor,
s.role AS Role,
b.name AS Biome,
r.name AS FoundResource,
s.created_at
FROM Survivors s
LEFT JOIN SurvivorInBiome sib ON s.survivor_id = sib.survivor_id
LEFT JOIN Biomes b ON sib.biome_id = b.biome_id
LEFT JOIN SurvivorFoundResource sfr ON s.survivor_id = sfr.survivor_id
LEFT JOIN Resources r ON sfr.resource_id = r.resource_id
ORDER BY s.created_at DESC;
אפשר לאמת את זה לפי התוצאה הבאה:

12. ☕️ [אופציונלי] Memory Bank עם Agent Engine
1. איך פועל הזיכרון
המערכת משתמשת בגישה של זיכרון כפול כדי לטפל גם בהקשר המיידי וגם בלמידה לטווח ארוך.

2. מהם נושאי הזיכרונות?
נושאים בזיכרון מגדירים את קטגוריות המידע שהנציג צריך לזכור בשיחות שונות. אפשר לחשוב עליהם כעל ארונות תיוק לסוגים שונים של העדפות משתמשים.
שני הנושאים שלנו:
search_preferences: איך המשתמש מעדיף לחפש- הם מעדיפים חיפוש לפי מילות מפתח או חיפוש סמנטי?
- אילו מיומנויות או ביומות הם מחפשים לעיתים קרובות?
- דוגמה לזיכרון: "המשתמש מעדיף חיפוש סמנטי של מיומנויות רפואיות"
-
urgent_needs_context: אילו משברים הם עוקבים אחריהם- אחרי אילו משאבים הם עוקבים?
- אילו שורדים מדאיגים אותם?
- דוגמה לזיכרון: "המשתמש עוקב אחרי מחסור בתרופות במחנה הצפוני"
3. הגדרת נושאים לזיכרונות
נושאי זיכרון בהתאמה אישית מגדירים מה הסוכן צריך לזכור. הם מוגדרים כשפורסים את Agent Engine.
👉💻 בטרמינל, פותחים את הקובץ ב-Cloud Shell Editor באמצעות הפקודה:
cloudshell edit ~/way-back-home/level_2/backend/deploy_agent.py
הפעולה הזו תפתח את ~/way-back-home/level_2/backend/deploy_agent.py בכלי העריכה.
אנחנו מגדירים אובייקטים של מבנה MemoryTopic כדי להנחות את ה-LLM איזה מידע לחלץ ולשמור.
👉בקובץ deploy_agent.py, מחליפים את # TODO: SET_UP_TOPIC בטקסט הבא:
# backend/deploy_agent.py
custom_topics = [
# Topic 1: Survivor Search Preferences
MemoryTopic(
custom_memory_topic=CustomMemoryTopic(
label="search_preferences",
description="""Extract the user's preferences for how they search for survivors. Include:
- Preferred search methods (keyword, semantic, direct lookup)
- Common filters used (biome, role, status)
- Specific skills they value or frequently look for
- Geographic areas of interest (e.g., "forest biome", "mountain outpost")
Example: "User prefers semantic search for finding similar skills."
Example: "User frequently checks for survivors in the Swamp Biome."
""",
)
),
# Topic 2: Urgent Needs Context
MemoryTopic(
custom_memory_topic=CustomMemoryTopic(
label="urgent_needs_context",
description="""Track the user's focus on urgent needs and resource shortages. Include:
- Specific resources they are monitoring (food, medicine, ammo)
- Critical situations they are tracking
- Survivors they are particularly concerned about
Example: "User is monitoring the medicine shortage in the Northern Camp."
Example: "User is looking for a doctor for the injured survivors."
""",
)
)
]
4. שילוב סוכנים
כדי לשמור ולאחזר מידע, קוד הנציג צריך להיות מודע ל-Memory Bank.
👉💻 בטרמינל, פותחים את הקובץ ב-Cloud Shell Editor באמצעות הפקודה:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
הפעולה הזו תפתח את ~/way-back-home/level_2/backend/agent/agent.py בכלי העריכה.
יצירת סוכן
כשיוצרים את הנציג, אנחנו מעבירים את after_agent_callback כדי לוודא שהסשנים נשמרים בזיכרון אחרי האינטראקציות. הפונקציה add_session_to_memory פועלת באופן אסינכרוני כדי לא להאט את התגובה בצ'אט.
👉בקובץ agent.py, מאתרים את ההערה # TODO: REPLACE_ADD_SESSION_MEMORY, מחליפים את כל השורה הזו בקוד הבא:
async def add_session_to_memory(
callback_context: CallbackContext
) -> Optional[types.Content]:
"""Automatically save completed sessions to memory bank in the background"""
if hasattr(callback_context, "_invocation_context"):
invocation_context = callback_context._invocation_context
if invocation_context.memory_service:
# Use create_task to run this in the background without blocking the response
asyncio.create_task(
invocation_context.memory_service.add_session_to_memory(
invocation_context.session
)
)
logger.info("Scheduled session save to memory bank in background")
שמירה ברקע
👉בקובץ agent.py, מאתרים את ההערה # TODO: REPLACE_ADD_MEMORY_BANK_TOOL, מחליפים את כל השורה הזו בקוד הבא:
if USE_MEMORY_BANK:
agent_tools.append(PreloadMemoryTool())
👉בקובץ agent.py, מאתרים את ההערה # TODO: REPLACE_ADD_CALLBACK, מחליפים את כל השורה הזו בקוד הבא:
after_agent_callback=add_session_to_memory if USE_MEMORY_BANK else None
הגדרת שירות הסשנים של Vertex AI
👉💻 בטרמינל, פותחים את הקובץ chat.py ב-Cloud Shell Editor באמצעות הפקודה:
cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py
👉בקובץ chat.py, מאתרים את ההערה # TODO: REPLACE_VERTEXAI_SERVICES, Replace this whole line ומחליפים אותה בקוד הבא:
session_service = VertexAiSessionService(
project=project_id,
location=location,
agent_engine_id=agent_engine_id
)
memory_service = VertexAiMemoryBankService(
project=project_id,
location=location,
agent_engine_id=agent_engine_id
)
13. ☕️ [אופציונלי] צירוף סוכן באמצעות Agent Engine
1. הגדרה ופריסה
לפני שבודקים את תכונות הזיכרון, צריך לפרוס את הנציג עם נושאי הזיכרון החדשים ולוודא שהסביבה מוגדרת בצורה נכונה.
סיפקנו סקריפט נוח לטיפול בתהליך הזה.
הרצת סקריפט הפריסה
👉💻 במסוף, מריצים את סקריפט הפריסה:
cd ~/way-back-home/level_2
./deploy_and_update_env.sh
הסקריפט הזה מבצע את הפעולות הבאות:
- מריץ את
backend/deploy_agent.pyכדי לרשום את הסוכן ואת נושאי הזיכרון ב-Vertex AI. - מתעדים את מזהה מנוע הסוכן החדש.
- עדכון אוטומטי של קובץ
.envבאמצעותAGENT_ENGINE_ID. - מוודאים שהערך
USE_MEMORY_BANK=TRUEמוגדר בקובץ.env.
[!IMPORTANT] אם מבצעים שינויים ב-custom_topics ב-deploy_agent.py, צריך להריץ מחדש את הסקריפט הזה כדי לעדכן את Agent Engine.
אימות של Memory Bank
עכשיו אתם יכולים לוודא שמאגר הזיכרון פועל: מלמדים את הנציג העדפה מסוימת ובודקים אם הוא זוכר אותה בסשנים הבאים.
שלב ראשון. פתיחת האפליקציה
פותחים שוב את האפליקציה לפי ההוראות הבאות: אם הטרמינל הקודם עדיין פועל, סוגרים אותו בלחיצה על Ctrls+C.
👉💻 פתיחת האפליקציה:
cd ~/way-back-home/level_2/
./start_app.sh
👉 לוחצים על Local: http://localhost:5173/ בטרמינל.
שלב שני. בדיקת Memory Bank עם טקסט
בממשק הצ'אט, מסבירים לנציג את ההקשר הספציפי:
"I'm planning a medical rescue mission in the mountains. I need survivors with first aid and climbing skills."
👉 מחכים כ-30 שניות עד שהזיכרון יעובד ברקע.
שלב שלישי. התחלת סשן חדש
כדי למחוק את היסטוריית השיחות הנוכחית (הזיכרון לטווח קצר), מרעננים את הדף.
שואלים שאלה שמסתמכת על ההקשר שסיפקתם קודם:
"What kind of missions am I interested in?"
התשובה הצפויה:
"לפי השיחות הקודמות שלך, יש לך עניין בנושאים הבאים:
- משימות חילוץ רפואיות
- פעולות בהרים או בגובה רב
- מיומנויות נדרשות: עזרה ראשונה, טיפוס
רוצה שאחפש ניצולים שעומדים בקריטריונים האלה?"
שלב 4. בדיקה באמצעות העלאת תמונה
מעלים תמונה ושואלים:
remember this
אפשר לבחור כל אחת מהתמונות שכאן או תמונה משלכם ולהעלות אותה לממשק המשתמש:
שלב חמישי. אימות ב-Vertex AI Agent Engine
נכנסים ל-Agent Engine במסוף Google Cloud.
- חשוב לבחור את הפרויקט מהבורר שבפינה הימנית העליונה:

- מאמתים את מנוע הסוכן שפרסתם באמצעות הפקודה הקודמת
use_memory_bank.sh:
לוחצים על מנוע הסוכן שיצרתם. - לוחצים על הכרטיסייה
Memoriesבסוכן שנפרס, וכאן אפשר לראות את כל הזיכרון.
👉💻 בסיום הבדיקה, לוחצים על Ctrl + C בטרמינל כדי לסיים את התהליך.
🎉 איזה יופי! עכשיו קישרתם את זיכרון הנתונים לסוכן שלכם.
14. ☕️ [אופציונלי] פריסה ב-Cloud Run
1. הרצת סקריפט הפריסה
👉💻 מריצים את סקריפט הפריסה:
cd ~/way-back-home/level_2
./deploy_cloud_run.sh
אחרי שהפריסה תסתיים, תקבלו את כתובת ה-URL של הפריסה. 
👉💻 לפני שמעתיקים את כתובת ה-URL, צריך להעניק את ההרשאה באמצעות הפקודה הבאה:
source .env && gcloud run services add-iam-policy-binding survivor-frontend --region $REGION --member=allUsers --role=roles/run.invoker && gcloud run services add-iam-policy-binding survivor-backend --region $REGION --member=allUsers --role=roles/run.invoker
עוברים לכתובת ה-URL של הפריסה, ורואים את האפליקציה פעילה.
2. הסבר על צינור עיבוד הנתונים של ה-build
הקובץ cloudbuild.yaml מגדיר את השלבים הבאים ברצף:
- Backend Build: יוצר את קובץ האימג' של Docker מ-
backend/Dockerfile. - Backend Deploy: פריסת הקונטיינר של הקצה העורפי ב-Cloud Run.
- Capture URL: מקבל את כתובת ה-URL החדשה של הקצה העורפי.
- פיתוח ממשק משתמש:
- מתקין את יחסי התלות.
- יוצר את אפליקציית React ומזריק את
VITE_API_URL=.
- Frontend Image: יוצר את קובץ האימג' של Docker מ-
frontend/Dockerfile(אריזת הנכסים הסטטיים). - Frontend Deploy: פריסת מאגר התגים של הקצה הקדמי.
3. אימות הפריסה
אחרי שה-build מסתיים (בודקים את הקישור ליומנים שסופק על ידי הסקריפט), אפשר לאמת:
- נכנסים למסוף Cloud Run.
- מוצאים את השירות
survivor-frontend. - לוחצים על כתובת ה-URL כדי לפתוח את האפליקציה.
- מבצעים שאילתת חיפוש כדי לוודא שהחזית יכולה לתקשר עם הקצה העורפי.
(אופציונלי) 4. פריסה ידנית
אם אתם מעדיפים להריץ את הפקודות באופן ידני או להבין את התהליך טוב יותר, כך משתמשים ב-cloudbuild.yaml ישירות.
כותב את cloudbuild.yaml
קובץ cloudbuild.yaml אומר ל-Google Cloud Build אילו שלבים לבצע.
- steps: רשימה של פעולות עוקבות. כל שלב פועל בקונטיינר (למשל,
docker,gcloud,node,bash). - substitutions: משתנים שאפשר להעביר בזמן ה-build (למשל,
$_REGION). - workspace: ספרייה משותפת שבה השלבים יכולים לשתף קבצים (כמו שאנחנו משתפים את
backend_url.txt).
הרצת הפריסה
כדי לפרוס באופן ידני בלי הסקריפט, משתמשים בפקודה gcloud builds submit. חובה להעביר את משתני ההחלפה הנדרשים.
# Load your env vars first or replace these values manually
export PROJECT_ID=your-project-id
export REGION=us-central1
gcloud builds submit --config cloudbuild.yaml \
--project "$PROJECT_ID" \
--substitutions _REGION="us-central1",_GOOGLE_API_KEY="",_AGENT_ENGINE_ID="your-agent-id",_USE_MEMORY_BANK="TRUE",_GOOGLE_GENAI_USE_VERTEXAI="TRUE"
15. סיכום
1. מה שבניתם
✅ מסד נתונים של גרפים: Spanner עם צמתים (שורדים, מיומנויות) וקצוות (קשרים)
✅ חיפוש מבוסס-AI: חיפוש סמנטי, חיפוש היברידי וחיפוש לפי מילות מפתח עם הטמעות
✅ צינור עיבוד נתונים מולטימודלי: חילוץ ישויות מתמונות או מסרטונים באמצעות Gemini
✅ מערכת מרובת סוכנים (MAS): תהליך עבודה מתואם עם ADK
✅ Memory Bank: התאמה אישית לטווח ארוך באמצעות Vertex AI
✅ פריסה בסביבת ייצור: Cloud Run + Agent Engine
2. סיכום הארכיטקטורה

3. מסקנות עיקריות
- Graph RAG: משלב מבנה של מסד נתונים של גרפים עם הטמעות סמנטיות לחיפוש חכם
- תבניות של כמה סוכנים: צינורות עיבוד נתונים רציפים לתהליכי עבודה מורכבים עם כמה שלבים
- AI מולטימודלי: חילוץ נתונים מובְנים ממדיה לא מובְנית (תמונות או סרטונים)
- סוכנים עם שמירת מצב: Memory Bank מאפשר התאמה אישית בין סשנים
4. תוכן הסדנה
- Level0: זיהוי עצמי
- Level1: מיקום מדויק
- רמה 2: פיתוח סוכן AI מולטימודלי באמצעות Graph RAG, ADK ו-Memory Bank
- Level3: פיתוח סוכן סטרימינג דו-כיווני באמצעות ADK
- Level4: מערכת מרובת סוכנים דו-כיוונית בזמן אמת
- Level5: ארכיטקטורה מבוססת-אירועים עם Google ADK, A2A ו-Kafka