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

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

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

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

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

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

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

הבנה של מושגים ב-AI גנרטיבי
מיומנות בסיסית בתכנות ב-Python
השלמתם את שיעור ה-Codelab בנושא יצירה של סוכני AI באמצעות ADK: עקרונות היסוד או שיעור דומה

מה תלמדו

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

מה תצטרכו

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

2. מבוא

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

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

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

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

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

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

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

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

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

נתיב ב': התחלה חדשה

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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-2.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"

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

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

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

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

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

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

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

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

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

מה תלמדו

מה תצטרכו

2. מבוא

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

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

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

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

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

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

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

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

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

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

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

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

השבתה של Vertex AI API

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

8. סיכום

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

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

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

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

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

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