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

פריסה, ניהול ומעקב אחרי סוכן ADK ב-Cloud Run

1. מבוא

הערות חשובות:

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

פתיחת חלון פרטי
אם אתם מצטרפים לסדנה, כתובת ה-URL של פורטל מימוש השוברים בדרך כלל מופיעה בסדנה. אחרת, אתם יכולים לעבור אל פורטל מימוש השוברים של חשבון הניסיון לחיוב.
מתחברים באמצעות חשבון Gmail אישי ( אי אפשר להשתמש בחשבונות Google Workspace או בכתובות אימייל אחרות!) )
פועלים לפי ההוראות המפורטות כדי ליצור פרויקט חדש ב-Google Cloud לצורך המדריך הזה.

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

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

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

במהלך ה-codelab, תשתמשו בגישה שלב אחר שלב באופן הבא:

יצירת מסד נתונים של PostgreSQL ב-CloudSQL לשימוש בשירות סשן מסד הנתונים של סוכן ADK
הגדרה של סוכן ADK בסיסי
הגדרת שירות הפעלות מסד נתונים לשימוש בכלי ADK Runner
פריסה ראשונית של הסוכן ב-Cloud Run
בדיקות עומס ובדיקה של התאמה לעומס (auto-scaling) ב-Cloud Run
פריסת גרסה חדשה של סוכן והגדלה הדרגתית של נפח התנועה לגרסאות חדשות
הגדרת מעקב בענן ובדיקת מעקב של הפעלת סוכן

סקירה כללית של הארכיטקטורה

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

נוח לעבוד עם Python
הבנה של ארכיטקטורת full-stack בסיסית באמצעות שירות HTTP

מה תלמדו

המבנה של ADK וכלי עזר מקומיים
הגדרת סוכן ADK באמצעות שירות הפעלת מסד נתונים
הגדרת PostgreSQL ב-CloudSQL לשימוש בשירות של סשן מסד נתונים
פריסת אפליקציה ב-Cloud Run באמצעות Dockerfile והגדרת משתני סביבה ראשוניים
הגדרה ובדיקה של התאמה אוטומטית לעומס (autoscaling) ב-Cloud Run באמצעות בדיקת עומס
אסטרטגיה להפצה הדרגתית באמצעות Cloud Run
הגדרת מעקב של סוכן ADK ב-Cloud Trace

מה תצטרכו

דפדפן האינטרנט Chrome
חשבון Gmail
פרויקט ב-Cloud עם חיוב מופעל

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

2. 🚀 הכנה להגדרת סדנת פיתוח

שלב 1: בוחרים פרויקט פעיל ב-Cloud Console

במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים או יוצרים פרויקט ב-Google Cloud (ראו את הקטע הימני העליון במסוף).

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

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

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

אם הכותרת Billing / Overview ( בפינה הימנית העליונה של מסוף Cloud ) מופיעה עם הכיתוב Google Cloud Platform Trial Billing Account, הפרויקט שלכם מוכן לשימוש במדריך הזה. אם לא, חוזרים לתחילת המדריך הזה ומממשים את תקופת הניסיון של חשבון החיוב

שלב 2: הכנת מסד נתונים ב-Cloud SQL

בהמשך נצטרך מסד נתונים שישמש את סוכן ה-ADK. ניצור מסד נתונים של PostgreSQL ב-Cloud SQL. קודם כל, עוברים לסרגל החיפוש בחלק העליון של מסוף Cloud ומקלידים 'cloud sql'. לאחר מכן לוחצים על המוצר Cloud SQL.

לאחר מכן, צריך ליצור מכונה חדשה למסד נתונים. לוחצים על Create Instance (יצירת מכונה) ובוחרים באפשרות PostgreSQL.

יכול להיות שתצטרכו גם להפעיל את Compute Engine API אם אתם מתחילים עם פרויקט חדש. אם ההנחיה הזו מופיעה, פשוט לוחצים על Enable API.

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

