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

1. مقدمة

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

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

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

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

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

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

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

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

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

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

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

ما ستتعلمه

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

المتطلبات

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

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

2. 🚀 إعداد بيئة تطوير ورشة العمل

الأهداف: التأكّد من أنّ المشروع الذي يتضمّن حساب فوترة جاهز، والتعرّف على محرّر ونافذة Cloud Shell، وإعداد دليل العمل ووكيل أساسي

الخطوة 1: اختيار "المشروع النشط" في Cloud Console

في Google Cloud Console، في صفحة اختيار المشروع، اختَر أو أنشِئ مشروعًا على Google Cloud (راجِع القسم العلوي الأيمن من وحدة التحكّم).

انقر على هذا الرمز، وستظهر لك قائمة بجميع مشاريعك كما في المثال التالي:

القيمة الموضّحة في المربّع الأحمر هي معرّف المشروع وسيتم استخدام هذه القيمة في جميع أنحاء البرنامج التعليمي.

تأكَّد من تفعيل الفوترة لمشروعك على Cloud. للتأكّد من ذلك، انقر على رمز الهامبرغر ☰ في الشريط العلوي الأيمن الذي يعرض قائمة التنقّل وابحث عن قائمة "الفوترة".

إذا ظهر لك "حساب فوترة تجريبي في Google Cloud Platform" ضمن العنوان الفوترة / نظرة عامة ( الجزء العلوي الأيسر من Cloud Console )، يكون مشروعك جاهزًا للاستخدام في هذا البرنامج التعليمي. إذا لم يكن كذلك، ارجع إلى بداية هذا البرنامج التعليمي واستردّ قيمة حساب الفوترة التجريبي.

الخطوة 2: إعداد قاعدة بيانات Cloud SQL

سنحتاج إلى قاعدة بيانات يستخدمها وكيل ADK لاحقًا. لننشئ قاعدة بيانات PostgreSQL على Cloud SQL. أولاً، انتقِل إلى شريط البحث في القسم العلوي من وحدة تحكّم السحابة الإلكترونية، واكتب "Cloud SQL". بعد ذلك، انقر على منتج Cloud SQL.

بعد ذلك، علينا إنشاء مثيل قاعدة بيانات جديد، انقر على إنشاء مثيل واختَر PostgreSQL.

قد تحتاج أيضًا إلى تفعيل Compute Engine API إذا بدأت بمشروع جديد، ما عليك سوى النقر على تفعيل واجهة برمجة التطبيقات إذا ظهرت هذه الرسالة.

بعد ذلك، سنختار مواصفات قاعدة البيانات، ثم نختار إصدار Enterprise مع الإعداد المُسبَق لإصدار Sandbox.

بعد ذلك، اضبط اسم الجهاز الافتراضي وكلمة المرور التلقائية للمستخدم postgres هنا. يمكنك إعداد ذلك باستخدام أي بيانات اعتماد تريدها، ولكن لأغراض هذا البرنامج التعليمي، سنستخدم "adk-deployment" لاسم المثيل و "ADK-deployment123" لكلمة المرور هنا.

ملاحظة مهمة: اسم المستخدم وكلمة المرور هما بيانات حساسة، لذا احرص على إبقائهما سرًّا لا يعرفه أحد.

لنستخدِم us-central1 مع منطقة واحدة في هذا البرنامج التعليمي، ويمكننا إنهاء عملية إنشاء قاعدة البيانات بعد ذلك والسماح لها بإكمال جميع عمليات الإعداد المطلوبة من خلال النقر على الزر إنشاء مثيل.

يُرجى الانتظار، سيستغرق إنشاء قاعدة البيانات من 5 إلى 10 دقائق تقريبًا.

أثناء انتظار اكتمال هذه العملية، يمكننا الانتقال إلى القسم التالي.

الخطوة 3: التعرّف على Cloud Shell

