استقرار، مدیریت و مشاهده Agent ADK در Cloud Run

1. مقدمه

این آموزش شما را از طریق استقرار، مدیریت و نظارت بر یک عامل قدرتمند ساخته شده با Agent Development Kit (ADK) در Google Cloud Run راهنمایی می کند. ADK به شما این امکان را می دهد که عواملی را ایجاد کنید که قادر به گردش کار پیچیده و چند عاملی باشند. با استفاده از Cloud Run، یک پلتفرم بدون سرور کاملاً مدیریت شده، می‌توانید عامل خود را به عنوان یک برنامه کاربردی مقیاس‌پذیر و کانتینری بدون نگرانی در مورد زیرساخت‌های زیربنایی مستقر کنید. این ترکیب قدرتمند به شما امکان می‌دهد تا روی منطق اصلی عامل خود تمرکز کنید و در عین حال از محیط قوی و مقیاس‌پذیر Google Cloud بهره ببرید.

در طول این آموزش، ادغام یکپارچه ADK با Cloud Run را بررسی خواهیم کرد. شما یاد خواهید گرفت که چگونه عامل خود را مستقر کنید و سپس به جنبه های عملی مدیریت برنامه خود در محیطی شبیه تولید بپردازید. ما نحوه ارائه ایمن نسخه‌های جدید نماینده خود را با مدیریت ترافیک توضیح خواهیم داد و به شما امکان می‌دهد تا قبل از انتشار کامل ویژگی‌های جدید را با زیرمجموعه‌ای از کاربران آزمایش کنید.

علاوه بر این، تجربه عملی در نظارت بر عملکرد نماینده خود به دست خواهید آورد. ما یک سناریوی دنیای واقعی را با انجام آزمایش بار برای مشاهده قابلیت‌های مقیاس خودکار Cloud Run در عمل شبیه‌سازی می‌کنیم. برای به دست آوردن بینش عمیق تر در مورد رفتار و عملکرد نماینده خود، ردیابی را با Cloud Trace فعال می کنیم. این یک نمای دقیق و سرتاسر درخواست‌ها را در حین سفر از طریق نماینده شما ارائه می‌کند و به شما امکان می‌دهد هر گونه گلوگاه عملکرد را شناسایی و برطرف کنید. در پایان این آموزش، شما درک جامعی از نحوه استقرار، مدیریت و نظارت موثر عوامل مبتنی بر ADK خود در Cloud Run خواهید داشت.

از طریق کد لبه، شما یک رویکرد گام به گام را به شرح زیر به کار خواهید گرفت:

  1. ایجاد یک پایگاه داده PostgreSQL در CloudSQL برای استفاده برای سرویس جلسه پایگاه داده ADK Agent
  2. یک عامل اصلی ADK راه اندازی کنید
  3. راه اندازی سرویس جلسه پایگاه داده برای استفاده توسط ADK runner
  4. استقرار اولیه عامل در اجرای ابری
  5. تست را بارگیری کنید و مقیاس خودکار اجرای ابر را بررسی کنید
  6. بازبینی عامل جدید را اجرا کنید و به تدریج ترافیک را به ویرایش های جدید افزایش دهید
  7. ردیابی ابری را راه اندازی کنید و ردیابی اجرای عامل را بررسی کنید

نمای کلی معماری

5e38fc5607fb4543.jpeg

پیش نیازها

  • کار راحت با پایتون
  • درک معماری پایه تمام پشته با استفاده از سرویس HTTP

چیزی که یاد خواهید گرفت

  • ساختار ADK و ابزارهای محلی
  • راه اندازی عامل ADK با سرویس جلسه پایگاه داده
  • PostgreSQL را در CloudSQL راه اندازی کنید تا توسط سرویس جلسه پایگاه داده استفاده شود
  • برنامه را با استفاده از Dockerfile در Cloud Run اجرا کنید و متغیرهای محیط اولیه را تنظیم کنید
  • پیکربندی و تست مقیاس خودکار Cloud Run با تست بار
  • استراتژی انتشار تدریجی با Cloud Run
  • ردیابی عامل ADK را در Cloud Trace تنظیم کنید

آنچه شما نیاز دارید

  • مرورگر وب کروم
  • یک اکانت جیمیل
  • یک پروژه Cloud با فعال کردن صورت‌حساب

این کد لبه که برای توسعه دهندگان همه سطوح (از جمله مبتدیان) طراحی شده است، از پایتون در برنامه نمونه خود استفاده می کند. با این حال، دانش پایتون برای درک مفاهیم ارائه شده مورد نیاز نیست.

2. قبل از شروع

Active Project را در Cloud Console انتخاب کنید

