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

لمحة عن هذا الدرس التطبيقي حول الترميز

0 دقيقة

تاريخ التعديل الأخير: 19 يونيو 2025

تأليف: Alvin Prayuda Juniarta Dwiyantoro

1. مقدمة

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

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

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

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

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

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

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

الشعور بالارتياح عند العمل باستخدام لغة Python
فهم أساسي لبنية الحزمة الكاملة باستخدام خدمة HTTP

ما ستتعرّف عليه

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

المتطلبات

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

تم تصميم هذا المختبر البرمجي للمطوّرين من جميع المستويات (بما في ذلك المبتدئين)، ويستخدم لغة بايثون في تطبيقه النموذجي. ومع ذلك، لا يُشترط معرفة 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 Terminal

ستستخدم 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 وإعداد دليل عمل التطبيق

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

انقر على الزر Open Editor (فتح المحرِّر)، سيؤدي ذلك إلى فتح محرِّر Cloud Shell، ويمكننا كتابة الرمز هنا
تأكَّد من ضبط مشروع 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 وانقر على ملف->فتح مجلد، وابحث عن دليل username وابحث عن دليل deploy_and_manage_adk ثم انقر على الزر "حسنًا". سيؤدي ذلك إلى جعل الدليل الذي تم اختياره هو الدليل الرئيسي للعمل. في هذا المثال، اسم المستخدم هو alvinprayuda، وبالتالي يظهر مسار الدليل أدناه.

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

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

إعداد البيئة

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

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

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

# 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- إنشاء وكيل الطقس باستخدام ADK وGemini 2.5

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

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

إعداد بنية دليل موظّفي الدعم
تجربة التفاعل بسرعة من خلال إدخال وإخراج واجهة سطر الأوامر
إعداد واجهة مستخدم الويب لتطوير التطبيقات على الجهاز بسرعة

الآن، لنطّلِع على بنية الوكيل في دليل 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" واختَر معاينة على المنفذ 8080.

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

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

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

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

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

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

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 وانقر عليها.

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

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

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

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

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 . سننشئ هنا أداة تصدير مخصّصة لأنّ هناك حدًا أقصى لبيانات التتبّع التي يمكن تصديرها إلى تتبّع السحابة الإلكترونية. نحن نستخدم عملية تنفيذ من https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html للحصول على إمكانية التتبّع هذه.

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

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

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

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

حسنًا، لدينا الآن إمكانية مراقبة جيدة ومعلومات عن كل تفاعل بين موظّف الدعم والمستخدم للمساعدة في تصحيح الأخطاء. لا تتردد في تجربة أدوات أو سير عمل مختلفة.

9- التحدي

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

10. تَنظيم

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

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