ساختن یکپارچه‌سازی با عامل هوشواره‌ای و مهارت‌های عامل «یکپارچه‌سازی برنامه»

۱. مقدمه

در این آزمایشگاه، با توصیف کردن یکپارچه‌سازی Application Integration برای عامل هوش مصنوعی، آن را می‌سازید. سه مهارت عامل Application Integration عمومی را از مخزن google/skills نصب می‌کنید، سپس از Gemini CLI می‌خواهید که یک ادغام نمونه کوچک را بنویسد، بارگذاری کند، منتشر کند، و اجرا کند.

نمونه sample-claims-adjudication یک مطالبه بیمه را می‌گیرد و APPROVE، REVIEW، یا DENY را برمی‌گرداند.

آنچه انجام خواهید داد

  • «یکپارچه‌سازی برنامه» را در پروژه Google Cloud راه‌اندازی کنید.
  • مهارت‌های عامل «ادغام برنامه» را نصب کنید.
  • به Gemini CLI پیام‌واره دهید تا یکپارچه‌سازی را بسازد، بارگذاری کند، منتشر کند، و اجرا کند.
  • خودتان اجرا را بررسی کنید و از عامل بخواهید آن را عیب‌یابی کند.
  • ادغام نمونه را پاک‌سازی کنید.

آنچه خواهید آموخت

  • مهارت‌های application-integration-basics،‏ -authoring، و -troubleshooting چه چیزی به عامل می‌دهند.
  • نحوه بازبینی JSON نسخه ادغام و فرمان‌هایی که نماینده قبل‌از تأیید شما اجرا می‌کند.
  • نحوه خواندن سابقه اجرا.

۲. راه‌اندازی پروژه

  1. اگر ازقبل «حساب Google» ندارید، باید «حساب Google» ایجاد کنید.
    • به‌جای حساب کاری یا تحصیلی، از حساب شخصی استفاده کنید. حساب‌های کاری و تحصیلی ممکن است محدودیت‌هایی داشته باشند که مانع از فعال کردن میاناهای برنامه‌سازی کاربردی موردنیاز برای این آزمایشگاه شود.
  2. به سیستم کنسول Google Cloud وارد شوید.
  3. صدور صورت‌حساب را در «کنسول Cloud» فعال کنید.
    • تکمیل این آزمایشگاه باید کمتر از ۱ دلار امریکا در منابع Cloud هزینه داشته باشد.
    • برای جلوگیری از کسر هزینه‌های بیشتر، می‌توانید مراحل انتهای این آزمایشگاه را برای حذف منابع دنبال کنید.
    • کاربران جدید واجدشرایط دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
  4. پروژه جدیدی ایجاد کنید یا انتخاب کنید که از پروژه موجودی دوباره استفاده کنید.
    • اگر خطایی درباره سهمیه پروژه مشاهده کردید، از پروژه موجودی دوباره استفاده کنید یا پروژه موجودی را حذف کنید تا پروژه جدیدی ایجاد شود.

از پروژه جدید یا پروژه موجودی که بتوانید به‌طور ایمن در آن آزمایش کنید استفاده کنید، نه از پروژه تولید. عامل با اعتبارنامه‌های شما، ادغام‌ها را در آن بارگذاری، منتشر، و اجرا می‌کند.

۳. باز کردن Cloud Shell Editor

  1. برای رفتن مستقیم به ویرایشگر Cloud Shell، روی این پیوند کلیک کنید
  2. اگر امروز در هر نقطه‌ای از شما خواسته شد که مجوز دهید، روی مجوز دادن کلیک کنید تا ادامه دهید. برای صدور مجوز Cloud Shell کلیک کنید
  3. اگر پایانه در پایین صفحه نشان داده نمی‌شود، آن را باز کنید:
    • روی مشاهده کلیک کنید
    • روی پایانه کلیک کنیدباز کردن پایانه جدید در «ویرایشگر Cloud Shell»
  4. در پایانه، پروژه خود را با این فرمان تنظیم کنید:
    • قالب:
      gcloud config set project [PROJECT_ID]
      
    • مثال:
      gcloud config set project lab-project-id-example
      
    • اگر شناسه پروژه‌تان را به‌خاطر نمی‌آورید:
      • می‌توانید همه شناسه‌های پروژه‌تان را با این دستور فهرست کنید:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      تنظیم شناسه پروژه در پایانه Cloud Shell Editor
  5. باید این پیام را ببینید:
    Updated property [core/project].
    
    اگر WARNING را می‌بینید و از شما خواسته می‌شود Do you want to continue (Y/n)?، احتمالاً شناسه پروژه را اشتباه وارد کرده‌اید. n را فشار دهید، Enter را فشار دهید، و فرمان gcloud config set project را دوباره اجرا کنید.

