יצירת סוכני AI באמצעות ADK: הבסיס

1. לפני שמתחילים

ברוכים הבאים לחלק הראשון בסדרה 'יצירה של סוכני AI באמצעות ADK'. בסדרת ה-Codelab הזו, תצאו למסע מרתק ליצירת סוכן AI חכם משלכם באמצעות הערכה לפיתוח סוכנים (ADK) של Google.

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

אפשר להשלים את ה-codelab הזה בסביבה המקומית או ב-Google Cloud. כדי ליהנות מחוויית השימוש העקבית ביותר, מומלץ להשתמש ב-Cloud Shell בסביבת Google Cloud. ב-Cloud Shell יש גם אחסון מתמיד בנפח 5GB בספרייה $HOME. האפשרות הזו שימושית לאחסון סקריפטים, קובצי הגדרה או מאגרי קוד משוכפלים.

אפשר לגשת ל-codelab הזה גם באמצעות כתובת ה-URL המקוצרת הזו: goo.gle/adk-foundation.

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

הבנה של מושגים ב-AI גנרטיבי
מיומנות בסיסית בתכנות ב-Python
היכרות עם שורת הפקודה / טרמינל

מה תלמדו

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

מה תצטרכו

מחשב תקין וחיבור Wi-Fi אמין
דפדפן, כמו Chrome, כדי לגשת אל מסוף Google Cloud
סקרנות ורצון ללמוד

2. מבוא

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

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

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

3. הגדרת שירותי Google Cloud

יצירת פרויקט ב-Google Cloud

מתחילים ביצירת פרויקט חדש ב-Google Cloud כדי שהפעילויות מ-Codelab הזה יהיו מבודדות רק בפרויקט החדש הזה.

עוברים אל console.cloud.google.com/projectcreate
מזינים את המידע הנדרש:

שם הפרויקט – אפשר להזין כל שם שרוצים (לדוגמה: genai-workshop)
מיקום – משאירים את האפשרות ללא ארגון
חשבון לחיוב – אם האפשרות הזו מופיעה, בוחרים באפשרות חשבון לחיוב ב-Google Cloud Platform לניסיון. אל דאגה אם האפשרות הזו לא מוצגת. פשוט ממשיכים לשלב הבא.

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

אם הכול בסדר, לוחצים על הלחצן יצירה.

הגדרת Cloud Shell

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

1. הפעלת Cloud Shell

עוברים אל shell.cloud.google.com ואם מופיע חלון קופץ שמבקש לאשר, לוחצים על Authorize (אישור).

2. הגדרת מזהה פרויקט

מריצים את הפקודה הבאה במסוף Cloud Shell כדי להגדיר את מזהה הפרויקט הנכון. מחליפים את <your-project-id> במזהה הפרויקט בפועל שהעתקתם משלב יצירת הפרויקט שלמעלה.

gcloud config set project <your-project-id>

עכשיו אמור להופיע במסוף Cloud Shell הפרויקט הנכון. מזהה הפרויקט שנבחר מודגש בצבע צהוב.

3. הפעלת ממשקי ה-API הנדרשים

כדי להשתמש בשירותי Google Cloud, צריך קודם להפעיל את ממשקי ה-API המתאימים לפרויקט. מריצים את הפקודות הבאות בטרמינל של Cloud Shell כדי להפעיל את השירותים של ה-Codelab הזה:

gcloud services enable aiplatform.googleapis.com

אם הפעולה הושלמה, יופיע Operation/... finished successfully במסוף.

4. יצירת סביבה וירטואלית של Python

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

1. יוצרים ספריית פרויקט ועוברים אליה:

mkdir -p ai-agents-adk
cd ai-agents-adk

2. יוצרים ומפעילים סביבה וירטואלית:

uv venv --python 3.12
source .venv/bin/activate

הקידומת (ai-agents-adk) תוצג בהנחיית המסוף, כדי לציין שהסביבה הווירטואלית פעילה.

3. דף ההתקנה של ה-ADK

uv pip install google-adk

5. יצירת סוכן

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

‫agent.py: מכיל את קוד ה-Python הראשי של הסוכן, שבו מוגדרים השם שלו, מודל ה-LLM שבו הוא משתמש וההוראות העיקריות.
‫__init__.py: מציין שהספרייה היא חבילת Python, ועוזר ל-ADK לגלות ולטעון את הגדרת הסוכן.
‫.env: מאחסן מידע רגיש ומשתני הגדרה כמו מפתח API, מזהה פרויקט ומיקום.

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

