יצירת סוכני 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
  • פרויקט ב-Google Cloud שהחיוב בו מופעל
  • סקרנות ורצון ללמוד

2. מבוא

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

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

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

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

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

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

בחירה או יצירה של פרויקט ב-Google Cloud

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

הפעלת החיוב

הגדרת Cloud Shell

עכשיו נבדוק שההגדרה שלכם ב-Cloud Shell תקינה. זהו ממשק שורת פקודה שימושי שזמין ישירות ב-Google Cloud Console.

הפעלת Cloud Shell

בפינה השמאלית העליונה של Google Cloud Console, מופיע סמל שנראה כמו טרמינל (>_). לוחצים עליו כדי להפעיל את Cloud Shell.

8e234ad9973e49d4.png

אישור הרשאת הגישה

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

d5e271ec814f5769.png

אימות החשבון:

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

gcloud auth list

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

Credentialed Accounts

ACTIVE: *
ACCOUNT: current_account@example.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

מעבר לחשבון אחר (אם צריך):

אם החשבון הפעיל הוא לא החשבון שבו אתם רוצים להשתמש בסדנת הקוד הזו, אתם צריכים לעבור לחשבון הנכון באמצעות הפקודה הבאה. צריך להחליף את <your_desired_account@example.com> בכתובת האימייל שבה אתם רוצים להשתמש בסדנה הזו:

gcloud config set account <your_desired_account@example.com

אישור הפרויקט

עכשיו צריך לוודא ש-Cloud Shell מוגדר לשימוש בפרויקט הנכון ב-Google Cloud. הפעלה:

gcloud config list project

תוצג רשימת הגדרות. מחפשים את הקטע [core] ומוודאים שערך הפרויקט תואם למזהה של פרויקט Google Cloud שבו רוצים להשתמש ב-Codelab הזה:

[core]
project = <current-project-id>

הגדרת הפרויקט (אם צריך)

אם הערך project ID שגוי, מגדירים אותו לפרויקט הרצוי באמצעות הפקודה הבאה:

gcloud config set project <your-desired-project-id>

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

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

gcloud services enable aiplatform.googleapis.com

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

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

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

‫uv הוא כלי מודרני, מהיר ויעיל לניהול פרויקטים וסביבות של Python, שמשלב פונקציות שבדרך כלל נמצאות בכלים כמו pip,‏ venv,‏ pip-tools ו-pipx. הוא כתוב ב-Rust כדי להבטיח מהירות.

הכלי uv כבר זמין ב-Cloud Shell, כך שאפשר להתחיל מיד.

בדיקה אם uv מותקן בצורה נכונה

uv --version

יצירת תיקיית פרויקט חדשה לסוכן ה-AI

uv init ai-agents-adk
cd ai-agents-adk

יצירת סביבה וירטואלית באמצעות Python 3.12

uv venv --python 3.12

התקנת ספריית Google ADK בסביבה הווירטואלית

uv add google-adk

בדיקה אם חבילת google-adk הותקנה בהצלחה

uv pip list | grep google-adk

אם מופיעה שורת פלט עם google-adk והגרסה שלו, אפשר להמשיך לשלב הבא.

5. יצירת סוכן

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

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

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

כדי ליצור את הקבצים האלה בתיקייה ייעודית לסוכן של העוזר האישי, משתמשים בפקודות הבאות:

uv run 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

לבסוף, תתבקשו לאשר את מזהה הפרויקט ב-Google Cloud ואת האזור. אם הערכים שמולאו מראש (current-project-id ו-current-region) הם הערכים שבהם אתם רוצים להשתמש, פשוט מקישים על Enter לכל שאלה.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

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

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

עכשיו לוחצים על הלחצן Open Editor בחלק העליון של חלון Cloud Shell. לחיצה על הכפתור הזה תעביר אתכם לחלון העריכה, שבו קל יותר לעיין בתוכן של הקבצים. יכול להיות שיעבור זמן עד שהמעבר יתבצע. אם אתם נתקעים במסך טעינה יותר מכמה דקות, נסו לרענן את הדפדפן.

331da4cf37a1e8a4.png

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

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

ad3a52aebdae6142.png

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

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="personal_assistant": מזהה ייחודי של הסוכן. כך ה-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 באותו אזור.

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

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

77e87c904f45d1b2.png

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

מקלידים את הפקודות הבאות בטרמינל:

cd ai-agents-adk
uv run adk run personal_assistant

אם הכול מוגדר בצורה נכונה, תראו פלט דומה במסוף.

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

7. הפעלת הסוכן בממשק המשתמש של הפיתוח

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

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

uv run 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)

יש שתי דרכים לגשת לממשק המשתמש של הפיתוח:

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

9af437bf60562635.png

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

7b779b9601941a12.png

8. הסרת המשאבים

מכיוון שאין מוצרים שפועלים לאורך זמן ב-codelab הזה, מספיק להפסיק את הפעלת הסוכן (למשל, את מופע adk web במסוף) על ידי הקשה על Ctrl + 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, תוכלו לעיין במדריך הרשמי לקבלת הוראות מפורטות.

9. סיכום

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

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