ADK: From Basics to Multi-Tool Agents

1. מבוא

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

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

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

מודלי LLM לעומת סוכנים

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

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

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

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

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

מה תפַתחו

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

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

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