تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

نشر وكيل 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 Agent إلى Cloud Trace

المتطلبات

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

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

2. قبل البدء

اختيار المشروع النشط في Cloud Console

يفترض هذا الدرس العملي أنّ لديك مشروعًا على Google Cloud تم تفعيل الفوترة فيه. إذا لم تكن هذه الميزة متاحة لك بعد، يمكنك اتّباع التعليمات أدناه للبدء.

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

إعداد قاعدة بيانات Cloud SQL

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

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

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

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

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

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

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

إعداد مشروع Cloud في نافذة Cloud Shell

ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud. انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud".

بعد الاتصال بـ Cloud Shell، تحقَّق من أنّك قد تمّت مصادقتك وأنّه تم ضبط المشروع على معرّف مشروعك باستخدام الأمر التالي:

gcloud auth list

نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك.

gcloud config list project

إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:

gcloud config set project <YOUR_PROJECT_ID>

بدلاً من ذلك، يمكنك أيضًا الاطّلاع على معرّف PROJECT_ID في وحدة التحكّم.

انقر عليه وسيظهر لك كل مشروعك ورقم تعريف المشروع على الجانب الأيسر

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

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

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

Operation "operations/..." finished successfully.

يمكنك بدلاً من استخدام أمر gcloud، البحث عن كل منتج من خلال وحدة التحكّم أو استخدام هذا الرابط.

في حال عدم توفّر أي واجهة برمجة تطبيقات، يمكنك تفعيلها في أي وقت أثناء عملية التنفيذ.

راجِع المستندات لمعرفة أوامر gcloud وطريقة استخدامها.

الانتقال إلى Cloud Shell Editor وإعداد دليل عمل التطبيق

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

انقر على الزر "فتح المحرِّر" (Open Editor)، وسيؤدي ذلك إلى فتح "محرِّر Cloud Shell" (Cloud Shell Editor)، ويمكننا كتابة الرمز هنا
تأكَّد من ضبط مشروع Cloud Code في أسفل يمين (شريط الحالة) محرر Cloud Shell، كما هو موضّح في الصورة أدناه، ومن ضبطه على مشروع Google Cloud النشط الذي تم تفعيل الفوترة فيه. امنح الإذن إذا طُلب منك ذلك. إذا كنت قد اتّبعت الأمر السابق، قد يشير الزر أيضًا مباشرةً إلى مشروعك المفعّل بدلاً من زر تسجيل الدخول.

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

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

بعد ذلك، انتقِل إلى القسم العلوي من "محرّر Cloud Shell" وانقر على ملف (File) -> فتح مجلد (Open Folder)، وابحث عن دليل اسم المستخدم، ثم ابحث عن دليل deploy_and_manage_adk وانقر على الزر "حسنًا" (OK). سيؤدي ذلك إلى جعل الدليل الذي تم اختياره هو دليل العمل الرئيسي. في هذا المثال، اسم المستخدم هو alvinprayuda، وبالتالي يظهر مسار الدليل أدناه

من المفترض أن يظهر "محرّر Cloud Shell" الآن على النحو التالي

بعد ذلك، يمكننا ضبط إعداد بيئة Python

إعداد البيئة

إعداد بيئة Python الافتراضية

الخطوة التالية هي إعداد بيئة التطوير. يجب أن يكون دليل العمل النشط الحالي في نافذة الوحدة الطرفية ضِمن دليل العمل deploy_and_manage_adk. سنستخدم الإصدار 3.12 من لغة Python في هذا الدرس العملي، كما سنستخدم أداة إدارة مشاريع Python‏ uv لتسهيل عملية إنشاء إصدار Python وبيئة افتراضية وإدارتهما.

إذا لم تكن قد فتحت المحطة الطرفية بعد، افتحها بالنقر على المحطة الطرفية -> محطة طرفية جديدة، أو استخدِم Ctrl + Shift + C، وسيؤدي ذلك إلى فتح نافذة محطة طرفية في الجزء السفلي من المتصفح.

نزِّل uv وثبِّت الإصدار 3.12 من Python باستخدام الأمر التالي

curl -LsSf https://astral.sh/uv/0.6.16/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12

لنبدأ الآن بتهيئة البيئة الافتراضية باستخدام uv، وننفّذ الأمر التالي

uv sync --frozen

سيؤدي ذلك إلى إنشاء الدليل .venv وتثبيت الموارد التابعة. ستمنحك نظرة خاطفة سريعة على pyproject.toml معلومات عن التبعيات المعروضة على النحو التالي

dependencies = [
    "google-adk==1.3.0",
    "locust==2.37.10",
    "pg8000==1.31.2",
    "python-dotenv==1.1.0",
]

لاختبار البيئة الافتراضية، أنشئ ملفًا جديدًا باسم main.py وانسخ الرمز التالي

def main():
   print("Hello from deploy_and_manage_adk!")

if __name__ == "__main__":
   main()

بعد ذلك، شغِّل الأمر التالي

uv run main.py

ستظهر لك نتيجة مشابهة لما يلي

Using CPython 3.12
Creating virtual environment at: .venv
Hello from deploy_and_manage_adk!

يشير ذلك إلى أنّه يتم إعداد مشروع Python بشكل صحيح.

إعداد ملفات الإعداد

الآن، علينا إعداد ملفات الضبط لهذا المشروع.

أعِد تسمية الملف .env.example إلى .env وسيتم عرض القيمة أدناه. عدِّل قيمة GOOGLE_CLOUD_PROJECT إلى project-id

# 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
# SESSION_SERVICE_URI=postgresql+pg8000://<username>:<password>@/<database>?unix_sock=/cloudsql/<instance_connection_name>/.s.PGSQL.5432

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

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

