نشر وكيل ADK وإدارته ومراقبته على Cloud Run

1. مقدمة

سيرشدك هذا البرنامج التعليمي إلى كيفية نشر وكيل قوي تم إنشاؤه باستخدام حزمة تطوير الوكلاء (ADK) وإدارته ومراقبته على Google Cloud Run. تتيح لك "حزمة تطوير الوكلاء" إنشاء وكلاء قادرين على تنفيذ عمليات سير عمل معقّدة ومتعددة الوكلاء. من خلال الاستفادة من Cloud Run، وهي منصة مُدارة بالكامل بدون خادم، يمكنك تفعيل الوكيل كتطبيق قابل للتوسع ومضمّن في حاوية بدون القلق بشأن البنية الأساسية. يتيح لك هذا الدمج الفعّال التركيز على المنطق الأساسي للوكيل مع الاستفادة من بيئة Google Cloud المتينة والقابلة للتوسّع.

خلال هذا البرنامج التعليمي، سنتعرّف على عملية الدمج السلسة لحزمة تطوير التطبيقات (ADK) مع Cloud Run. ستتعرّف على كيفية نشر برنامجك الآلي ثم ستنتقل إلى الجوانب العملية لإدارة تطبيقك في بيئة مشابهة لبيئة الإنتاج. سنتناول كيفية طرح إصدارات جديدة من برنامجك بأمان من خلال إدارة عدد الزيارات، ما يتيح لك اختبار الميزات الجديدة مع مجموعة فرعية من المستخدمين قبل الإصدار الكامل.

بالإضافة إلى ذلك، ستكتسب خبرة عملية في مراقبة أداء وكيلك. سنحاكي سيناريو واقعيًا من خلال إجراء اختبار تحميل لمراقبة إمكانات التدرّج التلقائي في Cloud Run أثناء العمل. للحصول على إحصاءات أكثر تفصيلاً حول سلوك وكيلك وأدائه، سنفعّل ميزة التتبُّع باستخدام Cloud Trace. سيوفّر ذلك عرضًا تفصيليًا وشاملاً للطلبات أثناء انتقالها عبر الوكيل، ما يتيح لك تحديد أيّ مشاكل في الأداء ومعالجتها. في نهاية هذا الفيديو التعليمي، سيكون لديك فهم شامل لكيفية نشر وكلاء ADK وإدارتهم ومراقبتهم بفعالية على Cloud Run.

خلال هذا الدرس التطبيقي حول الترميز، ستتّبع نهجًا خطوة بخطوة على النحو التالي:

إنشاء قاعدة بيانات PostgreSQL على CloudSQL لاستخدامها في خدمة جلسات قاعدة بيانات ADK Agent
إعداد وكيل ADK أساسي
إعداد خدمة جلسة قاعدة البيانات ليستخدمها برنامج تشغيل ADK
نشر الوكيل الأوّلي إلى Cloud Run
اختبار التحميل وفحص ميزة التوسيع التلقائي في Cloud Run
نشر مراجعة جديدة للوكيل وزيادة عدد الزيارات تدريجيًا إلى المراجعات الجديدة
إعداد تتبُّع السحابة الإلكترونية وفحص تتبُّع تشغيل الوكيل

نظرة عامة على البنية

المتطلبات الأساسية

إجادة العمل باستخدام لغة Python
فهم أساسي لبنية التطبيقات المتكاملة باستخدام خدمة HTTP

ما ستتعلمه

بنية حزمة تطوير التطبيقات (ADK) والأدوات المساعدة المحلية
إعداد وكيل ADK باستخدام خدمة جلسة قاعدة البيانات
إعداد PostgreSQL في CloudSQL لاستخدامه من خلال خدمة جلسات قاعدة البيانات
نشر التطبيق على Cloud Run باستخدام Dockerfile وإعداد متغيرات البيئة الأولية
ضبط ميزة "التوسّع التلقائي" في Cloud Run واختبارها باستخدام اختبار التحميل
استراتيجية الإصدار التدريجي باستخدام Cloud Run
إعداد تتبُّع وكيل ADK إلى Cloud Trace

