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. إعداد المشروع
- إذا لم يكن لديك حساب على Google، عليك إنشاء حساب Google.
- استخدام حساب شخصي بدلاً من حساب عمل أو حساب تديره مؤسسة تعليمية قد تكون هناك قيود على حسابات العمل والمؤسسات التعليمية تمنعك من تفعيل واجهات برمجة التطبيقات اللازمة لهذا التمرين العملي.
- سجِّل الدخول إلى Google Cloud Console.
- فعِّل الفوترة في Cloud Console.
- من المفترض أن تبلغ تكلفة إكمال هذا التمرين أقل من دولار أمريكي واحد من موارد Cloud.
- يمكنك اتّباع الخطوات الواردة في نهاية هذا التمرين لحذف الموارد وتجنُّب تحصيل المزيد من الرسوم.
- يمكن للمستخدمين الجدد الاستفادة من فترة تجريبية مجانية بقيمة 300 دولار أمريكي.
- أنشِئ مشروعًا جديدًا أو اختَر إعادة استخدام مشروع حالي.
- إذا ظهر لك خطأ بشأن حصة المشروع، أعِد استخدام مشروع حالي أو احذِف مشروعًا حاليًا لإنشاء مشروع جديد.
استخدِم مشروعًا جديدًا أو مشروعًا حاليًا يمكنك تجربته بأمان، وليس مشروعًا إنتاجيًا. ويحمّل الوكيل عمليات الدمج وينشرها ويشغّلها فيه باستخدام بيانات الاعتماد الخاصة بك.
3- فتح Cloud Shell Editor
- انقر على هذا الرابط للانتقال مباشرةً إلى محرِّر Cloud Shell
- إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على منح الإذن للمتابعة.

- إذا لم تظهر الوحدة الطرفية في أسفل الشاشة، افتحها:
- انقر على عرض.
- انقر على Terminal

- في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:
- التنسيق:
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مرة أخرى.
4. إعداد Application Integration
تكون خدمة Application Integration إقليمية، لذا يمكنك إعدادها في منطقة واحدة. يستخدم هذا التمرين المعملي us-central1.
- دوِّن رقم تعريف مشروعك، لأنّك ستلصقه في طلب لاحقًا:
gcloud config get-value project - فعِّل واجهة برمجة التطبيقات Application Integration API:
gcloud services enable integrations.googleapis.com - انتقِل إلى صفحة Application Integration في وحدة تحكّم Google Cloud واختَر مشروعك.
- في صفحة نظرة عامة، اختَر منطقة
us-central1وانقر على الإعداد السريع. عند انتهاء عملية الإعداد، ستعرض وحدة التحكّم قائمة عمليات الدمج. إذا أعدت استخدام مشروع، تأكَّد من أنّ لديك الأدوار المدرَجة في إعداد Application Integration قبل النقر على الإعداد السريع.
لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد Application Integration.
5- تثبيت مهارات الوكيل
تمنح المهارات الوكيل معرفة بـ Application Integration:
application-integration-basics: المفاهيم، وتفعيل واجهات برمجة التطبيقات، وتوفير منطقة، وأدوار إدارة الهوية وإمكانية الوصول، والحدود.-
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.
6. بدء استخدام Gemini CLI
- ابدأ Gemini CLI من دليل التمرين:
عندما يسألك Gemini CLI عمّا إذا كنت تثق بهذا المجلد، اختَر الوثوق بالمجلد (Trust folder). لا يحمّل Gemini CLI المهارات من مجلد مشروع إلا بعد أن تضع علامة ثقة على المجلد، ثم يُعاد تشغيله. إذا لم تتم إعادة التشغيل، افتح نافذة وحدة طرفية جديدة وانتقِل إلىgemini~/appint-agent-labوشغِّلgeminiمرة أخرى. قد تحتاج إلى الضغط علىEnterلقبول بعض الإعدادات التلقائية. - عرض قائمة بالمهارات التي يمكن لـ Gemini CLI استخدامها:
من المفترض أن تظهر لك مهارات "/skillsapplication-integration-*" الثلاث في القائمة.
7. إنشاء عملية الدمج ونشرها وتشغيلها
- الصق هذا الطلب في 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. - عندما يستخدم الوكيل مهارة لأول مرة، سيطلب منك Gemini CLI تفعيلها. السماح بذلك
- يكتب الوكيل ملف إصدار الدمج، مثل
sample-claims-adjudication.json. يحتوي على المشغّل (triggerConfigs) والمهام (taskConfigs) والمتغيّرات (integrationParameters). يُرجى قراءته والطلب من الوكيل شرح أيّ شيء غير متوقّع. على سبيل المثال، تحقَّق مما إذا كان الوكيل قد فعّل Cloud Logging (cloudLoggingDetails.enableCloudLogging)، ما قد يؤدي إلى زيادة التكلفة. لإيقافها، اضبطenableCloudLoggingعلىfalseوأزِلcloudLoggingSeverity. - الموافقة على الأوامر يطلب Gemini CLI الإذن قبل تنفيذ كل أمر، بما في ذلك الأوامر المخصّصة للقراءة فقط. تطلب المهارات أيضًا من الوكيل أن يعرض لك الأمر أو الطلب الدقيق قبل تغيير أي شيء، مثل تحميل عملية الدمج أو نشرها أو تشغيلها. إذا طلب الوكيل الموافقة بدون عرض الأمر، اطلب منه عرض الأمر. تحقَّق من المشروع والمنطقة واسم عملية الدمج قبل الموافقة على الأوامر التي تقرأ أو تغيّر عمليات الدمج التي لا تملكها، وارفضها.
بعد موافقتك، يحمّل الوكيل ملف JSON كإصدار جديد (versions.upload)، وينشره (versions.publish)، ويشغّله من خلال مشغّل واجهة برمجة التطبيقات (integrations.execute)، ثم يعرض لك القرار والسبب ورقم تعريف التنفيذ.
8. التحقّق من التنفيذ
شغِّل عملية الدمج المنشورة بنفسك واقرأ سجلّ تنفيذها.
- افتح علامة تبويب جديدة في Cloud Shell، وانتقِل إلى دليل التمرين، واحفظ رقم تعريف مشروعك ومنطقتك في المتغيّرات:
cd ~/appint-agent-lab export PROJECT_ID=$(gcloud config get-value project) export LOCATION=us-central1 - نفِّذ عملية الدمج مع مطالبة تزيد عن 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. - اقرأ سجلّ التنفيذ. استبدِل
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.stateSUCCEEDED، ويعرض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. تَنظيم
- في 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
11. تهانينا
لقد أنشأت عملية تكامل ونشرتها وشغّلتها وتحقّقت منها من خلال توجيه طلب إلى وكيل ذكاء اصطناعي باستخدام مهارات وكيل Application Integration.
الخطوات التالية
- إنشاء عملية تكامل مع وكيل ذكاء اصطناعي
- مهارات وكيل Application Integration
- اطّلِع على المهارات على GitHub: الأساسيات والتأليف وتحديد المشاكل وحلّها.