۴. راه‌اندازی «یکپارچه‌سازی برنامه»

«ادغام برنامه» منطقه‌ای است، بنابراین آن را در یک منطقه راه‌اندازی می‌کنید. این آزمایش از us-central1 استفاده می‌کند.

  1. شناسه پروژه‌تان را یادداشت کنید؛ بعداً آن را در پیام‌واره جای‌گذاری می‌کنید:
    gcloud config get-value project
    
  2. Application Integration API را فعال کنید:
    gcloud services enable integrations.googleapis.com
    
  3. به صفحه ادغام برنامه در کنسول Google Cloud بروید و پروژه خود را انتخاب کنید.
  4. در صفحه نمای کلی، منطقه us-central1 را انتخاب کنید و روی راه‌اندازی سریع کلیک کنید. وقتی راه‌اندازی تمام شد، کنسول فهرست ادغام‌ها را نشان می‌دهد. اگر از پروژه‌ای دوباره استفاده می‌کنید، قبل‌از کلیک کردن روی راه‌اندازی سریع، بررسی کنید که نقش‌های فهرست‌شده در راه‌اندازی «ادغام برنامه» را داشته باشید.

برای کسب اطلاعات بیشتر، راه‌اندازی «ادغام برنامه» را ببینید.

۵. نصب کردن مهارت‌های عامل

مهارت‌ها به عامل دانش «ادغام برنامه» می‌دهند:

  • application-integration-basics: مفاهیم، فعال کردن میاناهای برنامه‌سازی کاربردی، تدارک منطقه، نقش‌های IAM، و محدودیت‌ها.
  • application-integration-authoring: نوشتن نسخه‌های ادغام به‌عنوان JSON، و بارگذاری، انتشار، و اجرای آن‌ها.
  • application-integration-troubleshooting: تشخیص اجراهای ناموفق، گیرکرده، یا بی‌صدا.
  1. دایرکتوری‌ای برای این آزمایشگاه ایجاد کنید و به آن بروید:
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. این سه مهارت را نصب کنید:
    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-troubleshooting
    
    برای هر مهارت، نصاب چند سؤال می‌پرسد. Gemini CLI در گزینه پیش‌فرض Universal (.agents/skills) گنجانده شده است، بنابراین Enter را فشار دهید تا آن را نگه دارید، Project را به‌عنوان محدوده نصب انتخاب کنید، و نصب را تأیید کنید.

مهارت‌ها اکنون در ~/appint-agent-lab/.agents/skills هستند.

‫۶. راه‌اندازی Gemini CLI

  1. ‫Gemini CLI را از دایرکتوری آزمایشگاه شروع کنید:
    gemini
    
    وقتی Gemini CLI می‌پرسد که آیا به این پوشه اعتماد دارید، Trust folder (اعتماد به پوشه) را انتخاب کنید. ‫Gemini CLI مهارت‌ها را از پوشه پروژه فقط پس‌از اینکه به پوشه اعتماد کردید بار می‌کند و سپس بازراه‌اندازی می‌شود. اگر بازراه‌اندازی نشد، پایانه جدیدی باز کنید، به ~/appint-agent-lab بروید، و gemini را دوباره اجرا کنید. ممکن است لازم باشد برای پذیرفتن برخی تنظیمات پیش‌فرض، Enter را فشار دهید.
  2. مهارت‌هایی را که Gemini CLI می‌تواند استفاده کند فهرست کنید:
    /skills
    
    باید سه مهارت application-integration-* را در فهرست ببینید.