المتطلبات

متصفّح الويب Chrome
حساب Gmail
مشروع على السحابة الإلكترونية تم تفعيل الفوترة فيه

يستخدم هذا الدرس التطبيقي حول الترميز، المصمَّم للمطوّرين من جميع المستويات (بما في ذلك المبتدئين)، لغة Python في تطبيق المثال. ومع ذلك، لا يُشترط معرفة لغة Python لفهم المفاهيم المقدَّمة.

2. 🚀 التحضير لإعداد ورشة العمل

ملاحظات مهمة:

يتطلّب هذا البرنامج التعليمي مشروعًا على Google Cloud مع حساب فوترة نشط. إذا لم يكن لديك حساب بعد، يُرجى اتّباع الخطوات التالية للحصول على حساب فوترة تجريبي يمكن استخدامه في هذا البرنامج التعليمي:

فتح نافذة التصفُّح المتخفي
إذا كنت ستنضم إلى جلسة ورشة عمل، سيتم عادةً تقديم عنوان URL لبوابة الاسترداد في الجلسة، وإلا يمكنك الانتقال إلى بوابة استرداد حساب الفوترة التجريبي.
سجِّل الدخول باستخدام حسابك الشخصي على Gmail ( لن تعمل حسابات Google Workspace أو عناوين البريد الإلكتروني الأخرى). )
اتّبِع تعليمات الاسترداد خطوة بخطوة من أجل إنشاء مشروع على السحابة الإلكترونية جديد على Google Cloud مرتبط بحساب فوترة تجريبي تمّت المطالبة به سابقًا لهذا الدليل التوجيهي.

سنستخدم الآن بيئة التطوير المتكاملة في Cloud Shell لهذا البرنامج التعليمي، انقر على الزر التالي للانتقال إليها

بعد الدخول إلى Cloud Shell، استنسِخ دليل العمل الخاص بالقالب لهذا الدرس التطبيقي حول الترميز من 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

بعد ذلك، من المفترض أن تبدو واجهتك مشابهة لما يلي

