ADK: From Basics to Multi-Tool Agents

1. מבוא

בשיעור Codelab הזה נסביר איך ליצור סוכנים באמצעות ADK, החל מהיסודות ועד לפיתוח סוכנים מרובי-כלים.

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

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

מודלים גדולים של שפה (LLM) לעומת סוכנים

המוח (LLM): מספק חשיבה רציונלית, תכנון והבנת שפה טבעית (NLU). הוא מחליט מה צריך לעשות.

הידיים (כלים): אלה ממשקי ה-API, ערכות ה-SDK והפונקציות המותאמות אישית שמאפשרות לסוכן ליצור אינטראקציה עם העולם האמיתי. הוא מבצע את התוכנית.

הערכה לפיתוח סוכנים (ADK)

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

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

מה תפַתחו

בשיעור Codelab הזה נסביר איך ליצור את סוכן 'טיפים לתזונה בריאה', יועץ תזונה חכם שעובר מניתוח טקסט פשוט למרכז עוצמתי של כלים. תתחילו ביצירת סוכן שיחה בסיסי שמבין מושגים בתחום התזונה, ואז תציידו אותו בהדרגה בכלי Storage SDK לארכיון של תמונות רכיבים ובכלי Vision ל'קריאה' ולניתוח של התמונות האלה. בסיום ה-Lab הזה, יהיה לכם כלי תזמור עם פונקציונליות מלאה שיכול לקבל תמונה של תווית מזון שהועלתה, לשמור אותה בדלי ב-Cloud לצורך תיעוד, ולספק באופן מיידי 'טיפים בריאותיים' לכל רכיב.

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

• פרויקט ב-Google Cloud עם חיוב מופעל
• דפדפן אינטרנט

יצירת הפרויקט

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

הפעלת Cloud Shell

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

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

gcloud auth list

• מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט:

gcloud config list project

• אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:

gcloud config set project <YOUR_PROJECT_ID>

אפשר לעיין במאמרי העזרה בנושא פקודות gcloud ושימוש בהן.

פתיחת כלי העריכה

• בשיעור Codelab הזה נשתמש בעורך המובנה של Cloud. בחלון Cloud Shell, לוחצים על הלחצן Open editor (פתיחת כלי העריכה) בפינה השמאלית העליונה. ייפתח כלי העריכה של VSCode.

3. הגדרת ADK

נעבור לטרמינל Cloud Shell שהפעלנו בקטע הקודם:

• יצירה והפעלה של סביבה וירטואלית (מומלץ)

בטרמינל של Cloud Shell, יוצרים סביבה וירטואלית:

python -m venv .venv

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

source .venv/bin/activate

• התקנת ADK

pip install google-adk

4. מפתח Google API

יצירת מפתח Google API באמצעות AI Studio:

• עוברים אל https://aistudio.google.com/ ובתפריט הימני התחתון לוחצים על Get API Key

• יופיע חלון API Keys (מפתחות API). לוחצים על Create API key (יצירת מפתח API) בחלון הזה:

• יופיע חלון קופץ ליצירת מפתח חדש. נותנים למפתח את השם: healthy-hints-key

עוברים לתפריט הנפתח 'בחירת פרויקט מיובא'.

• לוחצים על Import Project. בחלון הצדדי שמופיע, בוחרים את אחד מהפרויקטים ב-Google Cloud שרוצים לעבוד איתו.

לוחצים על 'ייבוא'.

• הרשימה הנפתחת תעודכן עם הפרויקט שיובא. בוחרים את הפרויקט מהתפריט הנפתח. לוחצים על Create Key now (יצירת מפתח). תוצג רשימת מפתחות ה-API שנוצרו. לוחצים על סמל ההעתקה של מפתח ה-API שיצרתם.

5. סוכן לדוגמה

• במסוף Cloud Shell, יוצרים ספריית שורש לסוכן במיקום הפרויקט הרצוי:

adk create healthy_hints

אפשר לבחור כל מודל, אבל בשיעור Codelab הזה נשתמש במודל gemini-2.5-flash

ב-Codelab הזה נשתמש ב-Google AI. מדביקים את מפתח ה-API שיצרתם בשלב הקודם.

• נפתח את התיקייה שיצרנו עכשיו. בתפריט הימני ביותר, לוחצים על הסמל , לוחצים על קובץ -> פתיחת תיקייה. בוחרים את התיקייה healthy_hints שנוצרה, שבדרך כלל נמצאת בתיקייה /home/<username>.
• מבנה התיקיות healthy_hints בדרך כלל נראה כך:

• יוצג קובץ ‎ .env שמכיל את מפתח Google API. אפשר להשתמש בקובץ הזה כדי להגדיר כל משתנה סביבה.
• נוצר גם קובץ נוסף בשם agent.py, והוא קובץ הסוכן הראשי שלנו. כאן נוצר סוכן לדוגמה ברמת הבסיס. בואו נבדוק את התוכן של הקובץ הזה. קודם מייבאים את llm_agent מ-ADK. לאחר מכן, אנחנו משתמשים ב-ADK DSL כדי ליצור את סוכן הבסיס. אנחנו מציינים את שם המודל כ-Gemini-2.5-flash, נותנים לנציג שם ומספקים תיאור נחמד שלו. ההוראה היא הדבר הכי חשוב כאן. זה המקום שבו אנחנו אומרים לנציג מה הוא צריך לעשות בשפה טבעית.
• הסוכן לדוגמה הזה הוא די כללי, הוא פשוט יענה על כל שאלה של משתמש.
• עכשיו נפעיל את הסוכן הזה באופן מקומי. יש שתי דרכים לתקשר עם הסוכן הזה : CLI ואינטרנט.
• ‫CLI: מריצים את הפקודה הבאה מחוץ לספרייה healthy_hints

