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

1. מה תלמדו

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

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

מפת הדרכים של הקורס

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

  • איך יוצרים סוכן AI ראשון: מדריך ליצירת סוכן מתפקד שיכול להבין את הצרכים של המשתמש, להשתמש בכלים כמו חיפוש Google וליצור תשובות מפורטות ומועילות.
  • שליטה בכלי מותאם אישית: כדי לחשוף את העוצמה האמיתית של הסוכנים, אפשר לחבר אותם לפונקציות ולממשקי API מותאמים אישית. תלמדו את הסוכן לאחזר נתונים בזמן אמת, כמו תחזיות מזג אוויר.
  • יצירת מערכות מרובות סוכנים: הסבר על התבנית Agent-as-a-Tool (סוכן ככלי), קונספט חדשני שבו סוכנים מעבירים משימות לסוכנים מומחים אחרים, ויוצרים צוות של מומחי AI שעובדים יחד.
  • ארגון תהליכי עבודה מורכבים: מעבר להקצאת משימות פשוטה, אפשר להשתמש בדפוסים מתקדמים כמו נתבים, שרשרות רציפות, לולאות וביצוע מקביל כדי ליצור אפליקציות חזקות, יעילות וחכמות שיכולות לטפל כמעט בכל בקשה.
  • איך נותנים לסוכנים זיכרון: הסבר על התפקיד החשוב של זיכרון שיחות, שמאפשר לסוכנים לטפל בשאלות המשך, ללמוד ממשוב ולנהל משימות מרובות שלבים בצורה חלקה.

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

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

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

כדי להפעיל את סוכני ה-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 בפרויקט קיים.
    • אם הוא לא מופיע ברשימה: לוחצים על יצירת פרויקט.

aistudio

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

✏️ מדביקים אותו במקום בטוח – תצטרכו אותו בשביל קובצי ה-notebook של Colab וההגדרה של ADK Web (בנספח).

שלב 2 – הוספת מפתח ה-API ל-Colab (דקה)

לכל מחברת יש תא הגדרה שבו מועלה מפתח ה-API. יש שתי אפשרויות – בוחרים את האפשרות המועדפת:

אפשרות א': Colab Secrets (מומלצת – המפתח נשאר מוסתר)

  1. בנוטבוק של Colab, לוחצים על סמל המפתח 🔑 בסרגל הצד השמאלי.
  2. לוחצים על הוספת סוד חדש.
  3. מגדירים את Name לערך GOOGLE_API_KEY.
  4. מדביקים את מפתח ה-API (משלב 1) בשדה Value (ערך).
  5. מעבירים את המתג 'גישה ל-Notebook' למצב מופעל.

colab secrets

כשמריצים את תא ההגדרה, המפתח יזוהה באופן אוטומטי:

✅ API key loaded from Colab Secrets.

אפשרות ב': הדבקה כשמופיעה בקשה (מהיר וקל)

אם מדלגים על Colab Secrets ומריצים ישירות את codelab1 ואת codelab2, ב-notebook תוצג הנחיה להזין סיסמה:

🔑 Enter your Google AI Studio API key: ••••••••

מדביקים את מפתח ה-API ומקישים על Enter. המפתח לא יוצג על המסך.

✅ API key entered manually.

אחרי שמריצים את התא של מפתח ה-API, התא הבא מגדיר את הסביבה:

✅ API key configured (starts with 'AIzaSy...')
✅ Using Google AI Studio (not Vertex AI).

‫✅ נקודת ביקורת: שתי ההודעות עם הסימן ✅ מופיעות למעלה במחברת. מפתח ה-API מוגדר ואפשר להתחיל ליצור סוכנים.

3. סשן 1: הסוכן הראשון שלכם עם Runner

roadmap1

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

  • סוכן: המוח המרכזי של הפעולה. ההגדרה של סוכן AI כוללת את ההוראות שלו (האישיות והמשימה שלו), את מודל ה-AI שבו הוא משתמש (כמו Gemini) ואת הכלים שהוא יכול לגשת אליהם.
  • סשן: הזיכרון של השיחה. הוא שומר את היסטוריית האינטראקציות (הודעות של משתמשים ותשובות של סוכנים), וכך מאפשר דיאלוג רציף.
  • ‫Runner: המנוע שמבצע את המשימה. הוא לוקח את הסוכן ואת הסשן, מעבד את שאילתת המשתמש החדשה ומתזמן את השלבים ליצירת תשובה.

