۱. مقدمه
در این آزمایشگاه، با توصیف کردن یکپارچهسازی Application Integration برای عامل هوش مصنوعی، آن را میسازید. سه مهارت عامل Application Integration عمومی را از مخزن google/skills نصب میکنید، سپس از Gemini CLI میخواهید که یک ادغام نمونه کوچک را بنویسد، بارگذاری کند، منتشر کند، و اجرا کند.
نمونه sample-claims-adjudication یک مطالبه بیمه را میگیرد و APPROVE، REVIEW، یا DENY را برمیگرداند.
آنچه انجام خواهید داد
- «یکپارچهسازی برنامه» را در پروژه Google Cloud راهاندازی کنید.
- مهارتهای عامل «ادغام برنامه» را نصب کنید.
- به Gemini CLI پیامواره دهید تا یکپارچهسازی را بسازد، بارگذاری کند، منتشر کند، و اجرا کند.
- خودتان اجرا را بررسی کنید و از عامل بخواهید آن را عیبیابی کند.
- ادغام نمونه را پاکسازی کنید.
آنچه خواهید آموخت
- مهارتهای
application-integration-basics،-authoring، و-troubleshootingچه چیزی به عامل میدهند. - نحوه بازبینی JSON نسخه ادغام و فرمانهایی که نماینده قبلاز تأیید شما اجرا میکند.
- نحوه خواندن سابقه اجرا.
۲. راهاندازی پروژه
- اگر ازقبل «حساب Google» ندارید، باید «حساب Google» ایجاد کنید.
- بهجای حساب کاری یا تحصیلی، از حساب شخصی استفاده کنید. حسابهای کاری و تحصیلی ممکن است محدودیتهایی داشته باشند که مانع از فعال کردن میاناهای برنامهسازی کاربردی موردنیاز برای این آزمایشگاه شود.
- به سیستم کنسول Google Cloud وارد شوید.
- صدور صورتحساب را در «کنسول Cloud» فعال کنید.
- تکمیل این آزمایشگاه باید کمتر از ۱ دلار امریکا در منابع Cloud هزینه داشته باشد.
- برای جلوگیری از کسر هزینههای بیشتر، میتوانید مراحل انتهای این آزمایشگاه را برای حذف منابع دنبال کنید.
- کاربران جدید واجدشرایط دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
- پروژه جدیدی ایجاد کنید یا انتخاب کنید که از پروژه موجودی دوباره استفاده کنید.
- اگر خطایی درباره سهمیه پروژه مشاهده کردید، از پروژه موجودی دوباره استفاده کنید یا پروژه موجودی را حذف کنید تا پروژه جدیدی ایجاد شود.
از پروژه جدید یا پروژه موجودی که بتوانید بهطور ایمن در آن آزمایش کنید استفاده کنید، نه از پروژه تولید. عامل با اعتبارنامههای شما، ادغامها را در آن بارگذاری، منتشر، و اجرا میکند.
۳. باز کردن Cloud Shell Editor
- برای رفتن مستقیم به ویرایشگر Cloud Shell، روی این پیوند کلیک کنید
- اگر امروز در هر نقطهای از شما خواسته شد که مجوز دهید، روی مجوز دادن کلیک کنید تا ادامه دهید.

- اگر پایانه در پایین صفحه نشان داده نمیشود، آن را باز کنید:
- روی مشاهده کلیک کنید
- روی پایانه کلیک کنید

- در پایانه، پروژه خود را با این فرمان تنظیم کنید:
- قالب:
gcloud config set project [PROJECT_ID] - مثال:
gcloud config set project lab-project-id-example - اگر شناسه پروژهتان را بهخاطر نمیآورید:
- میتوانید همه شناسههای پروژهتان را با این دستور فهرست کنید:
gcloud projects list | awk '/PROJECT_ID/{print $2}'

