דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

מה תלמדו

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

מה צריך

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

מימוש חשבון לחיוב לתקופת ניסיון

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

פותחים חלון פרטי בדפדפן.
עוברים אל פורטל מימוש השוברים הזה.
מתחברים באמצעות חשבון Gmail לשימוש אישי
פועלים לפי ההוראות המפורטות בפורטל.

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 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, כספק שירותי ה-Backend.

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 ובוחרים אותה.
לוחצים על אישור.

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

אחרי שחלון העורך נטען במלואו, עוברים לתיקייה 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="...": הנחיית המערכת שמכוונת את ההתנהגות של הסוכן ומגדירה את האישיות שלו. ההנחיה הזו אומרת ל-LLM איך לפעול ומה המטרה העיקרית שלו. במקרה הזה, ההנחיה מגדירה את הסוכן כ'עוזר מועיל'. ההוראה הזו היא המפתח לעיצוב סגנון השיחה והיכולות של הסוכן.

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 web במקום בפקודה adk run..

אם הטרמינל עדיין מריץ את הפקודה adk run, מקלידים exit כדי לסגור אותו לפני שמקלידים את הפקודה הבאה:

adk web

הפלט במסוף אמור להיראות כך:

...
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 (מסוף)

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

פתיחה באמצעות תצוגה מקדימה באינטרנט

לוחצים על הלחצן Web Preview (תצוגה מקדימה באינטרנט).
בוחרים באפשרות שינוי היציאה.
מזינים את מספר היציאה (למשל 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 הבא בסדרה הזו, Building AI Agents with ADK: Empowering with Tools, שבו מוסבר על התהליך הזה.