יצירה ופריסה של סוכן ADK שמשתמש בשרת MCP ב-Cloud Run

1. מבוא

ב-Lab הזה מתמקדים בהטמעה ובפריסה של שירות סוכן לקוח. תשתמשו ב-Agent Development Kit (ערכה לפיתוח סוכנים, ADK) כדי ליצור סוכן AI שמשתמש בכלים מרוחקים כמו שרת ה-MCP שנוצר ב-Lab 1. העיקרון הארכיטקטוני המרכזי שמוצג הוא הפרדה בין תחומים, עם שכבת חשיבה רציונלית נפרדת (ה-Agent) שמתקשרת עם שכבת כלים נפרדת (שרת ה-MCP) באמצעות API מאובטח.

בשיעור Lab 1, יצרתם שרת MCP שמספק נתונים על בעלי החיים בגן חיות פיקטיבי למודלים גדולים של שפה (LLM), למשל כשמשתמשים ב-Gemini CLI. בשיעור ה-Lab הזה נבנה סוכן מדריך סיורים לגן החיות הבדיוני. הסוכן ישתמש באותו שרת MCP ממעבדה 1 כדי לגשת לפרטים על בעלי החיים בגן החיות, וגם ישתמש בוויקיפדיה כדי ליצור את חוויית הסיור הטובה ביותר.

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

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

• שרת MCP שפועל ב-Cloud Run או כתובת ה-URL של השירות המשויך אליו.
• פרויקט ב-Google Cloud שהחיוב בו מופעל.

מה תלמדו

• איך לבנות פרויקט Python לפריסת ADK.
• איך מטמיעים סוכן שמשתמש בכלי באמצעות google-adk.
• איך מחברים סוכן לשרת MCP מרוחק כדי להשתמש בכלי העבודה שלו.
• איך פורסים אפליקציית Python כקונטיינר ללא שרת ב-Cloud Run.
• איך מגדירים אימות מאובטח בין שירותים באמצעות תפקידים ב-IAM.
• איך מוחקים משאבי Cloud כדי להימנע מעלויות עתידיות.

מה תצטרכו

• חשבון Google Cloud ופרויקט Google Cloud
• דפדפן אינטרנט כמו Chrome

2. למה כדאי לפרוס ל-Cloud Run?

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

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

תכונות עיקריות

הפעלת Containers Anywhere:

• אתם מביאים קונטיינר (קובץ אימג' של Docker) שהאפליקציה שלכם נמצאת בתוכו.
• ‫Cloud Run מריץ אותו בתשתית של Google.
• אין צורך בתיקון מערכת ההפעלה, בהגדרת מכונה וירטואלית או בהתמודדות עם בעיות בהתאמה לעומס.

התאמה אוטומטית של נפח האחסון:

• אם אף אחד לא משתמש באפליקציה → 0 מופעים פועלים (ההיקף מצטמצם ל-0 מופעים, מה שחוסך עלויות).
• אם נשלחות 1,000 בקשות → המערכת מפעילה כמה עותקים שצריך.

בלי שמירת מצב כברירת מחדל:

• כל בקשה יכולה להישלח למופע אחר.
• אם אתם צריכים לאחסן מצב, אתם יכולים להשתמש בשירות חיצוני כמו Cloud SQL,‏ Firestore או Memorystore.

תמיכה בכל שפה או מסגרת:

• כל עוד האפליקציה פועלת במאגר Linux, לא משנה ל-Cloud Run אם היא כתובה ב-Python, ב-Go, ב-Node.js, ב-Java או ב-‎ .Net.

תשלום לפי שימוש:

• חיוב לפי בקשה: חיוב לפי בקשה + זמן מחשוב (עד 100 אלפיות השנייה).
• חיוב לפי מופע: חיוב על משך החיים המלא של המופע (ללא עמלה לכל בקשה).

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

הגדרת סביבה בקצב אישי

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

• שם הפרויקט הוא השם המוצג של הפרויקט הזה למשתתפים. זו מחרוזת תווים שלא נמצאת בשימוש ב-Google APIs. תמיד אפשר לעדכן את המיקום.
• מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שהוא מוגדר). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית, ובדרך כלל לא צריך לדעת מה היא. ברוב ה-Codelabs, תצטרכו להפנות למזהה הפרויקט (בדרך כלל מסומן כ-PROJECT_ID). אם אתם לא אוהבים את המזהה שנוצר, אתם יכולים ליצור מזהה אקראי אחר. אפשר גם לנסות כתובת משלכם ולבדוק אם היא זמינה. אי אפשר לשנות את הערך הזה אחרי השלב הזה, והוא יישאר כזה למשך הפרויקט.
• לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. במאמרי העזרה מפורט מידע נוסף על שלושת הערכים האלה.

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