- میتوانید همه شناسههای پروژهتان را با این دستور فهرست کنید:
- قالب:
- باید این پیام را ببینید:
اگرUpdated property [core/project].
WARNINGرا میبینید و از شما خواسته میشودDo you want to continue (Y/n)?، احتمالاً شناسه پروژه را اشتباه وارد کردهاید.nرا فشار دهید،Enterرا فشار دهید، و فرمانgcloud config set projectرا دوباره اجرا کنید.
۴. راهاندازی «یکپارچهسازی برنامه»
«ادغام برنامه» منطقهای است، بنابراین آن را در یک منطقه راهاندازی میکنید. این آزمایش از us-central1 استفاده میکند.
- شناسه پروژهتان را یادداشت کنید؛ بعداً آن را در پیامواره جایگذاری میکنید:
gcloud config get-value project - Application Integration API را فعال کنید:
gcloud services enable integrations.googleapis.com - به صفحه ادغام برنامه در کنسول Google Cloud بروید و پروژه خود را انتخاب کنید.
- در صفحه نمای کلی، منطقه
us-central1را انتخاب کنید و روی راهاندازی سریع کلیک کنید. وقتی راهاندازی تمام شد، کنسول فهرست ادغامها را نشان میدهد. اگر از پروژهای دوباره استفاده میکنید، قبلاز کلیک کردن روی راهاندازی سریع، بررسی کنید که نقشهای فهرستشده در راهاندازی «ادغام برنامه» را داشته باشید.
برای کسب اطلاعات بیشتر، راهاندازی «ادغام برنامه» را ببینید.
۵. نصب کردن مهارتهای عامل
مهارتها به عامل دانش «ادغام برنامه» میدهند:
application-integration-basics: مفاهیم، فعال کردن میاناهای برنامهسازی کاربردی، تدارک منطقه، نقشهای IAM، و محدودیتها.application-integration-authoring: نوشتن نسخههای ادغام بهعنوان JSON، و بارگذاری، انتشار، و اجرای آنها.application-integration-troubleshooting: تشخیص اجراهای ناموفق، گیرکرده، یا بیصدا.
- دایرکتوریای برای این آزمایشگاه ایجاد کنید و به آن بروید:
mkdir ~/appint-agent-lab && cd ~/appint-agent-lab - این سه مهارت را نصب کنید:
برای هر مهارت، نصاب چند سؤال میپرسد. Gemini CLI در گزینه پیشفرض Universal (.agents/skills) گنجانده شده است، بنابراینnpx skills add google/skills --skill application-integration-basics npx skills add google/skills --skill application-integration-authoring npx skills add google/skills --skill application-integration-troubleshootingEnterرا فشار دهید تا آن را نگه دارید، Project را بهعنوان محدوده نصب انتخاب کنید، و نصب را تأیید کنید.
مهارتها اکنون در ~/appint-agent-lab/.agents/skills هستند.
۶. راهاندازی Gemini CLI
- Gemini CLI را از دایرکتوری آزمایشگاه شروع کنید:
وقتی Gemini CLI میپرسد که آیا به این پوشه اعتماد دارید، Trust folder (اعتماد به پوشه) را انتخاب کنید. Gemini CLI مهارتها را از پوشه پروژه فقط پساز اینکه به پوشه اعتماد کردید بار میکند و سپس بازراهاندازی میشود. اگر بازراهاندازی نشد، پایانه جدیدی باز کنید، بهgemini~/appint-agent-labبروید، وgeminiرا دوباره اجرا کنید. ممکن است لازم باشد برای پذیرفتن برخی تنظیمات پیشفرض،Enterرا فشار دهید. - مهارتهایی را که Gemini CLI میتواند استفاده کند فهرست کنید:
باید سه مهارت/skillsapplication-integration-*را در فهرست ببینید.
۷. ساختن، منتشر کردن، و اجرای ادغام
- این پیامواره را در Gemini CLI جایگذاری کنید.
PROJECT_IDرا با شناسه پروژهای که در راهاندازی ادغام برنامه یادداشت کردید جایگزین کنید.Using the Application Integration skills, build an integration named sample-claims-adjudication in project PROJECT_ID, region us-central1. - Start it with an API trigger named adjudicate_claim. - Inputs: claimId (string), claimAmount (double), policyActive (boolean). - Outputs: decision (string) and reason (string). - Rules: if policyActive is false, return DENY. If claimAmount is 1000 or less, return APPROVE. Otherwise, return REVIEW. Set reason to a short explanation. - Save the integration version JSON in this directory so I can review it. - Show me every command before you run it, then upload, publish, and run it once with a sample claim. - وقتی نماینده برای اولینبار از مهارتی استفاده میکند، Gemini CLI از شما میخواهد آن را فعال کنید. مجاز باشد.
- نماینده فایل نسخه ادغام را مینویسد، مثلاً
sample-claims-adjudication.json. این کد حاوی راهانداز (triggerConfigs)، تکالیف (taskConfigs)، و متغیرها (integrationParameters) است. آن را بخوانید و از عامل بخواهید هر چیزی را که انتظار ندارید توضیح دهد. برای مثال، بررسی کنید که آیا عامل Cloud Logging (cloudLoggingDetails.enableCloudLogging) را روشن کرده است یا نه، که میتواند هزینه اضافه کند. برای خاموش کردن آن،enableCloudLoggingرا رویfalseتنظیم کنید وcloudLoggingSeverityرا بردارید. - فرمانها را تأیید کنید. Gemini CLI قبلاز اجرای هر فرمان، ازجمله فرمانهای فقط خواندنی، از شما اجازه میگیرد. این مهارتها همچنین به نماینده میگویند که قبلاز تغییر هر چیزی، مانند بارگذاری، انتشار، یا اجرای ادغام، فرمان یا درخواست دقیق را به شما نشان دهد. اگر نماینده بدون نشان دادن فرمان درخواست تأیید کرد، از آن بخواهید فرمان را نشان دهد. قبلاز تأیید، پروژه، منطقه، و نام ادغام را بررسی کنید و فرمانهایی را که ادغامهای متعلق به شما را میخوانند یا تغییر میدهند رد کنید.
پساز تأیید شما، عامل فایل JSON را بهعنوان نسخه جدید (versions.upload) بارگذاری میکند، آن را منتشر میکند (versions.publish)، و آن را ازطریق راهانداز API اجرا میکند (integrations.execute). سپس تصمیم، دلیل، و شناسه اجرا را به شما نشان میدهد.
۸. درستیسنجی اجرا
خودتان ادغام منتشرشده را اجرا کنید و سابقه اجرای آن را بخوانید.
- برگه پایانه Cloud Shell جدیدی باز کنید، به دایرکتوری آزمایشگاه بروید، و شناسه پروژه و منطقه را در متغیرها ذخیره کنید:
cd ~/appint-agent-lab export PROJECT_ID=$(gcloud config get-value project) export LOCATION=us-central1 - ادغام را با ادعای بیشاز ۱۰۰۰ اجرا کنید:
پاسخ حاویcurl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "triggerId": "api_trigger/adjudicate_claim", "inputParameters": { "claimId": {"stringValue": "CLM-1001"}, "claimAmount": {"doubleValue": 2500}, "policyActive": {"booleanValue": true} } }' \ "https://integrations.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/integrations/sample-claims-adjudication:execute"executionIdوoutputParametersباdecisionتنظیمشده رویREVIEWاست. - سوابق اجرا را بخوانید.
EXECUTION_IDرا باexecutionIdاز پاسخ جایگزین کنید: در پاسخ،curl -G \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ --data-urlencode 'filter=execution_id="EXECUTION_ID"' \ "https://integrations.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/integrations/sample-claims-adjudication/executions"executionDetails.stateبرابر باSUCCEEDEDاست وexecutionDetails.executionSnapshotsوضعیت هر تکلیف را نشان میدهد.
همچنین میتوانید اجرا را در گزارشهای اجرا در کنسول Google Cloud ببینید.
۹. عیبیابی
پاسخ موفقیتآمیز همیشه به این معنی نیست که هر تکلیف همان کاری را انجام داده است که انتظار داشتید. از عامل بخواهید اجرا را بررسی کند. در Gemini CLI، این پیامواره را وارد کنید و EXECUTION_ID را جایگزین کنید:
Check execution EXECUTION_ID of sample-claims-adjudication. Did every task
succeed? If anything failed, tell me why and propose a fix.
عامل سابقه اجرا را با executions.list میخواند، براساس شناسه اجرا فیلتر میکند، و وضعیت اجرا و هر تکلیف را خلاصه میکند.
اگر مشکلی در این آزمایشگاه پیش آمد، این دلایل رایج را بررسی کنید:
/skillsمهارتهای «ادغام برنامه» را فهرست نمیکند. Gemini CLI را از~/appint-agent-labشروع کنید و پوشه را مورداعتماد قرار دهید.- تماس با
PERMISSION_DENIEDبرقرار نمیشود. بررسی کنید که از پروژه درست استفاده میکنید و نقش «ویرایشگر ادغام برنامه» (roles/integrations.integrationEditor) را در آن دارید. - اجرای ادغام با
No integrations found for the requested trigger_idناموفق بود. بررسی کنید که پروژه و منطقه در درخواست با جایی که ادغام منتشر شده است مطابقت داشته باشد،triggerIdapi_trigger/adjudicate_claimباشد، و نسخهای از ادغام منتشر شده باشد. اگر نسخهای را بارگذاری کرده باشید اما آن را منتشر نکرده باشید، همین خطا را دریافت میکنید.
۱۰. مرتبسازی
- در Gemini CLI، از عامل بخواهید ادغام نمونه را بردارد:
پساز تأیید شما، نماینده انتشار نسخه منتشرشده (Unpublish sample-claims-adjudication, then delete every version of it.versions.unpublish) را لغو میکند و هر نسخه (versions.delete) را حذف میکند. وقتی هیچ نسخهای باقی نماند، ادغام دیگر در فهرست ادغامهای شما نشان داده نمیشود.اگر پروژهای را فقط برای این آزمایشگاه ایجاد کردهاید، میتوانید بهجای برداشتن ادغام، پروژه را حذف کنید. این فرمان را در برگه پایانه که در درستیسنجی اجرا باز کردید اجرا کنید:gcloud projects delete $(gcloud config get-value project) /quitرا تایپ کنید وEnterرا فشار دهید تا از Gemini CLI خارج شوید.- حذف فهرست راهنمای آزمایشگاه:
cd ~ && rm -rf ~/appint-agent-lab
۱۱. تبریک میگوییم
شما با درخواست کردن از عامل هوش مصنوعی با مهارتهای عامل Application Integration، یکپارچهسازی را ساختید، منتشر کردید، اجرا کردید، و بررسی کردید.
قدم بعدی چیست
- ساختن ادغام با عامل هوشوارهای
- مهارتهای عامل «ادغام برنامه»
- مهارتها را در GitHub بخوانید: مبانی، نوشتن، و عیبیابی.