این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

۱. مقدمه

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

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

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

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

یک پایگاه داده PostgreSQL روی CloudSQL ایجاد کنید تا برای سرویس جلسه پایگاه داده ADK Agent استفاده شود.
یک عامل ADK پایه راه‌اندازی کنید
تنظیم سرویس نشست پایگاه داده برای استفاده توسط ADK runner
استقرار اولیه عامل در فضای ابری
تست بار و بررسی مقیاس‌بندی خودکار اجرای ابری
نسخه جدید Agent را مستقر کنید و به تدریج ترافیک را به نسخه‌های جدید افزایش دهید
راه‌اندازی ردیابی ابری و اجرای ردیابی توسط عامل بازرسی

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

پیش‌نیازها

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

آنچه یاد خواهید گرفت

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

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

مرورگر وب کروم
یک حساب جیمیل
یک پروژه ابری با قابلیت پرداخت صورتحساب

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

۲. 🚀 آماده‌سازی مقدمات کارگاه

نکات مهم:

این آموزش به یک پروژه گوگل کلود با یک حساب پرداخت فعال نیاز دارد. اگر هنوز حساب ندارید، لطفاً مراحل زیر را برای دریافت یک حساب پرداخت آزمایشی که می‌توانید برای این آموزش استفاده کنید، دنبال کنید:

باز کردن پنجره ناشناس
اگر در حال پیوستن به یک جلسه کارگاه هستید، معمولاً آدرس اینترنتی پورتال بازخرید در جلسه ارائه می‌شود، در غیر این صورت می‌توانید به این پورتال بازخرید حساب صورتحساب آزمایشی بروید
با استفاده از حساب جیمیل شخصی خود وارد شوید (Google Workspace / سایر ایمیل‌ها کار نخواهند کرد!)
دستورالعمل‌های بازخرید را گام به گام دنبال کنید تا با موفقیت یک پروژه جدید Google Cloud ایجاد کنید که به حساب پرداخت آزمایشی قبلاً ادعا شده برای این آموزش مرتبط باشد .

اکنون، ما از Cloud Shell IDE برای این آموزش استفاده خواهیم کرد، برای رفتن به آنجا روی دکمه زیر کلیک کنید.

پس از ورود به Cloud Shell، پوشه کاری قالب را برای این codelab از Github کپی کنید و دستور زیر را اجرا کنید. این دستور پوشه کاری را در پوشه deploy_and_manage_adk ایجاد می‌کند.

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

سپس، دستور زیر را در ترمینال اجرا کنید تا مخزن کلون شده به عنوان دایرکتوری کاری شما باز شود.

cloudshell workspace ~/deploy_and_manage_adk && cd ~/deploy_and_manage_adk

پس از آن، رابط کاربری شما باید شبیه به این باشد

این رابط اصلی ما خواهد بود، IDE در بالا، ترمینال در پایین. حالا باید ترمینال خود را برای ایجاد و فعال‌سازی پروژه Google Cloud خود که به حساب پرداخت آزمایشی قبلاً ادعا شده مرتبط خواهد بود، آماده کنیم. ما یک اسکریپت برای شما آماده کرده‌ایم تا همیشه مطمئن شوید که جلسه ترمینال شما آماده است. دستور زیر را اجرا کنید (مطمئن شوید که از قبل در فضای کاری deploy_and_manage_adk هستید)

bash setup_trial_project.sh && source .env

هنگام اجرای این دستور، نام پیشنهادی برای شناسه پروژه از شما پرسیده می‌شود، می‌توانید برای ادامه، Enter فشار دهید.

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

این نشان می‌دهد که ترمینال شما از قبل احراز هویت شده و روی شناسه پروژه صحیح (رنگ زرد کنار مسیر دایرکتوری فعلی) تنظیم شده است. کاری که این دستور انجام می‌دهد این است که به شما در ایجاد یک پروژه جدید، پیدا کردن و پیوند دادن پروژه به یک حساب پرداخت آزمایشی، آماده‌سازی فایل .env برای پیکربندی متغیر محیطی و همچنین فعال کردن شناسه پروژه صحیح در ترمینال برای شما کمک می‌کند.

