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

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

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

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

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

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

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

מה תלמדו

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

מה תצטרכו

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

2. מבוא

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

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

‫ADK מציע שלוש קטגוריות של כלים:

  1. כלים לפונקציות: כלים בהתאמה אישית שאתם מפתחים כדי לענות על הדרישות הייחודיות של האפליקציה, כמו פונקציות וסוכנים מוגדרים מראש.
  2. כלים מובנים: כלים מוכנים לשימוש שמסופקים על ידי המסגרת לפעולות נפוצות, כמו חיפוש Google והרצת קוד.
  3. כלים של צד שלישי: ספריות חיצוניות פופולריות כמו Serper וכלים מ-LangChain ומ-CrewAI.

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

3. תחילת העבודה: סוכן הבסיס

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

נתיב א': המשך מ-Codelab בנושא Foundation

אם סיימתם את שיעור ה-Codelab יצירה של סוכני AI באמצעות ADK: עקרונות היסוד, אתם מוכנים להמשך. אפשר להמשיך לעבוד בספריית הפרויקטים הקיימת של ai-agents-adk.

אם לא מופיע (ai-agents-adk) בהנחיה של Cloud Shell, מריצים את הפקודות הבאות כדי להפעיל את הסביבה הווירטואלית של Python:

cd ~/ai-agents-adk
source .venv/bin/activate

נתיב ב': מתחילים מחדש

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

  1. הגדרת שירותי Google Cloud
  2. יצירת סביבה וירטואלית של Python
  3. יצירת סוכן
  4. הפעלת הסוכן בממשק המשתמש למפתחים

אחרי שתשלימו את השלבים, תוכלו להתחיל את מסע הלמידה שלכם.

4. יצירת כלי מותאם אישית להמרת מטבעות

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

נניח שאתם מתכוננים לנסוע ליפן בחודש הבא ואתם רוצים לבדוק את שער החליפין הנוכחי. שואלים את הסוכן "What is the exchange rate from Singapore dollars to Japanese yen?" (מהו שער החליפין מדולר סינגפורי לין יפני?)

7b3c502f88e8ab80.png

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

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

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

יצירת קובץ custom_functions.py

מריצים את הפקודה הזו בטרמינל כדי ליצור קובץ Python בשם custom_functions.py בתיקייה personal_assistant וגם לפתוח אותו בכלי לעריכת קוד.

cloudshell edit personal_assistant/custom_functions.py

כך צריך להיראות מבנה התיקיות עכשיו:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    └── custom_functions.py

קובץ custom_functions.py זה יכיל את פונקציית Python שאחראית לאחזור נתוני שער חליפין מ-API חיצוני. מעתיקים את הקוד הבא ומדביקים אותו בקובץ:

import requests

# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
        """
        Fetches the current exchange rate between two currencies.

        Args:
                base: The base currency (e.g., "SGD").
                target: The target currency (e.g., "JPY").

        Returns:
                The exchange rate information as a json response,
                or None if the rate could not be fetched.
        """
        base_url = "https://hexarate.paikama.co/api/rates/latest"
        api_url = f"{base_url}/{base}?target={target}"

        response = requests.get(api_url)
        if response.status_code == 200:
                return response.json()

עכשיו עורכים את הקובץ agent.py: מייבאים את הפונקציה get_fx_rate ומקצים אותה כ-FunctionTool.

עדכון קובץ agent.py

מעתיקים את בלוק הקוד הזה ומחליפים את התוכן הקיים בקובץ agent.py:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

from .custom_functions import get_fx_rate

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',
    tools=[FunctionTool(get_fx_rate)]
)

אחרי השינויים, מפעילים מחדש את הסוכן על ידי הקלדה של:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

כשהנציג יתחבר, שואלים שוב את אותה שאלה: "What is the exchange rate from Singapore dollars to Japanese yen?" (מהו שער החליפין מדולר סינגפורי לין יפני?)

הפעם אמור להופיע שער החליפין בפועל שמוצג בכלי get_fx_rate.

76b1647fbfc0687a.png

אתם מוזמנים לשאול כל שאלה שקשורה להמרת מטבע.

5. שילוב עם כלי חיפוש Google המובנה