ستكون هذه هي واجهتنا الرئيسية، مع وضع بيئة التطوير المتكاملة في الأعلى والوحدة الطرفية في الأسفل. الآن، علينا إعداد الجهاز لإنشاء مشروع Google Cloud وتفعيله، وسيتم ربطه بحساب الفوترة التجريبي الذي تمّت المطالبة به سابقًا. لقد أعددنا لك نصًا برمجيًا لضمان جاهزية جلسة الجهاز الطرفي دائمًا. نفِّذ الأمر التالي ( تأكَّد من أنّك داخل مساحة عمل deploy_and_manage_adk

bash setup_trial_project.sh && source .env

عند تشغيل هذا الأمر، سيُطلب منك إدخال اسم رقم تعريف المشروع المقترَح، ويمكنك الضغط على Enter للمتابعة.

بعد الانتظار لبعض الوقت، إذا ظهرت لك هذه النتيجة في وحدة التحكّم، يمكنك الانتقال إلى الخطوة التالية

يشير ذلك إلى أنّ الوحدة الطرفية قد تمّت مصادقتها وضبطها على رقم تعريف المشروع الصحيح ( اللون الأصفر بجانب مسار الدليل الحالي). يساعدك هذا الأمر في إنشاء مشروع جديد والعثور على المشروع وربطه بحساب فوترة تجريبي وإعداد ملف .env لإعداد متغير البيئة وتفعيل رقم تعريف المشروع الصحيح في الوحدة الطرفية.

الآن، نحن جاهزون للخطوة التالية

3- 🚀 تفعيل واجهات برمجة التطبيقات

في هذا الدرس التعليمي، سنتفاعل مع قاعدة بيانات CloudSQL ونموذج Gemini وCloud Run، وستتطلّب هذه المنتجات تفعيل واجهة برمجة التطبيقات التالية، لذا نفِّذ الأوامر التالية لتفعيلها:

قد يستغرق هذا بعض الوقت.

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 ومتغيرات البيئة

سنستخدم الإصدار 3.12 من Python في هذا الدرس التطبيقي حول الترميز، كما سنستخدم أداة إدارة مشاريع Python‏ (uv) لتسهيل عملية إنشاء إصدار Python وبيئته الافتراضية وإدارتهما. تم تثبيت حزمة uv هذه مسبقًا على Cloud Shell.

نفِّذ هذا الأمر لتثبيت الاعتمادات المطلوبة في البيئة الافتراضية في الدليل .venv.

uv sync --frozen

بعد ذلك، سنفحص ملفات متغيرات البيئة المطلوبة لهذا المشروع. كانت تتم في السابق إعداد هذا الملف بواسطة البرنامج النصي setup_trial_project.sh. نفِّذ الأمر التالي لفتح ملف .env في المحرّر

cloudshell open .env

ستظهر لك الإعدادات التالية التي تم تطبيقها مسبقًا على الملف .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

في هذا الدرس التطبيقي، سنستخدم القيم التي تم ضبطها مسبقًا لكل من GOOGLE_CLOUD_LOCATION وGOOGLE_GENAI_USE_VERTEXAI..

يمكننا الآن الانتقال إلى الخطوة التالية، وهي إنشاء قاعدة البيانات التي سيستخدمها برنامجنا للحفاظ على الحالة والجلسة.

5- 🚀 تجهيز قاعدة بيانات CloudSQL

سنحتاج إلى قاعدة بيانات يستخدمها وكيل 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

في الأمر أعلاه، يمثّل 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. ‫🚀 إنشاء "وكيل الطقس" باستخدام "حزمة تطوير الوكلاء" وGemini 2.5

مقدّمة عن بنية دليل ADK

لنبدأ باستكشاف ما يقدّمه "إطار عمل تطوير التطبيقات" وكيفية إنشاء الوكيل. يمكنك الاطّلاع على مستندات ADK الكاملة من خلال عنوان URL هذا . توفّر لنا "حزمة تطوير التطبيقات" العديد من الأدوات المساعدة في تنفيذ أوامر واجهة سطر الأوامر. في ما يلي بعض هذه الحالات :

إعداد بنية دليل الوكيل
تجربة التفاعل بسرعة من خلال إدخال وإخراج واجهة سطر الأوامر
إعداد واجهة ويب لواجهة مستخدم التطوير المحلي بسرعة

الآن، لنلقِ نظرة على بنية الوكيل في الدليل 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)

الآن، للتحقّق من ذلك، انقر على الزر معاينة الويب في أعلى منطقة "محرّر Cloud Shell"، ثم انقر على معاينة على المنفذ 8080.

ستظهر لك صفحة الويب التالية حيث يمكنك اختيار الوكلاء المتاحين من زر القائمة المنسدلة في أعلى اليمين ( في حالتنا، يجب أن يكون weather_agent) والتفاعل مع الروبوت. ستظهر لك العديد من المعلومات حول تفاصيل السجلّ أثناء وقت تشغيل الوكيل في النافذة اليمنى.

الآن، حاوِل التفاعل معه. في الشريط الأيمن، يمكننا فحص التتبُّع لكل إدخال، ما يتيح لنا معرفة المدة التي يستغرقها كل إجراء يتخذه الوكيل قبل تكوين الإجابة النهائية.

هذه إحدى ميزات إمكانية تتبّع البيانات المضمّنة في "حزمة تطوير التطبيقات"، ونحن نفحصها حاليًا على الجهاز. سنرى لاحقًا كيف يتم دمج ذلك في Cloud Tracing حتى يكون لدينا تتبُّع مركزي لجميع الطلبات.

7. 🚀 نشر التطبيق على Cloud Run

الآن، لننشر خدمة الوكيل هذه على Cloud Run. لأغراض هذا العرض التوضيحي، سيتم عرض هذه الخدمة كخدمة عامة يمكن للآخرين الوصول إليها. ومع ذلك، يُرجى العِلم أنّ هذه ليست أفضل الممارسات لأنّها غير آمنة.