adk create personal_assistant

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

בשלב הראשון, בוחרים באפשרות 1 כדי להשתמש במודל gemini-2.5-flash, מודל מהיר ויעיל שמתאים במיוחד למשימות שיחה.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

בשלב השני, בוחרים באפשרות Vertex AI (אפשרות 2), פלטפורמת ה-AI המנוהלת והעוצמתית של Google Cloud, כספק שירות לקצה העורפי.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

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

Enter Google Cloud project ID [your-project-id]:

לבסוף, לוחצים על Enter בשאלה הבאה כדי להשתמש ב-us-central1 כאזור של ה-codelab הזה.

Enter Google Cloud region [us-central1]:

הפלט במסוף אמור להיראות דומה.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

6. עיון בקודים של סוכנים

כדי לראות את הקבצים שנוצרו, פותחים את התיקייה ai-agents-adk ב-Cloud Shell Editor.

בתפריט העליון, לוחצים על קובץ > פתיחת תיקייה....
מוצאים את התיקייה ai-agents-adk ובוחרים אותה.
לוחצים על אישור.

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

אחרי שהחלון של Editor נטען במלואו, עוברים לתיקייה personal-assistant. הקבצים הנדרשים יופיעו כמו שצוין למעלה (agent.py,‏ __init__.py ו-.env).

קובץ ה-.env מוסתר בדרך כלל כברירת מחדל. כדי שהקובץ יהיה גלוי ב-Cloud Shell Editor:

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

בודקים את התוכן של כל קובץ.

agent.py

הקובץ הזה יוצר מופע של הסוכן באמצעות המחלקה Agent מהספרייה google.adk.agents.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

‫from google.adk.agents import Agent: השורה הזו מייבאת את המחלקה Agent הנדרשת מספריית ה-ADK.
‫root_agent = Agent(...): כאן יוצרים מופע של סוכן ה-AI.
‫name="root_agent": מזהה ייחודי של הסוכן. כך ADK יזהה את הסוכן שלכם ויתייחס אליו.
‫model="gemini-2.5-flash": הפרמטר החשוב הזה מציין באיזה מודל שפה גדול (LLM) הסוכן ישתמש כ "מוח" בסיסי להבנה, להסקת מסקנות וליצירת תשובות. ‫gemini-2.5-flash הוא מודל מהיר ויעיל שמתאים למשימות שיחה.
‫description="...": סיכום תמציתי של מטרת הסוכן או היכולות שלו. התיאור מיועד בעיקר להבנה אנושית או לסוכנים אחרים במערכת מרובת סוכנים, כדי להבין מה הסוכן הספציפי הזה עושה. הוא משמש לרוב לרישום ביומן, לניפוי באגים או להצגת מידע על הסוכן.
‫instruction="...": הנחיית המערכת שמכוונת את ההתנהגות של הסוכן ומגדירה את האישיות שלו. ההנחיה הזו אומרת למודל שפה גדול איך להתנהג ומה המטרה העיקרית שלו. במקרה הזה, ההנחיה מגדירה את הסוכן כ "עוזר מועיל". ההוראה הזו חשובה מאוד לעיצוב סגנון השיחה והיכולות של הסוכן.

init.py

הקובץ הזה נחוץ כדי שמערכת Python תזהה את personal-assistant כחבילה, וכך כלי ה-ADK יוכל לייבא את הקובץ agent.py בצורה נכונה.

from . import agent

‫from . import agent: השורה הזו מבצעת ייבוא יחסי, ומורה ל-Python לחפש מודול בשם agent (שמתאים ל-agent.py) בחבילה הנוכחית (personal-assistant). השורה הפשוטה הזו מבטיחה שכאשר ADK ינסה לטעון את סוכן personal-assistant, הוא יוכל למצוא את root_agent שמוגדר ב-agent.py ולאתחל אותו. גם אם הוא ריק, הנוכחות של __init__.py היא מה שהופכת את הספרייה לחבילת Python.

‎.env

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

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

