1. מבוא
The Modern Agent Stack
כדי ליצור סוכן AI ברמת ייצור, צריך יותר ממודל שפה גדול (LLM). מודל שפה גדול מספק את יכולות החשיבה הרציונלית, אבל כדי שהסוכן יהיה חזק הוא צריך לבצע אינטראקציה עם העולם החיצוני, לנהל את מצב השיחה ולזכור את העדפות המשתמש לאורך זמן.
בסדנה הזו תלמדו איך לתכנן ולבנות מערכת מקיפה מבוססת-סוכנים באמצעות שלוש טכנולוגיות בסיסיות:
- קישוריות (MCP): כדי לתת לסוכן גישה לכלים ולנתונים מקומיים.
- תזמור (ADK): לניהול לולאת חשיבה רציונלית והמצב של הסוכן.
- זיכרון (Memory Bank): כדי לספק הקשר מותאם אישית לטווח ארוך.
מושגי ליבה
רכיב | פונקציה |
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 שיספק את הבסיס.
חלק ראשון: הפעלת החשבון לחיוב
כדי להריץ את ה-codelab הזה, צריך חשבון לחיוב עם קרדיט. כדי להתחיל, משתמשים בקרדיטים שמופיעים בבאנר בחלק העליון של ה-codelab. אם כבר קישרתם חשבון לחיוב, אתם יכולים לדלג על השלב הזה.
חלק שני: סביבה פתוחה
- 👈 לוחצים על הקישור הזה כדי לעבור ישירות אל 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 עד לאחרונה. מפתחים נאלצו לכתוב קוד מותאם אישית כדי לחבר מודלים של LLM למסדי נתונים, למערכות קבצים או לממשקי API.
מזינים את Model Context Protocol (MCP). אפשר לחשוב על MCP כיציאת USB-C לאפליקציות AI. הוא מספק דרך סטנדרטית לחבר מודלים של AI למקורות נתונים ולכלים.
אם יוצרים שרת MCP לכלים פעם אחת, אפשר לחבר אותו ל-Gemini CLI, ל-IDE או לכל לקוח אחר שתואם ל-MCP בלי לשנות אף שורת קוד.
מה תפַתחו
ב-Codelab הזה תלמדו איך ליצור עוזר לעיצוב חגים שיכול:
- מתחבר לסביבה המקומית (כלים לסטודיו) באמצעות 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) כבר בוצע. עם זאת, ארבע פונקציות הליבה הן כרגע placeholders ריקים.
חלק שני: הטמעה של כלי ליצירת סצנות לחגים
קודם כל, אנחנו צריכים כלי שלוקח את תחומי העניין של המשתמש (למשל, 'ציפורים') והופך אותם להנחיה עשירה ומפורטת שעברה אופטימיזציה ליצירת תמונות.
מאתרים את התגובה #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
בדיקת התמונה
- כדי לסיים את השימוש ב-Gemini CLI, מקישים על
Control+C. - בודקים את התמונה שנוצרה בתיקייה:
~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.
כאן אפשר לראות את התמונה: 
סיכום והשלבים הבאים
מעולה! יצרתם בהצלחה שרת MCP תקין. עכשיו יש לכם קבוצה פונקציונלית של 'כלים מבוססי-AI' שיכולים ליצור דפוסים, לשלב תמונות ולשפר סצנות.
עם זאת, האם שמת לב למשהו בבדיקה שלמעלה? היית צריך להוביל את התהליך. היית צריך לבקש את הסצנה, ואז לבקש את התבנית, ואז לבקש לשלב אותם.
Gemini הוא כלי חכם, אבל כדי ליצור תהליך עבודה מורכב – שבו צריך ליצור דוגמה לפני שאפשר להדפיס אותה על סוודר, ולטפל בשגיאות אם יצירת התמונה נכשלת – אנחנו רוצים יותר שליטה. אנחנו רוצים מערכת ייעודית שתדע לתכנן, לבקר את העבודה שלה ולנהל את המצב של כרטיס החג שלנו בלי שנצטרך להנחות אותה בכל שלב.
בקטע הבא נסביר איך אפשר להשתמש בנתונים האלה כדי להפיק תובנות. אנחנו נטמיע את הערכה לפיתוח סוכנים (ADK) כדי ליצור סוכן מובנה שמתאם בין כלי ה-MCP האלה לפייפליין הפקה מושלם.
5. תכנות סוכן ADK בשיטת Vibe coding
יש לנו מערך כלים פעיל (שרת ה-MCP שלנו), אבל כרגע אנחנו אלה שמבצעים את כל העבודה הקשה – אנחנו אומרים ל-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 כדי לצאת.
סיכום והשלבים הבאים
הצלחתם 'לקודד את האווירה' של סוכן 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 מטפלת בזה בצורה מושלמת.
- חוסר מצב: שימו לב שנקודת הקצה ל-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 שפת תכנות?" (העדפות משתמש). ההגדרה הזו אמורה להישמר לנצח.
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". אם המשתמש שואל שאלה כללית כמו "תביא לי את הקפה הרגיל שלי", הסוכן יכול להשתמש בכלי הזה כדי לשלוח שאילתה ל-Memory Bank על "העדפות קפה" לפני שהוא עונה. -
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
הסוכן יזהה את זה כהעדפה ויאחסן אותה ב-Memory Bank.
בשבוע הבא(או בכל פעם שתפעילו מחדש את האפליקציה באמצעות 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.