הערה: אם אתם משתמשים בחשבון Gmail, אתם יכולים להשאיר את המיקום שמוגדר כברירת מחדל כללא ארגון. אם אתם משתמשים בחשבון Google Workspace, אתם צריכים לבחור מיקום שמתאים לארגון שלכם.

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

מפעילים את Cloud Shell

1. עוברים אל Cloud Shell Editor.
2. אם הטרמינל לא מופיע בתחתית המסך, פותחים אותו:
   • לוחצים על Terminal (מסוף).
   • לוחצים על New Terminal (טרמינל חדש).
   
3. בטרמינל, מגדירים את הפרויקט באמצעות הפקודה הבאה. אם השלמתם את מעבדת 1, ודאו שאתם משתמשים באותו מזהה פרויקט:
   ‫

   gcloud config set project [YOUR-PROJECT-ID]
   

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

   gcloud projects list | awk '/PROJECT_ID/{print $2}'
   

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

5. תוצג ההודעה הבאה:

   Updated property [core/project].
   

   אם מופיע WARNING ומוצגת השאלה Do you want to continue (Y/n)?, כנראה שהזנתם את מזהה הפרויקט בצורה שגויה. לוחצים על n, לוחצים על Enter ומנסים להריץ שוב את הפקודה gcloud config set project.

4. הגדרת הסביבה

הפעלת ממשקי API והגדרת משתני סביבה

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

gcloud services enable \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    aiplatform.googleapis.com

הפלט הצפוי

Operation "operations/acat.p2-[GUID]" finished successfully.

יוצרים את ספריית הפרויקט.

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

cd && mkdir zoo_guide_agent && cd zoo_guide_agent

יוצרים את קובץ ה-requirements.txt. בקובץ הזה מפורטות ספריות Python שהסוכן צריך. הפקודה הבאה יוצרת את הקובץ ומאכלסת אותו.

cloudshell edit requirements.txt

google-adk==1.14.0
langchain-community==0.3.27
wikipedia==1.4.0

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

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export SA_NAME=lab2-cr-service
export SERVICE_ACCOUNT="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for lab 2 "

יוצרים ופותחים קובץ .env כדי לאמת את הסוכן בספרייה zoo_guide_agent.

cloudshell edit .env

הפקודה cloudshell edit תפתח את הקובץ .env בעורך שמעל הטרמינל. מזינים את הפקודות הבאות בקובץ .env וחוזרים לטרמינל.

MODEL="gemini-2.5-flash"

מוסיפים את כתובת ה-URL של שרת ה-MCP. אם סיימתם את Lab 1, אתם יכולים לפעול לפי השלבים הבאים כדי להשתמש בשרת ה-MCP שיצרתם ב-Lab 1:

הערה: אם השלמתם את שיעור Lab 1 ואתם רוצים להשתמש בשרת ה-MCP שנוצר בשיעור הזה, מריצים את שלוש הפקודות הבאות. אם אתם כבר משתמשים בקישור הציבורי לשרת ה-MCP שקיבלתם במהלך אירוע בשידור חי, אתם לא צריכים להריץ את שתי הפקודות האלה.

נותנים לחשבון השירות של הסוכן הרשאות להשתמש ב-Gemini ב-Vertex AI ולבצע קריאה לשרת ה-MCP המרוחק:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

שומרים את כתובת ה-URL של שרת ה-MCP ממעבדה 1 במשתנה סביבה.

echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp" >> .env

אם אתם משתמשים בקישור ציבורי לשרת MCP, מריצים את הפקודה הבאה ומחליפים את PROJECT_NUMBER בערך שמופיע.

echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp" >> .env

5. יצירת תהליך עבודה של סוכן

יוצרים קובץ init.py

יוצרים את הקובץ init.py. הקובץ הזה אומר ל-Python שהספרייה zoo_guide_agent היא חבילה.

cloudshell edit __init__.py

הפקודה הקודמת פותחת את עורך הקוד. מוסיפים את הקוד הבא אל __init__.py:

from . import agent

יצירת הקובץ הראשי agent.py

יוצרים את הקובץ הראשי agent.py. הפקודה הזו יוצרת את קובץ ה-Python ומדביקה בו את הקוד המלא של מערכת מרובת הסוכנים.

cloudshell edit agent.py

ייבוא והגדרה ראשונית