این کد لبه فرض می کند که شما قبلاً یک پروژه Google Cloud با فعال بودن صورتحساب دارید. اگر هنوز آن را ندارید، می توانید دستورالعمل های زیر را برای شروع دنبال کنید.

  1. در Google Cloud Console ، در صفحه انتخاب پروژه، یک پروژه Google Cloud را انتخاب یا ایجاد کنید.
  2. مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورت‌حساب در پروژه آشنا شوید.

c714d4741fc97644.png

پایگاه داده Cloud SQL را آماده کنید

ما به یک پایگاه داده نیاز داریم تا بعداً توسط عامل ADK مورد استفاده قرار گیرد. بیایید یک پایگاه داده PostgreSQL در Cloud SQL ایجاد کنیم. ابتدا به نوار جستجو در قسمت بالای کنسول ابری بروید و "cloud sql" را تایپ کنید. سپس روی محصول Cloud SQL کلیک کنید

1005cb65520eb3fc.png

پس از آن، ما باید یک نمونه پایگاه داده جدید ایجاد کنیم، روی Create Instance کلیک کرده و PostgreSQL را انتخاب کنید.

7f2ad19bc246895d.png

ead4a98e7a8d8a39.png

همچنین اگر با پروژه جدید شروع می کنید، ممکن است لازم باشد Compute Engine API را فعال کنید، اگر این درخواست ظاهر شد، فقط روی Enable API کلیک کنید.

724cf67681535679.png

در مرحله بعد، مشخصات پایگاه داده را انتخاب می کنیم، نسخه Enterprise با از پیش تعیین شده نسخه Sandbox را انتخاب می کنیم.

24aa9defed93a3ef.png

پس از آن، نام نمونه و رمز عبور پیش فرض برای postgres کاربر را در اینجا تنظیم کنید. شما می توانید این را با هر اعتباری که می خواهید تنظیم کنید، با این حال به خاطر این آموزش ما برای نام نمونه و رمز عبور از " adk-deployment " استفاده می کنیم.

573719a4582f541c.png

بیایید از us-central1 با منطقه تک برای این آموزش استفاده کنیم، سپس می‌توانیم ایجاد پایگاه داده خود را نهایی کنیم و با کلیک بر روی دکمه Create Instance ، تمام تنظیمات لازم را به پایان برسانیم.

773e2ea11d97369d.png

در حالی که منتظر اتمام این کار هستیم، می توانیم به بخش بعدی ادامه دهیم

راه اندازی پروژه Cloud در ترمینال Cloud Shell

  1. شما از Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا می شود، استفاده خواهید کرد. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.

1829c3759227c19b.png

  1. پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که قبلاً احراز هویت شده‌اید و پروژه به ID پروژه شما تنظیم شده است: 
gcloud auth list
  1. دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد. 
gcloud config list project
  1. اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید: 
gcloud config set project <YOUR_PROJECT_ID>

همچنین می‌توانید شناسه PROJECT_ID را در کنسول ببینید

4032c45803813f30.jpeg

روی آن کلیک کنید و تمام پروژه و شناسه پروژه را در سمت راست خواهید دید

8dc17eb4271de6b5.jpeg

  1. API های مورد نیاز را از طریق دستور زیر فعال کنید. این ممکن است چند دقیقه طول بکشد، پس لطفا صبور باشید. 
gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com

در اجرای موفقیت آمیز دستور، باید پیامی مشابه تصویر زیر مشاهده کنید:

Operation "operations/..." finished successfully.

جایگزین دستور gcloud از طریق کنسول با جستجوی هر محصول یا استفاده از این پیوند است.

اگر هر یک از API از دست رفته است، همیشه می توانید آن را در طول پیاده سازی فعال کنید.

برای دستورات و استفاده از gcloud به اسناد مراجعه کنید.

به Cloud Shell Editor and Setup Application Working Directory بروید

اکنون، می‌توانیم ویرایشگر کد خود را برای انجام برخی موارد کدنویسی تنظیم کنیم. برای این کار از Cloud Shell Editor استفاده خواهیم کرد

  1. روی دکمه Open Editor کلیک کنید، با این کار یک Cloud Shell Editor باز می شود، ما می توانیم کد خود را اینجا بنویسیم b16d56e4979ec951.png
  2. مطمئن شوید که پروژه Cloud Code در گوشه سمت چپ پایین (نوار وضعیت) ویرایشگر Cloud Shell تنظیم شده است، همانطور که در تصویر زیر مشخص شده است و روی پروژه فعال Google Cloud که در آن صورت‌حساب را فعال کرده‌اید، تنظیم شده است. در صورت درخواست مجوز دهید . اگر از قبل دستور قبلی را دنبال کرده اید، دکمه ممکن است به جای دکمه ورود مستقیماً به پروژه فعال شده شما اشاره کند

