1. מבוא
The Modern Agent Stack
כדי ליצור סוכן AI ברמת ייצור, צריך יותר ממודל שפה גדול (LLM). מודל 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
רגע ה-USB-C של ה-AI
תארו לעצמכם שבכל פעם שאתם קונים עכבר חדש, אתם צריכים להלחים אותו ללוח האם. זה היה המצב של כלי AI עד לאחרונה. מפתחים נאלצו לכתוב קוד מותאם אישית כדי לחבר מודלים של שפה גדולה למסדי נתונים, למערכות קבצים או לממשקי 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) כבר בוצע. עם זאת, ארבע פונקציות הליבה הן כרגע ערכי פלייסהולדר ריקים.
חלק שני: הטמעה של כלי ליצירת סצנות לחגים
קודם כל, אנחנו צריכים כלי שלוקח את תחומי העניין של המשתמש (למשל, 'ציפורים') והופך אותם להנחיה מפורטת ועשירה שעברה אופטימיזציה ליצירת תמונות.
מאתרים את התגובה #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
יש לנו מערך כלים פעיל (שרת ה-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 כדי ליצור קוד עם אווירה מסוימת, ה-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 שיצרנו בשיעור ה-Lab הקודם.
מזינים את הפרומפט הבא ב-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 מטפלת בזה בצורה מושלמת.
- חוסר מצב: שימו לב שנקודת הקצה (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?" (מה אמרתי עכשיו?) (היסטוריית הפעילויות). המידע הזה נעלם כשחלון הצ'אט נסגר.
- זיכרון לטווח ארוך: "מה שפת התכנות האהובה עליי?" (העדפות משתמש). הערך הזה צריך להישאר קבוע.
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
הסוכן יזהה את זה כהעדפה וישמור אותה בזיכרון.
בשבוע הבא(או בכל פעם שמפעילים מחדש את האפליקציה באמצעות Control+C ו-./start_app.sh), אם תשאלו:
what is my preference on sweater pattern?
הסוכן יבצע שאילתה במאגר הזיכרון, יראה את ההעדפה שלכם ויצור דוגמה לסוודר בלי שתצטרכו לבקש. 
- כדי לאמת ב-Vertex AI Agent Engine, עוברים אל מסוף Google Cloud Agent Engine
- חשוב לבחור את הפרויקט מהתפריט לבחירת הפרויקט בפינה הימנית העליונה:
- מאמתים את מנוע הנציג שפרסתם באמצעות הפקודה הקודמת
use_memory_bank.sh
לוחצים על מנוע הנציג שיצרתם.
- חשוב לבחור את הפרויקט מהתפריט לבחירת הפרויקט בפינה הימנית העליונה:
- לוחצים על הכרטיסייה
Memoriesבסוכן הפרוס הזה כדי לראות את כל הזיכרון.
מעולה! הרגע צירפת את בנק הזיכרון לסוכן שלך!
11. סיכום
סיכום
תכננתם ובניתם בהצלחה מערכת מלאה שמבוססת על סוכנים.
- קישוריות: השתמשתם ב-MCP כדי לקבוע תקן לגישה של הסוכן לכלים מקומיים.
- אורקסטרציה: השתמשתם ב-ADK כדי לנהל את לולאת החשיבה הרציונלית המורכבת שנדרשת למשימות מרובות שלבים.
- התאמה אישית: השתמשתם ב-Memory Bank כדי ליצור שכבת למידה מתמשכת שזוכרת את ההקשר של המשתמש.
השלבים הבאים
- יצירת שרת MCP משלכם: יצירת שרת ל-API או למסד נתונים פנימיים.
- עיון בתבניות של ADK: מידע על 'לולאות נימוקים' ו'ניהול' בתיעוד של ADK.
- פריסה: מעבירים את הסוכן מסקריפט מקומי לשירות ייצור ב-Cloud Run.