حالا، ما برای مرحله بعدی آماده‌ایم

۳. 🚀 فعال‌سازی APIها

در این آموزش، ما با پایگاه داده CloudSQL، مدل Gemini و Cloud Run تعامل خواهیم داشت و این محصولات برای فعال شدن به API زیر نیاز دارند، برای فعال کردن آنها این دستور را اجرا کنید.

این ممکن است مدتی طول بکشد.

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

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

Operation "operations/..." finished successfully.

۴. 🚀 تنظیمات محیط پایتون و متغیرهای محیطی

ما در این آزمایشگاه کد از پایتون ۳.۱۲ استفاده خواهیم کرد و از ابزار مدیریت پروژه uv python برای ساده‌سازی نیاز به ایجاد و مدیریت نسخه پایتون و محیط مجازی استفاده خواهیم کرد. این بسته uv از قبل روی Cloud Shell نصب شده است.

این دستور را اجرا کنید تا وابستگی‌های مورد نیاز برای محیط مجازی در دایرکتوری .venv نصب شود.

uv sync --frozen

در مرحله بعد، فایل‌های متغیر محیطی مورد نیاز برای این پروژه را بررسی خواهیم کرد. قبلاً این فایل توسط اسکریپت setup_trial_project.sh تنظیم می‌شد. دستور زیر را برای باز کردن فایل .env در ویرایشگر اجرا کنید.

cloudshell open .env

تنظیمات زیر را که قبلاً روی فایل .env اعمال شده‌اند، مشاهده خواهید کرد.

# .env

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
# DB_CONNECTION_NAME=your-db-connection-name

برای این آزمایشگاه کد، ما از مقادیر از پیش تنظیم‌شده برای GOOGLE_CLOUD_LOCATION و GOOGLE_GENAI_USE_VERTEXAI.

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

۵. 🚀 آماده‌سازی پایگاه داده CloudSQL

ما به یک پایگاه داده نیاز داریم که بعداً توسط عامل ADK مورد استفاده قرار گیرد. بیایید یک پایگاه داده PostgreSQL روی Cloud SQL ایجاد کنیم. دستور زیر را برای ایجاد نمونه پایگاه داده اجرا کنید. ما از نام پیش‌فرض پایگاه داده postgres استفاده خواهیم کرد، بنابراین در اینجا از ایجاد پایگاه داده صرف نظر می‌کنیم. همچنین باید نام کاربری پیش‌فرض پایگاه داده خود ( که postgres نیز هست) را نیز پیکربندی کنیم، برای آموزش، بیایید از ADK-deployment123 به عنوان رمز عبور خود استفاده کنیم.

gcloud sql instances create adk-deployment \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --tier=db-g1-small \
  --region=us-central1 \
  --availability-type=ZONAL \
  --project=${GOOGLE_CLOUD_PROJECT} && \
gcloud sql users set-password postgres \
  --instance=adk-deployment \
  --password=ADK-deployment123

در دستور بالا، اولین gcloud sql instances create adk-deployment دستوری است که ما برای ایجاد نمونه پایگاه داده استفاده می‌کنیم. ما برای این آموزش از مشخصات حداقلی sandbox استفاده می‌کنیم. دستور دوم gcloud sql users set-password postgres برای تغییر رمز عبور پیش‌فرض نام کاربری postgres استفاده می‌شود.

توجه داشته باشید که ما از adk-deployment به عنوان نام نمونه پایگاه داده خود استفاده می‌کنیم. پس از اتمام، باید خروجی مانند زیر را در ترمینال مشاهده کنید که نشان می‌دهد نمونه آماده است و رمز عبور پیش‌فرض کاربر به‌روزرسانی شده است.