ستستخدم Cloud Shell في معظم أجزاء البرامج التعليمية، لذا انقر على "تفعيل Cloud Shell" في أعلى وحدة تحكّم Google Cloud. إذا طُلب منك التفويض، انقر على تفويض.

بعد الاتصال بـ Cloud Shell، علينا التحقّق مما إذا كان قد تمّت مصادقة الصدفة ( أو الوحدة الطرفية) باستخدام حسابنا.

gcloud auth list

إذا ظهر لك حساب Gmail الشخصي كما في مثال الناتج أدناه، يعني ذلك أنّ كل شيء على ما يرام.

Credentialed Accounts

ACTIVE: *
ACCOUNT: [e-mail]

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

إذا لم يكن كذلك، جرِّب إعادة تحميل المتصفّح وتأكَّد من النقر على تفويض عند مطالبتك بذلك ( قد يتمّ مقاطعة العملية بسبب مشكلة في الاتصال).

بعد ذلك، نحتاج أيضًا إلى التحقّق مما إذا كان قد تمّ إعداد الواجهة باستخدام معرّف المشروع الصحيح الذي لديك. إذا رأيت قيمة داخل ( ) قبل رمز $ في نافذة الأوامر ( في لقطة الشاشة أدناه، القيمة هي "adk-cloudrun-deployment-476504")، تشير هذه القيمة إلى المشروع الذي تمّ إعداده لجلسة الواجهة النشطة.

إذا كانت القيمة المعروضة صحيحة، يمكنك تخطّي الأمر التالي. ومع ذلك، إذا كان غير صحيح أو غير متوفّر، شغِّل الأمر التالي

gcloud config set project <YOUR_PROJECT_ID>

بعد ذلك، استنسِخ دليل العمل الخاص بهذا الدرس النموذجي من Github، ونفِّذ الأمر التالي. سيتم إنشاء دليل العمل في الدليل deploy_and_manage_adk.

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

الخطوة 4: التعرّف على "محرّر Cloud Shell" وإعداد دليل عمل التطبيق

الآن، يمكننا إعداد محرّر الرموز البرمجية لتنفيذ بعض مهام الترميز. سنستخدم "محرّر Cloud Shell" لهذا الغرض.

انقر على الزر فتح المحرِّر، وسيؤدي ذلك إلى فتح في "محرِّر Cloud Shell".

بعد ذلك، انتقِل إلى القسم العلوي من "محرّر Cloud Shell" وانقر على ملف (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. سنستخدم الإصدار 3.12 من لغة Python في هذا الدرس العملي، كما سنستخدم أداة إدارة مشاريع Python‏ (uv) لتسهيل عملية إنشاء إصدار 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.

الآن، علينا تفعيل واجهات برمجة التطبيقات المطلوبة من خلال الأمر الموضّح أدناه. قد يستغرق هذا بعض الوقت.

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 إلى project-id.

ملاحظة: إذا لم تتمكّن من العثور على ملف .env المعروض في المحرّر، يرجع ذلك إلى أنّه مصنّف كملف مخفي. انقر على عرض (View) -> تبديل الملفات المخفية (Toggle Hidden Files) لعرضها

# .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_PROJECT باستخدام رقم تعريف مشروعك.

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

يمكننا الآن الانتقال إلى الخطوة التالية، وهي فحص منطق الوكيل ونشره.

3- 🚀 إنشاء "وكيل الطقس" باستخدام "حزمة تطوير التطبيقات" و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],
)

ملاحظة: بنية الدليل واستيراد الوكيل داخل init.py وتعريف root_agent في agent.py هي البنية الإلزامية التي يجب أن يتعرّف عليها ADK CLI.

شرح الرمز في 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 حتى يكون لدينا تتبُّع مركزي لجميع الطلبات.

تذكير لنوقف عملية adk web مؤقتًا، يمكنك الضغط على CTRL + C لإيقاف العملية

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 sql". بعد ذلك، انقر على منتج Cloud SQL.

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

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