يتيح لك سيناريو النشر هذا تخصيص خدمة الخلفية الخاصة بالوكيل، وسنستخدم Dockerfile لنشر الوكيل على Cloud Run. في هذه المرحلة، تتوفّر لدينا جميع الملفات اللازمة ( Dockerfile وserver.py) لنشر تطبيقاتنا على Cloud Run. من خلال توفّر هذين العنصرين، يمكنك تخصيص عملية تفعيل الوكيل بمرونة ( مثل إضافة مسارات خلفية مخصّصة و/أو إضافة خدمة إضافية متزامنة لأغراض الرصد). وسنتناول هذا الموضوع بالتفصيل لاحقًا.

الآن، لنبدأ بنشر الخدمة أولاً، ثم انتقِل إلى "وحدة Cloud Shell الطرفية" وتأكَّد من إعداد المشروع الحالي لمشروعك النشط، ثم شغِّل نص الإعداد البرمجي مرة أخرى. يمكنك أيضًا استخدام الأمر gcloud config set project [PROJECT_ID] لإعداد مشروعك النشط.

bash setup_trial_project.sh && source .env

الآن، علينا إعادة فتح الملف .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 SQL". بعد ذلك، انقر على منتج Cloud SQL.

بعد ذلك، سيظهر لك الجهاز الافتراضي الذي تم إنشاؤه سابقًا، انقر عليه

داخل صفحة المثيل، انتقِل للأسفل إلى قسم الاتصال بهذا المثيل ويمكنك نسخ اسم الاتصال لاستبدال قيمة 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، وبالتالي سيستخدم هذا الأمر لإنشاء التطبيق.

بعد اكتمال عملية النشر، من المفترض أن تحصل على رابط مشابه لما يلي:

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

بعد الحصول على عنوان URL هذا، يمكنك استخدام تطبيقك من نافذة التصفّح المتخفي أو جهازك الجوّال والوصول إلى واجهة مستخدم المطور الخاصة بالوكيل. أثناء انتظار عملية النشر، لنلقِ نظرة على الخدمة التفصيلية التي نشرناها للتو في القسم التالي.

8. 💡 ملف Dockerfile ونص برمجي لخادم الخلفية

لإتاحة الوصول إلى الوكيل كخدمة، سنغلّف الوكيل داخل تطبيق 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"]

يمكننا هنا ضبط الخدمات اللازمة لدعم الوكيل، مثل إعداد خدمة الجلسة أو الذاكرة أو العنصر لأغراض الإنتاج. في ما يلي رمز 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. بهذه الطريقة، سنرث تعريف المسار نفسه المستخدَم في واجهة مستخدم تطوير الويب.
اضبط خدمة "الجلسة" أو "الذاكرة" أو "العنصر" اللازمة من خلال إضافة وسيطات الكلمات الرئيسية إلى طريقة get_fast_api_app. في هذا البرنامج التعليمي، إذا ضبطنا متغير البيئة SESSION_SERVICE_URI، ستستخدم خدمة الجلسة هذا المتغير، وإلا ستستخدم الجلسة في الذاكرة.
يمكننا إضافة مسار مخصّص لدعم منطق الأنشطة التجارية الأخرى في الخلفية، وفي النص البرمجي، نضيف مثالاً على مسار وظيفة الملاحظات.
فعِّل تتبُّع السحابة الإلكترونية في مَعلمات get_fast_api_app arg لإرسال التتبُّع إلى Google Cloud Trace
تشغيل خدمة FastAPI باستخدام uvicorn

الآن، إذا انتهى نشر وكيلك، يُرجى محاولة التفاعل معه من واجهة مستخدم المطوّرين على الويب من خلال الوصول إلى عنوان URL الخاص بخدمة Cloud Run.

9- ‫🚀 فحص ميزة "التوسّع التلقائي" في Cloud Run باستخدام "اختبار التحميل"