f5003b9c38b43262.png

  1. سپس، بیایید دایرکتوری کار قالب را برای این کد لبه از Github کلون کنیم، دستور زیر را اجرا کنیم. دایرکتوری کاری را در دایرکتوری deploy_and_manage_adk ایجاد می کند 
git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk
  1. پس از آن، به بخش بالای ویرایشگر پوسته ابری بروید و روی File->Open Folder کلیک کنید، دایرکتوری نام کاربری خود را پیدا کنید و دایرکتوری deploy_and_manage_adk را پیدا کنید و سپس روی دکمه OK کلیک کنید. این دایرکتوری انتخاب شده را به عنوان دایرکتوری اصلی تبدیل می کند. در این مثال، نام کاربری alvinprayuda است، از این رو مسیر دایرکتوری در زیر نشان داده شده است

2c53696f81d805cc.png

a51615f22ba1690f.png

حال، ویرایشگر پوسته ابری شما باید به این شکل باشد

228d4c1844790573.png

بعد، ما می توانیم تنظیمات محیط پایتون خود را پیکربندی کنیم

راه اندازی محیط

محیط مجازی پایتون را آماده کنید

مرحله بعدی آماده سازی محیط توسعه است. فهرست کار ترمینال فعال فعلی شما باید در دایرکتوری کاری deploy_and_manage_adk باشد. ما از Python 3.12 در این کد لبه استفاده خواهیم کرد و از مدیر پروژه uv python برای ساده سازی نیاز به ایجاد و مدیریت نسخه پایتون و محیط مجازی استفاده خواهیم کرد.

  1. اگر هنوز ترمینال را باز نکرده اید، آن را با کلیک بر روی Terminal -> New Terminal باز کنید یا از Ctrl + Shift + C استفاده کنید، یک پنجره ترمینال در قسمت پایین مرورگر باز می شود.

f8457daf0bed059e.jpeg

  1. uv را دانلود و با دستور زیر پایتون 3.12 را نصب کنید 
curl -LsSf https://astral.sh/uv/0.6.16/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12
  1. حال اجازه دهید محیط مجازی را با استفاده از 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",
]
  1. برای تست env مجازی، فایل جدید main.py ایجاد کنید و کد زیر را کپی کنید 
def main():
   print("Hello from deploy_and_manage_adk!")

if __name__ == "__main__":
   main()
  1. سپس، دستور زیر را اجرا کنید 
uv run main.py

مانند شکل زیر خروجی دریافت خواهید کرد 

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

این نشان می دهد که پروژه پایتون به درستی راه اندازی شده است.

راه اندازی فایل های پیکربندی

اکنون باید فایل های پیکربندی این پروژه را تنظیم کنیم.

نام فایل .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 ارائه می دهد و نحوه ساخت عامل شروع کنیم. اسناد کامل ADK در این URL قابل دسترسی است. ADK ابزارهای بسیاری را در اجرای دستور CLI خود به ما ارائه می دهد. برخی از آنها به شرح زیر است:

  • ساختار دایرکتوری عامل را تنظیم کنید
  • به سرعت تعامل را از طریق خروجی ورودی CLI امتحان کنید
  • به سرعت رابط وب UI توسعه محلی را تنظیم کنید

حال، بیایید ساختار عامل را در دایرکتوری 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 به ما این امکان را می دهد که یک رابط کاربری وب توسعه داشته باشیم تا بتوانیم با هم تعامل داشته باشیم و آنچه را که در طول تعامل در حال انجام است بررسی کنیم. دستور زیر را برای راه اندازی سرور UI توسعه محلی اجرا کنید 

uv run adk web --port 8080

مانند مثال زیر خروجی ایجاد می کند، به این معنی که ما می توانیم از قبل به رابط وب دسترسی داشته باشیم 

INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

اکنون برای بررسی آن، روی دکمه Web Preview در قسمت بالای Cloud Shell Editor خود کلیک کرده و Preview در پورت 8080 را انتخاب کنید.

e7c9f56c2463164.png

صفحه وب زیر را مشاهده خواهید کرد که در آن می توانید عوامل موجود را در دکمه کشویی بالا سمت چپ انتخاب کنید (در مورد ما باید weather_agent باشد) و با ربات تعامل کنید. در پنجره سمت چپ، اطلاعات زیادی در مورد جزئیات گزارش در طول اجرای Agent مشاهده خواهید کرد

d95b1e057315fee2.png