‫GOOGLE_GENAI_USE_VERTEXAI: הערך הזה מציין ל-ADK שאתם מתכוונים להשתמש בשירות Vertex AI של Google לפעולות של AI גנרטיבי. ההגדרה הזו חשובה כדי למנף את השירותים המנוהלים והמודלים המתקדמים של Google Cloud.
‫GOOGLE_CLOUD_PROJECT: המשתנה הזה יכיל את המזהה הייחודי של הפרויקט שלכם ב-Google Cloud. ה-ADK צריך את זה כדי לשייך את הסוכן למשאבי הענן שלכם בצורה נכונה וכדי לאפשר חיוב.
‫GOOGLE_CLOUD_LOCATION: כאן מציינים את האזור ב-Google Cloud שבו נמצאים המשאבים של Vertex AI (לדוגמה, us-central1). שימוש במיקום הנכון מבטיח שהסוכן יוכל לתקשר ביעילות עם שירותי Vertex AI באותו אזור.

7. הפעלת הסוכן בטרמינל

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

adk run personal_assistant

אם הכול מוגדר בצורה נכונה, תראו פלט דומה במסוף. אל תתייחסו לאזהרות בשלב הזה, כל עוד אתם רואים את [user]: אתם יכולים להמשיך.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

אפשר להמשיך בשיחה עם הנציג. מקלידים משהו כמו "שלום. מה אפשר לעשות בשבילי?" ותקבלו תשובה.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

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

פתרון בעיות

כדי להשתמש ב-method הזה של API, צריך להפעיל את החיוב

אם קיבלתם הודעה עם הכיתוב {‘message': ‘This API method requires billing to be enabled'}, עליכם לבצע את הפעולות הבאות:

בודקים אם משתמשים במזהה הפרויקט הנכון בקובץ .env
עוברים לדף linked billing account ובודקים אם החשבון לחיוב כבר מקושר.
אם לא, בוחרים באפשרות Google Cloud Platform Trial Biling Account (חשבון לחיוב בתקופת ניסיון ב-Google Cloud Platform)

לא נעשה שימוש ב-Vertex AI API בפרויקט

אם מופיעה הודעת שגיאה עם {'message': 'Vertex AI API has not been used in project...'}, מפעילים את Vertex AI API על ידי הקלדת הפקודה הבאה במסוף:

gcloud services enable aiplatform.googleapis.com

אם הפעולה הושלמה, יופיע Operation/... finished successfully במסוף.

שגיאות אחרות

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

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

ערכת הכלים לפיתוח סוכנים (ADK) מציעה גם דרך נוחה להשיק את הסוכן כאפליקציית צ'אט באמצעות ממשק המשתמש לפיתוח. פשוט משתמשים בפקודה adk web במקום בפקודה adk run..

אם המסוף עדיין פועל adk run, מקלידים exit כדי לסגור אותו לפני שמקלידים את הפקודה.

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

במסוף אמור להופיע פלט שדומה לזה:

...
INFO:     Started server process [4978]
INFO:     Waiting for application startup.
+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

אפשר לגשת לממשק המשתמש של הפיתוח באמצעות אחת משתי השיטות הבאות:

ישירות דרך Terminal: לוחצים על הקישור שמופיע, כמו http://localhost:8000, תוך כדי החזקת המקשים Ctrl + Click (או Cmd + Click).
שימוש בתצוגה מקדימה באינטרנט:

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

ממשק המשתמש של אפליקציית הצ'אט יופיע בדפדפן. אתם יכולים להתכתב בצ'אט עם העוזר האישי שלכם דרך הממשק הזה.

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

9. ניקוי (אופציונלי)

מכיוון שאין מוצרים שפועלים לאורך זמן ב-codelab הזה, מספיק להפסיק את הפעלת הסוכנים הפעילים (למשל, את מופע adk web במסוף) על ידי הקשה על Ctrl + C או Cmd + C במסוף.

מחיקת תיקיות וקבצים של פרויקט סוכן

אם רוצים להסיר את הקוד רק מסביבת Cloud Shell, משתמשים בפקודות הבאות:

cd ~
rm -rf ai-agents-adk

השבתה של Vertex AI API

כדי להשבית את Vertex AI API שהופעל קודם, מריצים את הפקודה הבאה:

gcloud services disable aiplatform.googleapis.com

השבתה של כל הפרויקט ב-Google Cloud

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

10. סיכום

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

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