adk run healthy_hints

או אם אתם נמצאים בספרייה healthy_hints, מריצים את הפקודה הבאה:

adk run .

הפלט שיוצג יהיה דומה לזה:

אפשר לכתוב 'היי' או כל שאלה אחרת. התשובה עשויה להיות שונה עבור כל אחד ואחת, זה הטבע של AI גנרטיבי.

• אינטרנט: מריצים את הפקודה הבאה מהספרייה הראשית של healthy_hints :

adk web

6. סוכן מולטיטול

כלי הוא קטע קוד מודולרי – בדרך כלל פונקציה או API – שמאפשר לנציג ליצור אינטראקציה עם העולם מעבר לידע הפנימי שלו.

סוגי כלים ב-ADK

• כלים לפונקציות: לוגיקה מותאמת אישית שאתם כותבים בעצמכם. לדוגמה, פונקציה שמתחברת למסד הנתונים הספציפי שלכם או 'כלי ניתוח יומנים' בהתאמה אישית לפורמט הייחודי של החברה שלכם.
• כלים מובנים: יכולות מוכנות לשימוש שסופקו על ידי Google או ADK, כמו חיפוש Google, Code Interpreter או Google RAG Engine.
• Agents-as-Tools: במערכות מתקדמות של 'כלים מרובים' או 'סוכנים מרובים', סוכן אחד מיוחד יכול לשמש ככלי עבור סוכן אחר. לדוגמה, 'סוכן חיפוש' יכול להיות כלי שמשמש 'סוכן מנהל מחקר'.

ב-Codelab הזה נסביר על כלי הפונקציות. עכשיו נשפר את הסוכן ונהפוך אותו לכלי רב-תכליתי.

נוסיף שיטה חדשה get_weather בקובץ agent.py

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

בואו נשנה את הקובץ agent.py ונשנה את השם, התיאור וההוראות של הסוכן:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

עד עכשיו יצרנו רק כלי אחד. עכשיו ניצור כמה כלים:

ניצור שיטה נוספת בשם get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

בואו נשנה את הסוכן כדי להפעיל גם את הכלי הזה:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

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

7. שילוב SDK

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

• קודם ניצור קטגוריה ב-Google Cloud Storage כדי להעלות את התמונה. פותחים כרטיסייה חדשה ועוברים לכתובת https://console.cloud.google.com/. בסרגל החיפוש, מקלידים cloud storage. עכשיו בוחרים באפשרות Cloud Storage בקטע Products & pages (מוצרים ודפים):

תועברו לדף הסקירה הכללית של Google Cloud Storage. לוחצים על הלחצן Create bucket. בדף 'יצירת קטגוריה', מזינים את שם הקטגוריה. השם יכול להיות כל דבר, אבל ב-Codelab הזה נשתמש בשם healthy-hints-bucket-kolkata . משאירים את כל שאר ההגדרות כמו שהן ולוחצים על הלחצן Create.

• ניצור קובץ חדש בשם requirements.txt ונוסיף לו את google-cloud-storage. נשתמש ב-Python Storage SDK כדי להעלות את התמונה ל-Storage.

קודם נתקין את יחסי התלות:

pip install -r requirements.txt

יכול להיות שתצטרכו להפעיל קודם את Storage API. כדי לעשות זאת, מריצים את הפקודה הבאה בטרמינל:

gcloud services enable storage.googleapis.com 

עכשיו נוסיף כלי חדש להעלאת התמונה.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

• עכשיו נעדכן את הסוכן כדי שישתמש בכלי החדש:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

• עכשיו נוסיף עוד כלי שיקריא את רשימת הרכיבים שבתמונה. נוסיף את google-cloud-vision ב-requirements.txt ונתקין את התלות החדשה.

pip install -r requirements.txt

שוב, יכול להיות שתצטרכו להפעיל קודם את Vision API. כדי לעשות זאת, מריצים את הפקודה הבאה בטרמינל:

gcloud services enable vision.googleapis.com

עכשיו נוסיף כלי חדש read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

ועכשיו נעדכן את הסוכן שלנו כדי להשתמש בכלי הזה

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. סיכום

כל הכבוד, סיימתם את ה-Codelab בנושא טיפים לשמירה על הבריאות! הצלחתם להפוך AI רגיל מכלי ליצירת טקסט לסוכן פרואקטיבי רב-תכליתי. באמצעות ADK, שילבתם את Vision API ואת Cloud Storage SDK, וכך הענקתם לסוכן שלכם את היכולת לקרוא תוויות ואת היכולת לאחסן אותן בארכיון. ראיתם איך הסוכן מחליט באופן אוטונומי מתי לשמור קובץ ואיך לפרש נתונים גולמיים כדי לספק ייעוץ בריאותי שמתייחס למקרים מהעולם האמיתי.

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