حالا سعی کنید با آن تعامل داشته باشید. در نوار سمت چپ، می‌توانیم ردیابی را برای هر ورودی بررسی کنیم، بنابراین می‌توانیم بفهمیم که برای هر اقدام انجام شده توسط عامل قبل از تشکیل پاسخ نهایی چقدر زمان می‌برد.

39c0a06ace937683.png

این یکی از ویژگی های قابل مشاهده است که در ADK تعبیه شده است، در حال حاضر ما آن را به صورت محلی بررسی می کنیم. بعداً خواهیم دید که چگونه این مورد در Cloud Tracing یکپارچه شده است بنابراین ما ردیابی متمرکز همه درخواست ها را داریم

4. اسکریپت سرور Backend

به منظور دسترسی به عامل به عنوان یک سرویس، ما عامل را در داخل یک برنامه 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 تعریف شده است:

  1. عامل ما را با استفاده از روش get_fast_api_app به یک برنامه FastAPI تبدیل کنید. به این ترتیب ما همان تعریف مسیری را که برای رابط کاربری توسعه وب استفاده می شود به ارث می بریم.
  2. سرویس Session، Memory یا Artifact لازم را با افزودن آرگومان های کلمه کلیدی به متد get_fast_api_app پیکربندی کنید. در این آموزش، اگر SESSION_SERVICE_URI env var را پیکربندی کنیم، سرویس session از آن استفاده خواهد کرد در غیر این صورت از جلسه درون حافظه استفاده خواهد کرد.
  3. ما می‌توانیم مسیر سفارشی را برای پشتیبانی از منطق تجاری دیگر باطن اضافه کنیم، در اسکریپت مثال مسیر عملکرد بازخورد را اضافه می‌کنیم
  4. برای ارسال ردیابی به Google Cloud Trace، ردیابی ابری را فعال کنید

5. استقرار در Cloud Run

اکنون، بیایید این سرویس عامل را در Cloud Run مستقر کنیم. به خاطر این نسخه ی نمایشی، این سرویس به عنوان یک سرویس عمومی که برای دیگران قابل دسترسی است در معرض دید قرار می گیرد. با این حال، به خاطر داشته باشید که این بهترین روش نیست زیرا ایمن نیست

5e38fc5607fb4543.jpeg

در این کد لبه، ما از 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} را جایگزین کنید. به عنوان مثال به تصویر زیر نگاه کنید

5d7d6c6f17e559c1.png

اگر از شما خواسته شد که ایجاد یک رجیستری مصنوع را برای مخزن docker تأیید کنید، فقط به Y پاسخ دهید. توجه داشته باشید که ما در اینجا اجازه دسترسی غیرقانونی را می دهیم زیرا این یک برنامه آزمایشی است. توصیه این است که از احراز هویت مناسب برای برنامه های تجاری و تولیدی خود استفاده کنید.

پس از تکمیل استقرار، باید پیوندی شبیه به زیر دریافت کنید:

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

ادامه دهید و از برنامه خود از پنجره ناشناس یا دستگاه تلفن همراه خود استفاده کنید. از قبل باید زنده باشد.

6. بازرسی Cloud Run Auto Scaling با تست بار

اکنون، ما قابلیت‌های مقیاس خودکار اجرای ابری را بررسی می‌کنیم. برای این سناریو، اجازه دهید بازبینی جدید را اجرا کنیم و در عین حال حداکثر همزمانی را در هر نمونه فعال کنیم. دستور زیر را اجرا کنید 

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

پس از آن اجازه دهید فایل load_test.py را بررسی کنیم. این اسکریپتی است که برای انجام تست بارگذاری با استفاده از Locus Framework استفاده می کنیم. این اسکریپت کارهای زیر را انجام خواهد داد:

  1. user_id و session_id تصادفی
  2. session_id را برای user_id ایجاد کنید
  3. با user_id و session_id ایجاد شده، نقطه پایانی "/run_sse" را بزنید

اگر آن را از دست دادید، باید URL سرویس مستقر شده خود را بدانیم. به کنسول Cloud Run بروید و روی سرویس عامل هواشناسی خود کلیک کنید

f5cc953cc422de6d.png

سپس، سرویس عامل هواشناسی خود را پیدا کرده و روی آن کلیک کنید

ddd0df8544aa2bfb.png

URL سرویس درست در کنار اطلاعات منطقه نمایش داده می شود. به عنوان مثال

41b1276616379ee8.png

سپس دستور زیر را برای انجام تست بارگذاری اجرا کنید 

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