➡️ איפה אפשר למצוא את זה ב-Notebook

‫👈 זה מתאים לתאים בקטע חלק 1: הסוכן הראשון שלך – Genie של טיול היום 🧞.🌟

רובוט סוכן קורא

  • הגדרת סוכן: מחפשים את הפונקציה create_day_trip_agent(). כאן מוגדר הסוכן. שימו לב למחרוזת ההוראות המפורטת – זו ההנחיה שמגדירה לסוכן איך להתנהג. אנחנו גם נותנים לו את הכלי הראשון שלו: חיפוש Google.
  • פונקציית עזר: כאן מוגדרת פונקציית העזר run_agent_query(). נשתמש בכלי הזה לאורך ה-notebook כדי לפשט את הרצת השאילתות.
  • הרצת בדיקה: הפונקציה run_day_trip_genie() מדמה משתמש שמבקש טיול יום "במחיר סביר" ו "מרגיע". הסוכן משתמש בהוראות ובכלי חיפוש Google כדי למצוא מיקומים מתאימים וליצור מסלול נסיעה בפורמט Markdown.

‫➡️ פעולה: בודקים את ההנחיה להוראות של day_trip_agent. אפשר לראות איך הבקשה לנסיעה במחיר סביר בשאילתת הבדיקה קשורה ישירות להנחיה של הסוכן להיות מודע לתקציב.

4. סשן 2: כלים בהתאמה אישית 🛠️

roadmap2

חיפוש Google הוא כלי רב עוצמה, אבל כדי לממש את הפוטנציאל האמיתי של סוכני AI, צריך לקשר אותם למקורות נתונים ייחודיים, לממשקי API או ללוגיקה מותאמת אישית. בקטע הזה ניצור כלי בהתאמה אישית מפונקציית Python פשוטה.

החלק הכי חשוב בכלי פונקציה הוא מחרוזת התיעוד שלו. ה-ADK מנתח באופן אוטומטי את מחרוזת התיעוד כדי להבין מה הכלי עושה, אילו פרמטרים הוא מקבל (Args) ומה הוא מחזיר (Returns). מודל השפה הגדול (LLM) קורא את התיאור הזה כדי להחליט מתי ואיך להשתמש בכלי.

➡️ איפה אפשר למצוא את זה ב-Notebook

‫👈 זה מתאים לתאים בקטע 2.1 כלי פשוט לפונקציות: קריאה ל-API של מזג אוויר בזמן אמת. 🌟

adk tools

  • הגדרת הכלי: הפונקציה get_live_weather_forecast(location: str) היא הליבה של הכלי המותאם אישית שלנו. הפונקציה מקבלת שם של עיר, קוראת ל-API הציבורי של National Weather Service (שירות מזג האוויר הלאומי) ומחזירה מילון עם הטמפרטורה והתחזית.
  • הגדרת הסוכן: הסוכן weather_agent נוצר ומצויד בכלי החדש שלנו על ידי העברת tools=[get_live_weather_forecast] במהלך האתחול שלו. ההוראות לסוכן מציינות במפורש שהוא צריך להשתמש בכלי הזה לפני שהוא מציע פעילויות בחוץ.
  • הרצת בדיקה: השאילתה "אני רוצה לצאת לטיול רגלי ליד אגם טאהו, מה מזג האוויר?" מפעילה ישירות את הסוכן לשימוש בכלי get_live_weather_forecast כי ההוראות שלו מחייבות זאת.

‫➡️ פעולה: קוראים את מחרוזת התיעוד של הפונקציה get_live_weather_forecast ואת ההוראה של weather_agent. שימו לב לקשר הישיר ביניהם.

5. סשן 3: סוכן ככלי 🧑🍳

roadmap3

למה לבנות סוכן יחיד ומונוליטי אם אפשר ליצור צוות של מומחים? תבנית Agent-as-a-Tool היא דרך יעילה לבניית מערכות מורכבות שבהן סוכן ראשי, שלרוב נקרא סוכן תזמור או נתב, מעביר משימות לסוכנים אחרים וממוקדים יותר.

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

➡️ איפה אפשר למצוא את זה ב-Notebook

‫👈 זה מתאים לתאים בקטע 2.2 סוכן ככלי: התייעצות עם מומחה 🧑🍳.🌟

נתוני הנסיעה

