إنشاء عملية تكامل مع وكيل ذكاء اصطناعي ومهارات وكيل Application Integration

1. مقدمة

في هذا التمرين المعملي، ستنشئ عملية تكامل Application Integration من خلال وصفها لوكيل الذكاء الاصطناعي. يمكنك تثبيت مهارات وكيل Application Integration الثلاث المتاحة للجميع من مستودع google/skills، ثم توجيه طلب إلى Gemini CLI لكتابة نموذج دمج صغير وتحميله ونشره وتشغيله.

يأخذ النموذج sample-claims-adjudication مطالبة تأمين ويعرض APPROVE أو REVIEW أو DENY.

الإجراءات التي ستنفذّها

  • إعداد Application Integration في مشروع على Google Cloud
  • ثبِّت مهارات وكيل Application Integration.
  • اطلب من Gemini CLI إنشاء عملية تكامل وتحميلها ونشرها وتشغيلها.
  • تحقَّق من التنفيذ بنفسك، واطلب من الوكيل تحديد المشاكل وحلّها.
  • احذف نموذج الدمج.

أهداف الدورة التعليمية

  • ما تمنحه مهارات application-integration-basics و-authoring و-troubleshooting للوكيل
  • كيفية مراجعة ملف JSON الخاص بإصدار عملية الدمج والأوامر التي ينفّذها الوكيل قبل الموافقة عليها
  • كيفية قراءة سجلّ التنفيذ

2. إعداد المشروع

  1. إذا لم يكن لديك حساب على Google، عليك إنشاء حساب Google.
    • استخدام حساب شخصي بدلاً من حساب عمل أو حساب تديره مؤسسة تعليمية قد تكون هناك قيود على حسابات العمل والمؤسسات التعليمية تمنعك من تفعيل واجهات برمجة التطبيقات اللازمة لهذا التمرين العملي.
  2. سجِّل الدخول إلى Google Cloud Console.
  3. فعِّل الفوترة في Cloud Console.
    • من المفترض أن تبلغ تكلفة إكمال هذا التمرين أقل من دولار أمريكي واحد من موارد Cloud.
    • يمكنك اتّباع الخطوات الواردة في نهاية هذا التمرين لحذف الموارد وتجنُّب تحصيل المزيد من الرسوم.
    • يمكن للمستخدمين الجدد الاستفادة من فترة تجريبية مجانية بقيمة 300 دولار أمريكي.
  4. أنشِئ مشروعًا جديدًا أو اختَر إعادة استخدام مشروع حالي.
    • إذا ظهر لك خطأ بشأن حصة المشروع، أعِد استخدام مشروع حالي أو احذِف مشروعًا حاليًا لإنشاء مشروع جديد.

استخدِم مشروعًا جديدًا أو مشروعًا حاليًا يمكنك تجربته بأمان، وليس مشروعًا إنتاجيًا. ويحمّل الوكيل عمليات الدمج وينشرها ويشغّلها فيه باستخدام بيانات الاعتماد الخاصة بك.

3- فتح Cloud Shell Editor

  1. انقر على هذا الرابط للانتقال مباشرةً إلى محرِّر Cloud Shell
  2. إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على منح الإذن للمتابعة. انقر لتفويض Cloud Shell
  3. إذا لم تظهر الوحدة الطرفية في أسفل الشاشة، افتحها:
    • انقر على عرض.
    • انقر على Terminalفتح وحدة طرفية جديدة في "محرِّر 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"
  5. من المفترض أن تظهر لك هذه الرسالة:
    Updated property [core/project].
    
    إذا ظهر لك WARNING وطُلِب منك Do you want to continue (Y/n)?، من المحتمل أنّك أدخلت رقم تعريف المشروع بشكل غير صحيح. اضغط على n، ثم اضغط على Enter، وحاوِل تشغيل الأمر gcloud config set project مرة أخرى.

4. إعداد Application Integration