אחרי זה, מגדירים כאן את שם המופע ואת סיסמת ברירת המחדל למשתמש postgres. אתם יכולים להגדיר את זה עם פרטי הכניסה שאתם רוצים, אבל לצורך המדריך הזה נשתמש ב-adk-deployment כשם המופע וב-ADK-deployment123 כסיסמה.

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

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

שלב 3: הכרת Cloud Shell

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

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

gcloud auth list

אם אתם רואים את כתובת Gmail האישית שלכם כמו בדוגמה שלמטה, הכול בסדר

Credentialed Accounts

ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

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

בשלב הבא, צריך לבדוק אם המעטפת כבר מוגדרת למזהה הפרויקט הנכון שיש לכם. אם מופיע ערך בתוך ( ) לפני הסמל $ במסוף ( בצילום המסך שלמטה, הערך הוא "adk-cloudrun-deployment-476504"), הערך הזה מציין את הפרויקט שהוגדר עבור סשן המעטפת הפעיל.

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

gcloud config set project <YOUR_PROJECT_ID>

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

git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk

שלב 4: היכרות עם Cloud Shell Editor והגדרת ספריית העבודה של האפליקציה

עכשיו אפשר להגדיר את עורך הקוד כדי לבצע פעולות שקשורות לקוד. נשתמש ב-Cloud Shell Editor לצורך הזה

לוחצים על הלחצן Open Editor כדי לפתוח את Cloud Shell Editor .

אחרי זה, עוברים לחלק העליון של Cloud Shell Editor ולוחצים על File->Open Folder (קובץ > פתיחת תיקייה), מחפשים את ספריית שם המשתמש ואת הספרייה deploy_and_manage_adk ואז לוחצים על הלחצן OK. הפעולה הזו תגדיר את הספרייה שנבחרה כספריית העבודה הראשית. בדוגמה הזו, שם המשתמש הוא alvinprayuda, ולכן נתיב הספרייה מוצג למטה

עכשיו, ספריית העבודה שלכם ב-Cloud Shell Editor אמורה להיראות כך ( בתוך deploy_and_manage_adk)

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

הטרמינל הפעיל הנוכחי צריך להיות בתוך ספריית העבודה deploy_and_manage_adk. ב-codelab הזה נשתמש ב-Python 3.12 וב-uv python project manager כדי לפשט את הצורך ביצירה ובניהול של גרסת Python וסביבה וירטואלית. חבילת uv כבר מותקנת מראש ב-Cloud Shell.

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

uv sync --frozen

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

gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com

אם הפקודה תפעל בהצלחה, תוצג הודעה שדומה לזו שמופיעה בהמשך:

Operation "operations/..." finished successfully.

בשלב הבא, נצטרך להגדיר קובצי הגדרה לפרויקט הזה.

משנים את השם של הקובץ .env.example ל-.env.

cp .env.example .env

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

# .env

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
# DB_CONNECTION_NAME=your-db-connection-name

בשיעור הזה נשתמש בערכים שהוגדרו מראש עבור GOOGLE_CLOUD_LOCATION ו-GOOGLE_GENAI_USE_VERTEXAI.. בשלב הזה, נשאיר את DB_CONNECTION_NAME כהערה.

עכשיו אפשר לעבור לשלב הבא, לבדוק את הלוגיקה של הסוכן ולפרוס אותו

3. ‫🚀 בניית סוכן מזג האוויר באמצעות ADK ו-Gemini 2.5

מבוא למבנה הספריות של ADK

נתחיל בסקירה של האפשרויות ש-ADK מציע ושל אופן בניית הסוכן. אפשר לגשת לתיעוד המלא של ADK בכתובת ה-URL הזו . חבילת ה-ADK מציעה לנו הרבה כלי עזר בביצוע פקודות ה-CLI שלה. לדוגמה :

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

עכשיו נבדוק את מבנה הסוכן בספרייה weather_agent

weather_agent/
├── __init__.py
├── agent.py
└── tool.py

אם בודקים את הקבצים init.py ו-agent.py, אפשר לראות את הקוד הזה

# __init__.py

from weather_agent.agent import root_agent

__all__ = ["root_agent"]

# agent.py


import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)


# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="""
You are a helpful AI assistant designed to provide accurate and useful information.
""",
    tools=[get_weather],
)

הסבר על הקוד ב-ADK

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

הגדרת המודל לשימוש בתור gemini-2.5-flash
מספק כלי get_weather לתמיכה בפונקציונליות של הסוכן כסוכן מזג אוויר

הפעלת ממשק המשתמש באינטרנט

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

uv run adk web --port 8080

יוצג פלט כמו בדוגמה הבאה, כלומר כבר יש לנו גישה לממשק האינטרנט

INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

כדי לבדוק את זה, לוחצים על הלחצן Web Preview (תצוגה מקדימה של אתר) בחלק העליון של Cloud Shell Editor ובוחרים באפשרות Preview on port 8080 (תצוגה מקדימה ביציאה 8080).

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

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

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

4. 🚀 פריסה ב-Cloud Run

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

בשיעור הזה נשתמש ב-Dockerfile כדי לפרוס את הסוכן שלנו ב-Cloud Run. בשלב הזה, כבר יש לנו את כל הקבצים שנדרשים ( Dockerfile ו-server.py) כדי לפרוס את האפליקציות שלנו ב-Cloud Run. נרחיב על הנושא הזה בהמשך.

עכשיו נפרס את השירות. עוברים לטרמינל של Cloud Shell ומוודאים שהפרויקט הנוכחי מוגדר לפרויקט הפעיל שלכם. אם לא, צריך להשתמש בפקודה gcloud configure כדי להגדיר את מזהה הפרויקט:

gcloud config set project [PROJECT_ID]

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

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
DB_CONNECTION_NAME=your-db-connection-name

כדי לקבל את הערך של DB_CONNECTION_NAME, אפשר להיכנס שוב ל-Cloud SQL וללחוץ על המופע שיצרתם. עוברים לסרגל החיפוש בחלק העליון של מסוף Cloud ומקלידים 'Cloud SQL'. לאחר מכן לוחצים על המוצר Cloud SQL.

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

בדף של המופע, גוללים למטה לקטע Connect to this instance (התחברות למופע הזה) ומעתיקים את Connection Name (שם החיבור) כדי להחליף את הערך של DB_CONNECTION_NAME.

אחרי זה פותחים את הקובץ .env ומשנים את המשתנה DB_CONNECTION_NAME. קובץ ה-env אמור להיראות כמו בדוגמה הבאה

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
DB_CONNECTION_NAME=your-project-id:your-location:your-instance-name

לאחר מכן מריצים את סקריפט הפריסה

bash deploy_to_cloudrun.sh

אם מוצגת בקשה לאישור יצירה של מאגר ארטיפקטים עבור מאגר Docker, פשוט משיבים Y.

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

#!/bin/bash

# Load environment variables from .env file
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
else
    echo "Error: .env file not found"
    exit 1
fi

# Validate required variables
required_vars=("GOOGLE_CLOUD_PROJECT" "DB_CONNECTION_NAME")
for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        echo "Error: $var is not set in .env file"
        exit 1
    fi
done

gcloud run deploy weather-agent \
    --source . \
    --port 8080 \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --allow-unauthenticated \
    --add-cloudsql-instances ${DB_CONNECTION_NAME} \
    --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:ADK-deployment123@postgres/?unix_sock=/cloudsql/${DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT} \
    --region us-central1 \
    --min 1 \
    --memory 1G \
    --concurrency 10

הסקריפט הזה יטען את המשתנה .env ואז יריץ את פקודת הפריסה.

אם בוחנים את הפקודה מקרוב, רואים שצריך רק פקודה אחת של gcloud run deploy כדי לבצע את כל הפעולות הנדרשות אם רוצים לפרוס שירות: בניית התמונה, העלאה למאגר, פריסת השירות, הגדרת מדיניות IAM, יצירת עדכון ואפילו ניתוב תנועה. בדוגמה הזו, אנחנו כבר מספקים את קובץ ה-Dockerfile, ולכן הפקודה הזו תשתמש בו כדי לבנות את האפליקציה.

אחרי שהפריסה תושלם, תקבלו קישור שדומה לקישור שבהמשך:

https://weather-agent-*******.us-central1.run.app

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

5. 💡 קובץ Docker ותסריט השרת העורפי

כדי להפוך את הסוכן לנגיש כשירות, נשתמש בו באפליקציית FastAPI שתופעל בפקודה של Dockerfile. בהמשך מופיע התוכן של Dockerfile

FROM python:3.12-slim

RUN pip install --no-cache-dir uv==0.7.13

WORKDIR /app

COPY . .

RUN uv sync --frozen

EXPOSE 8080

CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]

כאן אפשר להגדיר את השירותים הדרושים לתמיכה בסוכן, כמו הכנת שירות Session, שירות Memory או שירות Artifact למטרות ייצור. זה הקוד של server.py שבו נשתמש

import os

from dotenv import load_dotenv
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
from pydantic import BaseModel
from typing import Literal
from google.cloud import logging as google_cloud_logging


# Load environment variables from .env file
load_dotenv()

logging_client = google_cloud_logging.Client()
logger = logging_client.logger(__name__)

AGENT_DIR = os.path.dirname(os.path.abspath(__file__))

# Get session service URI from environment variables
session_uri = os.getenv("SESSION_SERVICE_URI", None)

# Prepare arguments for get_fast_api_app
app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

# Only include session_service_uri if it's provided
if session_uri:
    app_args["session_service_uri"] = session_uri
else:
    logger.log_text(
        "SESSION_SERVICE_URI not provided. Using in-memory session service instead. "
        "All sessions will be lost when the server restarts.",
        severity="WARNING",
    )

# Create FastAPI app with appropriate arguments
app: FastAPI = get_fast_api_app(**app_args)

app.title = "weather-agent"
app.description = "API for interacting with the Agent weather-agent"


class Feedback(BaseModel):
    """Represents feedback for a conversation."""

    score: int | float
    text: str | None = ""
    invocation_id: str
    log_type: Literal["feedback"] = "feedback"
    service_name: Literal["weather-agent"] = "weather-agent"
    user_id: str = ""


# Example if you want to add your custom endpoint
@app.post("/feedback")
def collect_feedback(feedback: Feedback) -> dict[str, str]:
    """Collect and log feedback.

    Args:
        feedback: The feedback data to log

    Returns:
        Success message
    """
    logger.log_struct(feedback.model_dump(), severity="INFO")
    return {"status": "success"}


# Main execution
if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8080)

הסבר על קוד השרת

אלה הדברים שמוגדרים בסקריפט server.py:

אפשר להמיר את הסוכן לאפליקציית FastAPI באמצעות השיטה get_fast_api_app. כך נשתמש באותה הגדרת נתיב שמשמשת את ממשק המשתמש של פיתוח האתר.
מגדירים את השירותים הנדרשים של Session,‏ Memory או Artifact על ידי הוספת ארגומנטים של מילות מפתח לשיטה get_fast_api_app. במדריך הזה, אם נגדיר את משתנה הסביבה SESSION_SERVICE_URI, שירות הסשן ישתמש בו, אחרת הוא ישתמש בסשן בזיכרון
אנחנו יכולים להוסיף מסלול מותאם אישית כדי לתמוך בלוגיקה עסקית אחרת של ה-Backend. בסקריפט אנחנו מוסיפים דוגמה למסלול של פונקציונליות משוב
מפעילים מעקב בענן בפרמטרים של הארגומנט get_fast_api_app כדי לשלוח את המעקב אל Google Cloud Trace
הפעלת שירות FastAPI באמצעות uvicorn

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

6. 🚀 בדיקת התאמה אוטומטית לעומס (auto-scaling) ב-Cloud Run באמצעות בדיקת עומס

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

נבדוק את הקובץ load_test.py. זה יהיה הסקריפט שבו נשתמש כדי לבצע את בדיקת העומס באמצעות מסגרת locust. הסקריפט הזה יבצע את הפעולות הבאות :

מזהה משתמש (user_id) ומזהה סשן (session_id) רנדומליים
יצירת session_id עבור user_id
הפעלת נקודת הקצה (endpoint) '/run_sse' עם הערכים של user_id ו-session_id שנוצרו

אם פספסתם את כתובת ה-URL של השירות שפרסתם, נצטרך לדעת אותה. נכנסים למסוף Cloud Run ולוחצים על השירות weather-agent.

אחר כך, מחפשים את שירות weather-agent ולוחצים עליו.

כתובת ה-URL של השירות תוצג לצד פרטי האזור. לדוגמה

לאחר מכן מריצים את הפקודה הבאה כדי לבצע את בדיקת העומס

uv run locust -f load_test.py \
              -H {YOUR_SERVICE_URL} \
              -u 60 \
              -r 5 \
              -t 120 \
              --headless

כשמריצים את הפקודה הזו, מוצגים מדדים כמו אלה. ( בדוגמה הזו כל הבקשות הצליחו )

Type     Name                                  # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
POST     /run_sse end                             813     0(0.00%) |   5817    2217   26421   5000 |    6.79        0.00
POST     /run_sse message                         813     0(0.00%) |   2678    1107   17195   2200 |    6.79        0.00
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
         Aggregated                              1626     0(0.00%) |   4247    1107   26421   3500 |   13.59        0.00

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

7. 🚀 השקה הדרגתית של תיקונים חדשים

עכשיו נבחן את התרחיש הבא. אנחנו רוצים לעדכן את ההנחיה של הסוכן. פותחים את weather_agent/agent.py ומחליפים את התוכן שלו בקוד הבא:

# weather_agent/agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)


# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="""
You are a helpful AI assistant designed to provide accurate and useful information.
You only answer inquiries about the weather. Refuse all other user query
""",
    tools=[get_weather],
)

לאחר מכן, אתם רוצים לפרסם גרסאות חדשות, אבל לא רוצים שכל התנועה של הבקשות תעבור ישירות לגרסה החדשה. אפשר לבצע השקה הדרגתית באמצעות Cloud Run. קודם כול, צריך לפרוס גרסה חדשה, אבל עם הדגל ‎–no-traffic. שומרים את סקריפט הסוכן הקודם ומריצים את הפקודה הבאה

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

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

Service [weather-agent] revision [weather-agent-xxxx-xxx] has been deployed and is serving 0 percent of traffic.

עכשיו נעבור לדף המוצר של Cloud Run ונחפש את המופע שפרסתם. מקלידים cloud run בסרגל החיפוש ולוחצים על המוצר Cloud Run.

אחר כך, מחפשים את שירות weather-agent ולוחצים עליו.

עוברים לכרטיסייה Revisions (גרסאות) ורואים את רשימת הגרסאות שנפרסו.

אפשר לראות שהגרסאות החדשות שפרסמתם מציגות 0% מהתנועה. מכאן אפשר ללחוץ על לחצן האפשרויות הנוספות (⋮) ולבחור באפשרות ניהול תנועה.

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

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

8. 🚀 מעקב ב-ADK

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

# server.py

...

app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

...

app: FastAPI = get_fast_api_app(**app_args)

...

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

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

בדף של כלי המעקב אחר נתונים, תראו שהשיחה שלנו עם הסוכן נשלחה למעקב. אפשר לראות את זה בקטע Span name ולסנן את ה-span שספציפי לסוכן שלנו ( השם שלו הוא agent_run [weather_agent])

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

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

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

9. 🎯 אתגר

כדאי לנסות תהליכי עבודה מרובי-סוכנים או תהליכי עבודה שמבוססים על סוכנים כדי לראות איך הם פועלים בעומסים גבוהים ואיך נראה המעקב

10. 🧹 ניקוי

כדי לא לצבור חיובים לחשבון Google Cloud על המשאבים שבהם השתמשתם ב-Code Lab הזה:

במסוף Google Cloud, עוברים לדף Manage resources.
ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.
לחלופין, אפשר לעבור אל Cloud Run במסוף, לבחור את השירות שפרסתם ולמחוק אותו.