۱. مقدمه
نمای کلی
این آزمایشگاه نشان میدهد که چگونه میتوان فراخوانی رویدادمحور یک عامل ADK مستقر در Cloud Run را با استفاده از سرویسهای Eventarc و Pub/Sub به صورت ایمن پیادهسازی کرد. اغلب اوقات یک عامل توسط یک کاربر یا عامل دیگر مستقیماً فراخوانی میشود. با این حال، هنگامی که یک عامل در گردشهای کاری مبتنی بر رویداد موجود ادغام میشود، ایجاد یک فراخوانی مستقیم نیاز به تغییراتی در نرمافزار موجود دارد. راهاندازی فراخوانی عامل بر اساس یک رویداد، امکان گنجاندن یک عامل در گردشهای کاری موجود را بدون تغییر در گردشهای کاری فراهم میکند.
کاری که انجام خواهید داد
در این آزمایش شما یک برنامه عامل محور ZooKeeper ایجاد خواهید کرد که دارای یک عامل هوش مصنوعی است و از چند ابزار برای ارائه اطلاعات در مورد حیوانات در باغ وحش خیالی استفاده میکند.

شما برنامه ZooKeeper را به عنوان یک سرویس در Cloud Run مستقر خواهید کرد، که یک پلتفرم محاسباتی کاملاً مدیریتشده و بدون سرور است که کانتینرهای بدون وضعیت را در زیرساخت گوگل اجرا میکند. سپس یک تریگر Eventarc راهاندازی خواهید کرد که نقطه پایانی سرویس را برای مدیریت ناهمگام پیامهای منتشر شده در یک موضوع Pub/Sub فراخوانی میکند. شما اطمینان حاصل خواهید کرد که استقرار از بهترین شیوهها، از جمله استفاده از حسابهای سرویس IAM تعیینشده، اعطای دسترسی با حداقل امتیاز و به حداقل رساندن سطح حمله بالقوه با افشای نقطه پایانی برنامه ZooKeeper فقط به Eventarc، پیروی میکند. شما این کار را با کمک Cloud Shell و کنسول Cloud انجام خواهید داد. از کتابخانههای ADK و Cloud SDK برای پایتون استفاده خواهید کرد. برای بررسی رفتار، از gcloud CLI استفاده خواهید کرد.
آنچه یاد خواهید گرفت
- عامل ADK خود را در Google Cloud Run مستقر کنید.
- تریگر Eventarc را با عامل ADK که روی Google Cloud Run اجرا میشود، ادغام کنید.
- با استفاده از اصل دسترسی با کمترین امتیاز و با کمک Google Cloud IAM، استقرار و ادغام خود را با Eventarc ایمن کنید.
- پیامها را به Pub/Sub منتشر و دریافت کنید.
- نمایش عمومی برنامهی کاربردی خود را که در Google Cloud Run مستقر کردهاید، به حداقل برسانید.
آنچه نیاز دارید
- مرورگر وب کروم †
- یک حساب گوگل شخصی ‡
- یک پروژه ابری گوگل که به یک حساب صورتحساب فعال متصل است
توجه داشته باشید که حساب کاربری شما باید دسترسی IAM به پروژه داشته باشد که به شما امکان میدهد منابع را تأمین کرده و دسترسی IAM به این منابع را پیکربندی کنید.
† تجربه کاربری با استفاده از مرورگرهای دیگر ممکن است با آنچه در آزمایشگاه شرح داده شده است متفاوت باشد.
‡ استفاده از حساب کاربری شرکتی یا مدرسه ممکن است در انجام برخی از عملیات شرح داده شده در آزمایشگاه محدودیت داشته باشد.
۲. تنظیمات محیطی
برای اطمینان از یک محیط توسعه کاملاً کاربردی برای آزمایشگاه، از Google Cloud Shell استفاده خواهید کرد که تمام ابزارهای لازم را از قبل نصب کرده است. برای تنظیم محیط، دستورالعملها را دنبال کنید.
اگر حساب گوگل ندارید، یک حساب گوگل ایجاد کنید .
دستورالعملهای راهاندازی
- از حساب گوگل خود برای ورود به کنسول ابری گوگل استفاده کنید.
- 👉 انتخابگر پروژه را در نوار ناوبری بالا باز کنید (ممکن است عبارت «انتخاب یک پروژه» نوشته شده باشد یا نام یک پروژه موجود را نشان دهد) یا روی میانبر صفحهکلید
Ctrl+Oکلیک کنید و یک پروژه موجود را انتخاب کنید یا یک پروژه جدید ایجاد کنید. ایجاد یک پروژه جدید چند ثانیه طول میکشد. صبر کنید تا آماده شود و سپس آن را با استفاده از انتخابگر پروژه انتخاب کنید.
- 👉 روی آیکون Cloud Shell در بالای کنسول Google Cloud کلیک کنید (با مستطیل قرمز مشخص شده است):

