۱. هدف این آزمایشگاه
در این آزمایشگاه عملی، شما یک برنامه چندعاملی با استفاده از ADK (کیت توسعه عامل) خواهید ساخت که بر اساس درخواست شما، تصویری تولید میکند و آن را با درخواست شما مقایسه میکند. اگر تصویر به طور رضایتبخشی الزامات شرح داده شده در درخواست را برآورده نکند، عامل به طور مداوم تصاویر را تولید میکند تا تصویری که الزامات شما را برآورده میکند، تولید شود. هر یک از عاملهای موجود در این آزمایش عملی، یک هدف واحد دارند، عاملها برای دستیابی به هدف کلی با یکدیگر همکاری میکنند. شما یاد خواهید گرفت که چگونه برنامه را به صورت محلی آزمایش کنید و در موتور عامل هوش مصنوعی Vertex مستقر کنید.
آنچه یاد خواهید گرفت
- اصول اولیه ADK (کیت توسعه عامل) را درک کنید و یاد بگیرید که چگونه یک سیستم چند عامله ایجاد کنید.
- بیاموزید که چگونه به راحتی عاملها را در Vertex AI Agent Engine مستقر و استفاده کنید.
- آشنایی با اصول اولیه پروتکل A2A
- یاد بگیرید که چگونه از پروتکل A2A و ADK (کیت توسعه عامل) برای ایجاد عاملهای باز استفاده کنید.
۲. راهاندازی پروژه
- اگر از قبل پروژهای ندارید که بتوانید از آن استفاده کنید، باید یک پروژه جدید در کنسول GCP ایجاد کنید.
- در این آزمایش، ما از GCP Cloud Shell برای انجام وظایف خود استفاده خواهیم کرد. Cloud Shell را باز کنید و پروژه را با استفاده از Cloud Shell تنظیم کنید.
- با کلیک روی اینجا، Cloud Shell، پوسته ابری GCP را باز کنید. اگر پنجره "Authorize Shell" را مشاهده کردید، برای تأیید ویرایشگر Cloud Shell کلیک کنید.
- میتوانید با استفاده از دستور زیر در ترمینال Cloud Shell بررسی کنید که آیا پروژه از قبل احراز هویت شده است یا خیر.
gcloud auth list
- برای تأیید پروژه خود، دستور زیر را در Cloud Shell اجرا کنید
gcloud config list project
- شناسه پروژه را کپی کنید و از دستور زیر برای تنظیم آن استفاده کنید.
gcloud config set project <YOUR_PROJECT_ID>
- برای اجرای این آزمایشگاه باید برخی از سرویسها را فعال کنیم. دستور زیر را در Cloud Shell اجرا کنید.
gcloud services enable aiplatform.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com
۳. مقدمهای بر کیت توسعه عامل
کیت توسعه عامل چندین مزیت کلیدی برای توسعهدهندگانی که برنامههای عاملمحور میسازند، ارائه میدهد:
- سیستمهای چندعاملی : با ترکیب چندین عامل تخصصی در یک سلسله مراتب، برنامههای کاربردی ماژولار و مقیاسپذیر بسازید. هماهنگی و تفویض اختیار پیچیده را امکانپذیر کنید.
- اکوسیستم غنی ابزار : عاملها را به قابلیتهای متنوعی مجهز کنید: از ابزارهای از پیش ساخته شده (جستجو، اجرای کد و غیره) استفاده کنید، توابع سفارشی ایجاد کنید، ابزارها را از چارچوبهای عامل شخص ثالث (LangChain، CrewAI) ادغام کنید، یا حتی از عاملهای دیگر به عنوان ابزار استفاده کنید.
- ارکستراسیون انعطافپذیر : تعریف گردشهای کاری با استفاده از عاملهای گردش کار (
SequentialAgent،ParallelAgentوLoopAgent) برای خطوط لوله قابل پیشبینی، یا بهرهگیری از مسیریابی پویا مبتنی بر LLM (انتقالLlmAgent) برای رفتار تطبیقی. - تجربه یکپارچه توسعهدهنده : توسعه، آزمایش و اشکالزدایی به صورت محلی با یک رابط خط فرمان قدرتمند و یک رابط کاربری توسعه تعاملی. بررسی رویدادها، وضعیت و اجرای عامل گام به گام.
- ارزیابی داخلی : با ارزیابی کیفیت پاسخ نهایی و مسیر اجرای گام به گام در برابر موارد آزمایشی از پیش تعریف شده، عملکرد عامل را به طور سیستماتیک ارزیابی کنید.
- آماده برای استقرار : عاملهای خود را در هر مکانی کانتینریزه و مستقر کنید - به صورت محلی اجرا کنید، با Vertex AI Agent Engine مقیاسپذیر کنید، یا با استفاده از Cloud Run یا Docker در زیرساختهای سفارشی ادغام شوید.
در حالی که سایر SDK های Gen AI یا چارچوب های عامل نیز به شما امکان می دهند مدل ها را پرس و جو کنید و حتی آنها را با ابزارها توانمند کنید، هماهنگی پویا بین چندین مدل نیاز به مقدار قابل توجهی کار از طرف شما دارد.
کیت توسعه عامل، چارچوبی سطح بالاتر از این ابزارها ارائه میدهد و به شما این امکان را میدهد که به راحتی چندین عامل را برای گردشهای کاری پیچیده اما آسان برای نگهداری، به یکدیگر متصل کنید.
شکل ۱: موقعیت ADK (کیت توسعه عامل)
۴. مقدمهای بر موتور عامل هوش مصنوعی ورتکس
موتور عامل هوش مصنوعی ورتکس (Vertex AI Agent Engine ) یک سرویس کاملاً مدیریتشده برای استقرار عاملها در گوگل کلود است. با استفاده از موتور عامل هوش مصنوعی ورتکس ، توسعهدهندگان میتوانند عاملهای هوش مصنوعی OSS ( ADK (Agent Development Kit) ، LangChain، LangGraph، CrewAI، AutoGen و موارد دیگر!) را در ورتکس هوش مصنوعی توسعه، سفارشیسازی، استقرار، سرویسدهی و مدیریت کنند.
موتور عامل همچنین سرویسهایی را برای مدیریت دادههای کاربر ارائه میدهد که به عنوان حافظه عامل نیز شناخته میشود. در حال حاضر دو نوع سرویس حافظه در دسترس است.
- حافظه کوتاهمدت : با استفاده از جلسات موتور عامل، میتوانید تاریخچه مکالمات جاری (وضعیت) را در یک جلسه واحد به عنوان حافظه کوتاهمدت ذخیره، مدیریت و بازیابی کنید.
- حافظه بلندمدت : با بانک حافظه موتور عامل ، خاطرات (وضعیت) را ذخیره، تبدیل و بازیابی کنید، بهویژه در طول چندین جلسه به عنوان خاطرات بلندمدت.
شما میتوانید Agentها را در سایر سرویسهای Google Cloud مانند Cloud Run یا GKE نیز مستقر کنید، برای موارد استفاده زیر باید استفاده از Vertex AI Agent Engine را در نظر بگیرید.
- زمان اجرای مدیریتشده با وضعیت : اگر به یک زمان اجرای کاملاً مدیریتشده و با وضعیت برای استقرار عامل خود نیاز دارید ، موتور عامل هوش مصنوعی ورتکس انتخاب خوبی است زیرا وظایف رایجی مانند مدیریت جلسه و پایداری برای عاملهای هوش مصنوعی را خلاصه میکند.
- اجرای کد : اگر Agent شما نیاز به اجرای کدی دارد که به صورت پویا در طول جلسه کاربر تولید میشود، Agent Engine یک Sandbox امن فراهم میکند که میتوانید کد را در آن اجرا کنید.
- حافظه بلندمدت انعطافپذیر : اگر به حافظه بلندمدت انعطافپذیر برای عاملهای خود نیاز دارید، بانک حافظه هوش مصنوعی ورتکس که میتواند با موتور عامل هوش مصنوعی ورتکس استفاده شود، میتواند روشی انعطافپذیر برای به خاطر سپردن اطلاعات مربوط به کاربر شما فراهم کند که میتواند در طول جلسات مورد استفاده قرار گیرد.
همچنین میتوانید Vertex AI Agent Engine را با سایر زمانهای اجرا مانند Cloud Run ترکیب کنید تا یک معماری برنامه انعطافپذیر ایجاد کنید. در زیر مثالی از یک معماری مرجع با استفاده از سرویسهای مختلف برای ساخت یک عامل آورده شده است.
شکل ۲: یک معماری مرجع نمونه برای ساخت عاملها با استفاده از چندین سرویس.
۵. مقدمهای بر A2A
پروتکل Agent2Agent (A2A) یک استاندارد باز است که برای ایجاد ارتباط و همکاری یکپارچه و ایمن بین عاملهای هوش مصنوعی مستقل از چارچوبها، فروشندگان و دامنههای مختلف طراحی شده است.
- قابلیت همکاری جهانی: A2A به عاملها اجازه میدهد تا صرف نظر از فناوریهای زیربنایی خود با یکدیگر همکاری کنند و یک اکوسیستم واقعاً چندعاملی را پرورش دهند. این بدان معناست که عاملهای ساخته شده توسط شرکتهای مختلف روی پلتفرمهای مختلف میتوانند با هم ارتباط برقرار کرده و هماهنگ شوند.
- کشف قابلیتها: عاملها میتوانند قابلیتهای خود را با استفاده از «کارتهای عامل» (اسناد JSON) که هویت، ویژگیهای پشتیبانیشده A2A، مهارتها و الزامات احراز هویت آنها را توصیف میکند، تبلیغ کنند. این امر به سایر عاملها اجازه میدهد تا مناسبترین عامل را برای یک کار مشخص کشف و انتخاب کنند.
- امنیت پیشفرض: امنیت یک اصل اساسی است. A2A مکانیزمهای احراز هویت و مجوز در سطح سازمانی را در خود جای داده و از استانداردهایی مانند HTTPS/TLS، JWT، OIDC و کلیدهای API برای تضمین تعاملات ایمن و محافظت از دادههای حساس استفاده میکند.
- مستقل از روش (Modality Agnostic): این پروتکل از روشهای ارتباطی مختلفی از جمله پخش متن، صدا و تصویر و همچنین فرمهای تعاملی و iframe های تعبیه شده پشتیبانی میکند. این انعطافپذیری به عاملها اجازه میدهد تا اطلاعات را در مناسبترین قالب برای وظیفه و کاربر تبادل کنند.
- مدیریت ساختاریافته وظایف: A2A پروتکلهای روشنی را برای واگذاری وظایف، نظارت و تکمیل آنها تعریف میکند. این پروتکل از گروهبندی وظایف مرتبط و مدیریت آنها بین عوامل مختلف با استفاده از شناسههای منحصر به فرد وظایف پشتیبانی میکند. وظایف میتوانند از طریق چرخههای عمر تعریفشده (مثلاً ارسالشده، در حال کار، تکمیلشده) منتقل شوند.
- اجرای غیرشفاف: یکی از ویژگیهای قابل توجه این است که عاملها نیازی به آشکار کردن فرآیندهای استدلال داخلی، حافظه یا ابزارهای خاص خود برای سایر عاملها ندارند. آنها فقط سرویسهای قابل فراخوانی خود را در معرض نمایش قرار میدهند و ماژولاریتی و حریم خصوصی را ارتقا میدهند.
- ساخته شده بر اساس استانداردهای موجود: A2A از فناوریهای وب جاافتاده مانند HTTP، رویدادهای ارسالشده از سرور (SSE) برای پخش زنده و JSON-RPC برای تبادل ساختاریافته دادهها بهره میبرد و ادغام آن با زیرساختهای فناوری اطلاعات موجود را آسانتر میکند.
- ارتباط غیرهمزمان: این پروتکل با در نظر گرفتن ارتباط غیرهمزمان به عنوان یک ملاحظه اصلی طراحی شده است، که پیشرفت انعطافپذیر وظایف را تسهیل میکند و امکان ارسال اعلانهای فوری برای بهروزرسانیها را حتی زمانی که اتصال به طور مداوم برقرار نیست، فراهم میکند.
۶. معماری عامل
در این آزمایش، شما یک برنامه چندعاملی ایجاد خواهید کرد که تصویری را طبق مشخصات شما تولید میکند و قبل از ارائه به شما، آن را ارزیابی میکند.
این سیستم با یک عامل اصلی به نام image_scoring ساختار یافته است که کل فرآیند را هماهنگ میکند. این عامل اصلی دارای یک عامل فرعی به نام image_generation_scoring_agent است که به نوبه خود دارای عاملهای فرعی مخصوص به خود برای وظایف خاصتر است. این یک رابطه سلسله مراتبی ایجاد میکند که در آن عامل اصلی وظایف را به عاملهای فرعی خود واگذار میکند. 
شکل ۳: جریان کلی عاملها.
فهرست همه نمایندگان
عامل | هدف | زیرعاملها |
امتیازدهی تصویر (نماینده اصلی) | این عامل ریشهای است که کل گردش کار را مدیریت میکند. این عامل به طور مکرر image_generation_scoring_agent و checker_agent را در یک حلقه اجرا میکند تا زمانی که شرط خاتمه برآورده شود. | image_generation_scoring_agent |
image_generation_scoring_agent (زیرعامل امتیازدهی تصویر) | این عامل مسئول منطق اصلی تولید و امتیازدهی تصاویر است. برای دستیابی به این هدف، توالیای از سه زیرعامل را اجرا میکند. | image_generation_prompt_agent |
checker_agent_instance (زیرعامل امتیازدهی تصویر) | این عامل بررسی میکند که آیا فرآیند امتیازدهی تصویر باید ادامه یابد یا خاتمه یابد. این عامل از ابزار check_tool_condition برای ارزیابی شرط خاتمه استفاده میکند. | - |
checker_agent_instance (زیرعامل امتیازدهی تصویر) | این عامل در ایجاد دستورالعملهایی برای تولید تصویر متخصص است. این عامل یک متن ورودی را دریافت میکند و یک دستورالعمل دقیق مناسب برای مدل تولید تصویر تولید میکند. | - |
image_generation_prompt_agent (زیرعامل image_generation_scoring_agent) | این عامل در ایجاد دستورالعملهایی برای تولید تصویر متخصص است. این عامل یک متن ورودی را دریافت میکند و یک دستورالعمل دقیق مناسب برای مدل تولید تصویر تولید میکند. | - |
scoring_images_prompt (زیرعامل image_generation_scoring_agent): | این عامل، متخصص در ارزیابی و امتیازدهی تصاویر بر اساس معیارهای مختلف است. تصویر تولید شده را میگیرد و به آن امتیاز میدهد. | - |
فهرست تمام ابزارهای مورد استفاده
ابزار | توضیحات | عامل کاربر |
بررسی_وضعیت_ابزار | این ابزار بررسی میکند که آیا شرط خاتمه حلقه برقرار است یا اینکه به حداکثر تعداد تکرارها رسیدهایم. اگر هر یک از این موارد درست باشد، حلقه را متوقف میکند. | checker_agent_instance |
تولید_تصاویر | این ابزار با استفاده از مدل Imagen 3 تصاویر را تولید میکند. همچنین میتواند تصاویر تولید شده را در یک فضای ذخیرهسازی ابری گوگل ذخیره کند. | image_generation_agent |
دریافت_سیاست | این ابزار یک سیاست را از یک فایل JSON دریافت میکند. این سیاست توسط image_generation_prompt_agent برای ایجاد اعلان تولید تصویر و توسط scoring_images_prompt برای امتیازدهی به تصاویر استفاده میشود. | image_generation_agent |
دریافت_تصویر | این ابزار، تصویر مصنوعی تولید شده را بارگذاری میکند تا بتوان آن را امتیازدهی کرد. | امتیازدهی_تصاویر_سریع |
تنظیم_امتیاز | این ابزار امتیاز کل تصویر تولید شده در حالت جلسه را تعیین میکند. | امتیازدهی_تصاویر_سریع |
۷. ADK را نصب کنید و محیط خود را راهاندازی کنید
در این آموزش عملی، ما از Cloud Shell برای انجام وظایف استفاده خواهیم کرد.
آمادهسازی یک تب ویرایشگر Cloud Shell
- برای دسترسی مستقیم به ویرایشگر Cloud Shell ، روی این لینک کلیک کنید.
- روی ادامه کلیک کنید.
- وقتی از شما خواسته شد Cloud Shell را تأیید کنید، روی تأیید کلیک کنید.
- در ادامهی این آزمایش، میتوانید در این پنجره به عنوان IDE خود با ویرایشگر Cloud Shell و ترمینال Cloud Shell کار کنید.
- با استفاده از مسیر Terminal>New Terminal در ویرایشگر Cloud Shell، یک ترمینال جدید باز کنید. تمام دستورات زیر در این ترمینال اجرا خواهند شد.
ADK و نمونههای کد مربوط به این آزمایشگاه را دانلود و نصب کنید.
- دستورات زیر را برای کپی کردن منبع مورد نیاز از گیتهاب و نصب کتابخانههای لازم اجرا کنید. دستورات را در ترمینال باز شده در ویرایشگر Cloud Shell اجرا کنید.
#create the project directory
mkdir ~/imagescoring
cd ~/imagescoring
#clone the code in the local directory
git clone https://github.com/haren-bh/multiagenthandson.git
- ما از uv برای ایجاد محیط پایتون استفاده خواهیم کرد (در ترمینال ویرایشگر Cloud Shell اجرا کنید):
#Install uv if you do not have installed yet
pip install uv
#Create the virtual environment
uv venv .adkvenv
source .adkvenv/bin/activate
#go to the project directory
cd ~/imagescoring/multiagenthandson
#install dependencies
uv pip install -r pyproject.toml
- اگر باکت ذخیرهسازی ابری ندارید، یک باکت جدید در Google Cloud Storage ایجاد کنید. همچنین میتوانید با استفاده از دستور gsutil باکت را ایجاد کنید. به Agent Engine دسترسی به Google Cloud Storage بدهید (در ترمینال ویرایشگر Cloud Shell اجرا کنید).
# First, make sure your PROJECT_ID variable is set
PROJECT_ID=$(gcloud config get-value project)
# Now, create the bucket with a unique name
# We'll use the project ID to help ensure uniqueness
gsutil mb gs://${PROJECT_ID}-imagescoring-bucket
#Now lets give Agent Engine the permission to access Cloud Storage
# 1. Get the current Project ID (text) and Project Number (numeric)
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
# 2. Construct the Reasoning Engine Service Account email
SA_EMAIL="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
# 3. Create Agent Engine Service account if not already created
gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_NUMBER}
# 3. Grant GCS Access
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/storage.objectUser" --condition=None
- در ویرایشگر به View->Toggle hidden files بروید. و در پوشه image_scoring یک فایل .env با محتوای زیر ایجاد کنید. جزئیات مورد نیاز مانند نام پروژه و مخزن ذخیرهسازی ابری خود را اضافه کنید (در ترمینال ویرایشگر Cloud Shell اجرا کنید).
#go to image_scoring folder
cd ~/imagescoring/multiagenthandson/image_scoring
cat <<EOF>> .env
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_CLOUD_STORAGE_BUCKET=$(gcloud config get-value project)-imagescoring-bucket
GCS_BUCKET_NAME=$(gcloud config get-value project)-imagescoring-bucket
SCORE_THRESHOLD=40
IMAGEN_MODEL="imagen-3.0-generate-002"
GENAI_MODEL="gemini-2.5-flash"
EOF
- به ساختار عامل در کد منبع نگاه کنید، از agent.py شروع کنید. این عامل شامل عامل ریشه است که به سایر عاملها متصل میشود.
- در ترمینال به دایرکتوری multiagenthandson در بالا برگردید و دستور زیر را برای اجرای عامل به صورت محلی اجرا کنید (اجرا در ترمینال ویرایشگر Cloud Shell).
#go to the directory multiagenthandson
cd ~/imagescoring/multiagenthandson
# Run the following command to run agents locally
adk web
شکل ۴
Ctrl+Click (CMD+Click برای MacOS) روی آدرس http:// نمایش داده شده در ترمینال، رابط کاربری گرافیکی مبتنی بر مرورگر ADK را باز میکند. باید مانند شکل ۲ باشد.
- از منوی کشویی سمت چپ بالا، گزینه image_scoring را انتخاب کنید (شکل ۵ را ببینید). حالا بیایید چند تصویر ایجاد کنیم! باید تصاویر را در فضای ذخیرهسازی ابری گوگل نیز پیدا کنید. دستورالعملهای زیر یا دستورالعملهای خودتان را امتحان کنید.
- منظره کوهستانی آرام در غروب آفتاب
- گربهای که دوچرخهسواری میکند
شکل ۵: نمونه خروجی
۸. استقرار در موتور عامل
حالا ما عامل را در Agent Engine مستقر میکنیم. Agent Engine یک سرویس کاملاً مدیریتشده برای استقرار عاملها در GCP است. Agent Engine با ADK (کیت توسعه عامل) سازگار است، بنابراین عاملهای ساختهشده با ADK (کیت توسعه عامل) میتوانند در Agent Engine مستقر شوند.
- فایل requirements.txt را با استفاده از Poetry ایجاد کنید. Poetry از pyproject.toml برای ایجاد فایل requirements.txt استفاده خواهد کرد. پس از اجرای دستور، بررسی کنید که آیا فایل requirements.txt ایجاد شده است یا خیر (در ترمینال ویرایشگر Cloud Shell اجرا کنید).
# Go to the parent folder containing pyproject.toml file
cd ~/imagescoring/multiagenthandson
# install poetry-plugin-export
uv pip install poetry-plugin-export
#Create requirements.txt file
python3 -m poetry export -f requirements.txt --output requirements.txt --without-hashes
- بسته را ایجاد کنید. ما باید برنامه خود را در یک بسته پایتون .whl قرار دهیم. برای انجام این کار از Poetry استفاده خواهیم کرد. پس از اجرای دستور، مطمئن شوید که یک پوشه dist ایجاد شده و حاوی فایل .whl است (در ترمینال ویرایشگر Cloud Shell اجرا کنید).
# Go to the parent folder containing pyproject.toml file
cd ~/imagescoring/multiagenthandson
#Create python package, to create whl file
python3 -m poetry build
- حالا اسکریپت deploy را آماده میکنیم. اسکریپت deploy، سرویس image-scoring agent یا agent engine ما را مستقر میکند. لطفاً محتوای deploy.py را در پوشه deploy مانند زیر تأیید کنید (برای یافتن فایل از پنل کناری ویرایشگر Cloud Shell استفاده کنید).
import vertexai
from image_scoring.agent import root_agent
import os
import glob # To easily find the wheel file
from dotenv import load_dotenv
# Load environment variables from image_scoring/.env
env_path = os.path.join(os.path.dirname(__file__), "..", "image_scoring", ".env")
load_dotenv(env_path)
PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1")
STAGING_BUCKET = f"gs://{os.getenv('GOOGLE_CLOUD_STORAGE_BUCKET')}"
from vertexai import agent_engines
client=vertexai.Client(
project=PROJECT_ID,
location=LOCATION,
)
remote_app = client.agent_engines.create(
agent=root_agent,
config={
"display_name": "image-scoring",
"staging_bucket": STAGING_BUCKET,
"requirements": open(os.path.join(os.getcwd(), "requirements.txt")).readlines() + ["./dist/image_scoring-0.1.0-py3-none-any.whl"],
"extra_packages": [
"./dist/image_scoring-0.1.0-py3-none-any.whl",
], "env_vars":{"GCS_BUCKET_NAME":os.getenv('GOOGLE_CLOUD_STORAGE_BUCKET')}
}
)
print(f"DEBUG: AgentEngine attributes: {dir(remote_app)}")
try:
print(remote_app.api_resource.name)
except AttributeError:
print("Could not find resource_name, check DEBUG output above.")
- اکنون میتوانیم اسکریپت deploy را اجرا کنیم. ابتدا به پوشهی بالایی multiagenthandson بروید (در ترمینال ویرایشگر Cloud Shell اجرا کنید).
#go to multiagenthandson folder
cd ~/imagescoring/multiagenthandson
#run deploy script from the parent folder containing deploy.py
python3 -m deploy.deploy
بعد از نصب، باید چیزی شبیه به زیر ببینید، 
شکل ۶: نمونه خروجی
- حالا بیایید عامل مستقر شده را آزمایش کنیم. برای آزمایش موتور عامل مستقر شده از راه دور، ابتدا مکان عامل را از خروجی deploy در ترمینال کپی کنید. باید چیزی شبیه به این باشد: projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680 .
به پوشه testclient بروید، فایل remote_test.py را در ویرایشگر Cloud Shell باز کنید و خطوط زیر را ویرایش کنید.
REASONING_ENGINE_ID = "projects/xxx/locations/us-central1/reasoningEngines/xxx" # TODO: Change this
- از پوشهی بالایی multiagenthandson ، دستور زیر را اجرا کنید. باید خروجی مانند شکل ۴ را دریافت کنید. پس از اتمام اجرا، باید بتوانید (اجرا در ترمینال ویرایشگر Cloud Shell) را ببینید.
#go to multiagenthandson folder
cd ~/imagescoring/multiagenthandson
#execute remote_test.py
python3 -m testclient.remote_test
شکل ۷: نمونه خروجی
۹. یک نماینده A2A ایجاد کنید
در این مرحله، ما قصد داریم یک عامل A2A ساده بر اساس عاملی که در مراحل قبلی ایجاد کردیم، ایجاد کنیم. عاملهای ADK (کیت توسعه عامل) موجود میتوانند تحت پروتکل A2A منتشر شوند. اینها نکات کلیدی هستند که در این مرحله یاد خواهید گرفت.
- اصول اولیه پروتکل A2A را بیاموزید.
- بیاموزید که چگونه پروتکلهای ADK و A2A با یکدیگر کار میکنند.
- یاد بگیرید چگونه با پروتکل A2A تعامل داشته باشید.
در این تمرین، ما از کد موجود در پوشه image_scoring_adk_a2a_server استفاده خواهیم کرد. قبل از شروع کار، لطفاً پوشه خود را به این پوشه تغییر دهید (در ترمینال ویرایشگر Cloud Shell اجرا کنید).
#change directory to image_scoring_adk_a2a_server
cd ~/imagescoring/multiagenthandson/image_scoring_adk_a2a_server
#copy the env file
cp ~/imagescoring/multiagenthandson/image_scoring/.env remote_a2a/image_scoring
۱. کارت نماینده A2A ایجاد کنید
پروتکل A2A به یک کارت عامل نیاز دارد که شامل تمام اطلاعات مربوط به عامل مانند قابلیتهای عامل، راهنمای استفاده از عامل و غیره باشد. پس از استقرار یک عامل A2A ، کارت عامل با استفاده از لینک " .well-known/agent-card.json " قابل مشاهده است. کلاینتها میتوانند برای ارسال درخواست به عاملها به این اطلاعات مراجعه کنند.
در پوشه remote_a2a/image_scoring، با استفاده از ویرایشگر Cloud Shell، تأیید کنید که فایل agents.json با محتوای زیر وجود دارد.
{
"name": "image_scoring",
"description": "Agent that generates images based on user prompts and scores their adherence to the prompt.",
"url": "http://localhost:8001/a2a/image_scoring",
"version": "1.0.0",
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["image/png", "text/plain"],
"capabilities": {
"streaming": true,
"functions": true
},
"skills": [
{
"id": "generate_and_score_image",
"name": "Generate and Score Image",
"description": "Generates an image from a given text prompt and then evaluates how well the generated image adheres to the original prompt, providing a score.",
"tags": ["image generation", "image scoring", "evaluation", "AI art"],
"examples": [
"Generate an image of a futuristic city at sunset",
"Create an image of a cat playing a piano",
"Show me an image of a serene forest with a hidden waterfall"
]
}
]
}
۲. ایجاد عامل A2A
در پوشه ریشه image_scoring_adk_a2a_server ، با استفاده از پنل کناری Cloud Shell Editor، تأیید کنید که یک فایل a2a_agent.py وجود دارد که نقطه ورود برای عامل A2A است. این فایل باید محتوای زیر را داشته باشد:
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
root_agent = RemoteA2aAgent(
name="image_scoring",
description="Agent to give interesting facts.",
agent_card="http://localhost:8001/a2a/image_scoring/.well-known/agent.json",
# Optional configurations
timeout=300.0, # HTTP timeout (seconds)
httpx_client=None, # Custom HTTP client
)
۳. عامل A2A را اجرا کنید
حالا آمادهایم تا عامل را اجرا کنیم! برای اجرای عامل، دستور زیر را از داخل پوشهی image_scoring_adk_a2a_server اجرا کنید (در ترمینال ویرایشگر Cloud Shell اجرا کنید).
#following command runs the ADK agent as a2a agent
adk api_server --a2a --port 8001 remote_a2a
۴. تست عامل A2A
وقتی عامل اجرا شد، میتوانیم آن را آزمایش کنیم. اول از همه، بیایید کارت عامل را بررسی کنیم. با استفاده از Terminal>New Terminal یک ترمینال جدید باز کنید و دستور زیر را اجرا کنید (در ترمینال ویرایشگر Cloud Shell که تازه باز شده است، اجرا کنید).
#Execute the following
curl http://localhost:8001/a2a/image_scoring/.well-known/agent.json
اجرای دستور فوق باید کارت عامل (agent card) مربوط به عامل A2A ما را نشان دهد، که عمدتاً محتوای agent.json است که در مرحله قبل ایجاد کردیم.
حالا بیایید یک درخواست به عامل ارسال کنیم. میتوانیم از curl برای ارسال درخواست به عامل استفاده کنیم (در ترمینال ویرایشگر Cloud Shell که تازه باز شده است اجرا کنید)،
curl -X POST http://localhost:8001/a2a/image_scoring -H 'Content-Type: application/json' -d '{
"id": "uuid-123",
"params": {
"message": {
"messageId": "msg-456",
"parts": [{"text": "Create an image of a cat"}],
"role": "user"
}
}
}'
در درخواست بالا، میتوانید با تغییر خط « ایجاد یک تصویر از یک گربه » (Create an image of a cat)، اعلان را تغییر دهید. پس از اجرای دستور، میتوانید تصویر خروجی را در فضای ذخیرهسازی ابری گوگل مشخصشده بررسی کنید.
۱۰. تمیز کردن
حالا بیایید چیزی را که تازه ایجاد کردهایم، تمیز کنیم.
- سرور Vertex AI Agent Engine که تازه ایجاد کردیم را حذف کنید. با تایپ Vertex AI در نوار جستجوی Google Cloud Console به Vertex AI بروید. روی Agent Engine در سمت چپ کلیک کنید. میتوانید با کلیک روی delete، Agent را حذف کنید.
شکل ۸
- فایلهای موجود در Cloud Shell را حذف کنید
#Execute the following to delete the files
cd ~
rm -R ~/imagescoring
- سطل را حذف کنید. میتوانید به کنسول GCP->Cloud Storage بروید، سطل خود را انتخاب و حذف کنید.
شکل ۹: حذف سطل
۱۱. نتیجهگیری
تبریک! شما با موفقیت یک برنامه ADK (کیت توسعه عامل) چندعاملی را در Vertex AI Agent Engine مستقر کردید. این یک دستاورد مهم است که چرخه حیات اصلی یک برنامه مدرن مبتنی بر ابر را پوشش میدهد و پایه محکمی برای استقرار سیستمهای عامل پیچیده شما فراهم میکند.
خلاصه
در این آزمایشگاه یاد گرفتید که:
- ایجاد برنامه چند عامله با استفاده از ADK (کیت توسعه عامل)
- برنامه را در Vertex AI Agent Engine مستقر کنید
- یک عامل ایجاد کنید که بتواند با استفاده از پروتکل A2A ارتباط برقرار کند.
منابع مفید