‫۷. ساختن، منتشر کردن، و اجرای ادغام

  1. این پیام‌واره را در 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.
    
  2. وقتی نماینده برای اولین‌بار از مهارتی استفاده می‌کند، Gemini CLI از شما می‌خواهد آن را فعال کنید. مجاز باشد.
  3. نماینده فایل نسخه ادغام را می‌نویسد، مثلاً sample-claims-adjudication.json. این کد حاوی راه‌انداز (triggerConfigs)، تکالیف (taskConfigs)، و متغیرها (integrationParameters) است. آن را بخوانید و از عامل بخواهید هر چیزی را که انتظار ندارید توضیح دهد. برای مثال، بررسی کنید که آیا عامل Cloud Logging (cloudLoggingDetails.enableCloudLogging) را روشن کرده است یا نه، که می‌تواند هزینه اضافه کند. برای خاموش کردن آن، enableCloudLogging را روی false تنظیم کنید و cloudLoggingSeverity را بردارید.
  4. فرمان‌ها را تأیید کنید. ‫Gemini CLI قبل‌از اجرای هر فرمان، ازجمله فرمان‌های فقط خواندنی، از شما اجازه می‌گیرد. این مهارت‌ها همچنین به نماینده می‌گویند که قبل‌از تغییر هر چیزی، مانند بارگذاری، انتشار، یا اجرای ادغام، فرمان یا درخواست دقیق را به شما نشان دهد. اگر نماینده بدون نشان دادن فرمان درخواست تأیید کرد، از آن بخواهید فرمان را نشان دهد. قبل‌از تأیید، پروژه، منطقه، و نام ادغام را بررسی کنید و فرمان‌هایی را که ادغام‌های متعلق به شما را می‌خوانند یا تغییر می‌دهند رد کنید.

پس‌از تأیید شما، عامل فایل JSON را به‌عنوان نسخه جدید (versions.upload) بارگذاری می‌کند، آن را منتشر می‌کند (versions.publish)، و آن را ازطریق راه‌انداز API اجرا می‌کند (integrations.execute). سپس تصمیم، دلیل، و شناسه اجرا را به شما نشان می‌دهد.

‫۸. درستی‌سنجی اجرا

خودتان ادغام منتشرشده را اجرا کنید و سابقه اجرای آن را بخوانید.

  1. برگه پایانه Cloud Shell جدیدی باز کنید، به دایرکتوری آزمایشگاه بروید، و شناسه پروژه و منطقه را در متغیرها ذخیره کنید:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. ادغام را با ادعای بیش‌از ۱۰۰۰ اجرا کنید:
    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 است.
  3. سوابق اجرا را بخوانید. 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 ناموفق بود. بررسی کنید که پروژه و منطقه در درخواست با جایی که ادغام منتشر شده است مطابقت داشته باشد، triggerId api_trigger/adjudicate_claim باشد، و نسخه‌ای از ادغام منتشر شده باشد. اگر نسخه‌ای را بارگذاری کرده باشید اما آن را منتشر نکرده باشید، همین خطا را دریافت می‌کنید.

‫۱۰. مرتب‌سازی

  1. در Gemini CLI، از عامل بخواهید ادغام نمونه را بردارد:
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    پس‌از تأیید شما، نماینده انتشار نسخه منتشرشده (versions.unpublish) را لغو می‌کند و هر نسخه (versions.delete) را حذف می‌کند. وقتی هیچ نسخه‌ای باقی نماند، ادغام دیگر در فهرست ادغام‌های شما نشان داده نمی‌شود.اگر پروژه‌ای را فقط برای این آزمایشگاه ایجاد کرده‌اید، می‌توانید به‌جای برداشتن ادغام، پروژه را حذف کنید. این فرمان را در برگه پایانه که در درستی‌سنجی اجرا باز کردید اجرا کنید:
    gcloud projects delete $(gcloud config get-value project)
    
  2. /quit را تایپ کنید و Enter را فشار دهید تا از Gemini CLI خارج شوید.
  3. حذف فهرست راهنمای آزمایشگاه:
    cd ~ && rm -rf ~/appint-agent-lab
    

‫۱۱. تبریک می‌گوییم

شما با درخواست کردن از عامل هوش مصنوعی با مهارت‌های عامل Application Integration، یکپارچه‌سازی را ساختید، منتشر کردید، اجرا کردید، و بررسی کردید.

قدم بعدی چیست