תבנית ADK Agentic עם זיכרון ו-MCP

1. מה תלמדו

ברוכים הבאים לשיעור המתקדם בנושא ADK – המסע שלכם אל מערכות מרובות סוכנים

אתם עומדים להיכנס לעולם המלהיב של סוכני AI. שכחו מבוטים פשוטים שרק עונים על שאלות. אנחנו מתעמקים ב-Agent Development Kit (ADK) כדי לבנות מערכות מתוחכמות ואוטונומיות שיכולות להסיק מסקנות, לתכנן ולהשתמש בכלים כדי לבצע משימות מורכבות.

ה-Codelab הזה הוא מסע מעשי, והוא כולל מאגר GitHub אחד שמכיל את כל הקוד והדוגמאות לתרגולים שלנו. מאגר GitHub

בסוף המדריך הזה, תוכלו:

• יצירת סוכן AI ראשון: מדריך ליצירת סוכן פונקציונלי לחלוטין שיכול להבין את הצרכים של המשתמש, להשתמש בכלים כמו חיפוש Google וליצור תשובות מפורטות ומועילות.
• יצירת מערכות מרובות סוכנים: תוכלו ללמוד על התבנית 'סוכן ככלי', קונספט חדשני שבו סוכנים מעבירים משימות לסוכנים מומחים אחרים, ויוצרים צוות של מומחי AI שעובדים יחד.
• ארגון תהליכי עבודה מורכבים: מעבר להקצאת משימות פשוטה, אפשר להשתמש בדפוסים מתקדמים כמו נתבים, שרשרות רציפות, לולאות וביצוע מקביל כדי ליצור אפליקציות חזקות, יעילות וחכמות שיכולות לטפל כמעט בכל בקשה.
• איך נותנים לסוכנים זיכרון: הסבר על התפקיד החשוב של זיכרון שיחות, שמאפשר לסוכנים לטפל בשאלות המשך, ללמוד ממשוב ולנהל משימות מורכבות בצורה חלקה.
• חיבור באמצעות MCP: חיבור באמצעות MCP Toolbox.

קדימה, מתחילים! 🚀

2. הגדרה: קבלת מפתח API

הגדרת מפתח Google AI Studio API

השיעור הזה מבוסס כולו על מפתח API בחינם של Google AI Studio. לא נדרשים פרויקט Google Cloud, חשבון לחיוב או קרדיטים – כל סשן, כולל Memory (סשן 6) ו-MCP (סשן 7), מופעל באופן מקומי מול המפתח שלכם. כל תלמיד משתמש במפתח משלו, כך שהמכסה של ה-API היא לכל אדם ולא משותפת.

מה צריך:

• ‫Python 3.9 ואילך (python3 --version כדי לבדוק)
• חשבון Google (כדי ליצור את המפתח של AI Studio)
• טרמינל – אפשר להשתמש במחשב המקומי או ב-Cloud Shell
• כ-10 דקות

כדי להפעיל את סוכני ה-AI שלנו, אנחנו צריכים מפתח Gemini API מ-Google AI Studio. זו הדרך הכי מהירה להתחיל.

שלב 1 – קבלת מפתח Gemini API מ-AI Studio (דקה אחת)

1. פותחים את הכתובת https://aistudio.google.com/app/apikey בכרטיסייה חדשה בדפדפן.
2. נכנסים באמצעות חשבון Google.
3. לוחצים על יצירת מפתח API (בפינה השמאלית העליונה).
4. תיפתח תיבת דו-שיח עם תפריט נפתח של פרויקטים:

• אם כבר יצרתם פרויקט Google: בוחרים אותו ולוחצים על יצירת מפתח API בפרויקט קיים.
• אם הוא לא מופיע ברשימה: לוחצים על יצירת פרויקט.

5. מעתיקים את מפתח ה-API שמופיע. הוא מתחיל ב-AIza... ומכיל כ-40 תווים.

✏️ מדביקים אותו במקום בטוח – תצטרכו אותו בשלב 4 בהמשך.

מתייחסים למפתח ה-API כמו לסיסמה. אל תדביקו אותו בצ'אטים גלויים לכולם, בצילומי מסך או בביצוע commit למאגר ציבורי ב-GitHub.

שלב 2 – שיבוט המאגר (דקה)

‫👈💻 פותחים את הטרמינל (או Cloud Shell) ומשכפלים את מאגר המדריך:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

שלב 3 – יצירת הסביבה הווירטואלית והתקנת התלויות

‫👈💻 יוצרים ומפעילים סביבה וירטואלית בשם .adk_env, ואז מתקינים את יחסי התלות:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

