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

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

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

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

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

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

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

מה תלמדו

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

מה תצטרכו

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

2. מבוא

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

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

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

3. יצירת פרויקט ב-Google Cloud (אופציונלי)

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

  1. נכנסים לכתובת console.cloud.google.com/projectcreate
  2. מזינים את המידע הנדרש:
  • שם הפרויקט – אפשר להזין כל שם שרוצים (לדוגמה: genai-workshop)
  • מיקום – משאירים את האפשרות ללא ארגון
  • חשבון לחיוב – אם האפשרות הזו מופיעה, בוחרים באפשרות חשבון לחיוב של תקופת הניסיון ב-Google Cloud Platform. אם האפשרות הזו לא מופיעה, אל דאגה. פשוט עוברים לשלב הבא.
  1. מעתיקים את מזהה הפרויקט שנוצר, כי תצטרכו אותו בהמשך.

9cc4a060b8c46fb0.png

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

4. הגדרת הסביבה

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

הגדרת Cloud Shell

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

שלב 1. הפעלת Cloud Shell

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

186bc51f8f3ae589.png

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

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

gcloud config set project <your-project-id>

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

479ae540d1828559.png

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

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

gcloud services enable aiplatform.googleapis.com

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

יצירת סביבה וירטואלית של 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) תופיע לפני שורת הפקודה במסוף, כדי לציין שהסביבה הווירטואלית פעילה.

6512ff43e8f5aa04.png

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

uv pip install --no-cache google-adk

5. יצירת סוכן

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

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

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

adk create personal_assistant

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

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

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

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

1. Google AI
2. Gemini Enterprise Agent Platform
3. Login with Google
Choose a backend (1, 2, 3): 2

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

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

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

Enter Google Cloud region [us-central1]: global

בטרמינל אמור להופיע פלט דומה.

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

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

8d092e1c07966b24.png

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

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

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

ff4c617fa62e2da2.png

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

agent.py

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

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-3.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-3.5-flash": הפרמטר החשוב הזה מציין באיזה מודל שפה גדול (LLM) הסוכן ישתמש כ "מוח" בסיסי כדי להבין, להסיק מסקנות וליצור תשובות. ‫gemini-3.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_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION
  • ‫GOOGLE_GENAI_USE_ENTERPRISE: התג הזה מציין ל-ADK שאתם מתכוונים להשתמש בשירות Gemini Enterprise Agent Platform של Google לפעולות שקשורות ל-AI גנרטיבי. ההגדרה הזו חשובה למינוף השירותים המנוהלים והמודלים המתקדמים של Google Cloud.
  • ‫GOOGLE_CLOUD_PROJECT: המשתנה הזה יכיל את המזהה הייחודי של הפרויקט שלכם ב-Google Cloud. ה-ADK צריך את זה כדי לשייך את הסוכן למשאבי הענן שלכם בצורה נכונה וכדי לאפשר חיוב.
  • ‫GOOGLE_CLOUD_LOCATION: כאן מציינים את המיקום ב-Google Cloud של בקשות למודלים (לדוגמה, global). שימוש במיקום הנכון מבטיח שהסוכן יוכל לתקשר ביעילות עם השירותים של Gemini Enterprise Agent Platform.

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'}, צריך לבצע את הפעולות הבאות:

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

d9eb6361fd573427.pngf304212def88d3a3.png

לא נעשה שימוש ב-Gemini Enterprise Agent Platform API בפרויקט

אם מופיעה הודעת שגיאה עם {'message': 'API has not been used in project...'}, מפעילים את Gemini Enterprise Agent Platform 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)

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

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

43b8b9beedbb1766.png

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

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

e845ab685af1ad90.png

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

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

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

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

cd ~
rm -rf ai-agents-adk

השבתה של Gemini Enterprise Agent Platform API

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

gcloud services disable aiplatform.googleapis.com

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

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

10. סיכום

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

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

בנוסף, אתם יכולים להשתתף בתוכנית הדגל שלנו GEAR (Gemini Enterprise Agent Ready) כדי לקבל גישה למקורות מידע חשובים. אתם יכולים גם להשתתף בתוכנית ההסמכות, תוכנית הדרכה מעשית מובנית בהנחיית מדריכים מומחים.