בדוגמה הזו נבנה סוכן מתוחכם עם כמה שכבות:

  • המומחים:
    • ‫food_critic_agent: סוכן מומחה מאוד שמספק רק הצעות למסעדות.
    • ‫db_agent: סוכן מדומה שמבצע שאילתה במסד נתונים כדי לקבל מידע על מלונות.
    • ‫concierge_agent: סוכן ברמה בינונית שמתנהג כמו קונסיירז' מנומס. חשוב לציין שהיא כוללת את food_critic_agent ככלי משלה.
  • הסוכן המרכזי (trip_data_concierge_agent): זהו הסוכן ברמה העליונה שהמשתמש מקיים איתו אינטראקציה. ההוראות שלו הופכות אותו ל'מתכנן נסיעות ראשי', והוא מקבל שני כלים שקוראים לסוכנים האחרים:
    • ‫call_db_agent: פונקציה שמפעילה את db_agent.
    • ‫call_concierge_agent: פונקציה שמפעילה את concierge_agent.
  • התהליך: הרצת הבדיקה ב-run_trip_data_concierge() מדגימה את שרשרת ההעברה המלאה.
    • משתמש מבקש מהכלי לניהול תהליכים למצוא מלון ומסעדה בקרבת מקום.
    • ההוראות של הכלי לתזמור אומרות לו להשתמש קודם בכלי call_db_agent כדי לקבל נתוני מלונות.
    • לאחר מכן, כלי התזמור משתמש בכלי call_concierge_agent כדי לקבל המלצה.
    • כשמתקבלת בקשה, concierge_agent משתמש בכלי שלו, food_critic_agent, כדי לקבל רעיון למסעדה.

התגובה של מבקר המסעדות מועברת חזרה למלצר, שמנסח אותה בצורה מנומסת ושולח אותה חזרה למנהל התזמורת, שמציג אותה למשתמש.

‫➡️ Action: עוקבים אחרי זרימת הביצוע בהרצת הבדיקה בקטע run_trip_data_concierge(). שימו לב איך בדפי ההדפסה של TOOL CALLED מוצגת שרשרת ההעברה מסוכן התיאום ועד לסוכנים המומחים. זהו רצף של פקודות.

6. סשן 4: זיכרון של סוכן 🧠

roadmap4

סוכן חכם באמת צריך לעשות יותר מאשר רק להגיב לשאילתות חד-פעמיות. הוא צריך לזכור את השיחה, להבין את ההקשר ולהתאים את עצמו למשוב. הדבר הזה מושג באמצעות ניהול תקין של הסשן. אפשר לחשוב על 'סוכן לולאה' כסוכן שמעורב בלולאה שיחתית רציפה, שמבוססת על הזיכרון שלו.

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

➡️ איפה אפשר למצוא את זה ב-Notebook

‫👈 זה מתאים לתאים בקטע חלק 3: סוכן עם זיכרון – הכלי לתכנון אדפטיבי 🗺️. 🌟

הזיכרון של הסוכן

  • הגדרת הסוכן: הפונקציה create_multi_day_trip_agent() מגדירה סוכן שנועד לתכנן נסיעה באופן הדרגתי. ההוראות מדגישות את החשיבות של זכירת ההקשר, התייחסות למשוב ותכנון של יום אחד בכל פעם.

תרחיש 3א: סוכן עם זיכרון (✅)

הבדיקה הזו מופעלת בפונקציה run_adaptive_memory_demonstration().

  • נוצרת trip_session אחת שנעשה בה שימוש חוזר בשלושה תורים רצופים.
  • תור 1: המשתמש יוזם תוכנית לטיול של יומיים.
  • תור 2: המשתמש נותן משוב ("אני לא חובב גדול של טירות"). הסוכן זוכר את תור 1, ולכן הוא מבין איזה חלק בתוכנית צריך לשנות ומציע חלופה.
  • תור 3: המשתמש מאשר את השינוי ומבקש את השלב הבא. הסוכן זוכר הכול וממשיך לתכנן את היום השני.

תרחיש 3ב: סוכן ללא זיכרון (❌)

הבדיקה הזו מופעלת בפונקציה run_memory_failure_demonstration().

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

  • פנייה 1: המשתמש מתחיל את הנסיעה בסשן_אחד. הנציג עונה בצורה נכונה.
  • פנייה 2: המשתמש מבקש לתכנן את היום השני, אבל השאילתה נשלחת בסשן חדש לגמרי, session_two. בגלל שאין היסטוריה לסשן החדש הזה, הסוכן מבולבל. יש לו אמנזיה! הוא לא יודע איזו נסיעה מתכננים.