الآن، سنتفحّص إمكانات التدرّج التلقائي في Cloud Run. في هذا السيناريو، لننشئ مراجعة جديدة مع تفعيل الحد الأقصى لعدد عمليات التنفيذ المتزامنة لكل مثيل. في القسم السابق، ضبطنا الحد الأقصى للتزامن على 10 ( العلامة --concurrency 10). وبالتالي، يمكننا توقّع أنّ Cloud Run سيحاول توسيع نطاق مثيله عندما نجري اختبار تحميل يتجاوز هذا العدد.

لنلقِ نظرة على ملف load_test.py. سيكون هذا هو البرنامج النصي الذي نستخدمه لإجراء اختبار التحميل باستخدام إطار عمل locust. سيؤدي هذا النص البرمجي إلى تنفيذ الإجراءات التالية :

‫user_id وsession_id عشوائيان
إنشاء session_id لـ user_id
إرسال طلب إلى نقطة النهاية "/run_sse" باستخدام user_id وsession_id اللذين تم إنشاؤهما

سنحتاج إلى معرفة عنوان URL للخدمة التي تم نشرها، إذا فاتك ذلك. يمكننا الانتقال إلى وحدة تحكّم 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

سيؤدي تنفيذ هذا الأمر إلى عرض مقاييس على النحو التالي. ( في هذا المثال، نجحت جميع الطلبات )

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، وننتقل إلى الخدمة التي تم نشرها مرة أخرى، ونرى لوحة البيانات. سيوضّح ذلك كيف يمكن أن توسّع السحابة الإلكترونية تلقائيًا حجم الجهاز الافتراضي للتعامل مع الطلبات الواردة. بما أنّنا نحدّ من الحد الأقصى للتزامن إلى 10 لكل مثيل، سيحاول مثيل Cloud Run تعديل عدد الحاويات لاستيفاء هذا الشرط تلقائيًا.

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

بعد الانتهاء، ستتلقّى سجلاً مشابهًا لسجل عملية النشر السابقة مع اختلاف في عدد الزيارات التي تم عرضها. سيظهر 0 في المئة من عدد الزيارات التي تم عرض الإعلانات لها.

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

بعد ذلك، لننتقل إلى لوحة بيانات Cloud Run

بعد ذلك، ابحث عن خدمة weather-agent وانقر عليها

انتقِل إلى علامة التبويب المراجعات وستظهر لك قائمة بالمراجعات التي تم نشرها.

ستلاحظ أنّ المراجعات الجديدة التي تم نشرها تعرض نسبة %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".

في صفحة "مستكشف عمليات التتبُّع"، ستظهر محادثتنا مع عملية تتبُّع الموظف. يمكنك الاطّلاع على ذلك من قسم اسم النطاق وفلترة النطاق الخاص بالوكيل ( اسمه agent_run [weather_agent]) هناك.

عندما يتم فلترة النطاقات، يمكنك أيضًا فحص كل عملية تتبُّع مباشرةً. سيتم عرض مدة مفصّلة لكل إجراء اتّخذه الوكيل. على سبيل المثال، اطّلِع على الصور أدناه

في كل قسم، يمكنك فحص التفاصيل في السمات كما هو موضّح أدناه

بهذا نكون قد حصلنا على إمكانية تتبّع البيانات ومعلومات جيدة عن كل تفاعل بين الوكيل والمستخدم للمساعدة في تصحيح الأخطاء. يمكنك تجربة أدوات أو سير عمل مختلفة.

12. 🎯 التحدي

جرِّب استخدام سير عمل متعدد الوكلاء أو يعتمد على الوكلاء لمعرفة أدائه في ظل الأحمال وكيف يبدو التتبُّع.

13. ‫🧹 تنظيف

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا الدرس التطبيقي حول الترميز، اتّبِع الخطوات التالية:

في Google Cloud Console، انتقِل إلى صفحة إدارة الموارد.
في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف.
في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.
بدلاً من ذلك، يمكنك الانتقال إلى Cloud Run في وحدة التحكّم، واختيار الخدمة التي نشرتها للتو وحذفها.