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

1. מבוא

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

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

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

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

1. יצירת מסד נתונים של PostgreSQL ב-CloudSQL לשימוש בשירות סשן מסד הנתונים של ADK Agent
2. הגדרת סוכן ADK בסיסי
3. הגדרת שירות הפעלות מסד נתונים לשימוש בכלי ADK Runner
4. פריסה ראשונית של הסוכן ב-Cloud Run
5. בדיקות עומס ובדיקה של התאמה לעומס (auto-scaling) ב-Cloud Run
6. פריסת גרסה חדשה של סוכן והגדלה הדרגתית של נפח התנועה לגרסאות חדשות
7. הגדרת מעקב בענן ובדיקת מעקב של הפעלת סוכן

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

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

• ניסיון בעבודה עם 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. 🚀 הכנה להגדרת הסדנה

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

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

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

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

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

כניסה ל-Cloud Shell

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

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

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

cloudshell workspace ~/deploy_and_manage_adk && cd ~/deploy_and_manage_adk

אחרי כן, הממשק אמור להיראות כך

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

bash setup_trial_project.sh && source .env

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

אחרי שמחכים זמן מה, אם הפלט הזה מופיע במסוף, אפשר לעבור לשלב הבא

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

עכשיו אפשר לעבור לשלב הבא

3. 🚀 הפעלת ממשקי API

יעדים: לוודא שממשק ה-API הנדרש מופעל

במדריך הזה נשתמש במסד הנתונים של CloudSQL, במודל Gemini וב-Cloud Run. כדי להשתמש במוצרים האלה, צריך להפעיל את ה-API הבא. מריצים את הפקודה הזו כדי להפעיל אותו:

הפעולה עשויה להימשך זמן-מה.

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

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

Operation "operations/..." finished successfully.

4. 🚀 הגדרה של סביבת Python ומשתני סביבה

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

הערה: כשמשתמשים ב-uv כמנהל פרויקטים של Python, התהליך של יצירה והפעלה של סביבות וירטואליות הופך לפשוט יותר. עם זאת, כל פקודה בסקריפט python תוחלף בפקודה uv run. לדוגמה, uv run main.py במקום python main.py

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

uv sync --frozen

הערה: התלויות של Python מוצהרות בתוך pyproject.toml והגרסה שלהן נעולה בתוך הקובץ uv.lock.

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

cloudshell open .env

הערה: אם אתם לא מוצאים את קובץ .env שמוצג בכלי העריכה, יכול להיות שהוא מסווג כקובץ מוסתר. לוחצים על View -> Toggle Hidden Files (תצוגה -> החלפה של קבצים נסתרים) כדי להציג אותו.

ההגדרות הבאות כבר יחולו על הקובץ .env.

# .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

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

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

5. 🚀 הכנת מסד נתונים ב-Cloud SQL

יעדים: הכנת מסד הנתונים לשימוש על ידי סוכן ADK

בהמשך נצטרך מסד נתונים שישמש את סוכן ה-ADK. ניצור מסד נתונים של PostgreSQL ב-Cloud SQL. מריצים את הפקודה הבאה כדי ליצור קודם את מופע מסד הנתונים. נשתמש בשם מסד הנתונים שמוגדר כברירת מחדל, postgres, ולכן נדלג על יצירת מסד נתונים כאן. אנחנו צריכים גם להגדיר את שם המשתמש של מסד הנתונים שמוגדר כברירת מחדל (גם הוא postgres). לצורך המדריך, נשתמש ב-ADK-deployment123 כסיסמה.

gcloud sql instances create adk-deployment \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --tier=db-g1-small \
  --region=us-central1 \
  --availability-type=ZONAL \
  --project=${GOOGLE_CLOUD_PROJECT} && \
gcloud sql users set-password postgres \
  --instance=adk-deployment \
  --password=ADK-deployment123

אזהרה! יצירת מופע חדש של Cloud SQL יכולה להימשך כ-5-7 דקות. צריך להתאזר בסבלנות ולא לסגור את הטרמינל

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

בפקודה שלמעלה, gcloud sql instances create adk-deployment הוא פקודה נפוצה שמשמשת ליצירת מופע של מסד נתונים. לצורך המדריך הזה, אנחנו משתמשים במפרט מינימלי של ארגז חול. הפקודה השנייה gcloud sql users set-password postgres משמשת לשינוי הסיסמה של שם המשתמש שמוגדר כברירת מחדל postgres

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