3- إنشاء "وكيل الطقس" باستخدام "حزمة تطوير التطبيقات" وGemini 2.5

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

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

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

الآن، لنلقِ نظرة على بنية الوكيل في الدليل weather_agent

weather_agent/
├── __init__.py
├── agent.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 google.cloud import logging as google_cloud_logging

# 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")

logging_client = google_cloud_logging.Client()
logger = logging_client.logger("weather-agent")


def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Args:
        city (str): The name of the city (e.g., "New York", "London", "Tokyo").

    Returns:
        dict: A dictionary containing the weather information.
              Includes a 'status' key ('success' or 'error').
              If 'success', includes a 'report' key with weather details.
              If 'error', includes an 'error_message' key.
    """
    logger.log_text(
        f"--- Tool: get_weather called for city: {city} ---", severity="INFO"
    )  # Log tool execution
    city_normalized = city.lower().replace(" ", "")  # Basic normalization

    # Mock weather data
    mock_weather_db = {
        "newyork": {
            "status": "success",
            "report": "The weather in New York is sunny with a temperature of 25°C.",
        },
        "london": {
            "status": "success",
            "report": "It's cloudy in London with a temperature of 15°C.",
        },
        "tokyo": {
            "status": "success",
            "report": "Tokyo is experiencing light rain and a temperature of 18°C.",
        },
    }

    if city_normalized in mock_weather_db:
        return mock_weather_db[city_normalized]
    else:
        return {
            "status": "error",
            "error_message": f"Sorry, I don't have weather information for '{city}'.",
        }


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 Editor واختَر معاينة على المنفذ 8080.

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

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

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

4. نص برمجي لخادم الخلفية

لإتاحة الوصول إلى الوكيل كخدمة، سنغلّف الوكيل داخل تطبيق FastAPI. ويمكننا هنا ضبط الخدمات اللازمة لدعم الوكيل، مثل إعداد خدمة الجلسة أو الذاكرة أو القطع الأثرية لأغراض الإنتاج. في ما يلي رمز 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
from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export


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

# 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",
    )

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# 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 = ""


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

5- النشر على Cloud Run

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

في هذا الدرس التطبيقي حول الترميز، سنستخدم Dockerfile لنشر وكيلنا على Cloud Run. في ما يلي محتوى 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"]

في هذه المرحلة، لدينا جميع الملفات اللازمة لنشر تطبيقاتنا على Cloud Run، فلننفّذ عملية النشر. انتقِل إلى "وحدة Cloud Shell" وتأكَّد من ضبط المشروع الحالي على مشروعك النشط. وإذا لم يكن كذلك، عليك استخدام الأمر gcloud configure لضبط رقم تعريف المشروع:

gcloud config set project [PROJECT_ID]

بعد ذلك، شغِّل الأمر التالي لنشره على Cloud Run.

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --add-cloudsql-instances {YOUR_DB_CONNECTION_NAME} \
                  --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:{YOUR_DEFAULT_USER_PASS}@postgres/?unix_sock=/cloudsql/{YOUR_DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT={YOUR_PROJECT_ID} \
                  --region us-central1

للحصول على قيمة {YOUR_DB_CONNECTION_NAME}، يمكنك الانتقال إلى Cloud SQL مرة أخرى والنقر على المثيل الذي أنشأته. داخل صفحة المثيل، انتقِل للأسفل إلى قسم الاتصال بهذا المثيل ويمكنك نسخ اسم الاتصال لاستبدال القيمة {YOUR_DB_CONNECTION_NAME}. على سبيل المثال، انظر إلى الصورة الموضّحة أدناه.

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

يُرجى العِلم أنّه في المثال، نستخدم المستخدم التلقائي postgres وقاعدة البيانات التلقائية postgres . إذا كنت تستخدم القيم نفسها الواردة في البرنامج التعليمي، من المفترض أن يبدو SESSION_SERVICE_URI على النحو التالي

SESSION_SERVICE_URI="postgresql+pg8000://postgres:adk-deployment@postgres/?unix_sock=/cloudsql/{YOUR_PROJECT_ID}:us-central1:adk-deployment/.s.PGSQL.5432"

وبالتالي، ما عليك سوى استبدال رقم تعريف المشروع هنا.

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

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

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

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

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

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

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

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

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

7. إصدار مراجعات جديدة تدريجيًا

لنفترض الآن السيناريو التالي. نريد تعديل طلب الوكيل إلى ما يلي :

# agent.py

...

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash-preview-05-20",
    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 في المئة من عدد الزيارات التي تم عرض الإعلانات لها.

بعد ذلك، لننتقل إلى صفحة منتج Cloud Run ونبحث عن مثيلك الذي تم نشره. اكتب cloud run في شريط البحث وانقر على منتج Cloud Run

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

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

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

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

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

8. تتبُّع ADK

تتيح "حزمة تطوير التطبيقات" (ADK) تتبُّع العمليات باستخدام ميزة "التضمين المفتوح لنظام القياس عن بُعد". لدينا Cloud Trace لتسجيل عمليات التتبُّع هذه وعرضها بشكل مرئي. لنلقِ نظرة على server.py لمعرفة كيفية تفعيلها في الخدمة التي تم نشرها سابقًا.

# server.py

from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export

...

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

...

هنا، نضبط إعدادات أداة التتبُّع وأداة التصدير. يمكن الاطّلاع على تفاصيل المصدر على tracing.py . ننشئ هنا أداة تصدير مخصّصة لأنّ هناك حدًا أقصى لبيانات التتبُّع التي يمكن تصديرها إلى Cloud Trace. نستخدم عملية تنفيذ من https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html لتوفير إمكانية التتبُّع هذه.

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

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

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

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

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

9- التحدي

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

10. تَنظيم

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

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