פעולה: השוואה בין התשובות של הסוכן בשיחות run_adaptive_memory_demonstration() ו-run_memory_failure_demonstration(). זהו המושג החשוב ביותר במחברת: שיחה רציפה אחת דורשת סשן רציף אחד.

7. סשן 5: סוכן הנתבים 🚏

roadmap5

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

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

לדוגמה, שאילתה לגבי "הסושי הכי טוב" צריכה לעבור לסוכן foodie_agent, ואילו שאלה לגבי "קונצרטים בסוף השבוע הזה" צריכה להיות מטופלת על ידי weekend_guide_agent.

‫➡️ איפה אפשר למצוא את זה ב-Notebook:

‫👈 הרעיון הזה הוא מרכזי בכל המחברת, אבל הוא מוצג לראשונה בחלק 1: Multi-Agent Mayhem – Sequential Workflows 🧠→🤖→🤖 🌟

סוכן נתב

  • הגדרות של סוכנים: תא הקוד מגדיר כמה סוכנים מומחים (day_trip_agent,‏ foodie_agent,‏ transportation_agent) והכי חשוב, את router_agent. חשוב לשים לב להנחיה של router_agent, שמצוין בה במפורש להחזיר רק את השם של הסוכן הכי טוב למשימה.
  • לוגיקת הביצוע: הפונקציה run_sequential_app מדגימה איך קודם קוראים ל-router_agent כדי לקבל החלטה (chosen_route), ואז משתמשים בהחלטה הזו בבלוק if/elif כדי להפעיל את הסוכן המתאים.

8. סשן 6: SequentialAgent ⛓️

roadmap6

יש משימות שצריך לבצע בכמה שלבים בסדר מסוים. לדוגמה, "תמצא לי את הסושי הכי טוב בפאלו אלטו ואז תגיד לי איך להגיע לשם". התהליך כולל שני שלבים: קודם מוצאים את המסעדה, ואז מקבלים הוראות הגעה.

ה-ADK מספק דרך נקייה ויעילה לנהל את זה באמצעות SequentialAgent. זהו סוכן מיוחד של תהליך עבודה שמבצע רשימה של סוכני משנה בסדר מוגדר מראש.

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

‫➡️ איפה אפשר למצוא את זה ב-Notebook:

‫👈 הנושא הזה מוסבר בחלק 2 (הדרך של ADK): מהומה של כמה סוכנים עם SequentialAgent 🧠→⛓️→🤖. 🌟

סוכן עוקב

  • Agent Refactoring: בתא הקוד הראשון בקטע הזה, אפשר לראות את השינויים העיקריים ב-foodie_agent וב-transportation_agent:
    • מעכשיו ל-foodie_agent יש output_key="destination". ההוראה הזו אומרת ל-ADK לשמור את התשובה הסופית במשתנה בשם destination במצב המשותף.
    • לאפליקציה transportation_agent יש עכשיו את ה-placeholder ‏{destination} בהנחיה שלה. ערך המצב המשותף מוזרק אוטומטית ל-placeholder הזה על ידי ה-ADK.
  • הגדרת תהליך העבודה: find_and_navigate_agent מוגדר כ-SequentialAgent, והמאפיין sub_agents שלו מוגדר כ-‎[foodie_agent, transportation_agent]‎, כדי להבטיח שהם יפעלו בדיוק בסדר הזה.
  • ביצוע פשוט: אפשר לראות את הפונקציה run_sequential_app בקטע הזה. הלוגיקה המורכבת if/elif נעלמה! הקוד find_and_navigate_agent מטופל עכשיו כיחידה אחת שאפשר להפעיל, וכלי ה-ADK מטפל בשלבים הפנימיים ברצף באופן אוטומטי.

9. סשן 7: LoopAgent 🔁

roadmap7

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

לשם כך, ADK מציע את LoopAgent. סוכן זרימת העבודה הזה מפעיל שוב ושוב רצף של סוכני משנה עד שתנאי מסוים מתקיים. התכונה הזו מושלמת ליצירת סוכנים 'פרפקציוניסטים' שיכולים לתכנן, לבקר ולשפר את העבודה שלהם.