Created [https://sqladmin.googleapis.com/sql/v1beta4/projects/your-project-id/instances/adk-deployment].
NAME: adk-deployment
DATABASE_VERSION: POSTGRES_17
LOCATION: us-central1-a
TIER: db-g1-small
PRIMARY_ADDRESS: xx.xx.xx.xx
PRIVATE_ADDRESS: -
STATUS: RUNNABLE
Updating Cloud SQL user...done. 

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

אזהרה! שוב, אל תסגרו או תפסיקו את פעולת הטרמינל

6. 🚀 Build the Weather Agent with ADK and 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],
)

הערה: מבנה הספריות, ייבוא הסוכן בתוך init.py וההצהרה על root_agent ב-agent.py הם המבנה הנדרש כדי שה-CLI של ADK יזהה את הסוכן.

הסבר על הקוד ב-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, כדי שיהיה לנו מעקב מרכזי של כל הבקשות

תזכורת! בוא נסיים את התהליך adk web כרגע. אפשר להקיש על CTRL + C כדי לסיים את התהליך.

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

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

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

עכשיו נפרס את השירות. עוברים לטרמינל של Cloud Shell ומוודאים שהפרויקט הנוכחי מוגדר לפרויקט הפעיל שלכם. מריצים שוב את סקריפט ההגדרה. לחלופין, אפשר להשתמש בפקודה gcloud config set project [PROJECT_ID] כדי להגדיר את הפרויקט הפעיל.

bash setup_trial_project.sh && source .env

עכשיו צריך לחזור לקובץ .env, לפתוח אותו ולבטל סימון כהערה (uncomment) של המשתנה 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 SQL

ואז לוחצים על המופע שיצרתם. עוברים לסרגל החיפוש בחלק העליון של מסוף Cloud ומקלידים 'cloud sql'. לאחר מכן לוחצים על המוצר Cloud SQL.

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

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

אחרי זה פותחים את הקובץ .env באמצעות הפקודה הבאה

cloudshell edit .env

ולשנות את המשתנה DB_CONNECTION_NAME בקובץ .env. קובץ ה-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, ולכן הפקודה הזו תשתמש בו כדי לבנות את האפליקציה.

הערה: בסקריפט הפריסה, הגדרנו את משתני הסביבה SESSION_SERVICE_URI. אם המשתנה הזה מוגדר, סוכן ה-ADK שלנו ישתמש ב-URI של השירות כדי לאחסן את פרטי הסשן והמצב (מוגדר ב-server.py). במדריך הזה אנחנו משתמשים בחיבור שקע של PostgreSQL Unix עם מנהל ההתקן pg8000.

שימו לב שבדוגמה אנחנו משתמשים במשתמש ברירת המחדל postgres ובמסד נתוני ברירת המחדל postgres (עם הסיסמה ADK-deployment123).

חשוב! אנחנו מאפשרים כאן גישה לא מאומתת (הדגל ‎–allow_unauthenticated) כי זו אפליקציית הדגמה. מומלץ להשתמש באימות מתאים לאפליקציות הארגוניות ולאפליקציות הייצור.

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

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

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

8. 💡 קובץ 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:

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

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

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

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

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

1. ‫user_id ו-session_id רנדומליים
2. יצירת session_id עבור user_id
3. שליחת היט לנקודת הקצה ‎/run_sse עם הערכים של user_id ו-session_id שנוצרו

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

כניסה ל-Cloud Run

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

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

כדי לפשט את התהליך, נריץ את הסקריפט הבא כדי לקבל את כתובת ה-URL של השירות שנפרס לאחרונה ולאחסן אותה במשתנה הסביבה SERVICE_URL

export SERVICE_URL=$(gcloud run services describe weather-agent \
    --platform managed \
    --region us-central1 \
    --format 'value(status.url)')

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

uv run locust -f load_test.py \
              -H $SERVICE_URL \
              -u 60 \
              -r 5 \
              -t 120 \
              --headless

הערה חשובה: חשוב לוודא שכבר הגדרתם את המשתנה SERVICE_URL בצורה נכונה.

הערה: הפקודה הזו תדמה עלייה הדרגתית של 0 עד 60 בקשות משתמשים מקבילות, בקצב של 5 משתמשים בשנייה, במהלך תקופה של 120 שניות.

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

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

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

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

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

cloudshell edit 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 $GOOGLE_CLOUD_PROJECT \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

הערה חשובה: מוודאים שמשתנה הסביבה GOOGLE_CLOUD_PROJECT כבר מוגדר.

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

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

עכשיו נעבור ללוח הבקרה של Cloud Run.

כניסה ל-Cloud Run

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

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

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

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

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

11. ‫🚀 ADK Tracing

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

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

כניסה לדף Trace Explorer

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

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

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

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

12. 🎯 אתגר

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

13. 🧹 ניקוי

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

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