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' ומקשרים אותה.
שלב 3: יצירת מפתח Gemini API
כדי לאבטח את המפתח, צריך קודם שיהיה לכם מפתח.
- עוברים אל Google AI Studio.
- נכנסים באמצעות חשבון 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 כדי לפשט את הרצת השאילתות. - הרצת בדיקה: הפונקציה
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: המשתמש נותן משוב ("אני לא חובב גדול של טירות"). הסוכן זוכר את התור הראשון, ולכן הוא מבין איזה חלק בתוכנית צריך לשנות ומציע חלופה.
- תור 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.
➡️ איפה אפשר למצוא את זה ב-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 ⛓️
יש משימות שצריך לבצע בכמה שלבים בסדר מסוים. לדוגמה, "תמצא לי את הסושי הכי טוב בפאלו אלטו ואז תגיד לי איך להגיע לשם". זהו תהליך בשני שלבים: קודם מוצאים את המסעדה, ואז מקבלים הוראות הגעה.
ה-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 🔁
לא לכל הבעיות יש פתרון פשוט וחד-פעמי. לפעמים אנחנו צריכים להציע פתרון, לבקר אותו ולשפר אותו עד שהוא עומד במגבלה ספציפית.
לשם כך, ה-ADK כולל את LoopAgent. סוכן זרימת העבודה הזה מפעיל שוב ושוב רצף של סוכני משנה עד שמתקיים תנאי מסוים. התכונה הזו מושלמת ליצירת סוכנים 'פרפקציוניסטים' שיכולים לתכנן, לבקר ולשפר את העבודה שלהם.
בתרשים מוצג תהליך שבו Planner Agent יוצרים תוכנית קודם. לאחר מכן, מזינים את LoopAgent. הכלי Critic Agent בודק את התוכנית. אם יש פגם, Refiner Agent יוצר גרסה חדשה והלולאה חוזרת על עצמה. אם התוכנית טובה, Refiner Agent קורא לכלי exit_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 ⚡️
יעילות היא המפתח. אם משתמש מבקש כמה פריטי מידע לא קשורים בבת אחת, ביצוע החיפושים האלה בזה אחר זה יהיה איטי.
הפתרון הוא ParallelAgent. סוכן תהליך העבודה הזה מפעיל רשימה של סוכני משנה בו-זמנית. אחרי שכל המשימות המקבילות מסתיימות, אפשר לאסוף את התוצאות שלהן ולסכם אותן לתשובה מקיפה אחת.
בתרשים הזה אפשר לראות את ParallelAgent מקבל שאילתה אחת ומפצל את העבודה לשלושה מסלולים מקבילים. הפונקציות museum_finder, concert_finder ו-restaurant_finder מופעלות בו-זמנית. אחרי ששלושת הסוכנים מסיימים את העבודה, התוצאות שלהם (שנשמרו במצב המשותף) מאוחדות ומועברות לסוכן הסינתזה הסופי, שמשלב אותן לתשובה אחת.
➡️ איפה אפשר למצוא את זה ב-Notebook:
👈 תהליך העבודה הזה מפורט בקטע העוצמה של ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟
- סוכנים מומחים: מוגדרים שלושה סוכנים מומחים, שלכל אחד מהם יש output_key ייחודי (לדוגמה, museum_result).
- תהליך העבודה המקביל: סוכן המחקר המקביל מוגדר כסוכן מקביל, ושלושת סוכני החיפוש מוגדרים כסוכני המשנה שלו.
- שלב הסינתזה: אחרי השלב המקביל, סוכן סינתזה סופי אוסף את כל הממצאים מהמצב המשותף באמצעות 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: משתמשים ב-
python3במקום ב-python - ההרשאה נדחתה: צריך להריץ את הפקודה
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) תיעלם מההנחיה במסוף.