تكون خدمة Application Integration إقليمية، لذا يمكنك إعدادها في منطقة واحدة. يستخدم هذا التمرين المعملي us-central1.

  1. دوِّن رقم تعريف مشروعك، لأنّك ستلصقه في طلب لاحقًا:
    gcloud config get-value project
    
  2. فعِّل واجهة برمجة التطبيقات Application Integration API:
    gcloud services enable integrations.googleapis.com
    
  3. انتقِل إلى صفحة Application Integration في وحدة تحكّم Google Cloud واختَر مشروعك.
  4. في صفحة نظرة عامة، اختَر منطقة us-central1 وانقر على الإعداد السريع. عند انتهاء عملية الإعداد، ستعرض وحدة التحكّم قائمة عمليات الدمج. إذا أعدت استخدام مشروع، تأكَّد من أنّ لديك الأدوار المدرَجة في إعداد Application Integration قبل النقر على الإعداد السريع.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد Application Integration.

5- تثبيت مهارات الوكيل

تمنح المهارات الوكيل معرفة بـ Application Integration:

  • application-integration-basics: المفاهيم، وتفعيل واجهات برمجة التطبيقات، وتوفير منطقة، وأدوار إدارة الهوية وإمكانية الوصول، والحدود.
  • ‫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.

6. بدء استخدام Gemini CLI

  1. ابدأ Gemini CLI من دليل التمرين:
    gemini
    
    عندما يسألك Gemini CLI عمّا إذا كنت تثق بهذا المجلد، اختَر الوثوق بالمجلد (Trust folder). لا يحمّل Gemini CLI المهارات من مجلد مشروع إلا بعد أن تضع علامة ثقة على المجلد، ثم يُعاد تشغيله. إذا لم تتم إعادة التشغيل، افتح نافذة وحدة طرفية جديدة وانتقِل إلى ~/appint-agent-lab وشغِّل gemini مرة أخرى. قد تحتاج إلى الضغط على Enter لقبول بعض الإعدادات التلقائية.
  2. عرض قائمة بالمهارات التي يمكن لـ Gemini CLI استخدامها:
    /skills
    
    من المفترض أن تظهر لك مهارات "application-integration-*" الثلاث في القائمة.

7. إنشاء عملية الدمج ونشرها وتشغيلها

  1. الصق هذا الطلب في Gemini CLI. استبدِل PROJECT_ID برقم تعريف المشروع الذي دوّنته في إعداد Application Integration.
    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)، ويشغّله من خلال مشغّل واجهة برمجة التطبيقات (integrations.execute)، ثم يعرض لك القرار والسبب ورقم تعريف التنفيذ.

8. التحقّق من التنفيذ

شغِّل عملية الدمج المنشورة بنفسك واقرأ سجلّ تنفيذها.

  1. افتح علامة تبويب جديدة في Cloud Shell، وانتقِل إلى دليل التمرين، واحفظ رقم تعريف مشروعك ومنطقتك في المتغيّرات:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. نفِّذ عملية الدمج مع مطالبة تزيد عن 1000:
    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.

9. تحديد المشاكل وحلّها

لا يعني الردّ الناجح دائمًا أنّ كل مهمة تم تنفيذها على النحو المتوقّع. اطلب من الوكيل التحقّق من التنفيذ. في 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 لا يدرج مهارات Application Integration. ابدأ Gemini CLI من ~/appint-agent-lab وامنح الثقة للمجلد.
  • تعذُّر إجراء مكالمة باستخدام PERMISSION_DENIED. تأكَّد من استخدام المشروع الصحيح ومن أنّ لديك دور "محرِّر Application Integration" (roles/integrations.integrationEditor) فيه.
  • يتعذّر تشغيل عملية الدمج بسبب الخطأ No integrations found for the requested trigger_id. يُرجى التحقّق من أنّ المشروع والمنطقة في الطلب يتطابقان مع مكان نشر عملية الدمج، وأنّ triggerId هو api_trigger/adjudicate_claim، وأنّه تم نشر نسخة من عملية الدمج. ويظهر لك الخطأ نفسه إذا حمّلت إصدارًا ولكن لم تنشره.

10. تَنظيم

  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
    

11. تهانينا

لقد أنشأت عملية تكامل ونشرتها وشغّلتها وتحقّقت منها من خلال توجيه طلب إلى وكيل ذكاء اصطناعي باستخدام مهارات وكيل Application Integration.

الخطوات التالية