در صورت درخواست، در کادر محاورهای باز شده روی **مجاز** کلیک کنید تا Cloud Shell برای استفاده از اطلاعات حساب شما تأیید شود.
- 👉💻 مطمئن شوید که gcloud CLI برای استفاده از پروژهای که انتخاب کردهاید (یا ایجاد کردهاید) پیکربندی شده است. دستور زیر را برای بررسی شناسه پروژه پیکربندی شده اجرا کنید:
انتظار میرود خروجی مشابه زیر را مشاهده کنید:gcloud config get-value project که در آنYour active configuration is: [cloudshell-19597] [PROJECT_ID]
[PROJECT_ID]شناسه پروژهای است که انتخاب یا ایجاد کردهاید.👉💻 اگر مقدار دیگری میبینید، دستور زیر را اجرا کنید تا شناسه پروژه خود را به عنوان شناسه پیشفرض پروژه برای دستورات gcloud CLI پیکربندی کنید: برای مثال، اگر شناسه پروژه شما lab-project-id-example-123 باشد، دستور باید به صورت زیر باشد:gcloud config set project [YOUR_PROJECT_ID] 🤔💻 اگر شناسه پروژه خود را به خاطر نمیآورید، از دستور زیر برای فهرست کردن تمام شناسههای پروژهای که به آنها دسترسی دارید، از جدیدترین شروع کنید:gcloud config set project lab-project-id-example-123
gcloud projects list \ --format='value(projectId)' \ --sort-by='~createTime'
- 👉💻 مکان تأمین منابع و شناسه و شماره پروژه خود را در متغیرهای محیطی تنظیم کنید:
export LOCATION="us-central1" export PROJECT_ID=$(gcloud config get-value project) export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") - 👉💻 رابطهای برنامهنویسی کاربردی گوگل مورد نیاز برای این آزمایشگاه را فعال کنید.
صبور باشید، این دستور ممکن است چند دقیقه طول بکشد. در صورت اجرای موفقیتآمیز دستور، باید پیامی مشابه این را مشاهده کنید:gcloud services enable \ aiplatform.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ pubsub.googleapis.comOperation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.
۳. اپلیکیشن آزمایشی ZooKeeper را نصب کنید
مراحل زیر شامل تأمین و پیکربندی منابع از جمله استقرار برنامه کاربردی هوش مصنوعی عاملمحور است.
راهاندازی منابع Pub/Sub
شما دو موضوع Pub/Sub ایجاد خواهید کرد. یکی توسط سرویس شخص ثالث برای ارسال رویدادها به برنامه هوش مصنوعی عامل شما استفاده میشود و دیگری برای برنامه جهت انتشار نتایج پردازش رویدادها.
- 👉💻 یک موضوع Pub/Sub ایجاد کنید که برای راهاندازی برنامه هوش مصنوعی عاملدار استفاده شود:
gcloud pubsub topics create invoke_agent export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)") - 👉💻 یک موضوع Pub/Sub ایجاد کنید که برنامه بتواند پاسخهای خود را در آن ارسال کند:
این دستورات همچنین یک اشتراک برای موضوع Pub/Sub ایجاد شده ایجاد میکنند. این اشتراک هنگام اجرای نسخه آزمایشی به عنوان راهی برای مشاهده نتایج استفاده خواهد شد.gcloud pubsub topics create agent_responses export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)") gcloud pubsub subscriptions create agent_responses \ --topic=agent_responses
تنظیم حسابهای سرویس و سیاستهای IAM در سطح پروژه
شما دو حساب سرویس ایجاد خواهید کرد تا دامنه دسترسی سرویس Cloud Run و تریگر Eventarc را با رعایت اصل حداقل امتیاز دسترسی، به حداقل محدود کنید. سرویس Cloud Run برای نوشتن گزارشها و ردیابیها، فراخوانی Gemini LLM در Google Vertex AI و ارسال نتایج به یک موضوع Pub/Sub به مجوزهایی نیاز دارد. دسترسی حداقلی تریگر Eventarc برای فراخوانی سرویس Cloud Run ZooKeeper و دسترسی به Pub/Sub برای خواندن رویدادهای ارسال شده نیاز به مجوزهایی دارد. این دستورالعملها شما را راهنمایی میکنند تا مجوزهای لازم برای جعل هویت سرویس سیستم Pub/Sub را به حساب سرویس تریگر اعطا کنید. پس از ایجاد منبع تریگر Eventarc، دستوری را اجرا خواهید کرد که نقش roles/run.invoker را اعطا میکند تا حساب سرویس تریگر بتواند سرویس Cloud Run را فراخوانی کند.
- 👉💻 یک حساب کاربری برای سرویس Cloud Run ایجاد کنید:
gcloud iam service-accounts create zookeeper-cloudrun-sa export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 به حساب سرویس، مجوزهای لازم برای نوشتن گزارشها و ردیابیها و استفاده از مدلهای Gemini در Vertex AI را اعطا کنید:
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/logging.logWriter" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/cloudtrace.agent" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/aiplatform.user" \ --condition=None - 👉💻 به حساب سرویس، مجوزهای ارسال پیام به موضوع 'agent_responses' را اعطا کنید:
gcloud pubsub topics add-iam-policy-binding agent_responses \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/pubsub.publisher" - 👉💻 یک حساب کاربری سرویس برای تریگر Eventarc ایجاد کنید:
gcloud iam service-accounts create zookeeper-trigger-sa export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 مجوزهای حساب سرویس Pub/Sub system را برای ارسال درخواستهای پوش احراز هویت شده اعطا کنید:
اگر پروژهای پس از ۸ آوریل ۲۰۲۱ ایجاد شده باشد، این دستور اختیاری است .gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \ --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"
استقرار برنامه ZooKeeper در Cloud Run
شما کد برنامه آزمایشی را از گیتهاب دانلود خواهید کرد و کد را در Cloud Run مستقر خواهید کرد.
- 👉💻 اپلیکیشن هوش مصنوعی عاملگرا را دانلود کنید:
این دستورات از بررسی پراکندهی گیت در پوشهی برنامهی آزمایشی برای کاهش زمان دانلود استفاده میکنند.mkdir zoo-keeper-lab && cd zoo-keeper-lab git init git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos git config set core.sparseCheckout true echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout git pull origin main --depth 1 cd ai-ml/agent-labs/adk_invoke_with_pubsub/ - 👉💻 اپلیکیشن هوش مصنوعی عاملگرا را روی Cloud Run مستقر کنید:
gcloud run deploy zookeeper-agent \ --region="${LOCATION}" \ --source="." \ --no-allow-unauthenticated \ --quiet \ --service-account="${ZOOKEEPER_SA}" \ --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"
پیکربندی تریگر Eventarc
پس از آمادهسازی تمام منابع (موضوعات Pub/Sub، حسابهای سرویس IAM و سرویس Cloud Run)، زمان راهاندازی منبع trigger مربوط به Eventarc فرا رسیده است. شما منبع trigger مربوط به Eventarc را ایجاد خواهید کرد و مجوزهای لازم برای فراخوانی سرویس Cloud Run را به حساب سرویس trigger اعطا خواهید کرد.
- 👉💻 ایجاد تریگر Eventarc:
gcloud eventarc triggers create invoke-agent \ --location="${LOCATION}" \ --destination-run-service="zookeeper-agent" \ --destination-run-path="/zookeeper" \ --destination-run-region="${LOCATION}" \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --transport-topic="${INVOKE_TOPIC_ID}" \ --service-account="${TRIGGER_SA}" - 👉💻 به حساب سرویس تریگر مجوزهای لازم برای فراخوانی سرویس Cloud Run را اعطا کنید:
gcloud run services add-iam-policy-binding zookeeper-agent \ --region="${LOCATION}" \ --member="serviceAccount:${TRIGGER_SA}" \ --role="roles/run.invoker"
۴. نحوهی عملکرد راهحل را بررسی کنید
حالا آنچه را که مستقر کردهاید، مرور کنید. نمودار زیر تمام منابع و نحوه تعامل آنها با یکدیگر را نشان میدهد. شما از رابط خط فرمان gcloud برای انتشار پیامی در تاپیک 'invoke_agent' استفاده خواهید کرد. این رویدادی را شبیهسازی میکند که یک سرویس شخص ثالث برای فراخوانی برنامه هوش مصنوعی agentic به سرویس پیامرسانی گزارش میدهد.