הסימן (.adk_env) אמור להופיע בתחילת שורת הפקודה של הטרמינל.

שלב 4 – 🔥 חשוב: מוסיפים את מפתח ה-API

⚠️ אל תדלגו על השלב הזה! יוצרים קובץ .env בספריית הבסיס של התיקייה adk_tutorial. קובץ אחד הזה מפעיל כל סשן בשיעור Codelab הזה – סשנים של ADK Web‏ (1 עד 5) וסשנים של זיכרון ושליטה במעבד בשורת הפקודה (6 עד 7) קוראים אותו אוטומטית.

‫👉💻 יוצרים את הקובץ .env עם המפתח (מחליפים את your_actual_api_key_here במפתח משלב 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

הפרמטר ~/adk_tutorial/.env צריך לכלול עכשיו:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

‫🚨 קריטי: מחליפים את your_actual_api_key_here במפתח ה-API בפועל משלב 1 (הוא מתחיל ב-AIza...).

‫⚠️ מוודאים שהערך של GOOGLE_GENAI_USE_VERTEXAI מוגדר ל-FALSE. הפקודה הזו אומרת ל-ADK לבצע אימות באמצעות מפתח ה-API של Google AI Studio במקום באמצעות Vertex AI.

‫✅ נקודת ביקורת: יש לכם קובץ .env במיקום ~/adk_tutorial/.env שמכיל את מפתח AIza..., וההנחיה במסוף מציגה (.adk_env). עכשיו אפשר ליצור סוכנים.

3. מפגש 1: הסוכן הראשון שלכם ב-ADK Web

פותחים את ADK Web על ידי הרצת הפקודה:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

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

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

‫👈 לאחר מכן, פותחים את הדפדפן בכתובת http://localhost:8000 כדי לגשת אל ממשק המשתמש של ADK Dev.

מריצים ב-Cloud Shell במקום באופן מקומי? בסרגל הכלים של Cloud Shell (בדרך כלל בפינה השמאלית העליונה), לוחצים על סמל תצוגה מקדימה באינטרנט, בוחרים באפשרות שינוי יציאה, מגדירים את היציאה לערך 8000 ולוחצים על שינוי ותצוגה מקדימה. ממשק המשתמש של ADK Dev ייפתח ב-Cloud Shell בכרטיסייה חדשה בדפדפן.

‫👉 טקס הזימון הושלם והסוכן פועל עכשיו. ממשק המשתמש למפתחים של ADK בדפדפן הוא החיבור הישיר שלכם ל-Familiar.

בוחרים את הסוכן הראשון בתפריט הנפתח בחלק העליון של ממשק המשתמש, בוחרים באפשרות a_single_agent.

אפשר לבחור באפשרות a_single_agent כאן:

אפשר לראות את המעקב כאן:

‫👉 בדיקת הפרומפט:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. סשן 2: סוכן תהליך העבודה: סוכן רציף, סוכן מקביל, סוכן לולאה

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

Parallel Agent

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

‫👉 בדיקת הפרומפט:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

אפשר לבחור באפשרות b2_parallel_agent כאן:

אפשר לראות את המעקב כאן:

סוכן עוקב

בוחרים את הסוכן של זרימת העבודה העקבית בתפריט הנפתח בחלק העליון של ממשק המשתמש, בוחרים באפשרות b1_sequential_agent.

‫👉 בדיקת הפרומפט:

Find a good sushi near Standford and tell me how to get there.

אפשר לבחור באפשרות b1_sequential_agent כאן:

אפשר לראות את המעקב כאן:

סוכן Loop

בוחרים את הסוכן של תהליך העבודה ב-Loop בתפריט הנפתח בחלק העליון של ממשק המשתמש, בוחרים באפשרות b3_loop_agent.

‫👉 בדיקת הפרומפט:

Plan a trip from Sunnyvale to San Francisco today.

אפשר לבחור באפשרות b3_loop_agent כאן:

אפשר לראות את המעקב כאן:

5. סשן 3: סוכן בהתאמה אישית

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

אחרי שפותחים את ממשק האינטרנט של ADK, בוחרים באפשרות c_custom_agent מהתפריט הנפתח.

‫👉 בדיקת הפרומפט:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

אפשר לבחור באפשרות c_custom_agent כאן:

אפשר לראות את המעקב כאן:

6. סשן 4: דפוס של כלי תזמור – סוכן ניתוב

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

אחרי שפותחים את ממשק האינטרנט של ADK, בוחרים באפשרות d_routing_agent מהתפריט הנפתח.

‫👉 בדיקת הפרומפט:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

אפשר לבחור באפשרות d_routing_agent כאן:

אפשר לראות את המעקב כאן:

7. סשן 5: סוכן ככלי

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

אחרי שפותחים את ממשק האינטרנט של ADK, בוחרים באפשרות e_agent_as_tool מהתפריט הנפתח.

‫👉 בדיקת הפרומפט:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

אפשר לבחור באפשרות e_agent_as_tool כאן:

אפשר לראות את המעקב כאן:

8. סשן 6: סוכן עם זיכרון לטווח ארוך

הפעולה מתבצעת באופן מלא באופן מקומי. ההפעלה הזו מאחסנת את זיכרון השיחה במסד נתונים מקומי של SQLite (בקטגוריה ~/.adk/), כך שההעדפות שלכם נשמרות גם אחרי הפעלה מחדש, בלי שנדרשים Google Cloud, חיוב או קרדיטים. הסוכן קורא את המפתח שלכם ב-AI Studio מתוך ~/adk_tutorial/.env שיצרתם בהגדרה.

‫👈💻 כדי לבדוק את הזיכרון לטווח ארוך, עוברים לתיקייה ומשתמשים ב-runner כדי להפעיל את הסוכן:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

‫👉 בדיקת הפרומפט:

I like Art and Italian food.

לאחר מכן, מסיימים את הסשן על ידי הקשה על Ctrl+C. להפעיל מחדש את הסשן:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

‫👉 בדיקת הפרומפט:

Plan a trip to San Francisco based on my preference.

‫✅ הסוכן צריך לזכור את Art and Italian food מההרצה הקודמת – זהו הזיכרון לטווח ארוך שפועל בין סשנים.

9. סשן 7: שיפור היכולות של הסוכן באמצעות MCP

הפעולה מתבצעת באופן מלא באופן מקומי. בסשן הזה מופעל שרת מקומי של MCP Toolbox שקורא מסד נתונים של SQLite מקומי (destinations.db) – לא נדרשים Google Cloud, חיוב או קרדיטים. ההורדה החיצונית היחידה היא של קובץ הבינארי של ארגז הכלים של MCP בקוד פתוח.

שלב 1: הכנת מסד הנתונים המקומי

‫👈💻 משורש המאגר, יוצרים את מסד הנתונים לדוגמה:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

הפעולה הזו יוצרת את destinations.db ב-~/adk_tutorial/.

‫⚠️ במסד הנתונים לדוגמה יש רק ארבע ערים – פריז, רומא, ניו יורק וטוקיו (סוגי אטרקציות: ציוני דרך, מוזיאון, פארק). הנחיות שמפנות לערים אחרות (למשל סן פרנסיסקו או סאניווייל) יחזירו no results (אין תוצאות) בצורה נכונה, כי השורות האלה לא קיימות. כשבודקים את הסשן הזה, צריך להשתמש בארבע הערים שלמעלה.

שלב 2: התקנה והפעלה של שרת MCP Toolbox

‫👈💻 מורידים את הקובץ הבינארי של ארגז הכלים MCP עבור מערכת ההפעלה:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

אחרי שמסיימים להוריד, ואז מפעילים

chmod +x toolbox

לא בטוחים איזה Mac יש לכם? מריצים את uname -m — arm64 = Apple Silicon, ‏ x86_64 = Intel. ב-Windows, מורידים את .../windows/amd64/toolbox.exe ומריצים אותו מ-PowerShell.

שלב 3

בטרמינל אחד מריצים את הפקודה הבאה (משאירים אותה פועלת – הסוכן מתחבר אליה בכתובת http://127.0.0.1:7001):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

בטרמינל אחר מריצים את הפקודה הבאה

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

‫👉 Test Prompts (use the cities that exist in the sample database — Paris, Rome, New York, or Tokyo):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

פתרון בעיות בסשן 7

• הודעה Connection refused (החיבור נדחה) / הסוכן לא מוצא כלים: שרת ארגז הכלים במסוף הראשון לא פועל – מפעילים אותו מחדש ומוודאים שהוא מאזין ליציאה 7001.
• כל שאילתה מחזירה תוצאות ריקות: מוודאים שהפעלתם את שלב 1 כך שקיים ~/adk_tutorial/destinations.db, ושההנחיה שלכם משתמשת באחת מארבע הערים (פריז, רומא, ניו יורק, טוקיו).
• toolbox: cannot execute binary file ב-macOS: הורדתם את גרסת ה-Linux – מריצים מחדש את שלב 2 עם OS=darwin/arm64 (Apple Silicon) או OS=darwin/amd64 (Intel).