הסוכן יכול עכשיו לספק שערי חליפין, והמשימה הבאה היא לקבל את תחזית מזג האוויר לחודש הבא. שואלים את הסוכן את השאלה "What is the weather forecast in Tokyo, Japan for next month?"

399f40c4ea3e0bb3.png

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

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

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

יצירת קובץ custom_agents.py

כדי ליצור קובץ Python בשם custom_agents.py בתיקייה personal_assistant ולפתוח אותו ב-Code Editor, מריצים את הפקודה הבאה בטרמינל:

cloudshell edit personal_assistant/custom_agents.py

כך צריך להיראות מבנה התיקיות עכשיו:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.py

קובץ custom_agents.py הזה יכיל את הקוד של google_search_agent המיוחד. מעתיקים את הקוד הבא לקובץ custom_agents.py:

from google.adk.agents import Agent
from google.adk.tools import google_search


# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-3.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

אחרי שיוצרים את הקובץ, מעדכנים את קובץ agent.py כמו שמוצג בהמשך.

עדכון קובץ agent.py

מעתיקים את בלוק הקוד הזה ומחליפים את התוכן הקיים בקובץ agent.py:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-3.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate),
        AgentTool(agent=google_search_agent),
    ]
)

נבחן את התבנית החדשה והעוצמתית בקוד:

  • סוכן מומחה חדש: הגדרנו סוכן חדש לגמרי, google_search_agent. שימו לב לתיאור הספציפי שלו ולכך שהכלי היחיד שלו הוא google_search. הוא מומחה לחיפוש.
  • ‫agent_tool.AgentTool: זוהי עטיפה מיוחדת מ-ADK. הוא לוקח סוכן שלם (google_search_agent שלנו) ואורז אותו כך שייראה ויתפקד כמו כלי רגיל.
  • ‫root_agent חכם יותר: root_agent כולל עכשיו כלי חדש: AgentTool(agent=google_search_agent). הוא לא יודע איך לחפש באינטרנט, אבל הוא יודע שיש לו כלי שאפשר להעביר אליו משימות חיפוש.

שימו לב ששדה ההוראות נעלם מ-root_agent. ההוראות שלו מוגדרות עכשיו באופן מרומז על ידי הכלים שזמינים לו.

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

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

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

אחרי שהסוכן יפעל, שואלים אותו שוב את השאלה "What is the weather forecast in Tokyo, Japan for next month?"‎

8a2a6d9532b54301.png

הסוכן משתמש עכשיו ב-google_search_agent כדי לקבל את המידע העדכני ביותר

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

ff3739a0b5ede6c2.png

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

6. שימוש בכלי ויקיפדיה של LangChain

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

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

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

קודם כול, עוצרים את תהליך הסוכן הפועל (Ctrl + C) ומתקינים ספריות נוספות בסביבה הווירטואלית הנוכחית של Python על ידי הקלדת הפקודות הבאות בטרמינל.

uv pip install langchain-community wikipedia

יצירת קובץ third_party_tools.py

הפקודה הבאה יוצרת קובץ Python בשם third_party_tools.py בתיקייה personal_assistant ופותחת אותו ב-Cloud Editor:

cloudshell edit personal_assistant/third_party_tools.py

כך צריך להיראות מבנה התיקיות עכשיו:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    ├── custom_agents.py
    └── third_party_tools.py

הקובץ הזה יכיל את ההטמעה של כלי ויקיפדיה של LangChain. מעתיקים את הקוד הבא לקובץ third_party_tools.py:

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)

# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks, concepts, and places."
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

עדכון קובץ agent.py

מעדכנים את הקובץ agent.py עם התוכן הבא:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.langchain_tool import LangchainTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool


root_agent = Agent(
    model='gemini-3.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate),
        AgentTool(agent=google_search_agent),
        LangchainTool(langchain_wikipedia_tool),
    ]
)

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

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

כשהסוכן מוכן, שואלים אותו את השאלה הבאה: "ספר לי על ההיסטוריה של קיוטו".

9098274a483dee32.png

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

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

eb2cdb9806cd3734.png

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

119d55bfb0b36e17.png

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

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

8. סיכום

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

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

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