בתרשים מוצג תהליך שבו Planner Agent יוצרת תוכנית קודם. לאחר מכן, מזינים את LoopAgent. הכלי Critic Agent בודק את התוכנית. אם יש פגם, Refiner Agent יוצר גרסה חדשה והלולאה חוזרת על עצמה. אם התוכנית טובה, Refiner Agent קורא לכלי exit_loop, והתוכנית הסופית והמאומתת מוחזרת.

נציג Loop

‫➡️ איפה אפשר למצוא את זה ב-Notebook:

‫👈 כאן מוסבר איך משתמשים ב-LoopAgent כדי לפתח רעיונות בצורה איטרטיבית 🧠→🔁→🤖. 🌟

  • הסוכנים המרכזיים: תהליך העבודה משתמש ב-planner_agent, critic_agent ו-refiner_agent.
  • הגדרת הלולאה: refinement_loop מוגדר כ-LoopAgent שמנהל את critic_agent, refiner_agent ו-sets max_iterations=3.
  • תנאי היציאה: הלולאה מסתיימת כשה-critic_agent מאשר את התוכנית, וכתוצאה מכך refiner_agent קורא לכלי המותאם אישית exit_loop.

10. מפגש 8: ParallelAgent ⚡️

roadmap8

יעילות היא גורם מרכזי. אם משתמש מבקש כמה פריטי מידע לא קשורים בבת אחת, ביצוע החיפושים האלה בזה אחר זה יהיה איטי.

הפתרון הוא ParallelAgent. סוכן תהליך העבודה הזה מפעיל רשימה של סוכני משנה בו-זמנית. אחרי שכל המשימות המקבילות מסתיימות, אפשר לאסוף את התוצאות שלהן ולסכם אותן לתשובה מקיפה אחת.

בתרשים הזה אפשר לראות את ParallelAgent מקבל שאילתה אחת ומפצל את העבודה לשלושה מסלולים מקבילים. הפונקציות museum_finder,‏ concert_finder ו-restaurant_finder פועלות בו-זמנית. אחרי ששלושת הסוכנים מסיימים את העבודה, התוצאות שלהם (שנשמרו במצב המשותף) מאוחדות ומועברות לסוכן הסינתזה הסופי, שמשלב אותן לתשובה אחת.

‫➡️ איפה אפשר למצוא את זה ב-Notebook:

‫👈 תהליך העבודה הזה מפורט בקטע הפעלה מקבילה באמצעות ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟

Parallel Agent

  • סוכנים מומחים: מוגדרים שלושה סוכנים מומחים, שלכל אחד מהם יש output_key ייחודי (לדוגמה, museum_result).
  • תהליך העבודה המקביל: סוכן המחקר המקביל מוגדר כסוכן מקביל, ושלושת סוכני החיפוש מופיעים כסוכני המשנה שלו.
  • שלב הסינתזה: אחרי השלב המקביל, סוכן סינתזה סופי אוסף את כל הממצאים מהמצב המשותף באמצעות placeholders ‏ ({museum_result},‏ {concert_result} וכו') כדי ליצור סיכום מסודר.

11. נספח: ADK Web –‏ 🍎 ל-Mac/Linux

roadmap9

במדריך הזה נסביר איך להגדיר ולהריץ במחשב המקומי את הסוכן ADK Day Trip Planning Agent (סוכן לתכנון טיול יומי).

דרישות מוקדמות

  • ‫Python 3.8 ואילך
    • ‫Python 3.9 ואילך: המערכת מתקינה את google-adk==1.5.0 (הגרסה האחרונה עם כל התכונות)
    • ‫Python 3.8: מתקין את google-adk==0.3.0 (גרסה תואמת)
  • מפתח API של Google AI Studio (משלב ההגדרה שלמעלה)
  • חיבור אינטרנט

שלב 1: שיבוט המאגר

פותחים את Terminal ומריצים את הפקודה:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

שלב 2: הגדרת סביבה וירטואלית והתקנת תלות

אפשרות א': הגדרה אוטומטית (מומלץ)

# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

אפשרות ב': הגדרה ידנית

# Create virtual environment
python3 -m venv .adk_env

# Activate virtual environment
source .adk_env/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

שלב 3: 🔥 חשוב – יצירת משתני סביבה

⚠️ אל תדלגו על השלב הזה! יוצרים קובץ .env בספרייה agent/:

# Create the .env file
touch agent/.env

# Open it in your default text editor
open agent/.env

מוסיפים את השורות הבאות לקובץ:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 קריטי: מחליפים את your_actual_api_key_here במפתח ה-API בפועל משלב ההגדרה: קבלת מפתח ה-API.

שלב 4: מפעילים את הסביבה הווירטואלית (אם היא עדיין לא פעילה)

source .adk_env/bin/activate

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

שלב 5: מריצים את ממשק האינטרנט של ADK

adk web

שלב 6: פותחים את הדפדפן

  1. פותחים את הדפדפן ועוברים לכתובת ה-URL שמוצגת במסוף (בדרך כלל http://localhost:8000)
  2. בתפריט הנפתח בפינה הימנית העליונה, בוחרים באפשרות agent
  3. אפשר להתחיל להתכתב בצ'אט עם סוכן התכנון של הטיול היומי.

תוצג שיחה כמו: דוגמה לממשק משתמש באינטרנט של ADK

השבתה של הסביבה

כשמסיימים לעבוד על הפרויקט:

deactivate

הפקודה הזו פועלת באופן זהה ב-Mac/Linux וב-Windows. הקידומת (.adk_env) תיעלם מההנחיה במסוף.

פתרון בעיות ב-Mac

  • לא נמצא Python: במקום python, צריך להשתמש ב-python3
  • ההרשאה נדחתה: מריצים את הפקודה chmod +x setup_venv.sh לפני שמריצים את התסריט

12. נספח: ADK Web – 🪟 למשתמשי Windows

roadmap9

במדריך הזה נסביר איך להגדיר ולהריץ במחשב המקומי את הסוכן ADK Day Trip Planning Agent (סוכן לתכנון טיול יומי).

דרישות מוקדמות

  • ‫Python 3.8 ואילך
    • ‫Python 3.9 ואילך: המערכת מתקינה את google-adk==1.5.0 (הגרסה האחרונה עם כל התכונות)
    • ‫Python 3.8: מתקין את google-adk==0.3.0 (גרסה תואמת)
  • מפתח API של Google AI Studio (משלב ההגדרה שלמעלה)
  • חיבור אינטרנט

שלב 1: שיבוט המאגר

פותחים את שורת הפקודה או את PowerShell ומריצים את הפקודה:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

שלב 2: הגדרת סביבה וירטואלית והתקנת תלות

אפשרות א': הגדרה אוטומטית (מומלץ)

# Run the setup script in Command Prompt
setup_venv.bat

אפשרות ב': הגדרה ידנית

בשביל שורת הפקודה:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

ל-PowerShell:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\Activate.ps1

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

שלב 3: 🔥 חשוב – יצירת משתני סביבה

⚠️ אל תדלגו על השלב הזה! יוצרים קובץ .env בספרייה agent/:

# Create the .env file
type nul > agent\.env

# Open it in Notepad
notepad agent\.env

מוסיפים את השורות הבאות לקובץ:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 קריטי: מחליפים את your_actual_api_key_here במפתח ה-API בפועל משלב ההגדרה: קבלת מפתח ה-API.

שלב 4: מפעילים את הסביבה הווירטואלית (אם היא עדיין לא פעילה)

שורת הפקודה:

.adk_env\Scripts\activate

‫PowerShell:

.adk_env\Scripts\Activate.ps1

ההנחיה צריכה להתחיל במילים (.adk_env).

שלב 5: מריצים את ממשק האינטרנט של ADK

adk web

שלב 6: פותחים את הדפדפן

  1. פותחים את הדפדפן ועוברים לכתובת ה-URL שמוצגת במסוף (בדרך כלל http://localhost:8000)
  2. בתפריט הנפתח בפינה הימנית העליונה, בוחרים באפשרות agent
  3. אפשר להתחיל להתכתב בצ'אט עם סוכן התכנון של הטיול היומי.

פתרון בעיות ב-Windows

  • שגיאה במדיניות ההפעלה של PowerShell: מריצים את Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

תוצג שיחה כמו: דוגמה לממשק משתמש באינטרנט של ADK

השבתה של הסביבה

כשמסיימים לעבוד על הפרויקט:

deactivate

הפקודה הזו פועלת באופן זהה ב-Mac/Linux וב-Windows. הקידומת (.adk_env) תיעלם מההנחיה במסוף.