۱. مرور کلی
در این آزمایشگاه کد، شما یک عامل ADK 2.0 را از یک محیط توسعه محلی به یک محیط عملیاتی منتقل میکنید. شما agents-cli برای بستهبندی، تأیید و میزبانی گردش کار مبتنی بر گراف خود به صورت زنده در Agent Runtime در Google Cloud استفاده خواهید کرد.
برای بررسی این فرآیند استقرار، شما یک نمونه اولیه محلی از Ambient Expense Agent را از ابتدا و قبل از استقرار آن در فضای ابری خواهید ساخت. (برای بررسی عمیقتر منطق اصلی این Agent، به codelabs بنیادی در سایت رویداد Kaggle مراجعه کنید). Ambient Expense Agent با تأیید فوری ادعاهای استاندارد و در عین حال علامتگذاری هزینههای بزرگتر برای بررسی توسط انسان در حلقه، گزارش هزینههای کارکنان را ساده میکند. در باطن، از یک گردش کار مبتنی بر نمودار ADK 2.0 برای هماهنگی این تأییدیههای خودکار و مراحل تحلیل ریسک استفاده میکند.
آنچه یاد خواهید گرفت
- چگونه پروژه محلی Ambient Expense Agent خود را برای میزبانی ابری آماده کنید.
- چگونه توصیفگرهای استقرار و پوششهای عملیاتی لازم را داربستبندی کنیم.
- نحوه انجام تستهای آزمایشی (dry-run) و استقرار مستقیم کد در Agent Runtime .
- چگونه با استفاده از Cloud Trace، ردیابیهای اجرای عامل تولید خود را رصد کنید.
آنچه نیاز دارید
- یک پروژه فعال گوگل کلود با قابلیت پرداخت.
- gcloud SDK نصب و احراز هویت شد.
- مدیر بسته uv نصب شده است.
- گوگل آنتی گراویتی IDE نصب شده است.
پیشنیازها
این آزمایشگاه کد فرض میکند که شما با موارد زیر راحت هستید:
- پیمایش سیستم با استفاده از ترمینال
- مفاهیم اولیه توسعه پایتون
- مفاهیم اساسی گوگل کلود
۲. محیط ابری گوگل خود را تنظیم کنید
قبل از استقرار، باید پروژه Google Cloud خود را پیکربندی کرده و API های لازم را فعال کنید.
👉 ضد جاذبه سریع:
Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).
وقتی Antigravity این اعلان را اجرا میکند، دستورات ترمینال gcloud لازم را برای پیکربندی پروژه شما و فعال کردن سرویسها پیشنهاد و اجرا میکند. در طول مرحله احراز هویت، Antigravity یک URL مجوز در ترمینال نمایش میدهد. برای ورود به سیستم از طریق مرورگر وب و اعطای دسترسی، روی لینک کلیک کنید. پس از تکمیل ورود به سیستم مرورگر، Antigravity اجرا را از سر میگیرد تا متغیرهای محیطی پروژه شما را تنظیم کرده و APIهای مورد نیاز را فعال کند.
۳. مهارتهای رابط خط فرمان و ابزار توسعه نرمافزار (ADK) را برای Agentها تنظیم کنید
برای اینکه Antigravity بتواند عاملهای ADK را به خوبی بسازد و مستقر کند، به مجموعه مهارتهای ADK نیاز دارد. اینها منابعی برای API ADK، چارچوببندی پروژه، گردش کار استقرار agents-cli و ارزیابی هستند. نصب زنجیره ابزار agents-cli همچنین این مهارتها را در عامل کدنویسی شما نصب میکند و آن را برای مدیریت چرخه کامل حیات عامل شما از چارچوببندی محلی تا استقرار ابری مجهز میکند.
👉 دستور زیر را در Antigravity کپی و پیست کنید:
Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.
وقتی Antigravity این اعلان را اجرا میکند، دستور uvx google-agents-cli setup در ترمینال اجرا میکند تا CLI و مهارتهای همراه آن را نصب کند. سپس agents-cli info اجرا میکند تا نصب را تأیید کند و مهارتهای دامنه تازه نصب شده (مانند google-agents-cli-deploy و google-agents-cli-workflow ) را مستقیماً در چت فهرست میکند.
۴. پروژه نماینده خود را ایجاد کنید
با پیکربندی محیط ابری و نصب مهارتهای CLI، آماده تولید کدبیس محلی برای عامل خود هستید. در این مرحله، از Antigravity برای ایجاد یک نمونه اولیه کاملاً کاربردی Ambient Expense Agent سازگار با ADK 2.0 استفاده میکنید.
👉 ضد جاذبه سریع:
Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.
وقتی Antigravity این اعلان را اجرا میکند، از مهارتهای scaffolding تازه نصب شده برای اجرای agents-cli scaffold create expense-agent --adk در ترمینال استفاده میکند. سپس کد نمونه اولیه تولید شده را تأیید و تنظیم میکند تا مطمئن شود که expense-agent شما به درستی آستانه تأیید خودکار $100 و جریان بررسی انسانی در حلقه را در گردش کار نمودار کیت توسعه عامل (ADK) خود پیادهسازی میکند.
۵. برای استقرار در محیط عملیاتی آماده شوید
Agent Runtime یک سرویس Google Cloud کاملاً مدیریتشده است که به شما امکان میدهد عاملهای هوش مصنوعی را در محیط عملیاتی مستقر، مدیریت و مقیاسبندی کنید. Agent Runtime پیچیدگیهای عملیاتی میزبانی را مدیریت میکند و یک محیط Stateful با ویژگیهایی مانند مدیریت جلسه، حافظه بلندمدت و جعبههای شنی اجرای کد امن ارائه میدهد.
چرا باید در Agent Runtime مستقر شویم؟
هنگام ساخت عاملها به صورت محلی با Antigravity، عامل شما روی دستگاه محلی شما در برابر localhost اجرا میشود. اگرچه برای نمونهسازی سریع عالی است، اما عاملهای محلی به محض بستن لپتاپ شما متوقف میشوند.
استقرار عامل شما در Agent Runtime، گردش کار شما را به یک محیط Google Cloud کاملاً مدیریتشده و همیشه در دسترس منتقل میکند. این امر یک نقطه پایانی امن و زنده در backend ایجاد میکند که 24 ساعته و 7 روز هفته فعال میماند. در codelab بعدی، یک frontend وب خواهید ساخت که مستقیماً به این نقطه پایانی ابری متصل میشود و به عامل شما یک URL عمومی میدهد.
علاوه بر این، Agent Runtime زیرساخت اختصاصی بهینه شدهای را برای عاملهای هوش مصنوعی فراهم میکند که قابلیتهای داخلی مانند موارد زیر را ارائه میدهد:
- اجرای مدیریتشدهی مبتنی بر وضعیت: مدیریت داخلی نشست و ماندگاری در حافظهی بلندمدت در طول نوبتهای مکالمه.
- سندباکسینگ امن: فراخوانیهای ابزار پویا و کد تولید شده توسط عامل را در محیطهای ایزوله به طور ایمن اجرا میکند.
- قابلیت مشاهده سازمانی: انتقال مستقیم دادههای تلهمتری از قبل به Cloud Trace و Cloud Logging.
برای میزبانی عامل خود در Agent Runtime، باید دایرکتوری پروژه محلی خود را با توصیفگرهای تولید، طرحوارهها و بستهبندیهای نقطه پایانی ارتقا دهید.
👉 ضد جاذبه سریع:
Scaffold the production deployment files for Agent Runtime.
وقتی Antigravity این اعلان را اجرا میکند، دستور agents-cli scaffold enhance --deployment-target agent_runtime --yes را در ریشه پروژه شما اجرا میکند. این دستور دایرکتوری شما را اسکن کرده و به طور خودکار موارد زیر را تولید میکند:
-
app/agent_runtime_app.py: بستهبندی سرویس در سطح تولید. -
deployment_metadata.json: طرحوارهی مورد استفاده توسط Agent Runtime برای چرخش منابع.
منطق عامل اصلی شما در app/agent.py کاملاً دست نخورده و حفظ شده باقی میماند.
۶. بستهبندی و تأیید محلی
قبل از شروع آپلود ابری، بستههای خود را قفل کنید و یک تست محلی انجام دهید تا تداخلهای وابستگی احتمالی را شناسایی کنید.
👉 ضد جاذبه سریع:
Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.
وقتی Antigravity این اعلان را اجرا میکند، ابتدا uv lock در ترمینال اجرا میکند تا یک فایل قفل قطعی ایجاد کند و از نسخههای کتابخانهای سازگار در ابر اطمینان حاصل کند. سپس agents-cli deploy --dry-run اجرا میکند تا اعتبار پیکربندی را تأیید کند و مراحل استقرار را بدون تأمین منابع ابری پیشنمایش دهد. میتوانید خروجی dry-run را در ترمینال بررسی کنید تا از صحت همه فایلها و تنظیمات اطمینان حاصل کنید.
۷. استقرار در زمان اجرای عامل
عامل هزینه محیطی خود را در Agent Runtime مستقر کنید.
👉 ضد جاذبه سریع:
Deploy this agent to Agent Runtime.
وقتی Antigravity این اعلان را اجرا میکند، مهارت google-agents-cli-deploy را فعال کرده و agents-cli deploy --project YOUR_PROJECT_ID --region us-west1 را اجرا میکند. فرآیند بستهبندی، آپلود و آمادهسازی Agent Runtime معمولاً ۵ تا ۱۰ دقیقه طول میکشد. Antigravity پیشرفت استقرار را در ترمینال رصد میکند و پس از تکمیل، URL نقطه پایانی زنده شما را نمایش میدهد.
💡 نکته حرفهای (مدیریت زمان انقضای ویندوز): اگر ترجیح میدهید ترمینال خود را در طول استقرارهای طولانی قفل نکنید، میتوانید به Antigravity دستور دهید که از پرچم --no-wait برای شروع استقرار به صورت ناهمزمان استفاده کند و بعداً با استفاده از agents-cli deploy --status پیشرفت را بررسی کند.
۸. کارگزار خود را آزمایش کنید
پس از استقرار نماینده شما، میتوانید تأیید کنید که بهطور خودکار هزینههای کوچک را تأیید میکند و برای هزینههای بزرگتر، تأیید انسانی را بهدرستی علامتگذاری میکند.
👉 از Antigravity بخواهید موتور مستقر شده را تأیید کند:
Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.
از طرف دیگر، میتوانید عامل خود را به صورت دستی با استفاده از پیشنمایش Cloud Console Playground آزمایش کنید. برای باز کردن Playground:
- در کنسول گوگل کلود، از منوی ناوبری برای انتخاب Agent Platform > Deployments استفاده کنید.
- عامل مستقر شده خود را از لیست استقرارها انتخاب کنید.
- برای باز کردن رابط چت آزمایشی تعاملی، روی دکمه Playground کلیک کنید.
👉 برای آزمایش تأیید خودکار(<$100) ، فایل JSON زیر را در کادر گفتگو قرار دهید:
{"data": {"amount": 50.0, "submitter": "user@example.com", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}
شما باید یک پاسخ JSON دریافت کنید که خروجی گره auto_approve را با وضعیت "approved" نشان میدهد.
👉 برای آزمایش جریان انسان در حلقه (HITL) ، فایل JSON زیر را وارد کنید.
{"data": {"amount": 150.0, "submitter": "user@example.com", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}
این کار باعث فعال شدن review_agent، انتشار هشدار و سپس مکث در اجرا میشود و یک RequestInput (انسان در حلقه) برای درخواست تأیید ارائه میدهد.
۹. بر نماینده تولید خود نظارت و نظارت داشته باشید
با Agent Runtime، تلهمتری به طور خودکار سیمکشی میشود. هر تعامل، فراخوانی مدل و اجرای ابزار، گزارشهای بلادرنگ را پخش میکند و به پروژه شما گسترش مییابد.
- بازرسی ردپاها : کنسول Cloud Trace را باز کنید تا نقشههای تراکنش زنده، تأخیرهای مدل و مراحل اجرای ابزار را بررسی کنید.
- گزارشهای حسابرسی : از گزارشگیری ابری برای بررسی خروجی استاندارد در لحظه و ردیابیهای تشخیصی پشته استفاده کنید.
- تجزیه و تحلیل تجمیعی : اگر پرچم
--bq-analyticsدر طول فرآیند scaffolding فعال شده باشد، میتوانید با استفاده از SQL، گزارشهای خود را در BigQuery جستجو کنید تا نسبتهای تأیید و روندهای نوبت مکالمه را مشاهده کنید.
کوئری SQL زیر مثالی برای محاسبه نسبتهای تأیید ارائه میدهد. میتوانید از Antigravity بخواهید که این کوئری را برای پروژه خاص شما و مجموعه دادههای BigQuery سفارشیسازی کند:
SELECT
COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
COUNT(1) AS total_processed,
SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
`[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
agent = 'expense_processor';
۱۰. (اختیاری) تأیید ثبت نام در فهرست نمایندگان
برای اینکه سایر سرویسها، توسعهدهندگان یا نمایندگان سازمان شما بتوانند با خیال راحت عامل هزینه شما را کشف و مصرف کنند، باید آن را در رجیستری عامل سازمانی (Gemini Enterprise) ثبت کنید.
از آنجا که شما عامل خود را در Agent Runtime مستقر کردهاید، به طور خودکار در Agent Registry ثبت میشود. هرگونه بهروزرسانی یا حذف عامل شما در Agent Runtime در آینده به طور خودکار با Agent Registry نیز همگامسازی خواهد شد.
👉 از Antigravity بخواهید ثبت نام خودکار نماینده شما را تأیید کند:
Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.
وقتی Antigravity این اعلان را اجرا میکند، agents-cli publish gemini-enterprise --list در ترمینال اجرا میکند. این دستور از رجیستری Agent پرسوجو میکند و تمام Agentهای ثبتشده Gemini Enterprise در پروژه شما را فهرست میکند و به شما این امکان را میدهد که تأیید کنید Ambient Expense Agent شما در سراسر سازمان شما فعال و قابل شناسایی است.
۱۱. تمیز کردن
برای جلوگیری از هزینههای جاری در حساب Google Cloud خود، باید پس از اتمام کار، منابع مستقر شده خود را خاموش و پاکسازی کنید.
👉 ضد جاذبه سریع:
Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.
وقتی Antigravity این اعلان را اجرا میکند، کل فرآیند پاکسازی منابع را خودکار میکند:
- حذف عامل مستقر : این دستور
deployment_metadata.jsonرا میخواند تا شناسه زمان اجرای عامل از راه دور شما را بدست آورد، سپس به صورت برنامهنویسیشده نمونه موتور زنده را از Vertex AI حذف میکند. - پاکسازی فضای کاری محلی : فایل قدیمی
deployment_metadata.jsonرا از ریشه پروژه شما حذف میکند. - پاکسازی رجیستری مصنوعات : این دستور
gcloud artifacts docker images deleteاجرا میکند تا تصاویر کانتینر ساخته شده را از رجیستری مصنوعات حذف کند و فضای ذخیرهسازی ابری را آزاد کند.
۱۲. تبریک
تبریک! شما با موفقیت یک Ambient Expense Agent در سطح تولید را در Google Cloud مستقر و تأیید کردید.
آنچه آموختید
- راهاندازی Google Cloud : اعتبارنامههای پروژه پیکربندی شده و APIهای پلتفرم مورد نیاز فعال شدهاند.
- ابزارها و مهارتها : نصب
agents-cliو بارگذاری مهارتهای همراه ADK در Antigravity. - داربست تولید : داربست تولید شده در زمان اجرای عامل برای یک عامل ADK 2.0.
- تأیید محلی : فایلهای قفل قطعی (
uv lock) ایجاد شده و بررسیهای اولیه اجرا شدهاند. - استقرار ابری : عامل شما را به صورت زنده در زیرساخت مدیریتشده Agent Runtime میزبانی کرد.
- قابلیت مشاهده و تجزیه و تحلیل : اجرای ردیابی شده در Cloud Trace و تلهمتری تجزیه و تحلیل شده در BigQuery.
- کشف سازمانی : ثبت خودکار تأیید شده در رجیستری نمایندگان سازمانی.
قدم بعدی چیست؟
- انجام تجزیه و تحلیل BigQuery : گزارشهای تلهمتری اپراتور خود را در BigQuery جستجو کنید تا نسبتهای تأیید و روندهای نوبت مکالمه را در طول زمان تجزیه و تحلیل کنید.
- Vibe to Live Codelab : از Google Antigravity برای توسعه یک کلاینت frontend در Cloud Run استفاده کنید و آن را مستقیماً به نقطه پایانی backend زنده Agent Runtime خود متصل کنید.
نشان 5 روزه Kaggle AI Agents خود را کسب کنید 🎉
این آزمایشگاه را به عنوان بخشی از دوره ۵ روزه هوش مصنوعی Kaggle: Intensive Vibe Coding Course with Google تکمیل کردید؟ نشان تکمیل دوره خود را دریافت کنید:
نشان 5 روزه نمایندگان هوش مصنوعی را دریافت کنید