1. מבוא
The Modern Agent Stack
כדי לבנות סוכן AI ברמת ייצור, צריך יותר ממודל שפה גדול (LLM). מודל שפה גדול מספק את יכולות הנימוק, אבל כדי שהסוכן יהיה חזק הוא צריך לבצע אינטראקציה עם העולם החיצוני, לנהל את מצב השיחה ולזכור את העדפות המשתמש לאורך זמן.
בסדנה הזו תלמדו איך לתכנן ולבנות מערכת מקיפה מבוססת-סוכנים באמצעות שלוש טכנולוגיות בסיסיות:
- קישוריות (MCP): כדי לתת לסוכן גישה לכלים ולנתונים מקומיים.
- תיאום (ADK): כדי לנהל את לולאת הנימוקים והמצב של הסוכן.
- זיכרון (מאגר זיכרונות): כדי לספק הקשר מותאם אישית לטווח ארוך.
מושגי ליבה
רכיב | פונקציה |
Model Context Protocol (MCP) | תקן אוניברסלי שמקשר מודלים של AI למערכות חיצוניות (מסדי נתונים, מערכות קבצים, ממשקי API) ללא שילובים מותאמים אישית. |
ערכת פיתוח של סוכנים (ADK) | מסגרת שמספקת את סביבת זמן הריצה לסוכנים, ומנהלת את לולאת האירועים, מעברי המצבים והפעלת הכלים. |
Session Service | מטפל בזיכרון לטווח קצר. הוא שומר על ההקשר המיידי של השיחה (למשל, "מה המשתמש שאל עכשיו?"), אבל הוא מתנקה בסיום הסשן. |
Vertex AI Memory Bank | מטפל בזיכרון לטווח ארוך. הוא שומר עובדות והעדפות ספציפיות למשתמש (למשל, ההעדפה של המשתמש לגבי Python) ללא הגבלת זמן, וכך הסוכן יכול להתאים אישית אינטראקציות עתידיות. |
Vertex AI Agent Engine | שירות מנוהל של תשתיות שמארח את הלוגיקה של הסוכן ואת רכיבי הזיכרון שלו בקנה מידה נרחב. |
מה תפַתחו
כדי להמחיש את המושגים האלה, נבנה עוזר לעיצוב חגים. הסוכן הזה יוכל לקבל בקשות משתמש ברמה גבוהה ולתזמן באופן אוטונומי כלים מקומיים של Python כדי ליצור קוד ותמונות בהתאמה אישית.
תהליך ההתקדמות כולל שלושה שלבים:
- שכבת כלי הפיתוח: יצירת שרת MCP כדי לחשוף פונקציות Python מקומיות ל-AI.
- שכבת הסוכן: אפשר להשתמש ב-ADK כדי ליצור סוכן שמתכנן ומבצע תהליכי עבודה מרובי-שלבים.
- שכבת זיכרון: שילוב של Memory Bank מאפשר לסוכן ללמוד ולזכור את העדפות הסגנון של המשתמש.
2. הגדרה
כדי להפעיל את סוכני ה-AI שלנו, אנחנו צריכים שני דברים: פרויקט ב-Google Cloud שיספק את הבסיס.
חלק ראשון: הפעלת החשבון לחיוב
- כדי לממש את הזיכוי של 5 דולר בחשבון לחיוב, תצטרכו אותו לפריסה. חשוב לוודא שאתם מחוברים לחשבון Gmail.
חלק שני: סביבה פתוחה
- 👈 לוחצים על הקישור הזה כדי לעבור ישירות אל Cloud Shell Editor
- 👉 אם מתבקשים לאשר בשלב כלשהו היום, לוחצים על אישור כדי להמשיך.
- 👈 אם הטרמינל לא מופיע בחלק התחתון של המסך, פותחים אותו:
- לוחצים על הצגה.
- לוחצים על Terminal (מסוף)
.
- 👈💻 בטרמינל, מוודאים שכבר עברתם אימות ושהפרויקט מוגדר למזהה הפרויקט שלכם באמצעות הפקודה הבאה:
gcloud auth list - 👈💻 משכפלים את פרויקט ה-bootstrap מ-GitHub:
git clone https://github.com/cuppibla/holiday_workshop - 👈💻 מריצים את סקריפט ההגדרה מהספרייה של הפרויקט.
cd ~/holiday_workshop ./init.sh - 👈💻 מגדירים את מזהה הפרויקט הנדרש:
gcloud config set project $(cat ~/project_id.txt) --quiet
חלק שלישי: הגדרת הרשאות
- 👉💻 מפעילים את ממשקי ה-API הנדרשים באמצעות הפקודה הבאה. היא עשויה להימשך כמה דקות.
gcloud services enable \ cloudresourcemanager.googleapis.com \ servicenetworking.googleapis.com \ run.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com - 👉💻 מעניקים את ההרשאות הנדרשות על ידי הרצת הפקודות הבאות בטרמינל:
. ~/holiday_workshop/set_env.sh
שימו לב שנוצר לכם קובץ .env. יוצג מידע על הפרויקט.
3. שיפור היכולות באמצעות MCP
התקופה שבה AI הפך ל-USB-C
תארו לעצמכם שבכל פעם שקונים עכבר חדש, צריך להלחים אותו ללוח האם. זה היה המצב של כלי AI עד לאחרונה. מפתחים נאלצו לכתוב קוד דבק מותאם אישית כדי לחבר מודלים של שפה גדולה למסדי נתונים, למערכות קבצים או לממשקי API.
מזינים את Model Context Protocol (MCP). אפשר לחשוב על MCP בתור יציאת USB-C לאפליקציות AI. הוא מספק דרך סטנדרטית לחבר מודלים של AI למקורות נתונים ולכלים.
אם תבנו שרת MCP לכלים שלכם פעם אחת, תוכלו לחבר אותו ל-Gemini CLI, ל-IDE או לכל לקוח אחר שתואם ל-MCP בלי לשנות אף שורת קוד.
מה תפַתחו
בשיעור הזה תלמדו איך ליצור עוזר לעיצוב חגים שיכול:
- מתחבר לסביבה המקומית (כלים של סטודיו) באמצעות MCP.
- ניהול אמין של הקשר בשיחה באמצעות ערכת פיתוח הסוכנים (ADK).
- לזכור את ההעדפות שלכם (למשל, "אני מעדיף קוד Python") בסשנים שונים באמצעות Vertex AI Memory Bank.
בניית הלוגיקה של השרת
הכנו את הסביבה, אבל הלוגיקה של השרת לא הושלמה. אנחנו צריכים להטמיע את ארבעת הכלים הספציפיים שהסוכן שלנו ישתמש בהם בסופו של דבר כדי ליצור את כרטיס החג.
חלק ראשון: פותחים את תבנית השרת
אנחנו נעבוד בספרייה 01-MCP-Files-Testing/01-starter.
- בטרמינל של Cloud Shell, מוודאים שאתם נמצאים בספרייה הנכונה:
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/ - פותחים את הקובץ ב-Cloud Shell Editor באמצעות הפקודה:
cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
אפשר לראות שקוד ה-boilerplate (הגדרת שרת ה-MCP, טיפול בחיבורים ואתחול לקוח Vertex AI) כבר בוצע. עם זאת, ארבע פונקציות הליבה הן כרגע ערכי פלייסהולדר ריקים.
חלק שני: הטמעה של כלי ליצירת סצנות לחגים
קודם כול, אנחנו צריכים כלי שיקבל את ההתעניינות של המשתמש (למשל, 'ציפורים') והופך אותה להנחיה עשירה ומפורטת שעברה אופטימיזציה ליצירת תמונות.
מאתרים את התגובה #REPLACE_GENERATE_HOLIDAY_SCENE בתוך הפונקציה generate_holiday_scene.
מחליפים את כל השורה הזו בקוד הבא:
prompt = (
f"""
Create a cozy, high-fidelity 3D render of a winter holiday scene.
The scene should be warm and inviting with soft cinematic lighting.
Seamlessly integrate the following specific theme/interest into the
holiday decor or landscape: {interest}.
The style should be whimsical but detailed.
Aspect Ratio: 16:9 Landscape.
"""
)
generate_image(prompt, "16:9", "static/generated_scene.png")
return "Done! Saved at generated_scene.png"
חלק שלישי: הטמעת התוצאה הסופית של התמונה
בסיום, אנחנו רוצים לוודא שהתאורה והסגנון נראים פוטוריאליסטיים וחגיגיים.
מאתרים את התגובה #REPLACE_GENERATE_FINAL_PHOTO.
מחליפים את כל השורה הזו בקוד הבא כדי לבצע את העברת הסגנון והעיבוד הסופיים:
prompt = (
"""
Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
Lighting: Warm, glowing ambient light from a fire below (out of frame).
Background: Softly blurred (bokeh) pine garland and twinkling lights.
Foreground Composition:
1. A wooden picture frame containing the [attached selfie image].
The face in the photo must be clearly visible.
2. A folded holiday greeting card standing upright next to the frame.
The front of the card displays the [attached holiday scene image] as a print.
Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
"""
)
generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
return "Done! Saved at generated_final_photo.png"
הגדרת הסביבה
אחרי שהקוד מוטמע, צריך לוודא שיחסי התלות שלנו מותקנים. נשתמש ב-uv, מנהל פרויקטים וחבילות Python מהיר.
👉💻 בטרמינל, מריצים את הפקודה הבאה כדי להוסיף את FastMCP כתלות של הפרויקט:
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp
תראו שתלות חדשה fastmcp>=2.13.3 נוספה לקובץ ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml.
4. בדיקה באמצעות Gemini CLI לשרת MCP
עכשיו, אחרי שסיימנו לכתוב את קוד השרת, איך בודקים אותו?
בדרך כלל, כדי לבדוק שרת backend צריך לבנות ממשק משתמש frontend או לכתוב בקשות curl מורכבות. אבל כאן אפשר להשתמש ב-Gemini CLI.
התכונה הזו שימושית מאוד לפיתוח כי היא מבודדת את הלוגיקה. אתם יכולים לוודא שהמודל מבין את הכלים שלכם וקורא להם בצורה נכונה לפני שאתם מתחילים לדאוג לגבי בניית ממשק אינטרנט או מסגרת של סוכן.
חיבור והפעלה
נשתמש בפקודה mcp add כדי להנחות את Gemini CLI לנהל את השרת שלנו.
בטרמינל, מריצים את הפקודה:
gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
-
add holidays: נתנו לשרת שלנו כינוי ("חגים"). -
uv run ...: סיפקנו את הפקודה המפורשת להפעלת שרת Python ששינינו זה עתה.
קדימה, נתחיל ליצור?
עכשיו, מתחילים את שיחת הצ'אט:
gemini
כדי לבדוק אם Gemini יכול 'לראות' את הכלים החדשים, אפשר לנסות את ההנחיה הבאה. שימו לב: יכול להיות שתצטרכו לאשר ל-Gemini CLI להשתמש בכלי החגים שלנו.
- 👉 User:
"I want to create a festive holiday photo. I like birds a lot." - Gemini:
*Thinking...* *Calling tool: generate_holiday_scene(interest='birds')* Done! Saved at generated_scene.png - 👉 User:
"Great! Now generate a knitting pattern for a sweater with reindeer on it." - Gemini:
*Thinking...* *Calling tool: generate_sweater_pattern(motif='reindeer')* Done! Saved at generated_pattern.png
בדיקת התמונה
- מקישים על
Control+Cכדי לסיים את השימוש ב-Gemini CLI. - בודקים את התמונה שנוצרה בתיקייה:
~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.
כאן אפשר לראות את התמונה: 
סיכום והשלבים הבאים
מעולה! יצרתם בהצלחה שרת MCP תקין. עכשיו יש לכם קבוצה פונקציונלית של 'כלים מבוססי-AI' שיכולים ליצור דפוסים, תמונות מורכבות ולשפר סצנות.
עם זאת, האם שמת לב למשהו בבדיקה שלמעלה? אתם הייתם צריכים להוביל את התהליך. היית צריך לבקש את הסצנה, ואז לבקש את התבנית, ואז לבקש לשלב ביניהם.
Gemini הוא כלי חכם, אבל כדי ליצור תהליך עבודה מורכב – שבו אנחנו צריכים ליצור דוגמה לפני שאנחנו יכולים להוסיף אותה לסוודר, ולטפל בשגיאות אם יצירת התמונה נכשלת – אנחנו רוצים יותר שליטה. אנחנו רוצים מערכת ייעודית שתתכנן את כרטיס החג, תבקר את העבודה שלה ותנהל את המצב שלו, בלי שנצטרך להנחות אותה בכל שלב.
בקטע הבא נסביר איך אפשר להשתמש בנתונים האלה כדי להפיק תובנות. אנחנו מתכוונים להטמיע את ערכת פיתוח הסוכנים (ADK) כדי ליצור סוכן מובנה שמארגן את כלי ה-MCP האלה לצינור הפקה מושלם.
5. תכנות בשיטת Vibe coding של סוכן ADK
יש לנו מערך כלים פעיל (השרת שלנו לניהול מרכזי של הרשאות), אבל כרגע אנחנו אלה שמבצעים את כל העבודה הקשה – אנחנו אומרים ל-Gemini בדיוק לאיזה כלי להתקשר ומתי.
בקטע הזה נבנה סוכן AI: מערכת שיכולה להסיק מסקנות, לתכנן ולבצע משימות מרובות שלבים באופן אוטונומי. לשם כך, נשתמש בערכת פיתוח סוכנים (ADK).
מה זה סוכן?
אם כלי ה-MCP הם ה "ידיים" (שמבצעות את העבודה), הסוכן הוא ה "מוח". סוכן משתמש ב-LLM כדי להבין את כוונת המשתמש ("צור לי כרטיס לחג"), מפרק אותה לשלבים ("קודם צריך סצנה, אחר כך דוגמה...") ומחליט באילו כלים להשתמש כדי להשיג את המטרה.
מה זה ADK?
ערכת פיתוח הנציגים (ADK) היא מסגרת של Google שמאפשרת ליצור את הנציגים האלה בקלות. הוא מטפל ב'אינסטלציה' המורכבת, כמו ניהול היסטוריית הצ'אט, חיבור לכלים ומעבר בין מודלים שונים – כך שאתם יכולים להתמקד באישיות ובלוגיקה של האפליקציה.
תכנות בשיטת Vibe coding מבוססת-הקשר
דפוס נפוץ הוא שימוש בהנחיה אחת גדולה כדי ליצור קוד. עם זאת, כשמפתחים אפליקציות מורכבות, עדיף להתייחס ל-AI כאל שותף ששומר על הקשר לאורך זמן.
נשתמש בתכונות הזיכרון של Gemini CLI כדי להכין את הקרקע לפני שכותבים שורה אחת של קוד.
1. הכנת הסביבה
פותחים את הטרמינל ועוברים לספריית ההתחלה:
cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter
מפעילים את Gemini CLI:
gemini
2. ניהול ההקשר והזיכרון
כשמבצעים קידוד של אווירה, ה-AI צריך לדעת מי הוא ומה הוא יודע. Gemini CLI מאפשר לנו לנהל את זה באופן מפורש.
-
/memory show: הקלידו את הטקסט הזה כדי לראות מה ה-AI יודע כרגע על הפרויקט והסשן שלכם. -
/memory add: משתמשים בזה כדי להוסיף ידע בסיסי שה-AI צריך לזכור לאורך השיחה.
נתחיל בהגדרת פרסונה של שותף התכנות שלנו. מריצים את הפקודה הבאה ב-Gemini CLI:
/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."
Gemini מבין עכשיו את התפקיד שלו. ההקשר הזה ישפיע על כל תשובה שתתקבל בהמשך, ויבטיח קוד איכותי שתואם ל-ADK.
3. שלב 1: קידוד האווירה של הסוכן הבסיסי
במקום לנסות ליצור את כל המערכת בבת אחת, נתחיל עם השלד. אנחנו רוצים להגדיר את מבנה הקבצים ואת האישיות הבסיסית של הסוכן.
מזינים את ההנחיה הבאה ב-Gemini CLI:
Let's start by building the basic agent structure.
Please create a file structure for a `root_agent`.
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant".
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.
Gemini ייצור את מבנה הקובץ ואת קוד ה-Python הראשוני. בודקים שהשינויים נראים נכון ואז מאשרים אותם.
4. שלב 2: הוספת שרת ה-MCP (הכלים)
עכשיו, אחרי שיצרנו סוכן בסיסי, אנחנו צריכים לתת לו "ידיים". אנחנו צריכים לחבר את הסוכן לשרת ה-MCP שבנינו במעבדה הקודמת.
מזינים את ההנחיה הבאה ב-Gemini CLI:
Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.
Gemini יבצע עכשיו רפקטורינג של agent.py הקיים כדי לכלול את הגדרות כלי ואת לוגיקת החיבור.
הערה: אם רוצים לבדוק את העבודה או אם הקוד שנוצר לא פועל כמצופה, אפשר להשוות את הקבצים לפתרון הייחוס שנמצא בכתובת: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution
6. הפעלת ממשק האינטרנט של הסוכן
ערכת ה-ADK כוללת ממשק בדיקה מובנה שנקרא adk web. כך נפתח ממשק משתמש קל משקל לצ'אט, כדי שנוכל לדבר עם הנציג שלנו באופן מיידי.
- אם GeminiCLI עדיין פתוח, מקישים על
control+Cכדי לסגור אותו. עכשיו במסוף(בתיקייהsolution, אפשר לעבור לתיקייהstarterכדי לבדוק את הקוד על ידי הפעלת הפקודהuv run adk webבתיקייהstarter), מריצים את הפקודה:cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution uv run adk web --port 8000 - תופיע התראה ב-Cloud Shell על כך ששירות פועל ביציאה 8000. לוחצים על תצוגה מקדימה באינטרנט -> תצוגה מקדימה ביציאה 8000.
בדיקת הנציג
עכשיו אמור להופיע ממשק צ'אט. נבדוק אם הסוכן שלנו פועל לפי ההוראות החדשות ומקבל גישה לכלים של MCP בצורה נכונה.
הנחיות לדוגמה:
- "היי! מי אתה?"
- (צריך לצפות לתגובה חגיגית ונלהבת).
- "אני צריך רקע לכרטיס החג שלי. תצור כפר מושלג".
- (הנציג צריך להתקשר אל
generate_holiday_scene. שימו לב שהסגנון 'חמוד/מצויר' שהוגדר בהוראות המערכת מוחל באופן אוטומטי).
- (הנציג צריך להתקשר אל
- "Generate a sweater pattern with little pizza slices on it.
- (הנציג צריך להתקשר אל
generate_sweater_pattern).
- (הנציג צריך להתקשר אל
כאן אפשר לראות את התמונה שנוצרה:
אם מסיימים את הבדיקה, לוחצים על Control+C כדי לצאת.
סיכום והשלבים הבאים
הצלחתם להשתמש בגישה מודעת-הקשר כדי להשתמש ב-Vibe-Code בסוכן ADK של Google!
- יצרנו הקשר: השתמשנו ב-
/memory addכדי להגדיר פרסונה של מומחה. - בנינו את Iteratively: יצרנו קודם את המסגרת, ואז הוספנו את החיבורים לכלי.
התצוגה המקדימה המובנית של ADK באינטרנט מצוינת לבדיקות, אבל למוצר הסופי אנחנו רוצים חוויה מותאמת אישית עם מיתוג. בקטע הבא נסביר איך לשלב את הסוכן הזה בחלק הקדמי של אתר אינטרנט בהתאמה אישית.
7. חיבור ADK באמצעות ממשק משתמש
עכשיו, אחרי שיש לנו הגדרה של סוכן, אנחנו צריכים להפעיל אותו. כאן נכנסים לתמונה Runner וSession Service.
הטמעה
- 👈 מקלידים את הפקודה הבאה:
cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.pyבכלי העריכה. - מחליפים את
# TODO: Create Session Serviceבערכים הבאים:from google.adk.sessions import InMemorySessionService from google.adk.memory import InMemoryMemoryService session_service = InMemorySessionService() memory_service = InMemoryMemoryService() - מחליפים את
# TODO: Initialize Runnerבערכים הבאים:runner = Runner( app_name="agents", agent=christmas_agent, session_service=session_service, memory_service=memory_service, )
- בדיקת שורה 158 ב
~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(אין צורך בפעולה): אם אתם רוצים לדעת איך האפליקציה מקבלת את התגובה הסופית. למטה מוצג לולאת אירועים שמופעלת על ידי runner:async for event in runner.run_async( user_id=user_id, session_id=session_id, new_message=content )
ירידה לפרטים: ארכיטקטורה ופריסה
אנחנו משתמשים ב-FastAPI כדי להציג את הסוכן הזה.
- למה FastAPI?: סוכנים הם לעיתים קרובות מוגבלים על ידי קלט/פלט (המתנה למודלים גדולים של שפה). התכונה האסינכרונית של FastAPI מטפלת בזה בצורה מושלמת.
- חוסר מצב: שימו לב שנקודת הקצה (endpoint) של ה-API היא חסרת מצב. אנחנו לא שומרים משתנים בהיקף גלובלי. אנחנו מסתמכים על
session_idועלSessionServiceכדי לשחזר את המצב של כל בקשה. המשמעות היא שאפשר לפרוס את זה ב-Cloud Run (Serverless) ולשנות את קנה המידה לאפס.
8. איך משתמשים באפליקציה עם הקסם של הסוכן
- 👈💻 מקלידים את הפקודה הבאה:
cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter ./start_app.sh~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.pyבכלי העריכה. - התוצאה תיראה כך:
👈👈 חשוב ללחוץ על http://localhost:5173/או לפתוח חלון חדש ולהקלידhttp://localhost:5173/. - לאחר מכן האתר ייפתח עם ממשק הצ'אט:
- בודקים את התמונה באמצעות העלאה של תמונה אחת(שלכם או של חיית המחמד שלכם)
- 👈 ואז שואלים
Can you generate a picture my cat wearing snowflake pattern sweater?
- 👈💻 בסיום הבדיקה, מקישים על
control+Cבמסוף כדי לסיים את התהליך.
אם אתם לא רואים שהדברים פועלים כצפוי, אתם יכולים לעבור אל ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution, להריץ את ./start_app.sh ולבצע את אותם השלבים כמו למעלה.
9. Vertex AI Memory Bank
זיכרון לטווח קצר לעומת זיכרון לטווח ארוך
- הקשר לטווח קצר: "What did I just say?" (מה אמרתי עכשיו?) (היסטוריית הסשנים). ההיסטוריה הזו נמחקת כשחלון הצ'אט נסגר.
- זיכרון לטווח ארוך: "What is my favorite programming language?" (העדפות משתמש). הערך הזה צריך להישאר קבוע.
Vertex AI Memory Bank מספק את האחסון לטווח ארוך. הוא מאפשר לסוכן לאחסן ולאחזר מידע מותאם אישית על המשתמש.
סשנים לעומת Memory Bank
- סשנים (
VertexAiSessionService): זהו היומן. הוא מאחסן את הרצף הגולמי והכרונולוגי של כל הודעה, קריאה לכלי ואירוע (AppendEvent,ListEvents). הוא מספק את האמת הבסיסית לגבי מה קרה. - Memory Bank (
VertexAiMemoryBankService): זהו הידע. הוא מאחסן עובדות מסונתזות לטווח ארוך (GenerateMemories,RetrieveMemories). הוא מוגבל ל-user_idספציפי, כדי להבטיח פרטיות ובידוד.
- 👈💻 מקלידים את הפקודה הבאה:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.pyבכלי העריכה. - מחפשים את
# TODO: Create Vertex AI Session Service & Memory Bank Serviceומחליפים את השורה כולה בטקסט הבא: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 )
- 👈💻 מקלידים את הפקודה הבאה:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.pyבכלי העריכה. - מחליפים את
# TODO: Set Up Configurationבערכים הבאים:# Basic configuration types MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig SimilaritySearchConfig = ( types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig ) GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig # Advanced configuration types CustomizationConfig = types.MemoryBankCustomizationConfig MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample ConversationSource = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource ) ConversationSourceEvent = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent ) ExampleGeneratedMemory = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory )
- 👉 באותו קובץ:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. מחפשים את# TODO: Set up topic, מחליפים את השורה כולה בשורה הבאה:custom_topics = [ # Topic 1: Sweater Preference MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="sweater_preference", description="""Extract the user's preferences for sweater styles, patterns, and designs. Include: - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.) - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted) - Color preferences (red, green, navy, pastel, etc.) - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft) - Themes (retro, modern, ugly christmas sweater, elegant) Example: "User wants a retro style sweater with a pixelated reindeer pattern." Example: "User prefers dark blue colors and hates itchy wool." """, ) ), # Topic 2: Personal Context MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="personal_context", description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include: - Hobbies and activities (skiing, reading, gaming, cooking, etc.) - Pets (type, breed, name, color) - Job or profession if relevant to their style - General interests (sci-fi, nature, vintage, tech) - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach) Example: "User has a golden retriever named Max." Example: "User loves skiing and wants a snowy mountain background." Example: "User is a software engineer who likes cyberpunk aesthetics." """, ) ) ] - 👉 באותו קובץ:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. מחפשים את# TODO: Create Agent Engineומחליפים את השורה כולה בשורה הבאה:agent_engine = client.agent_engines.create( config={ "display_name": AGENT_DISPLAY_NAME, "context_spec": { "memory_bank_config": { "generation_config": { "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash" }, "customization_configs": [customization_config] } }, } )
למה לא להשתמש רק בהנחיה?
יכול להיות שתשאלו: "למה שלא פשוט נדביק את ההיסטוריה של המשתמש בהנחיה?"
- מגבלות גודל: חלונות ההקשר גדולים, אבל לא אינסופיים. אי אפשר להציג היסטוריה של 5 שנים.
- עלות: העיבוד של מיליון טוקנים לכל 'שלום' הוא יקר מדי.
- מיקוד: Memory Bank פועל כמנוע חיפוש עבור הסוכן שלכם. הוא מאחזר רק את העובדות הרלוונטיות.
- 👈💻 מקלידים את הפקודה הבאה:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pyבכלי העריכה. - בקובץ:
~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pyמחליפים את# TODO: Add PreloadMemoryToolבטקסט הבא:if USE_MEMORY_BANK: agent_tools.append(PreloadMemoryTool())
PreloadMemoryTool וadd_session_to_memory
בכרטיסייה agent.py מוצגים שני רכיבים עיקריים:
-
PreloadMemoryTool: זהו כלי שמאפשר לסוכן "לחפש את עצמו ב-Google". אם המשתמש שואל שאלה לא ברורה כמו "תביא לי את הקפה הרגיל שלי", הסוכן יכול להשתמש בכלי הזה כדי לשאול את מאגר הזיכרון על "העדפות קפה" לפני שהוא עונה. -
add_session_to_memory: זו קריאה חוזרת ברקע.- למה אסינכרוני? שמירת הזיכרון לוקחת זמן (סיכום הצ'אט, חילוץ עובדות). אנחנו לא רוצים שהמשתמש יחכה לזה. אנחנו מריצים אותו ברקע (
add_session_to_memory) באמצעותafter_agent_callback.
- למה אסינכרוני? שמירת הזיכרון לוקחת זמן (סיכום הצ'אט, חילוץ עובדות). אנחנו לא רוצים שהמשתמש יחכה לזה. אנחנו מריצים אותו ברקע (
10. Memory Bank In Action
- 👈💻 מקלידים את הפקודה הבאה:
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./use_memory_bank.sh
בודקים את הקובץ ~/holiday_workshop/.envורואים את ההודעה (לא נדרשת פעולה)USE_MEMORY_BANK=TRUE AGENT_ENGINE_ID={agent_engine_id} - 👈💻 בדיקת הזיכרון באמצעות ממשק המשתמש של האפליקציה. מקלידים את הפקודה הבאה:
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./start_app.shhttp://localhost:5173/או פותחים חלון חדש ומקלידיםhttp://localhost:5173/.שימו לב ש-Uvicorn running on http://0.0.0.0:8000הוא רק שרת בק-אנד, ולא הקישור שאנחנו רוצים ללחוץ עליו.עכשיו ממשק הצ'אט באתר הוא הסוכן שלכם בהתאמה אישית! - 👈בודקים את הזיכרון. אם מקלידים בממשק המשתמש:
I want a sweater that matches my dog. He's a golden retriever.I'm a programmer, so I want something geeky. Maybe a matrix style?I like snowflake sweater pattern
הסוכן יזהה את זה כהעדפה וישמור אותה בבנק הזיכרון.
בשבוע הבא(או בכל פעם שתפעילו מחדש את האפליקציה באמצעות Control+C ו-./start_app.sh), אם תשאלו:
what is my preference on sweater pattern?
הסוכן יחפש בMemory Bank, יראה את ההעדפה שלכם ויצור דוגמה לסוודר בלי שתצטרכו לבקש. 
- כדי לאמת ב-Vertex AI Agent Engine, עוברים אל מסוף Google Cloud Agent Engine
- חשוב לבחור את הפרויקט מהתפריט לבחירת הפרויקט בפינה הימנית העליונה:
- מאמתים את מנוע הנציג שפרסתם באמצעות הפקודה הקודמת
use_memory_bank.sh
לוחצים על מנוע הנציג שיצרתם.
- חשוב לבחור את הפרויקט מהתפריט לבחירת הפרויקט בפינה הימנית העליונה:
- לוחצים על הכרטיסייה
Memoriesבסוכן שהופעל כדי לראות את כל הזיכרון.
מעולה! הרגע צירפת את בנק הזיכרון לסוכן שלך!
11. סיכום
סיכום
יצרתם בהצלחה ארכיטקטורה ובניתם מערכת מלאה של סוכנים.
- קישוריות: השתמשתם ב-MCP כדי לקבוע תקן לגישה של הסוכן לכלים מקומיים.
- אורקסטרציה: השתמשתם ב-ADK כדי לנהל את לולאת ההסקה המורכבת שנדרשת למשימות מרובות שלבים.
- התאמה אישית: השתמשתם ב-Memory Bank כדי ליצור שכבת למידה מתמשכת שזוכרת את ההקשר של המשתמש.
השלבים הבאים
- יצירת שרת MCP משלכם: יצירת שרת לממשק API או למסד נתונים פנימיים.
- עיון בתבניות של ADK: מידע על 'לולאות נימוקים' ו'ניהול' בתיעוד של ADK.
- פריסה: מעבירים את הסוכן מסקריפט מקומי לשירות ייצור ב-Cloud Run.