استقرار پس از دسترسی با حداقل امتیاز، ایمن میشود. سرویس Cloud Run احراز هویت را اعمال میکند (به آرگومان --no-allow-unauthenticated در مرحله 9 در بخش قبلی مراجعه کنید). فقط هویتهایی با مجوزهای roles/run.invoker یا مجوزهای مشابه میتوانند سرویس را فراخوانی کنند. و این نقش فقط به حساب سرویس trigger Eventarc اعطا میشود. به طور مشابه، دسترسی به موضوع 'invoke_agent' به حداقل میرسد تا انتشار غیرمجاز رویدادها مجاز نباشد. هنوز هم میتوان عامل ZooKeeper را مستقیماً با دور زدن ارسال به موضوع Pub/Sub فراخوانی کرد. برای یادگیری نحوه پنهان کردن نقطه پایانی برنامه از دسترسی عمومی، به بخش 6 مراجعه کنید.
گردش کار را اجرا کنید
شما با انتشار یک سوال به زبان طبیعی در ZooKeeper، یک رویداد خارجی را شبیهسازی خواهید کرد.
👉💻 برای ارسال پیام در موضوع Pub/Sub از دستور زیر استفاده کنید:
gcloud pubsub topics publish invoke_agent \
--message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'
در واقعیت، اطلاعات رویداد احتمالاً شکل خوانایی کمتری خواهد داشت. برای پردازش آن، یک برنامه هوش مصنوعی عاملمحور نیاز به دستورالعملهای دقیقی در مورد قالب رویداد، دادهها و نحوه برخورد عامل با اطلاعات رویداد دارد.
میتوانید بررسی کنید که آیا عامل رویداد را دریافت کرده، درخواست را پردازش کرده و پاسخ را در موضوع 'agent_responses' ارسال کرده است یا خیر. برای خواندن پاسخ، از اشتراک 'agent_responses' استفاده خواهید کرد (codelab از همان شناسه برای موضوع و اشتراک برای پاسخها استفاده میکند).
👉💻 از دستور زیر برای خواندن پاسخ عامل از اشتراک Pub/Sub استفاده کنید:
gcloud pubsub subscriptions pull agent_responses --auto-ack
خروجی، جدولی با فرادادههای پیام و محتوای دادهای که حاوی پاسخ «۳۳ گونه در باغوحش وجود دارد» است، چاپ میکند. پرچم --auto-ack بهطور خودکار پیام را پس از دریافت تأیید میکند، بنابراین دوباره تحویل داده نخواهد شد.
چگونه کار میکند؟
با باز کردن ویرایشگر Cloud Shell و مشاهده فایلهای موجود در پوشه ~/zoo-keeper-lab کد منبع برنامه هوش مصنوعی عاملمحور را مشاهده کنید. همچنین میتوانید کد منبع را در GitHub مشاهده کنید.
- فایل main.py یک برنامه وب FastAPI پایه را با یک هندلر واحد که رویدادهای Eventarc را پردازش میکند، پیادهسازی میکند.
- فایل processor.py پیام رویداد را تجزیه میکند تا شناسه کاربر و درخواست را بازیابی کند. سپس یک جلسه جدید در ADK runner ایجاد میکند و عامل Zookeeper را برای پردازش درخواست فراخوانی میکند. پاسخ از عامل به موضوع Pub/Sub با عنوان 'agent_responses' ارسال میشود.
- زیرپوشه zookeeper_agent میزبان کد منبع عامل ADK است. میتوانید دستور
adk run zookeeper_agentاز پوشه ریشه برنامه اجرا کنید تا با استفاده از adk CLI با عامل تعامل داشته باشید.
نحوه عیب یابی
در صورتی که هر یک از دستورات قبلی با شکست مواجه شد، پیام خطا را با دقت بخوانید. اگر استقرار در Cloud Run با شکست مواجه شد، اولین قدم این است که مشخص کنید در کدام مرحله از فرآیند، شکست رخ داده است.
- اگر خروجی دستور "gcloud run deploy..." گزارش داد که ساخت با شکست مواجه شد، URL گزارشهای ساخت را در خروجی مشاهده کنید و آن را در یک پنجره جداگانه باز کنید.
- اگر خروجی چیزی شبیه به "service failed to start" یا مشابه آن را نشان دهد، به این معنی است که سرویس مستقر میشود اما سپس در بررسی سلامت (healthcheck) با شکست مواجه میشود. در این صورت، Logs Explorer را باز کنید یا پاراگراف زیر را برای دستور gcloud CLI ببینید. برای یافتن علت اصلی خرابی، گزارشها را بخوانید.
اگر پیامی در Pub/Sub ارسال کردید اما نماینده پاسخی نداد یا پاسخ عجیب به نظر میرسید، چه باید کرد؟
👉💻 از دستور زیر برای خواندن لاگهای برنامه که از اجرای اخیر منتشر شدهاند، استفاده کنید:
gcloud logging read \
'resource.type = "cloud_run_revision" AND \
resource.labels.service_name = "zookeeper-agent" AND \
resource.labels.location = "us-central1"'
این گزارشها، اجرا را ردیابی کرده و خطاهایی مانند بار داده پیام نادرست یا غیرقابل تجزیه، پاسخ نامعتبر از مدل جمینی، تنظیمات نامعتبر محیط و سایر مشکلات احتمالی را گزارش میدهند.
۵. امنیت استقرار را تقویت کنید
سرویس Cloud Run که شما پیادهسازی کردهاید، یک نقطه پایانی عمومی را در معرض نمایش قرار میدهد که میتواند توسط هر کسی در اینترنت فراخوانی شود. در حالی که این نقطه پایانی در برابر فراخوانیهای غیرمجاز محافظت میشود و ساختار درخواست را به دقت اعتبارسنجی میکند، اما همچنان این بردار حمله را باقی میگذارد که امکان حملات انکار سرویس و انکار کیف پول را فراهم میکند. از آنجا که تنها مسیر فراخوانی برای سرویس در طراحی فعلی از طریق تریگر Eventarc است، سرویس نیازی به نمایش نقطه پایانی خود در اینترنت ندارد.
👉💻 با محدود کردن فراخوانیهای سرویس به مجموعهای محدود از منابع، از جمله تریگرهای Eventarc، این مسیر حمله را ببندید:
gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal
حال، اگر سعی کنید URL سرویس را از دستگاه محلی خود فراخوانی کنید، خطای "404 صفحه یافت نشد" را دریافت خواهید کرد.
👉💻 از curl برای ارسال درخواست به نقطه پایانی سرویس استفاده کنید:
URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"
خروجی مشابه زیر را مشاهده خواهید کرد:
<html><head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>404 Page not found</title> </head> <body text=#000000 bgcolor=#ffffff> <h1>Error: Page not found</h1> <h2>The requested URL was not found on this server.</h2> <h2></h2> </body></html>
پس از این تغییر، دیگر نمیتوان ZooKeeper را مستقیماً با فراخوانی نقطه پایانی سرویس Cloud Run فراخوانی کرد، مگر اینکه این فراخوانی را از VPC در همان پروژه، شبکه Shared VPC که نسخه شما برای ارسال ترافیک به آن پیکربندی شده است یا میزبانی که بخشی از محیط VPC Service Controls است، انجام دهید.
۶. خلاصه
تبریک! شما با موفقیت محیطی را برای فراخوانی ناهمگام برنامه هوش مصنوعی عامل خود که توسط رویدادهای ورودی فعال میشود، راهاندازی کردهاید.
تمیز کردن
توجه داشته باشید که نگه داشتن منابعی که تأمین کردهاید ممکن است از حساب صورتحساب شما هزینه داشته باشد. اگر قصد ندارید از این محیط برای آزمایشهای بیشتر استفاده کنید و برای جلوگیری از هزینههای بعدی، توصیه میشود منابعی را که در طول این آزمایش کد ایجاد کردهاید، حذف کنید.
دو روش برای انجام آن وجود دارد:
روش اول : متوقف کردن پروژه
خاموش کردن (حذف) پروژه، تمام منابع و دادههای پروژه را آزاد میکند و حساب صورتحساب را از حالت اتصال خارج میکند. استفاده از این روش از اعمال هزینههای بیشتر برای هرگونه منبع یا دادهای که برای این آزمایشگاه کد استفاده میشود، جلوگیری میکند. برای خاموش کردن پروژه از دستور زیر استفاده کنید:
gcloud projects delete $(gcloud config get-value project) --quiet
روش دوم : حذف منابع در پروژه
حذف سرویس Cloud Run از هزینههای بیشتر برای استفاده از پلتفرم بدون سرور جلوگیری میکند. توجه داشته باشید که این روش تمام دادههای تولید شده در طول codelab مانند Cloud Build و گزارشهای برنامه، تصاویر کانتینر و غیره را به طور کامل حذف نمیکند. برای حذف سرویس، دستور زیر را اجرا کنید:
gcloud run services delete zookeeper-agent --region=${LOCATION}
تعریف تریگر Eventarc و موضوعات Pub/Sub هزینههای مدیریتی را تحمیل نمیکنند (برای جزئیات بیشتر به قیمتگذاری Eventarc و قیمتگذاری Pub/Sub مراجعه کنید).
درباره خاموش کردن پروژه بیشتر بدانید.
قدم بعدی چیست؟
- با بررسی نسخه آزمایشی در GitHub ، درباره کد بیشتر بدانید.
- بررسی معماری که دسترسی به سیستمهای سازمانی مختلف را هماهنگ میکند
- یاد بگیرید چگونه Cloud Run را با استفاده از triggerهای Eventarc فعال کنید
- درباره ADK بیشتر بدانید