ملاحظة: في نص البرمجة الخاص بالنشر، نضبط متغيرات البيئة SESSION_SERVICE_URI. في حال إعداد هذا المتغيّر، سيستخدم وكيل ADK معرّف الموارد المنتظم (URI) للخدمة من أجل تخزين معلومات الجلسة والحالة (المحدّدة في server.py). في هذا البرنامج التعليمي، سنستخدم اتصال مقبس Unix في PostgreSQL مع برنامج التشغيل pg8000.

يُرجى العِلم أنّه في المثال، نستخدم المستخدم التلقائي postgres وقاعدة البيانات التلقائية postgres (مع كلمة المرور ADK-deployment123).

ملاحظة مهمة: نسمح هنا بالوصول بدون مصادقة (العلامة –allow_unauthenticated) لأنّ هذا التطبيق تجريبي. ننصحك باستخدام المصادقة المناسبة لتطبيقات المؤسسة والإنتاج.

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

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

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

5- 💡 ملف 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:

1. حوِّل وكيلنا إلى تطبيق FastAPI باستخدام طريقة get_fast_api_app. بهذه الطريقة، سنرث تعريف المسار نفسه المستخدَم في واجهة مستخدم تطوير الويب.
2. اضبط خدمة "الجلسة" أو "الذاكرة" أو "العنصر" اللازمة من خلال إضافة وسيطات الكلمات الرئيسية إلى طريقة get_fast_api_app. في هذا البرنامج التعليمي، إذا ضبطنا متغير البيئة SESSION_SERVICE_URI، ستستخدم خدمة الجلسة هذا المتغير، وإلا ستستخدم الجلسة في الذاكرة.
3. يمكننا إضافة مسار مخصّص لدعم منطق الأنشطة التجارية الأخرى في الخلفية، وفي النص البرمجي، نضيف مثالاً على مسار وظيفة الملاحظات.
4. فعِّل تتبُّع السحابة الإلكترونية في مَعلمات get_fast_api_app arg لإرسال التتبُّع إلى Google Cloud Trace
5. تشغيل خدمة FastAPI باستخدام uvicorn

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

6. ‫🚀 فحص ميزة "التوسّع التلقائي" في Cloud Run باستخدام أداة Load Testing

الآن، سنتفحّص إمكانات التوسّع التلقائي في 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 وانقر على خدمة weather-agent.

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

سيظهر عنوان URL الخاص بالخدمة بجانب معلومات المنطقة مباشرةً. مثلاً:

بعد ذلك، نفِّذ الأمر التالي لإجراء اختبار التحميل

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

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

ملاحظة: يمكنك التحكّم في الحد الأقصى للتزامن، بالإضافة إلى الحد الأدنى والأقصى لعدد مثيلات الحاويات. راجِع مستندات حزمة SDK للحصول على التفاصيل.

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

ملاحظة مهمة: عدِّل قيم YOUR_PROJECT_ID هنا

بعد الانتهاء، ستتلقّى سجلاً مشابهًا لسجل عملية النشر السابقة مع اختلاف عدد الزيارات التي تم عرضها. سيظهر 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 وانقر عليها

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

ستلاحظ أنّ المراجعات الجديدة التي تم نشرها تعرض نسبة %0، ويمكنك من هنا النقر على زر قائمة الخيارات (⋮) واختيار إدارة الزيارات.

في النافذة المنبثقة الجديدة، يمكنك تعديل النسبة المئوية للزيارات التي ستنتقل إلى أي من المراجعات.

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

8. ‫🚀 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 من خيارات النشر المختلفة.

حاوِل الوصول إلى واجهة مستخدم مطوّر الويب الخاصة بخدمتك وبدء محادثة مع الوكيل. بعد ذلك، انتقِل إلى شريط البحث في Cloud Console واكتب "Trace Explorer"، ثم اختَر منتج Trace Explorer.

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

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

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

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

9- 🎯 التحدي

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

10. ‫🧹 تنظيف

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

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