הבלוק הראשון הזה כולל את כל הספריות הנדרשות מ-ADK ומ-Google Cloud. הסקריפט גם מגדיר רישום ביומן ומטען את משתני הסביבה מקובץ .env, וזה חיוני לגישה לכתובת ה-URL של המודל והשרת.

מוסיפים את הקוד הבא לקובץ agent.py:

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

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

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")

הגדרת הכלים (היכולות של הסוכן)

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

מוסיפים את הקוד הבא לתחתית הקובץ agent.py:

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}


# Configuring the MCP Tool to connect to the Zoo MCP server

mcp_server_url = os.getenv("MCP_SERVER_URL")
if not mcp_server_url:
    raise ValueError("The environment variable MCP_SERVER_URL is not set.")

def get_id_token():
    """Get an ID token to authenticate with the MCP server."""
    target_url = os.getenv("MCP_SERVER_URL")
    audience = target_url.split('/mcp/')[0]
    request = google.auth.transport.requests.Request()
    id_token = google.oauth2.id_token.fetch_id_token(request, audience)
    return id_token

"""
# Use this code if you are using the public MCP Server and comment out the code below defining mcp_tools
mcp_tools = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url=mcp_server_url
    )
)
"""

mcp_tools = MCPToolset(
            connection_params=StreamableHTTPConnectionParams(
                url=mcp_server_url,
                headers={
                    "Authorization": f"Bearer {get_id_token()}",
                },
            ),
        )

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

הסבר על שלושת הכלים

1. add_prompt_to_state 📝

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

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

2. MCPToolset 🦁

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

איך: הוא מתחבר בצורה מאובטחת לכתובת ה-URL של השרת הפרטי של גן החיות. הוא משתמש ב-get_id_token כדי לקבל באופן אוטומטי "כרטיס מפתח" מאובטח (אסימון מזהה של חשבון שירות) כדי להוכיח את הזהות שלו ולקבל גישה.

3. LangchainTool 🌍

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

איך: הוא פועל כמתאם, ומאפשר לסוכן שלנו להשתמש בכלי WikipediaQueryRun שנבנה מראש מתוך ספריית LangChain.

מקורות מידע:

• חבילת הכלים של ה-MCP
• כלים לפונקציות
• מדינה

הגדרת סוכנים מומחים

בשלב הבא נגדיר את סוכן החוקר ואת סוכן מעצב התשובות. הסוכן החוקר הוא ה "מוח" של הפעולה שלנו. הסוכן מקבל את ההנחיה של המשתמש מ-State המשותף, בודק את הכלים המתקדמים שלו (הכלי של שרת ה-MCP של Zoo והכלי של ויקיפדיה) ומחליט באילו כלים להשתמש כדי למצוא את התשובה.

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

מוסיפים את הקוד הבא לחלק התחתון של agent.py:

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    {{ PROMPT }}
    """,
    tools=[
        mcp_tools,
        wikipedia_tool
    ],
    output_key="RESEARCH_DATA" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    {{ RESEARCH_DATA }}
    """
)

הסוכן של תהליך העבודה

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

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

מוסיפים את בלוק הקוד הזה לתחתית של agent.py:

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

הרכבת תהליך העבודה הראשי

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

מוסיפים את בלוק הקוד הסופי הזה לחלק התחתון של agent.py:

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

הקובץ agent.py הושלם. הבנייה הזו מאפשרת לראות איך לכל רכיב – כלים, סוכני עובדים וסוכני ניהול – יש תפקיד ספציפי ביצירת המערכת הסופית והחכמה. השלב הבא הוא פריסה.

6. פריסת הסוכן באמצעות ADK CLI

אחרי שהקוד המקומי מוכן והפרויקט בענן מוכן, הגיע הזמן לפרוס את הסוכן. תשתמשו בפקודה adk deploy cloud_run, כלי נוח שמבצע אוטומציה של כל תהליך הפריסה. הפקודה הזו אורזת את הקוד, יוצרת קובץ אימג' של קונטיינר, מעבירה אותו בדחיפה ל-Artifact Registry ומפעילה את השירות ב-Cloud Run, כך שאפשר לגשת אליו באינטרנט.

Deploy

מריצים את הפקודות הבאות כדי לפרוס את הסוכן. הפקודה uvx מאפשרת להריץ כלי שורת פקודה שפורסמו כחבילות Python בלי לדרוש התקנה גלובלית של הכלים האלה.

הערה: הפקודה הזו תימשך כמה דקות.