با اجرای این، معیارهایی مانند این را خواهید دید. (در این مثال همه reqs موفقیت آمیز هستند) 

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 در هر نمونه محدود می‌کنیم، نمونه اجرای ابری سعی می‌کند تعداد کانتینرها را تنظیم کند تا این شرط را به طور خودکار برآورده کند.

1ad41143eb9d95df.png

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],
)

سپس، می‌خواهید نسخه‌های جدیدی را منتشر کنید، اما نمی‌خواهید تمام ترافیک درخواست‌ها مستقیماً به نسخه جدید برود. ما می توانیم با اجرای ابری، انتشار تدریجی را انجام دهیم. اول، ما باید یک ویرایش جدید را اجرا کنیم، اما با پرچم بدون ترافیک . اسکریپت عامل قبلی را ذخیره کرده و دستور زیر را اجرا کنید 

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

پس از اتمام، یک گزارش مشابه مانند فرآیند استقرار قبلی با تفاوت تعداد ترافیک ارائه شده دریافت خواهید کرد. 0 درصد ترافیک ارائه شده را نشان می دهد.

در مرحله بعد، اجازه دهید به صفحه محصول Cloud Run برویم و نمونه مستقر شده خود را پیدا کنیم. ابر run را در نوار جستجو تایپ کنید و روی محصول Cloud Run کلیک کنید

f5cc953cc422de6d.png

سپس، سرویس عامل هواشناسی خود را پیدا کرده و روی آن کلیک کنید

ddd0df8544aa2bfb.png

به تب Revisions بروید و لیستی از نسخه های مستقر شده را در آنجا خواهید دید

8519c5a59bc7efa6.png

مشاهده خواهید کرد که نسخه‌های جدید مستقر شده 0% ارائه می‌شوند، از اینجا می‌توانید روی دکمه کباب (⋮) کلیک کنید و مدیریت ترافیک را انتخاب کنید.

d4d224e20813c303.png

در پنجره‌ای که به تازگی باز می‌شود، می‌توانید درصد ترافیکی که به آن ویرایش‌ها می‌رود را ویرایش کنید.

6df497c3d5847f14.png

پس از مدتی انتظار، ترافیک به طور متناسب بر اساس تنظیمات درصد هدایت می شود. به این ترتیب، اگر در نسخه جدید اتفاقی افتاد، به راحتی می‌توانیم به نسخه‌های قبلی برگردیم

8. ADK Tracing

عوامل ساخته شده با 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 برای این قابلیت ردیابی استفاده می کنیم.

سعی کنید به رابط کاربری وب توسعه دهنده سرویس خود دسترسی داشته باشید و با نماینده گپ بزنید. پس از آن به نوار جستجوی کنسول ابری بروید و "trace explorer" را تایپ کنید و محصول Trace Explorer را در آنجا انتخاب کنید

4353c0f8982361ab.png

در صفحه ردیابی کاوشگر، مشاهده خواهید کرد که مکالمه ما با عامل ردیابی ارسال شده است. می‌توانید از قسمت Span name ببینید و محدوده مخصوص عامل ما (نام آن agent_run [weather_agent] ) را در آنجا فیلتر کنید.

c4336d117a3d2f6a.png

هنگامی که دهانه ها از قبل فیلتر شده اند، می توانید هر ردیابی را مستقیماً بررسی کنید. مدت زمان دقیق هر اقدام انجام شده توسط نماینده را نشان می دهد. برای مثال به تصاویر زیر نگاه کنید

76a56dff77979037.png

1a3ce0a803d6061a.png

در هر بخش، می توانید جزئیات را در ویژگی هایی مانند شکل زیر بررسی کنید

2c87b6d67b0164a8.png

اکنون ما قابلیت مشاهده و اطلاعات خوبی در مورد هر تعامل نماینده خود با کاربر داریم تا به رفع اشکال کمک کنیم. با خیال راحت ابزارهای مختلف یا گردش کار را امتحان کنید!

9. چالش

گردش‌های کاری چند عاملی یا عاملی را امتحان کنید تا ببینید در زیر بارها چگونه عمل می‌کنند و ردیابی چگونه است.

10. پاکسازی کنید

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع مورد استفاده در این Codelab، این مراحل را دنبال کنید:

  1. در کنسول Google Cloud، به صفحه مدیریت منابع بروید.
  2. در لیست پروژه، پروژه ای را که می خواهید حذف کنید انتخاب کنید و سپس روی Delete کلیک کنید.
  3. در محاوره، شناسه پروژه را تایپ کنید و سپس روی Shut down کلیک کنید تا پروژه حذف شود.
  4. یا می‌توانید به Cloud Run در کنسول بروید، سرویسی را که به تازگی مستقر کرده‌اید انتخاب کرده و حذف کنید.