1. מה תלמדו
ברוכים הבאים לשיעור המומחים בנושא ADK – המסע שלכם אל מערכות מרובות סוכנים
אתם עומדים להיכנס לעולם המלהיב של סוכני AI. שכחו מצ'אטבוטים פשוטים שמספקים רק תשובות לשאלות. אנחנו מתעמקים ב-Agent Development Kit (ADK) כדי לבנות מערכות מתוחכמות ואוטונומיות שיכולות להסיק מסקנות, לתכנן ולהשתמש בכלים כדי לבצע משימות מורכבות.
בסוף המדריך הזה תוכלו:
- יצירת סוכן AI ראשון: תלמדו איך ליצור סוכן מתפקד שיכול להבין את הצרכים של המשתמש, להשתמש בכלים כמו חיפוש Google וליצור תשובות מפורטות ומועילות.
- שליטה בכלי מותאם אישית: כדי לחשוף את העוצמה האמיתית של הסוכנים, אפשר לקשר אותם לפונקציות ולממשקי API מותאמים אישית. תלמדו את הסוכן לאחזר נתונים בזמן אמת, כמו תחזיות מזג אוויר.
- בניית מערכות מרובות סוכנים: לומדים על התבנית Agent-as-a-Tool (סוכן ככלי), קונספט חדשני שבו סוכנים מעבירים משימות לסוכנים מומחים אחרים, ויוצרים צוות של מומחי AI שעובדים יחד.
- ארגון תהליכי עבודה מורכבים: מעבר להקצאת משימות פשוטה, אפשר לשלוט בדפוסים מתקדמים כמו נתבים, שרשרות רציפות, לולאות וביצוע מקביל כדי ליצור אפליקציות חזקות, יעילות וחכמות שיכולות לטפל כמעט בכל בקשה.
- איך נותנים לאגנטים זיכרון: חשוב להבין את התפקיד המרכזי של זיכרון שיחה, שמאפשר לאגנטים לטפל בשאלות המשך, ללמוד ממשוב ולנהל משימות מרובות שלבים בצורה חלקה.
קדימה, מתחילים! 🚀
2. הגדרה של מפתח GCP ו-Gemini API
הגדרת פרויקט GCP ומפתח Gemini API
כדי להפעיל את סוכני ה-AI שלנו, אנחנו צריכים שני דברים: פרויקט ב-Google Cloud שיספק את הבסיס ומפתח Gemini API כדי לגשת למודלים המתקדמים של Google.
שלב 1: הפעלת חשבון לחיוב
- כדי לממש את הזיכוי בסך 5 דולר בחשבון לחיוב, תצטרכו אותו לפריסה. חשוב לוודא שאתם מחוברים לחשבון Gmail.
שלב 2: יצירת פרויקט חדש ב-GCP
- נכנסים אל Google Cloud Console ויוצרים פרויקט חדש.
- נכנסים אל Google Cloud Console ויוצרים פרויקט חדש.
- פותחים את החלונית הימנית, לוחצים על
Billingובודקים אם החשבון לחיוב מקושר לחשבון GCP הזה.
אם הדף הזה מוצג, מסמנים את התיבה manage billing account, בוחרים באפשרות Google Cloud Trial One ומקשרים אליה.
שלב 3: יצירת מפתח Gemini API
כדי לאבטח את המפתח, צריך קודם שיהיה לכם מפתח.
- עוברים אל Google AI Studio : https://aistudio.google.com/
- נכנסים באמצעות חשבון Gmail.
- לוחצים על הלחצן Get API key (קבלת מפתח API), שנמצא בדרך כלל בחלונית הניווט בצד ימין או בפינה השמאלית העליונה.
- בתיבת הדו-שיח API keys (מפתחות API), לוחצים על Create API key in new project (יצירת מפתח API בפרויקט חדש).
- בוחרים את הפרויקט החדש שיצרתם והגדרתם בו חשבון לחיוב.
- המערכת תיצור בשבילכם מפתח API חדש. מעתיקים את המפתח הזה באופן מיידי ושומרים אותו במקום בטוח באופן זמני (למשל, במנהל סיסמאות או בהערה מאובטחת). זה הערך שתשתמשו בו בשלבים הבאים.
3. סשן 1: הסוכן הראשון שלכם עם Runner
נתחיל מהיסודות. בדוגמה הזו אנחנו יוצרים את הסוכן הפשוט הראשון שלנו, day_trip_agent. מטרת הסוכן הזה היא ליצור מסלול טיול ליום שלם על סמך בקשה של משתמש, כולל שיקולי תקציב. בדוגמה הזו מוצגים שלושת רכיבי הליבה של כל אינטראקציה עם סוכן ב-ADK:
- סוכן: המוח המרכזי של הפעולה. הוא מוגדר על ידי ההוראות שלו (האישיות והמשימה שלו), מודל ה-AI שבו הוא משתמש (כמו Gemini) והכלים שהוא יכול לגשת אליהם.
- סשן: הזיכרון של השיחה. הוא שומר את היסטוריית האינטראקציות (הודעות של משתמשים ותשובות של נציגים), וכך מאפשר דיאלוג רציף.
- Runner: המנוע שמבצע את המשימה. הוא מקבל את הסוכן ואת הסשן, מעבד את השאילתה החדשה של המשתמש ומתזמן את השלבים ליצירת תשובה.
➡️ איפה אפשר למצוא את זה ב-Notebook
👈 זה מתאים לתאים בקטע חלק 1: הסוכן הראשון שלך – הג'יני של טיול היום 🧞.🌟
- הגדרת הסוכן: מחפשים את הפונקציה
create_day_trip_agent(). כאן מוגדר הנציג. שימו לב למחרוזת ההוראות המפורטת – זו ההנחיה שמגדירה לנציג איך להתנהג. אנחנו גם נותנים לו את הכלי הראשון שלו: חיפוש Google. - פונקציית עזר: כאן מוגדרת פונקציית העזר
run_agent_query(). נשתמש בכלי הזה לאורך ה-notebook כדי לפשט את הרצת השאילתות. - Test Run: הפונקציה
run_day_trip_genie()מדמה משתמש שמבקש טיול יום "במחיר סביר" ו "מרגיע". הסוכן משתמש בהוראות ובכלי חיפוש Google כדי למצוא מיקומים מתאימים וליצור מסלול טיול בפורמט Markdown.
➡️ פעולה: בודקים את ההנחיה של day_trip_agent. אפשר לראות איך הבקשה לנסיעה במחיר סביר בשאילתת הבדיקה קשורה ישירות להנחיה של הסוכן להיות מודע לתקציב.
4. סשן 2: כלים מותאמים אישית 🛠️
חיפוש Google הוא כלי רב עוצמה, אבל כדי לממש את הפוטנציאל האמיתי של סוכני AI, צריך לחבר אותם למקורות נתונים ייחודיים משלכם, לממשקי API או ללוגיקה מותאמת אישית. בקטע הזה ניצור כלי בהתאמה אישית מפונקציית Python פשוטה.
החלק הכי חשוב בכלי פונקציה הוא מחרוזת התיעוד שלו. ה-ADK מנתח באופן אוטומטי את מחרוזת התיעוד כדי להבין מה הכלי עושה, אילו פרמטרים הוא מקבל (Args) ומה הוא מחזיר (Returns). מודל השפה הגדול (LLM) קורא את התיאור הזה כדי להחליט מתי ואיך להשתמש בכלי.
➡️ איפה אפשר למצוא את זה ב-Notebook
👈 זה מתאים לתאים בקטע 2.1 כלי הפונקציה הפשוט: קריאה ל-API של מזג אוויר בזמן אמת. 🌟
- הגדרת הכלי: הפונקציה
get_live_weather_forecast(location: str)היא הליבה של הכלי המותאם אישית שלנו. היא מקבלת שם של עיר, קוראת ל-API הציבורי של National Weather Service (שירות מזג האוויר הלאומי) ומחזירה מילון עם הטמפרטורה והתחזית. - הגדרת הסוכן: הסוכן weather_agent נוצר ומצויד בכלי החדש שלנו על ידי העברת
tools=[get_live_weather_forecast]במהלך האתחול שלו. בהוראות לסוכן מצוין במפורש להשתמש בכלי הזה לפני שמציעים פעילויות בחוץ. - הרצת בדיקה: השאילתה "I want to go hiking near Lake Tahoe, what's the weather like?" (אני רוצה לצאת לטיול רגלי ליד אגם טאהו, מה מזג האוויר?) מפעילה ישירות את הסוכן כדי להשתמש בכלי
get_live_weather_forecast, כי ההוראות שלו מחייבות זאת.
➡️ Action: Read the docstring for the get_live_weather_forecast function and the instruction for the weather_agent. שימו לב לקשר הישיר ביניהם.
5. סשן 3: סוכן ככלי 🧑🍳
למה ליצור סוכן יחיד ומונוליטי אם אפשר ליצור צוות של מומחים? תבנית 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.
- call_db_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: זיכרון הסוכן 🧠
סוכן חכם באמת צריך לעשות יותר מאשר רק להגיב לשאילתות חד-פעמיות. הוא צריך לזכור את השיחה, להבין את ההקשר ולהתאים את עצמו למשוב. הדבר הזה מתאפשר באמצעות ניהול תקין של סשנים. אפשר לחשוב על 'סוכן לולאה' כסוכן שמעורב בלולאה שיחתית רציפה, שמבוססת על הזיכרון שלו.
כשמשתמשים באותו אובייקט של סשן לכמה שאילתות רצופות, הסוכן יכול לראות את כל היסטוריית השיחה. כך הוא יכול לענות על שאלות המשך, לתקן את עצמו על סמך משוב ולתכנן משימות מרובות שלבים.
➡️ איפה אפשר למצוא את זה ב-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: סוכן הניתוב 🚏
סוכן יחיד יכול לעשות רק כמות מוגבלת של פעולות. כדי לטפל בבקשות מורכבות במיוחד של משתמשים, אנחנו צריכים צוות של נציגים מומחים. אבל איך יודעים באיזה סוכן להשתמש לשאילתה מסוימת? כאן נכנס לתמונה סוכן הניתוב.
הסוכן של הנתב פועל כסוכן ראשי או כסוכן שולח. המטרה היחידה שלו היא לנתח שאילתת משתמש נכנסת ולהחליט איזה סוכן מומחה (או תהליך עבודה של סוכנים) מתאים ביותר למשימה. הוא לא עונה לשאילתה עצמה, אלא רק מעביר אותה לסוכן המתאים בהמשך השרשרת.
לדוגמה, שאילתה לגבי "הסושי הכי טוב" צריכה לעבור לסוכן foodie_agent, בעוד ששאלה לגבי "קונצרטים בסוף השבוע הזה" צריכה להיות מטופלת על ידי weekend_guide_agent.
➡️ איפה אפשר למצוא את זה במחברת:
👈 הרעיון הזה הוא מרכזי בכל המחברת, אבל הוא מוצג לראשונה בחלק 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 ⛓️
יש משימות שצריך לבצע בכמה שלבים בסדר מסוים. לדוגמה, "תמצא לי את הסושי הכי טוב בפאלו אלטו ואז תגיד לי איך להגיע לשם". זהו תהליך בשני שלבים: קודם מוצאים את המסעדה, ואז מקבלים הוראות הגעה.
ה-ADK מספק דרך נקייה ויעילה לנהל את זה באמצעות SequentialAgent. זהו סוכן מיוחד של תהליך עבודה שמבצע רשימה של סוכני משנה בסדר מוגדר מראש.
הקסם טמון במצב המשותף. אפשר לשמור באופן אוטומטי את הפלט של סוכן אחד ברצף במילון מצב משותף, ואז להשתמש בו כקלט לסוכן הבא. כך לא צריך להשתמש בקוד ידני מורכב כדי להעביר מידע בין השלבים.
➡️ איפה אפשר למצוא את זה במחברת:
👈 הנושא הזה מוסבר בחלק 2 (הדרך של ADK): מהומה של כמה סוכנים עם SequentialAgent 🧠→⛓️→🤖. 🌟
- שינוי מבנה של סוכן: בתא הקוד הראשון בקטע הזה, אפשר לראות את השינויים העיקריים ב-
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 🔁
לא לכל הבעיות יש פתרון פשוט וחד-פעמי. לפעמים אנחנו צריכים להציע פתרון, לבקר אותו ולשפר אותו עד שהוא עומד במגבלה ספציפית.
לשם כך, ה-ADK כולל את LoopAgent. סוכן זרימת העבודה הזה מפעיל שוב ושוב רצף של סוכני משנה עד שתנאי מסוים מתקיים. התכונה הזו מושלמת ליצירת סוכנים "פרפקציוניסטים" שיכולים לתכנן, לבקר ולשפר את העבודה שלהם.
בתרשים מוצג Planner Agent יצירת תוכנית קודם. לאחר מכן, מזינים את LoopAgent. הכלי Critic Agent בודק את התוכנית. אם יש פגם, Refiner Agent יוצר גרסה חדשה והלולאה חוזרת על עצמה. אם התוכנית טובה, Refiner Agent קורא לכלי exit_loop, והתוכנית הסופית והמאומתת מוחזרת.
➡️ איפה אפשר למצוא את זה במחברת:
👈 הסבר על התהליך הזה מופיע במאמר פיתוח רעיונות איטרטיבי באמצעות 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 ⚡️
היעילות היא גורם מרכזי. אם משתמש מבקש כמה פריטי מידע לא קשורים בבת אחת, ביצוע החיפושים האלה בזה אחר זה יהיה איטי.
הפתרון הוא ParallelAgent. סוכן תהליך העבודה הזה מפעיל רשימה של סוכני משנה בו-זמנית. אחרי שכל המשימות המקבילות מסתיימות, אפשר לאסוף את התוצאות שלהן ולסכם אותן לתשובה מקיפה אחת.
בתרשים הזה אפשר לראות את ParallelAgent מקבל שאילתה אחת ומפצל את העבודה לשלושה מסלולים מקבילים. הפונקציות museum_finder, concert_finder ו-restaurant_finder מופעלות בו-זמנית. אחרי ששלושתם מסיימים, התוצאות האישיות שלהם (שנשמרות במצב המשותף) מצטרפות ועוברות לסוכן הסינתזה הסופי, שמשלב אותן לתשובה אחת.
➡️ איפה אפשר למצוא את זה במחברת:
👈 תהליך העבודה הזה מפורט בקטע העוצמה של ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟
- סוכנים מומחים: מוגדרים שלושה סוכנים מומחים, שלכל אחד מהם יש output_key ייחודי (לדוגמה, museum_result).
- תהליך העבודה המקביל: סוכן המחקר המקביל מוגדר כ-ParallelAgent, ושלושת סוכני החיפוש מופיעים כ-sub_agents שלו.
- שלב הסינתזה: אחרי השלב המקביל, סוכן סינתזה סופי אוסף את כל הממצאים מהמצב המשותף באמצעות placeholders (
{museum_result},{concert_result}וכו') כדי ליצור סיכום מסודר.
11. נספח: ADK Web – 🍎 ל-Mac/Linux
במדריך הזה נסביר איך מגדירים את ADK Day Trip Planning Agent ומריצים אותו במחשב המקומי.
דרישות מוקדמות
- Python 3.8 ואילך
- Python 3.9 ואילך: מתקין את google-adk==1.5.0 (הגרסה האחרונה עם כל התכונות)
- Python 3.8: מתקין google-adk==0.3.0 (גרסה תואמת)
- מפתח Google AI Studio API
- חיבור אינטרנט
שלב 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 בפועל!
שלב 4: מפעילים את הסביבה הווירטואלית (אם היא עדיין לא פעילה)
source .adk_env/bin/activate
הסימן (.adk_env) אמור להופיע בתחילת שורת הפקודה של הטרמינל.
שלב 5: מריצים את ממשק האינטרנט של ADK
adk web
שלב 6: פותחים את הדפדפן
- פותחים את הדפדפן ועוברים לכתובת ה-URL שמוצגת במסוף (בדרך כלל
http://localhost:8000) - בתפריט הנפתח בפינה הימנית העליונה, בוחרים באפשרות
agent - מתחילים להתכתב בצ'אט עם סוכן התכנון של הטיול היומי.
תוצג שיחה כמו: 
השבתת הסביבה
כשמסיימים לעבוד על הפרויקט:
deactivate
הפקודה הזו פועלת באופן זהה ב-Mac/Linux וב-Windows. הקידומת (.adk_env) תיעלם מההנחיה במסוף.
פתרון בעיות ב-Mac
- לא נמצא Python: במקום
python, משתמשים ב-python3 - ההרשאה נדחתה: צריך להריץ את הפקודה
chmod +x setup_venv.shלפני שמריצים את הסקריפט
12. נספח: ADK Web – 🪟 למשתמשי Windows
במדריך הזה נסביר איך מגדירים את ADK Day Trip Planning Agent ומריצים אותו במחשב המקומי.
דרישות מוקדמות
- Python 3.8 ואילך
- Python 3.9 ואילך: מתקין את google-adk==1.5.0 (הגרסה האחרונה עם כל התכונות)
- Python 3.8: מתקין google-adk==0.3.0 (גרסה תואמת)
- מפתח Google AI Studio API
- חיבור אינטרנט
שלב 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 בפועל!
שלב 4: מפעילים את הסביבה הווירטואלית (אם היא עדיין לא פעילה)
שורת הפקודה:
.adk_env\Scripts\activate
PowerShell:
.adk_env\Scripts\Activate.ps1
ההנחיה צריכה להתחיל במילים (.adk_env).
שלב 5: מריצים את ממשק האינטרנט של ADK
adk web
שלב 6: פותחים את הדפדפן
- פותחים את הדפדפן ועוברים לכתובת ה-URL שמוצגת במסוף (בדרך כלל
http://localhost:8000) - בתפריט הנפתח בפינה הימנית העליונה, בוחרים באפשרות
agent - מתחילים להתכתב בצ'אט עם סוכן התכנון של הטיול היומי.
פתרון בעיות ב-Windows
- שגיאה במדיניות ההפעלה של PowerShell: מריצים את
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
תוצג שיחה כמו:
השבתת הסביבה
כשמסיימים לעבוד על הפרויקט:
deactivate
הפקודה הזו פועלת באופן זהה ב-Mac/Linux וב-Windows. הקידומת (.adk_env) תיעלם מההנחיה במסוף.