# Run the deployment command
uvx --from google-adk==1.14.0 \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --labels=dev-tutorial=codelab-adk \
  --service-account=$SERVICE_ACCOUNT

אישור בקשות לאימות

יכול להיות שתופיע ההודעה הבאה:

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?

מקלידים Y ומקישים על ENTER.

יכול להיות שתופיע ההודעה הבאה:

Allow unauthenticated invocations to [your-service-name] (y/N)?.

בשיעור ה-Lab הזה אנחנו רוצים לאפשר הפעלות לא מאומתות כדי להקל על הבדיקה. מקלידים y ומקישים על Enter.

הערה: לכל מי שיש את כתובת ה-URL תהיה גישה לסוכן הזה, ולכן השיטה הזו מתאימה בעיקר לבדיקות.

קבלת קישור לפריסה

אחרי שהפקודה תופעל בהצלחה, היא תספק את כתובת ה-URL של שירות Cloud Run שנפרס. (היא תיראה בערך כך: https://zoo-tour-guide-123456789.europe-west1.run.app). מעתיקים את כתובת ה-URL הזו למשימה הבאה.

7. בדיקת הסוכן שנפרס

עכשיו שהסוכן פעיל ב-Cloud Run, צריך לבצע בדיקה כדי לוודא שהפריסה הצליחה והסוכן פועל כמו שצריך. תשתמשו בכתובת ה-URL הציבורית של השירות (למשל https://zoo-tour-guide-123456789.europe-west1.run.app/) כדי לגשת לממשק האינטרנט של ADK ולקיים אינטראקציה עם הסוכן.

פותחים את כתובת ה-URL הציבורית של שירות Cloud Run בדפדפן האינטרנט. בגלל שהשתמשת ב---with_ui flag, אמור להופיע ממשק המשתמש של מפתח ה-ADK.

מעבירים את המתג Token Streaming בפינה השמאלית העליונה למצב מופעל.

עכשיו אפשר לתקשר עם נציג הגן.

כדי להתחיל שיחה חדשה, מקלידים hello ולוחצים על Enter.

בודקים את התוצאה. הסוכן צריך להגיב במהירות עם ברכה:

"Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"

אפשר לשאול את הסוכן שאלות כמו:

Where can I find the polar bears in the zoo and what is their diet?

הסבר על Agent Flow

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

1. הדלפק לקבלת פנים בגן החיות

התהליך כולו מתחיל בסוכן המקבל את הפנייה.

התפקיד שלו: להתחיל את השיחה. ההוראה היא לברך את המשתמש ולשאול אותו על איזו חיה הוא רוצה לקבל מידע.

הכלי שלו: כשהמשתמש משיב, ה-Greeter משתמש בכלי add_prompt_to_state כדי לתעד את המילים המדויקות שלו (למשל, "תספר לי על אריות") ולשמור אותן בזיכרון של המערכת.

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

2. החוקר המקיף (החוקר העל)

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

התפקיד שלו: לנתח את השאלה של המשתמש וליצור תוכנית חכמה. הוא משתמש ביכולת החזקה של מודל השפה להשתמש בכלים כדי להחליט אם הוא צריך:

• נתונים פנימיים מהרשומות של גן החיות (דרך שרת ה-MCP).
• ידע כללי מהאינטרנט (באמצעות Wikipedia API).
• או בשתיהן, אם השאלה מורכבת.

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

3. הכלי לעיצוב תשובות (הכלי להצגת מידע)

אחרי שסוכן המחקר המקיף אוסף את כל העובדות, זה הסוכן האחרון שמופעל.

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

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

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

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

1. מסמכי ADK
2. יצירת כלים בהתאמה אישית לסוכני ADK

8. ניקוי הסביבה

gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet

9. מזל טוב

כל הכבוד, סיימתם את ה-Codelab.

מה נכלל

• איך לבנות פרויקט Python לפריסה באמצעות ממשק שורת הפקודה של ADK.
• איך מטמיעים תהליך עבודה עם כמה סוכנים באמצעות SequentialAgent ו-ParallelAgent.
• איך מתחברים לשרת MCP מרוחק באמצעות MCPToolset כדי להשתמש בכלים שלו.
• איך להרחיב את הנתונים הפנימיים באמצעות שילוב של כלים חיצוניים כמו Wikipedia API.
• איך פורסים סוכן כקונטיינר בלי שרת (serverless) ב-Cloud Run באמצעות הפקודה adk deploy.

סקר

איך תשתמשו במדריך הזה?

רק קוראים את הטקסט קוראים את הטקסט ומבצעים את התרגילים