۱. مقدمه
این آموزش شما را در استقرار، مدیریت و نظارت بر یک عامل قدرتمند ساخته شده با کیت توسعه عامل (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
آنچه نیاز دارید
- مرورگر وب کروم
- یک حساب جیمیل
- یک پروژه ابری با قابلیت پرداخت صورتحساب
این آزمایشگاه کد که برای توسعهدهندگان در تمام سطوح (از جمله مبتدیان) طراحی شده است، در برنامه نمونه خود از پایتون استفاده میکند. با این حال، برای درک مفاهیم ارائه شده، دانش پایتون لازم نیست.
۲. 🚀 آمادهسازی مقدمات توسعه کارگاه
مرحله ۱: انتخاب پروژه فعال در کنسول ابری
در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید (به بخش بالا سمت چپ کنسول خود مراجعه کنید)
روی آن کلیک کنید، و لیستی از تمام پروژههای خود را مانند این مثال مشاهده خواهید کرد،
مقداری که با کادر قرمز مشخص شده است، شناسه پروژه (PROJECT ID) است و این مقدار در طول آموزش استفاده خواهد شد.
مطمئن شوید که پرداخت صورتحساب برای پروژه ابری شما فعال است. برای بررسی این موضوع، روی نماد همبرگر ☰ در نوار بالا سمت چپ که منوی پیمایش را نشان میدهد کلیک کنید و منوی پرداخت صورتحساب را پیدا کنید.
اگر عبارت «حساب پرداخت آزمایشی پلتفرم ابری گوگل» را زیر عنوان «پرداخت / بررسی اجمالی» ( قسمت بالا سمت چپ کنسول ابری خود ) مشاهده کردید، پروژه شما آماده استفاده برای این آموزش است. در غیر این صورت، به ابتدای این آموزش برگردید و حساب پرداخت آزمایشی را فعال کنید.
مرحله 2: آمادهسازی پایگاه داده SQL ابری
ما به یک پایگاه داده نیاز داریم که بعداً توسط عامل ADK مورد استفاده قرار گیرد. بیایید یک پایگاه داده PostgreSQL روی Cloud SQL ایجاد کنیم. ابتدا به نوار جستجو در قسمت بالای کنسول ابری بروید و "cloud sql" را تایپ کنید. سپس روی محصول Cloud SQL کلیک کنید.
پس از آن، باید یک نمونه پایگاه داده جدید ایجاد کنیم، روی Create Instance کلیک کنید و PostgreSQL را انتخاب کنید.
اگر پروژه جدیدی را شروع میکنید، ممکن است لازم باشد Compute Engine API را نیز فعال کنید، در صورت نمایش این اعلان، کافیست روی Enable API کلیک کنید.
در مرحله بعد، مشخصات پایگاه داده را انتخاب خواهیم کرد، نسخه Enterprise را با تنظیمات پیشفرض نسخه Sandbox انتخاب کنید.
پس از آن، نام نمونه و رمز عبور پیشفرض را برای کاربر postgres در اینجا تنظیم کنید. میتوانید این را با هر اعتبارنامهای که میخواهید تنظیم کنید، با این حال، برای این آموزش، ما در اینجا از " adk-deployment " برای نام نمونه و "ADK-deployment123" برای رمز عبور استفاده خواهیم کرد.
بیایید برای این آموزش از us-central1 با یک منطقه واحد استفاده کنیم، سپس میتوانیم ایجاد پایگاه داده خود را نهایی کنیم و با کلیک بر روی دکمه Create Instance، اجازه دهیم تمام تنظیمات مورد نیاز انجام شود.
در حالی که منتظر پایان این بخش هستیم، میتوانیم به بخش بعدی برویم
مرحله ۳: آشنایی با Cloud Shell
شما در بیشتر بخشهای آموزش از Cloud Shell استفاده خواهید کرد، روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید. اگر از شما درخواست تأیید کرد، روی Authorize کلیک کنید.
پس از اتصال به Cloud Shell، باید بررسی کنیم که آیا shell (یا ترمینال) از قبل با حساب ما احراز هویت شده است یا خیر.
gcloud auth list
اگر خروجی جیمیل شخصی خود را مانند نمونه زیر مشاهده کردید، همه چیز درست است.
Credentialed Accounts
ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com
To set the active account, run:
$ gcloud config set account `ACCOUNT`
اگر اینطور نیست، مرورگر خود را رفرش کنید و مطمئن شوید که در صورت درخواست، روی «مجوز» کلیک میکنید (ممکن است به دلیل مشکل اتصال، قطع شود).
در مرحله بعد، باید بررسی کنیم که آیا پوسته از قبل با شناسه پروژه صحیحی که دارید پیکربندی شده است یا خیر، اگر مقداری را داخل () قبل از نماد $ در ترمینال مشاهده کردید (در تصویر زیر، مقدار "adk-cloudrun-deployment-476504" است)، این مقدار پروژه پیکربندی شده برای جلسه پوسته فعال شما را نشان میدهد.
اگر مقدار نمایش داده شده از قبل صحیح است، میتوانید از دستور بعدی صرف نظر کنید . اما اگر صحیح نیست یا وجود ندارد، دستور زیر را اجرا کنید
gcloud config set project <YOUR_PROJECT_ID>
سپس، پوشه کاری قالب را برای این codelab از Github کپی کنید، دستور زیر را اجرا کنید. این دستور پوشه کاری را در پوشه deploy_and_manage_adk ایجاد میکند.
git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk
مرحله ۴: آشنایی با ویرایشگر Cloud Shell و دایرکتوری کاری برنامه نصب
حالا میتوانیم ویرایشگر کد خود را برای انجام برخی کارهای کدنویسی تنظیم کنیم. برای این کار از ویرایشگر Cloud Shell استفاده خواهیم کرد.
روی دکمهی «باز کردن ویرایشگر» کلیک کنید، این کار یک ویرایشگر Cloud Shell را باز میکند. 
پس از آن، به بخش بالای ویرایشگر Cloud Shell بروید و روی File->Open Folder کلیک کنید، پوشه نام کاربری خود را پیدا کنید و پوشه deploy_and_manage_adk را پیدا کنید و سپس روی دکمه OK کلیک کنید. این کار پوشه انتخاب شده را به عنوان پوشه اصلی کار تبدیل میکند. در این مثال، نام کاربری alvinprayuda است، از این رو مسیر پوشه در زیر نشان داده شده است.
حالا، دایرکتوری کاری ویرایشگر پوسته ابری شما باید به این شکل باشد (داخل deploy_and_manage_adk )
حالا، ترمینال ویرایشگر را باز کنید. میتوانید این کار را با کلیک روی ترمینال -> ترمینال جدید در نوار منو انجام دهید، یا از Ctrl + Shift + C استفاده کنید، این کار یک پنجره ترمینال در قسمت پایین مرورگر باز میکند.
ترمینال فعال فعلی شما باید در دایرکتوری کاری deploy_and_manage_adk باشد. ما در این آزمایشگاه کد از پایتون ۳.۱۲ استفاده خواهیم کرد و از uv python project manager برای سادهسازی نیاز به ایجاد و مدیریت نسخه پایتون و محیط مجازی استفاده خواهیم کرد. این بسته uv از قبل روی Cloud Shell نصب شده است.
این دستور را اجرا کنید تا وابستگیهای مورد نیاز برای محیط مجازی در دایرکتوری .venv نصب شود.
uv sync --frozen
حالا باید APIهای مورد نیاز را از طریق دستور زیر فعال کنیم. این کار ممکن است کمی طول بکشد.
gcloud services enable aiplatform.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudresourcemanager.googleapis.com \
sqladmin.googleapis.com
در صورت اجرای موفقیتآمیز دستور، باید پیامی مشابه آنچه در زیر نشان داده شده است را مشاهده کنید:
Operation "operations/..." finished successfully.
در مرحله بعد، باید فایلهای پیکربندی این پروژه را تنظیم کنیم.
فایل .env.example را به .env تغییر نام دهید.
cp .env.example .env
فایل .env را باز کنید و مقدار GOOGLE_CLOUD_PROJECT را به شناسه پروژه خود بهروزرسانی کنید.
# .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. فعلاً، DB_CONNECTION_NAME به صورت کامنت باقی میگذاریم.
حالا میتوانیم به مرحله بعدی برویم، منطق عامل را بررسی و آن را مستقر کنیم
۳. 🚀 ساخت عامل آب و هوا با 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 مستقر کنیم. برای این نسخه آزمایشی، این سرویس به عنوان یک سرویس عمومی که توسط دیگران قابل دسترسی است، نمایش داده میشود. با این حال، به خاطر داشته باشید که این بهترین روش نیست زیرا امن نیست.
در این آزمایشگاه کد، ما از Dockerfile برای استقرار عامل خود در Cloud Run استفاده خواهیم کرد. در این مرحله، ما تمام فایلهای مورد نیاز ( Dockerfile و server.py ) را برای استقرار برنامههای خود در Cloud Run داریم. بعداً به تفصیل در مورد این موضوع صحبت خواهیم کرد.
حالا، بیایید ابتدا سرویس را مستقر کنیم، به ترمینال Cloud Shell برویم و مطمئن شویم که پروژه فعلی با پروژه فعال شما پیکربندی شده است، در غیر این صورت از دستور gcloud configure برای تنظیم شناسه پروژه استفاده کنید:
gcloud config set project [PROJECT_ID]
حالا باید دوباره فایل .env را بررسی کنیم، آن را باز کنیم. خواهید دید که باید متغیر DB_CONNECTION_NAME را از حالت کامنت خارج کرده و با مقدار صحیح پر کنیم.
# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
# Database connection for session service
DB_CONNECTION_NAME=your-db-connection-name
برای دریافت مقدار DB_CONNECTION_NAME ، میتوانید دوباره به Cloud SQL بروید و روی نمونهای که ایجاد کردهاید کلیک کنید. به نوار جستجو در قسمت بالای کنسول ابری بروید و "cloud sql" را تایپ کنید. سپس روی محصول Cloud SQL کلیک کنید.
پس از آن، نمونهای که قبلاً ایجاد کردهاید را خواهید دید، روی آن کلیک کنید
در داخل صفحه نمونه، به پایین اسکرول کنید تا به بخش « اتصال به این نمونه » برسید. در آنجا میتوانید نام اتصال را کپی کنید تا جایگزین مقدار DB_CONNECTION_NAME شود.
پس از آن فایل .env را باز کنید و متغیر DB_CONNECTION_NAME را تغییر دهید. فایل env شما باید مانند مثال زیر باشد.
# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
# Database connection for session service
DB_CONNECTION_NAME=your-project-id:your-location:your-instance-name
پس از آن اسکریپت استقرار را اجرا کنید
bash deploy_to_cloudrun.sh
اگر از شما خواسته شد که ایجاد یک رجیستری مصنوعات برای مخزن داکر را تأیید کنید، فقط با 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 بروید و روی سرویس weather-agent خود کلیک کنید.
سپس، سرویس هواشناسی خود را پیدا کنید و روی آن کلیک کنید
آدرس اینترنتی سرویس درست در کنار اطلاعات منطقه نمایش داده میشود. به عنوان مثال
سپس دستور زیر را برای انجام تست بار اجرا کنید
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 چه اتفاقی افتاده است، دوباره به سرویس مستقر شده خود بروید و داشبورد را ببینید. این نشان میدهد که چگونه cloud run ها به طور خودکار نمونه را برای رسیدگی به درخواستهای ورودی مقیاسبندی میکنند. از آنجا که ما حداکثر همزمانی را به 10 در هر نمونه محدود میکنیم، نمونه cloud run سعی میکند تعداد کانتینرها را به طور خودکار تنظیم کند تا این شرط را برآورده کند.
۷. 🚀 انتشار تدریجی نسخههای جدید
حالا، بیایید سناریوی زیر را داشته باشیم. میخواهیم اعلان عامل را بهروزرسانی کنیم. فایل 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 {YOUR_PROJECT_ID} \
--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 بروید و نمونه مستقر شده خود را پیدا کنید. عبارت cloud run را در نوار جستجو تایپ کنید و روی محصول 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 را در آنجا انتخاب کنید.
در صفحه trace explorer، خواهید دید که مکالمه ما با agent ردیابی شده است. میتوانید از بخش Span name ، span مخصوص agent ما (که agent_run [weather_agent] نام دارد) را فیلتر کنید.
وقتی که spanها از قبل فیلتر شدهاند، میتوانید هر trace را مستقیماً بررسی کنید. این کار مدت زمان دقیق هر اقدام انجام شده توسط agent را نشان میدهد. برای مثال، به تصاویر زیر نگاه کنید.
در هر بخش، میتوانید جزئیات مربوط به ویژگیها را مانند آنچه در زیر نشان داده شده است، بررسی کنید.
خب، حالا ما قابلیت مشاهده و اطلاعات خوبی در مورد هر تعامل عامل خود با کاربر داریم تا به رفع اشکال مشکلات کمک کند. میتوانید ابزارها یا گردشهای کاری مختلف را امتحان کنید!
۹. چالش🎯
گردشهای کاری چندعاملی یا عاملدار را امتحان کنید تا ببینید تحت بار کاری چگونه عمل میکنند و ردپا چگونه به نظر میرسد.
۱۰. 🧹 تمیز کردن
برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این codelab، این مراحل را دنبال کنید:
- در کنسول گوگل کلود، به صفحه مدیریت منابع بروید.
- در لیست پروژهها، پروژهای را که میخواهید حذف کنید انتخاب کنید و سپس روی «حذف» کلیک کنید.
- در کادر محاورهای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن کلیک کنید.
- روش دیگر این است که به Cloud Run در کنسول بروید، سرویسی را که اخیراً مستقر کردهاید انتخاب کرده و حذف کنید.