Created [https://sqladmin.googleapis.com/sql/v1beta4/projects/your-project-id/instances/adk-deployment].
NAME: adk-deployment
DATABASE_VERSION: POSTGRES_17
LOCATION: us-central1-a
TIER: db-g1-small
PRIMARY_ADDRESS: xx.xx.xx.xx
PRIVATE_ADDRESS: -
STATUS: RUNNABLE
Updating Cloud SQL user...done.

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

۶. 🚀 ساخت عامل آب و هوا با ADK و Gemini 2.5

مقدمه‌ای بر ساختار دایرکتوری ADK

بیایید با بررسی آنچه ADK ارائه می‌دهد و نحوه ساخت عامل شروع کنیم. مستندات کامل ADK را می‌توان در این URL مشاهده کرد. ADK ابزارهای زیادی را در اجرای دستورات CLI خود به ما ارائه می‌دهد. برخی از آنها عبارتند از:

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

حالا، بیایید ساختار عامل را در دایرکتوری weather_agent بررسی کنیم.

weather_agent/
├── __init__.py
├── agent.py
└── tool.py

و اگر init.py و agent.py را بررسی کنید، این کد را خواهید دید.

# __init__.py

from weather_agent.agent import root_agent

__all__ = ["root_agent"]

# agent.py


import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)


# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="""
You are a helpful AI assistant designed to provide accurate and useful information.
""",
    tools=[get_weather],
)

توضیح کد ADK

این اسکریپت شامل راه‌اندازی عامل ما است که در آن موارد زیر را مقداردهی اولیه می‌کنیم:

مدل مورد استفاده را روی gemini-2.5-flash تنظیم کنید.
ابزار get_weather برای پشتیبانی از عملکرد عامل به عنوان عامل آب و هوا ارائه دهید

رابط کاربری وب را به صورت محلی اجرا کنید

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

uv run adk web --port 8080

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

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

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

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

اکنون، برای بررسی آن، روی دکمه پیش‌نمایش وب در قسمت بالای ویرایشگر Cloud Shell خود کلیک کنید و پیش‌نمایش را روی پورت ۸۰۸۰ انتخاب کنید.

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

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

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

۷. 🚀 استقرار در Cloud Run

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

این سناریوی استقرار به شما امکان می‌دهد سرویس backend عامل خود را سفارشی کنید، ما از Dockerfile برای استقرار عامل خود در Cloud Run استفاده خواهیم کرد. در این مرحله، ما تمام فایل‌های مورد نیاز ( Dockerfile و server.py ) را برای استقرار برنامه‌های خود در Cloud Run داریم. با داشتن این دو مورد، می‌توانید استقرار عامل خود را به صورت انعطاف‌پذیر سفارشی کنید (مثلاً اضافه کردن مسیرهای backend سفارشی و/یا اضافه کردن سرویس sidecar اضافی برای اهداف نظارتی). بعداً به تفصیل در مورد این موضوع بحث خواهیم کرد.

حالا، بیایید ابتدا سرویس را مستقر کنیم، به ترمینال Cloud Shell برویم و مطمئن شویم که پروژه فعلی با پروژه فعال شما پیکربندی شده است، بیایید اسکریپت راه‌اندازی را دوباره اجرا کنیم، به صورت اختیاری می‌توانید از دستور gcloud config set project [PROJECT_ID] برای پیکربندی پروژه فعال خود استفاده کنید.

bash setup_trial_project.sh && source .env

حالا باید دوباره فایل .env را بررسی کنیم، آن را باز کنیم. خواهید دید که باید متغیر DB_CONNECTION_NAME را از حالت کامنت خارج کرده و با مقدار صحیح پر کنیم.

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
DB_CONNECTION_NAME=your-db-connection-name

برای دریافت مقدار DB_CONNECTION_NAME ، به داشبورد Cloud SQL مراجعه کنید.

سپس روی نمونه‌ای که ایجاد کرده‌اید کلیک کنید. به نوار جستجو در قسمت بالای کنسول ابری بروید و "cloud sql" را تایپ کنید. سپس روی محصول Cloud SQL کلیک کنید.

پس از آن، نمونه‌ای که قبلاً ایجاد کرده‌اید را خواهید دید، روی آن کلیک کنید

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

پس از آن فایل .env را با دستور زیر باز کنید

cloudshell edit .env

و متغیر DB_CONNECTION_NAME را در فایل .env تغییر دهید. فایل env شما باید مانند مثال زیر باشد.

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
DB_CONNECTION_NAME=your-project-id:your-location:your-instance-name

پس از آن اسکریپت استقرار را اجرا کنید

bash deploy_to_cloudrun.sh

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

در حالی که منتظر فرآیند استقرار هستیم، بیایید نگاهی به فایل deploy_to_cloudrun.sh بیندازیم.

#!/bin/bash

# Load environment variables from .env file
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
else
    echo "Error: .env file not found"
    exit 1
fi

# Validate required variables
required_vars=("GOOGLE_CLOUD_PROJECT" "DB_CONNECTION_NAME")
for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        echo "Error: $var is not set in .env file"
        exit 1
    fi
done

gcloud run deploy weather-agent \
    --source . \
    --port 8080 \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --allow-unauthenticated \
    --add-cloudsql-instances ${DB_CONNECTION_NAME} \
    --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:ADK-deployment123@postgres/?unix_sock=/cloudsql/${DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT} \
    --region us-central1 \
    --min 1 \
    --memory 1G \
    --concurrency 10

این اسکریپت متغیر ‎.env ‎ شما را بارگذاری می‌کند، سپس دستور استقرار را اجرا می‌کند.

اگر دقیق‌تر نگاه کنید، ما فقط به یک دستور gcloud run deploy نیاز داریم تا تمام کارهای لازم برای استقرار یک سرویس را انجام دهیم: ساخت تصویر، ارسال به رجیستری، استقرار سرویس، تنظیم سیاست IAM، ایجاد نسخه اصلاحی و حتی مسیریابی ترافیک. در این مثال، ما از قبل Dockerfile را ارائه داده‌ایم، از این رو این دستور از آن برای ساخت برنامه استفاده خواهد کرد.

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

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

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

۸. 💡 داکرفایل و اسکریپت سرور بک‌اند

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

ما می‌توانیم سرویس‌های لازم برای پشتیبانی از عامل را در اینجا پیکربندی کنیم، مانند آماده‌سازی سرویس 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


# 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 تعریف شده‌اند:

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

اکنون، اگر استقرار شما از قبل به پایان رسیده است، لطفاً با دسترسی به آدرس اینترنتی Cloud Run، از طریق رابط کاربری توسعه وب با عامل تعامل برقرار کنید.

۹. 🚀 بررسی مقیاس‌پذیری خودکار Cloud Run با تست بار

اکنون، قابلیت‌های مقیاس‌پذیری خودکار cloud run را بررسی خواهیم کرد. برای این سناریو، بیایید نسخه جدید را با فعال کردن حداکثر همزمانی به ازای هر نمونه، پیاده‌سازی کنیم. در بخش قبلی، حداکثر همزمانی را روی 10 تنظیم کردیم (flag --concurrency 10 ). از این رو می‌توانیم انتظار داشته باشیم که Cloud Run وقتی تست بارگذاری را انجام می‌دهیم که از این عدد فراتر می‌رود، سعی کند نمونه خود را مقیاس‌بندی کند.

بیایید فایل load_test.py را بررسی کنیم. این اسکریپتی خواهد بود که ما برای انجام تست بار با استفاده از چارچوب locust استفاده خواهیم کرد. این اسکریپت کارهای زیر را انجام خواهد داد:

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

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

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

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

برای ساده‌سازی کارها، اسکریپت زیر را اجرا کنید تا URL سرویس اخیراً پیاده‌سازی شده خود را دریافت کرده و آن را در متغیر محیطی SERVICE_URL ذخیره کنید.

export SERVICE_URL=$(gcloud run services describe weather-agent \
    --platform managed \
    --region us-central1 \
    --format 'value(status.url)')

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

uv run locust -f load_test.py \
              -H $SERVICE_URL \
              -u 60 \
              -r 5 \
              -t 120 \
              --headless

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

Type     Name                                  # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
POST     /run_sse end                             813     0(0.00%) |   5817    2217   26421   5000 |    6.79        0.00
POST     /run_sse message                         813     0(0.00%) |   2678    1107   17195   2200 |    6.79        0.00
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
         Aggregated                              1626     0(0.00%) |   4247    1107   26421   3500 |   13.59        0.00

سپس بیایید ببینیم در Cloud Run چه اتفاقی افتاده است، دوباره به سرویس مستقر شده خود بروید و داشبورد را ببینید. این نشان می‌دهد که چگونه cloud run ها به طور خودکار نمونه را برای رسیدگی به درخواست‌های ورودی مقیاس‌بندی می‌کنند. از آنجا که ما حداکثر همزمانی را به 10 در هر نمونه محدود می‌کنیم، نمونه cloud run سعی می‌کند تعداد کانتینرها را به طور خودکار تنظیم کند تا این شرط را برآورده کند.

۱۰. 🚀 انتشار تدریجی نسخه‌های جدید

حالا، بیایید سناریوی زیر را داشته باشیم. می‌خواهیم اعلان عامل را به‌روزرسانی کنیم. فایل weather_agent/agent.py را با دستور زیر باز کنید.

cloudshell edit weather_agent/agent.py

و آن را با کد زیر بازنویسی کنید:

# weather_agent/agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)


# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="""
You are a helpful AI assistant designed to provide accurate and useful information.
You only answer inquiries about the weather. Refuse all other user query
""",
    tools=[get_weather],
)

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

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project $GOOGLE_CLOUD_PROJECT \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

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

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

بعد، بیایید به داشبورد Cloud Run برویم

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

به برگه «ویرایش‌ها» بروید و فهرست ویرایش‌های پیاده‌سازی‌شده را در آنجا مشاهده خواهید کرد.

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

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

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

۱۱. 🚀 ردیابی ADK

عامل‌های ساخته شده با ADK از قبل از ردیابی با استفاده از تعبیه تله‌متری باز در آن پشتیبانی می‌کنند. ما Cloud Trace را برای ثبت این ردیابی‌ها و تجسم آنها داریم. بیایید server.py را بررسی کنیم که چگونه آن را در سرویس قبلاً مستقر شده خود فعال می‌کنیم.

# server.py

...

app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

...

app: FastAPI = get_fast_api_app(**app_args)

...

در اینجا، آرگومان trace_to_cloud را به True ارسال می‌کنیم. اگر با گزینه‌های دیگری در حال استقرار هستید، می‌توانید برای جزئیات بیشتر در مورد نحوه فعال کردن ردیابی به Cloud Trace از گزینه‌های مختلف استقرار ، این مستندات را بررسی کنید.

سعی کنید به رابط کاربری توسعه وب سرویس خود دسترسی پیدا کنید و با اپراتور چت کنید. پس از آن به صفحه Trace Explorer می‌رویم.

در صفحه trace explorer، خواهید دید که مکالمه ما با agent ردیابی شده است. می‌توانید از بخش Span name ، span مخصوص agent ما (که agent_run [weather_agent] نام دارد) را فیلتر کنید.

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

در هر بخش، می‌توانید جزئیات مربوط به ویژگی‌ها را مانند آنچه در زیر نشان داده شده است، بررسی کنید.

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

۱۲. چالش🎯

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

۱۳. 🧹 تمیز کردن

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

در کنسول گوگل کلود، به صفحه مدیریت منابع بروید.
در لیست پروژه‌ها، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی «حذف» کلیک کنید.
در کادر محاوره‌ای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن کلیک کنید.
روش دیگر این است که به Cloud Run در کنسول بروید، سرویسی را که اخیراً مستقر کرده‌اید انتخاب کرده و حذف کنید.