דף זה תורגם על ידי Cloud Translation API.

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

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

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

כדי להתחיל, במדריך הזה מוצגים שני מסלולים: אחד למי שממשיך מה-codelab‏ Building AI Agents with ADK: The Foundation, והשני למי שמתחיל מאפס. בשתי הדרכים האלה תוכלו לוודא שיש לכם את קוד הבסיס הנחוץ של הנציג כדי להתחיל.

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

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

הבנה של מושגים בבינה מלאכותית גנרטיבית
מיומנות בסיסית בתכנות ב-Python
השלמתם את ה-codelab‏ Building AI Agents with ADK: The Foundation או codelab דומה

מה תלמדו

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

מה צריך

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

2. מבוא

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

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

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

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

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

3. תחילת העבודה: הנציג הבסיסי

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

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

אם סיימתם את ה-Codelab‏ Building AI Agents with ADK: The Foundation (יצירת סוכני AI באמצעות ADK: הבסיס), אתם מוכנים להמשיך. אפשר להמשיך לעבוד בספריית הפרויקטים הקיימת ב-ai-agents-adk.

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

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

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

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

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

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

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

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

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

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

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

touch 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)]
)

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

uv run adk web

כשהסוכן יחזור לפעולה, שואלים שוב את אותה שאלה: "מה שער ההמרה מדולר סינגפורי לין יפני?"

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

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

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

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

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

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

כדי לעשות את זה, צריך לערוך את הקובץ agent.py באופן הבא:

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

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), 
        google_search,
    ]
)

אחרי שעורכים את הקובץ, מפעילים מחדש את מופע adk web. למקרה ששכחתם,

לוחצים על הטרמינל, מקישים על Ctrl + C או על Cmd + C כדי לעצור את המופע
uv run adk web כדי להפעיל את המופע
אפשר לשאול את אותה שאלה: "What is the weather forecast in Tokyo, Japan for next month?‎"

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

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

עכשיו, יוצרים קובץ Python בשם custom_agents.py בתיקייה personal_assistant.

touch personal_assistant/custom_agents.py

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

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.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 import agent_tool

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), 
        agent_tool.AgentTool(agent=google_search_agent),
    ]
)

נפרט את התבנית החדשה והעוצמתית בקוד:

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

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

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

עכשיו, מפעילים מחדש את

adk web

instance ולשאול שוב את השאלה הבאה את הסוכן: "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 או Cmd + C) ולהתקין ספריות נוספות בסביבה הווירטואלית הנוכחית של Python. לשם כך, מקלידים את הפקודות הבאות בטרמינל.

uv add langchain-community
uv add wikipedia

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

עכשיו, יוצרים קובץ Python בשם third_party_tools.py בתיקייה personal_assistant.

touch 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 Wikipedia. מעתיקים את הקוד הבא אל third_party_tools.py באמצעות Cloud Editor:

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 import agent_tool
from google.adk.tools import langchain_tool

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), 
        agent_tool.AgentTool(agent=google_search_agent),
        langchain_tool.LangchainTool(langchain_wikipedia_tool),
    ]
)

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

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

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

יצירת סוכני 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`