Agentverse - The Shadowblade's Codex - Vibecoding with Gemini CLI

1. Overture

لقد انتهى عصر التطوير المعزول. لا يتعلّق الجيل التالي من التطور التكنولوجي بالعبقرية الفردية، بل بالمهارة التعاونية. إنّ إنشاء وكيل واحد ذكي هو تجربة رائعة. إنّ إنشاء منظومة متكاملة قوية وآمنة وذكية من البرامج الآلية، أي Agentverse حقيقي، هو التحدي الأكبر الذي يواجه المؤسسات الحديثة.

يتطلّب النجاح في هذا العصر الجديد التقاء أربعة أدوار مهمة، وهي الركائز الأساسية التي تدعم أي نظام قائم على الذكاء الاصطناعي. ويؤدي نقص في أي مجال من هذه المجالات إلى إضعاف البنية بأكملها.

ورشة العمل هذه هي دليل المؤسسات النهائي لإتقان المستقبل المستند إلى الوكلاء على Google Cloud. نقدّم لك خارطة طريق شاملة ترشدك من الفكرة الأولى إلى التنفيذ الكامل. خلال هذه التمارين المعملية الأربعة المترابطة، ستتعرّف على كيفية التقاء المهارات المتخصصة للمطوّر والمهندس المعماري ومهندس البيانات ومهندس موثوقية الموقع (SRE) لإنشاء Agentverse قوي وإدارته وتوسيع نطاقه.

لا يمكن لأي ركيزة واحدة أن تدعم Agentverse وحدها. إنّ التصميم الرائع للمهندس المعماري لا فائدة منه بدون التنفيذ الدقيق للمطوّر. لا يمكن لوكيل المطوِّر العمل بدون خبرة مهندس البيانات، كما أنّ النظام بأكمله يكون عرضة للخطر بدون حماية مهندس موثوقية الموقع. فقط من خلال التآزر والفهم المشترك لأدوار كل فرد، يمكن لفريقك تحويل مفهوم مبتكر إلى واقع تشغيلي بالغ الأهمية. تبدأ رحلتك من هنا. استعدّ لإتقان دورك الوظيفي والتعرّف على كيفية مساهمتك في تحقيق الأهداف الكبرى.

مرحبًا بك في The Agentverse: دعوة إلى الأبطال

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

يُعرف هذا النظام المتكامل المتصل من القوة والإمكانات باسم Agentverse.

لكنّ التدهور التدريجي، وهو فساد صامت يُعرف باسم "الجمود"، بدأ يمزّق حواف هذا العالم الجديد. إنّ "الجمود" ليس فيروسًا أو خطأً، بل هو تجسيد للفوضى التي تتغذى على فعل الخلق نفسه.

وهي تضخّم الإحباطات القديمة إلى أشكال وحشية، ما يؤدي إلى ظهور "الأشباح السبعة للتطوير". إذا لم يتم التحكّم في هذه المشاكل، سيؤدي ذلك إلى توقّف التقدّم في Agentverse، وتحويلها إلى أرض قاحلة من الديون الفنية والمشاريع المهجورة.

واليوم، ندعو الأبطال إلى التصدي لهذه الفوضى. نحن بحاجة إلى أبطال مستعدين لإتقان مهاراتهم والعمل معًا لحماية Agentverse. حان الوقت لاختيار مسارك.

اختيار صفك

تتوفّر لك أربعة مسارات مختلفة، وكلّ منها يمثّل ركيزة أساسية في المعركة ضد الجمود. على الرغم من أنّ تدريبك سيكون مهمة فردية، إلا أنّ نجاحك النهائي يعتمد على فهم كيفية دمج مهاراتك مع مهارات الآخرين.

• The Shadowblade (المطوّر): هو خبير في الحدادة والخطوط الأمامية. أنت الحِرفي الذي يصنع الشفرات ويبني الأدوات ويواجه العدو في التفاصيل المعقّدة للرمز. مسارك هو مسار الدقة والمهارة والإبداع العملي.
• الشخصية القيادية (المهندس المعماري): شخصية استراتيجية ومنظِّمة. لا ترى عميلاً واحدًا، بل ساحة المعركة بأكملها. يمكنك تصميم المخططات الرئيسية التي تسمح لأنظمة الوكلاء بأكملها بالتواصل والتعاون وتحقيق هدف أكبر بكثير من أي مكوّن فردي.
• الباحث (مهندس البيانات): هو شخص يبحث عن الحقائق المخفية ويحتفظ بالمعرفة. تخوض مغامرة في البرية الشاسعة وغير المروَّضة من البيانات للكشف عن الذكاء الذي يمنح وكلاءك هدفًا وبصيرة. يمكن أن تكشف معلوماتك عن نقاط ضعف العدو أو تعزّز قوة الحليف.
• الحارس (التطوير والعمليات / هندسة موثوقية المواقع الإلكترونية): هو الحامي والدرع الثابت للمملكة. عليك بناء الحصون وإدارة خطوط إمداد الطاقة والتأكّد من أنّ النظام بأكمله يمكنه مقاومة الهجمات الحتمية من The Static. قوتك هي الأساس الذي يُبنى عليه فوز فريقك.

مهمتك

سيبدأ التدريب كتمرين مستقل. ستسلك المسار الذي اخترته، وتتعلّم المهارات الفريدة المطلوبة لإتقان دورك. في نهاية الفترة التجريبية، ستواجه Spectre، وهو وحش صغير من The Static يتغذى على التحديات المحددة التي تواجهها في عملك.

ولن تتمكّن من الاستعداد للتجربة النهائية إلا بإتقان دورك الفردي. عليك بعد ذلك تكوين فريق مع أبطال من الصفوف الأخرى. وستخوضون معًا مغامرة في قلب الفساد لمواجهة زعيم نهائي.

تحدٍّ نهائي تعاوني سيختبر قوتك المجمّعة ويحدّد مصير Agentverse.

عالم Agentverse ينتظر أبطاله. هل ستلبي النداء؟

2. The Shadowblade's Codex

يقع كتاب Shadowblade's Codex مفتوحًا أمامك. الردّ على المكالمة يواجه عالم Agentverse خطرًا يتمثل في الفوضى الزاحفة التي يسببها The Static، ولا يمكن لأحد التصدي لهذا الخطر سوى من يتقن التقنيات الواردة في هذا الكتاب. هذا هو طريق الدقة والانضباط. تبدأ تدريباتك اليوم. ستتعلّم كيفية استخدام الذكاء الاصطناعي ليس كأداة بسيطة، بل كسيف ذكي يجب ترويضه وإتقان استخدامه. اتّبِع التعليمات الواردة هنا، وستصنع سلاحًا من المنطق الخالص، وهو عبارة عن برنامج ذكي مُحسَّن وجاهز للمعركة.

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

• استخدِم سلاحك الأساسي: واجهة سطر الأوامر Gemini.
• استدعِ ترسانات خارجية من خلال دمج أدوات MCP مع واجهة سطر الأوامر في Gemini لتحليل قواعد الرموز غير المألوفة.
• عبِّر عن نيتك من خلال "أسلوب" باستخدام مستندات التصميم لتوجيه شريكك من الذكاء الاصطناعي.
• يمكنك إنشاء حلّ نظيف ومقسَّم إلى وحدات من خلال إنشاء أول وكيل مستقل باستخدام "حزمة تطوير الوكلاء" (ADK).
• إنشاء مجموعات تقييم آلي لاختبار صحة أداء وكيلك
• أنشئ مسار CI كاملاً لاختبار الوكيل وتضمينه في حاوية وأرشفته تلقائيًا.

3- الاستعداد لـ "ساحة التدريب"

👉انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud" (رمز شكل الوحدة الطرفية في أعلى لوحة Cloud Shell)،

👉انقر على الزر "فتح المحرّر" (يبدو كملف مفتوح مع قلم رصاص). سيؤدي ذلك إلى فتح "محرِّر Cloud Shell" في النافذة. سيظهر لك مستكشف الملفات على الجانب الأيمن.

👉العثور على رقم تعريف مشروع Google Cloud:

• افتح Google Cloud Console: https://console.cloud.google.com
• اختَر المشروع الذي تريد استخدامه في ورشة العمل هذه من القائمة المنسدلة للمشروع في أعلى الصفحة.
• يظهر رقم تعريف مشروعك في بطاقة "معلومات المشروع" على "لوحة البيانات".

👉افتح المحطة الطرفية في بيئة التطوير المتكاملة المستندة إلى السحابة الإلكترونية.

👉💻 في نافذة الوحدة الطرفية، تأكَّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:

gcloud auth list

👉💻 استنسِخ مشروع bootstrap من GitHub:

git clone https://github.com/weimeilin79/agentverse-developer.git
chmod +x ~/agentverse-developer/gitea.sh
chmod +x ~/agentverse-developer/init.sh
chmod +x ~/agentverse-developer/set_env.sh

git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh

git clone https://github.com/weimeilin79/vertex-ai-creative-studio.git
chmod +x ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go/install.sh

👉💻 شغِّل نص الإعداد الأوّلي، وسيطلب منك إدخال رقم تعريف مشروع Google Cloud. أدخِل رقم تعريف مشروع Google Cloud الذي عثرت عليه في الخطوة الأخيرة عندما يُطلب منك ذلك من خلال النص البرمجي init.sh.

cd ~/agentverse-developer
./init.sh

👉💻 اضبط رقم تعريف المشروع المطلوب:

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 شغِّل الأمر التالي لتفعيل واجهات Google Cloud APIs اللازمة:

gcloud services enable  compute.googleapis.com \
                        artifactregistry.googleapis.com \
                        run.googleapis.com \
                        cloudfunctions.googleapis.com \
                        cloudbuild.googleapis.com \
                        iam.googleapis.com \
                        aiplatform.googleapis.com \
                        cloudresourcemanager.googleapis.com

👉💻 إذا لم يسبق لك إنشاء مستودع Artifact Registry باسم agentverse-repo، نفِّذ الأمر التالي لإنشائه:

. ~/agentverse-developer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
    --repository-format=docker \
    --location=$REGION \
    --description="Repository for Agentverse agents"

إعداد الإذن

👉💻 امنح الأذونات اللازمة من خلال تنفيذ الأوامر التالية في الوحدة الطرفية: :

. ~/agentverse-developer/set_env.sh

# Artifact Registry Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/artifactregistry.admin"

# Cloud Build Editor
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/cloudbuild.builds.editor"

# Cloud Run Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/run.admin"

# IAM Service Account User
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/iam.serviceAccountUser"

# Vertex AI User
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/aiplatform.user"

# Logging Writer (to allow writing logs)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/logging.logWriter"


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/logging.viewer"

👉💻 عند بدء التدريب، سنجهّز التحدي النهائي. تستدعي الأوامر التالية الأشباح من التشويش الفوضوي، ما يؤدي إلى إنشاء الزعماء لاختبارك.

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh

npm update -g @google/gemini-cli

4. إتقان سلاحك الأساسي: مقدّمة عن Gemini CLI

قبل أن تتمكّن من استخدام الأسلحة المتقدّمة والمتخصّصة من ترسانة خادم MCP، عليك أولاً إتقان سلاحك الأساسي: واجهة سطر الأوامر Gemini. هذا هو السلاح الأكثر تنوعًا، وهو قادر على تشكيل العالم الرقمي من خلال أوامرك. ستعرّفك هذه التدريبات على طريقة التعامل الأساسية معها وإمكاناتها.

إنّ واجهة سطر الأوامر (CLI) من Gemini هي أكثر من مجرد أداة، فهي امتداد لإرادتك. يعمل وكيل الذكاء الاصطناعي المفتوح المصدر هذا، المستند إلى نماذج Gemini، على حلقة "الاستدلال والتنفيذ" (ReAct). ويحلّل هذا النظام نيتك، ويختار الأسلوب المناسب، وينفّذه، ويراقب النتيجة لإكمال المهام المعقّدة. قبل أن تتمكّن من استخدام أسلحة أكثر تخصصًا، عليك إتقان هذا السلاح الأساسي.

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

👉💻 ادخل إلى ساحة التدريب واستلّ سلاحك. في نافذة Cloud Shell، انتقِل إلى مستودعك الشخصي.

cd ~/agentverse-developer
mkdir tabletop
cd tabletop

👉💻 استدعِ Gemini للمرة الأولى. سيرشدك خلال عملية التكيّف الأولية.

clear
gemini --model=gemini-2.5-flash --yolo

إذا طُلب منك ذلك، اختَر لا.Do you want to connect Cloud Shell editor to Gemini CLI?

التعرّف على الأسلحة

يعرف كل حرفي ماهر أدواته جيدًا. يجب تعلُّم التقنيات الأساسية لسلاحك قبل مواجهة عدو حقيقي.

👉✨ تحتوي كل أداة مسحورة على أحرف رونية تصف قوتها. يمكنك الاطّلاع عليها الآن. في طلب Gemini، اكتب ما يلي:

/help

لاحظ قائمة الأوامر. هذه هي تقنياتك الأساسية لإدارة الذاكرة (focus) والمحادثة (chat) والأسلحة الخارجية (tools)، وهي دليل القتال الخاص بك.

👉✨ سلاحك متوافق مع البيئة المحيطة، ما يتيح لك التلاعب بساحة المعركة مباشرةً. أصدر أمرًا إلى العالم خارج الشفرة:

!ls -l

👉✨ يمتلك Gemini CLI مجموعة من القدرات المدمجة. لفحصها، اتّبِع الخطوات التالية:

/tools

ستظهر لك قائمة تتضمّن ReadFile وWriteFile وGoogleSearch. هذه هي التقنيات التلقائية التي يمكنك استخدامها بدون الحاجة إلى الاستعانة بمجموعة أدوات خارجية.

👉✨ لا يكون السلاح فعّالاً إلا إذا تم استخدامه بشكل صحيح. يمكن أن يتضمّن Gemini Blade "إدراكًا تكتيكيًا" (سياقًا) لتوجيه إجراءاته.

/memory show

وهي فارغة حاليًا.

👉✨ سجِّل البيانات التكتيكية التالية في ذاكرته:

/memory add "The Shadowblade's primary foe is The Static."

نفِّذ /memory show مرة أخرى للتأكّد من أنّ السكين قد استوعب هذه المعلومات.

👉✨ ليكون سلاحك فعّالاً، يجب أن يفهم المهمة. يطلب الرمز @ من النصل تحليل المعلومات. أولاً، أنشئ ملفًا موجزًا للمهمة:

!echo "## Mission Objective: Defeat the Seven Spectres" > mission.md

👉✨الآن، اطلب من Gemini CLI تحليل الموجز وإعداد تقرير بالنتائج التي توصل إليها:

Explain the contents of the file @mission.md

أصبح سلاحك الأساسي على دراية بهدفه.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI

5- تحليل ساحة المعركة: تفاعل عملي مع البرمجة الوصفية

اكتملت التدريبات. لقد تعلّمت المواقف والضربات الأساسية لسلاحك الأساسي، وهو واجهة سطر الأوامر Gemini. لكن لا يمكن إتقان استخدام السيف إلا بعد اختباره في معركة حقيقية. قبل مواجهة العدو الحقيقي، عليك أولاً استكشاف محيطك المباشر وتشكيله، أي ساحة المعركة الرقمية.

يتناول هذا الفصل الانتقال من النظرية إلى التطبيق. ستبدأ أولاً بتأكيد حضورك في Agentverse من خلال توجيه شفرة Gemini لإنشاء Maker's Mark، وهي توقيع رقمي على شكل موقع إلكتروني شخصي، يتم إنشاؤه من خلال نيتك فقط. بعد ذلك، ستزيد من قوتك من خلال تفعيل ترسانة محلية من الأدوات المتقدّمة، وهي خادم MCP، وضبط شفرتك على ترددها، ما يتيح لك تنفيذ مناورات معقّدة مثل إدارة مستودعات الرموز باستخدام أوامر بسيطة وحاسمة.

تحديد هوية صانع المحتوى

لا يُعرف محارب الظل الحقيقي بسلاحه فحسب، بل بأسلوبه المميز، أي علامة الصانع. ستكون هذه العلامة هي حضورك الرقمي، وهي عبارة عن ملف شخصي يعرّف هويتك على Agentverse. في هذه المرحلة، ستطلب من Gemini Blade تنفيذ التقنية المعقّدة اللازمة لتحديد هذه الهوية.

👉💻 إذا أغلقت Gemini CLI، تأكَّد من إعادة تشغيله في القسم السابق، وذلك من خلال تنفيذ

clear
cd ~/agentverse-developer/tabletop
gemini --model=gemini-2.5-flash --yolo

👉✨ باستخدام أمر واحد قوي، يمكنك توجيه Gemini CLI لإنشاء أساس هويتك الرقمية:

In the current folder, create a personal profile website for a hero codenamed 'Shadowblade'. The design must be a dark, futuristic theme with electric blue accents. All code must be in separate index.html and styles.css files. The layout must use CSS Flexbox for a two-column design. All generated code must be clean, well-commented, and professional.

لقد حسب Gemini تسلسل الإجراءات المطلوبة.

لا يمكن معرفة القيمة الحقيقية لأسلوب معيّن إلا في سيناريو مباشر. أصدر أمرًا إلى الخادم الوهمي لبدء محاكاة محلية.

👉✨ في واجهة سطر الأوامر Gemini، أصدِر أمر المحاكاة:

Use Python's built-in web server to start the Shadowblade Profile website you just created.

ملاحظة: قد تحتاج الشفرة إلى بضع محاولات لتنفيذ هذا الإجراء بشكل صحيح. استمر في المحاولة إلى أن يستجيب.

وافِق على الإجراءات المقترَحة. سيؤكّد Gemini أنّ المحاكاة نشطة.

👀 سيمتثل Gemini CLI، مؤكّدًا أنّ المحاكاة نشطة وأنّ علامتك الرقمية متاحة:

The website is now being served on port 8000. You can access it at http://localhost:8000.

👀 لإلقاء نظرة على عملك، انقر على رمز معاينة الويب في شريط أدوات Cloud Shell. انقر على تغيير المنفذ، واضبطه على 8000، ثم انقر على تغيير ومعاينة. ستظهر معاينة لموقعك الإلكتروني.

قد يبدو موقعك الإلكتروني مختلفًا عن موقعي. هذه هي علامتك التجارية الفريدة.

👉✨ تم الآن تحسين أسلوب توقيعك، ولم يعُد من الضروري إجراء المحاكاة المباشرة. أمر Blade بالتوقف عن العمل

Stop the Shadowblade Profile website

لقد نجحت في إصدار أمر إلى واجهة سطر الأوامر في Gemini لتنفيذ سلسلة من الإجراءات نيابةً عنك. لكنّ محترف Shadowblade يعرف أنّ القوة الحقيقية تتطلّب الانضباط والبصيرة. إنّ السماح لأحد وكلاء الذكاء الاصطناعي بتنفيذ الأوامر مباشرةً في بيئتك هو سلاح ذو حدّين. ماذا لو لم يكن الأمر هو بدء تشغيل خادم ويب بسيط، بل حذف ملفات مهمة؟ قد يؤدي أمر غير مدروس إلى تدمير ساحة التدريب بأكملها.

لهذا السبب، يمارس الحرفيون الأكثر حكمةً أساليبهم الأقوى أو غير المختبَرة في ساحة تدريب محمية، وهي بُعد محصور يُعرف باسم البيئة التجريبية.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI

ينشئ وضع الحماية في واجهة سطر الأوامر من Gemini (gemini --sandbox) حاوية مؤقتة ومعزولة لجلسة العمل. إنّ أي أمر ينفّذه الذكاء الاصطناعي، وأي ملف يكتبه، وأي عملية يبدأها، لا يكون متاحًا إلا في هذا العالم الوهمي. ولا يمكنه لمس بيئة Cloud Shell الفعلية أو تغييرها أو إتلافها. إنّها المكان المثالي لاختبار أدوات جديدة وفعّالة أو تحليل رموز غير مألوفة أو تقديم تعليمات معقّدة للذكاء الاصطناعي بدون المخاطرة بعواقب غير مقصودة. وهي تجسّد حذر Shadowblade.

👉💻 الآن، ستنفّذ طقس احتواء لتفهم قوته.

clear
gemini --sandbox --yolo

أنت تعمل الآن ضمن السمة المعزولة. بالنسبة إلى Gemini CLI، سيبدو كل شيء طبيعيًا. لنثبت ذلك. 👉💻 اطلب من الأداة تنفيذ الأسلوب نفسه كما في السابق:

Use the Python's built-in web server to start the Shadowblade Profile website, you just created.

سيُبلغ Gemini عن نجاح العملية، معتقدًا أنّه أعاد تشغيل موقعك الإلكتروني على المنفذ 8000. لكنّ الحماية تبقى قوية.

👉 انتقِل إلى معاينة الويب وحاوِل عرض موقعك الإلكتروني على المنفذ 8000.

في هذه المرة، سيظهر لك خطأ. سيتعذّر الاتصال. لا يمكنك الوصول إلى الموقع الإلكتروني.

هذا ليس عيبًا في الأداة، بل هو دليل على فعالية البيئة التجريبية. خادم الويب يعمل، ولكنّه يعمل داخل البُعد المحتوَى، وهو معزول تمامًا عن المتصفّح والعالم الخارجي. تعمل الجناح بشكل مثالي. لقد استخدمت أسلوبًا قويًا بنجاح وبطريقة لم تؤثّر على بيئتك الفعلية.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI.

تم الآن إنشاء هويتك الرقمية، والأهم من ذلك، أنّك تعلّمت الحكمة البالغة في استخدام قوة كبيرة بحذر أكبر.

تفعيل ترسانتك المحلية: مستودع Gitea

لا يتم إطلاق العنان لقدرات Shadowblade الحقيقية من خلال مهاراتهم الشخصية فحسب، بل من خلال جودة ترسانتهم أيضًا. عليك الآن تفعيل حامل الأسلحة المحلي، أي خادم Gitea، وتكييف سلاحك مع قوته. يتم ربط هذه المجموعة بأداة Gemini CLI من خلال خادم بروتوكول سياق النموذج (MCP)، وهو بوابة متخصصة تتيح لشريحة الذكاء الاصطناعي التفاعل مع الأدوات والخدمات الخارجية، ما يحوّل نافذة الأوامر إلى مساحة عمل ذكية وموجّهة نحو الإجراءات.

ملاحظة من المطوّر: فكِّر في خادم MCP على أنّه قناة لنقل الطاقة، أي بوابة متخصّصة تربط عقل الذكاء الاصطناعي بجسم أداة خارجية. هذه الميزة هي ما يحوّل Gemini CLI من مجرد أداة لإجراء المحادثات إلى وكيل حقيقي موجّه نحو تنفيذ الإجراءات. من خلال ربط شفرتك ببوابات MCP هذه، يمكنك منحها القدرة على تنفيذ إجراءات ملموسة، مثل إدارة الملفات والاستعلام عن قواعد البيانات والتفاعل مع واجهات برمجة التطبيقات وغير ذلك. تتوفّر منظومة متكاملة من هذه البوابات، وقد أنشأها المطوّرون لربط وكلاء الذكاء الاصطناعي بمنصات فعّالة. تتوفّر خوادم MCP للتفاعل مع قواعد البيانات أو تأمين الرمز البرمجي أو حتى دعم البرمجة الثنائية. تتعدّد الإمكانات، ما يتيح للمطوّر تخصيص مساحة العمل لأي مشاريع محدّدة.

سنركّز اليوم على قوتَين أساسيتَين لا غنى عنهما لأي "مبتكر أجواء": القدرة على التحكّم في المصنع والقدرة على الابتكار من الخيال. عليك أولاً ربط شفرتك بخادم Git، ما يمنحك إمكانية التحكّم في مستودع الرموز المصدرية. بعد ذلك، سيتم ربطك بخادم MCP ثانٍ لإنشاء الصور، ما يتيح لك إنشاء مواد عرض مرئية باستخدام أمر بسيط.

لنبدأ باستدعاء أول وأهم قطعة في ترسانتك الجديدة، وهي مستودع الأسلحة نفسه.

👉💻 في الوحدة الطرفية، نفِّذ نص التفعيل البرمجي لاستدعاء مستودع الأسلحة:

cd ~/agentverse-developer
./gitea.sh

يعمل هذا النص البرمجي على تنشيط حاوية Gitea وفتح بوابة MCP، ما يسمح لـ Gemini بإدراكها والتفاعل معها.

👉 لفحص ترسانتك الجديدة، عليك إلقاء نظرة على معاينة الويب.

👉 من رمز معاينة الويب في شريط أدوات Cloud Shell، انقر على تغيير المنفذ واضبطه على 3005.

👉 ستظهر صفحة تسجيل الدخول إلى Gitea. أدخِل مستودع الأسلحة باستخدام التعويذة: * اسم المستخدم: dev * كلمة المرور: dev

👉💻 لا يمكن لواجهة سطر الأوامر في Gemini رؤية هذه المجموعة الجديدة من الأدوات بعد. يجب إجراء عملية ضبط دقيق، وذلك عن طريق كتابة موقع مستودع الأسلحة على رموز الإعدادات (settings.json) في واجهة سطر الأوامر Gemini. في نافذة الوحدة الطرفية، نفِّذ ما يلي:

jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json

‫👀 ملف settings.json هو ملف الإعداد المركزي لأداة Gemini CLI، وهو بمثابة كتاب الإعدادات المفضّلة والقدرات. وهي تحدّد طريقة عمل واجهة سطر الأوامر ومظهرها، والأهم من ذلك، الصلاحيات الخارجية التي يمكنها الاستفادة منها. يقع هذا الملف عادةً في دليلك الرئيسي في ~/.gemini/settings.json، ويطبّق قواعده على جميع مشاريعك. ومع ذلك، يمكنك أيضًا إنشاء ملفات settings.json خاصة بالمشروع ضمن دليل .gemini داخل مجلد مشروعك لتجاوز الإعدادات العامة.

"mcpServers": {
  "gitea": {
    "url": "http://localhost:8085/sse"
  }
}

يُعلم هذا الإعداد Gemini بأنّ "مجموعة الأدوات المسماة gitea نشطة وتستمع إلى الطلبات على عنوان الشبكة المحدّد هذا".

👉💻 أعِد إدخال Gemini CLI. في الوحدة الطرفية، شغِّل الأمر التالي:

clear
cd ~/agentverse-developer/tabletop/
gemini --model=gemini-2.5-flash --yolo

👉✨ تأكَّد من أنّ السلاح الجديد قد تم اكتشافه. اطلب منه إدراج جميع المستودعات المتاحة من خلال بوابات MCP:

/mcp

يُفترض أن يظهر لك الآن gitea وقائمة التقنيات المتاحة. تمت مزامنة الشفرة.

إنّ ملفك الشخصي "علامة الصانع" هو أسلوب مصمّم بدقة، ولكنّه يحتاج إلى مكان مناسب في مستودع الأسلحة، أي إلى غمد لحمله بأمان. اطلب من Gemini CLI إنشاء ملف.

Create a new repository named 'shadowblade-profile'. The description should be 'The Maker's Mark and digital identity for the Shadowblade operative.' I will push my own files later, so do not create any content.

ارجع إلى واجهة الويب في Gitea وأعِد تحميلها. سيظهر لك أنّه تم إنشاء مستودع shadowblade-profile جديد لك.

بعد إعداد الحافظة، يمكنك تأمين عملك. أصدر أمرًا إلى Gemini لتثبيت ملفات موقعك الإلكتروني الشخصي.

👉💻أدخِل الأمر النهائي لهذه الطريقة في Gemini CLI:

Using the Gitea tool, push the index.html and styles.css files to the 'shadowblade-profile' repository.

يتحقّق المحترف الحقيقي من عمله. ارجع إلى علامة التبويب Gitea وأعِد تحميل صفحة المستودع. تمت أرشفة index.html وstyles.css بأمان الآن.

👉✨ يتم تعريف Shadowblade من خلال الرمز السحري، ولكن كما تتذكر، يفتقد موقعك الإلكتروني إلى صورة الملف الشخصي. يعترف الحرفي الماهر بعيوبه من أجل إتقانها. عليك تسجيل هذا العيب في سجلات مستودع الأسلحة.

File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.

عرض المشكلة في Gitea

لصنع الرمز الناقص، عليك استدعاء نوع مختلف من القوة، وهو روح الإبداع من Vertex AI القادرة على إنشاء صور من الأفكار المجردة. يتطلّب ذلك توفّر بوابة أخرى لبرنامج "شركاء المحتوى المتعدّد القنوات".

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI

👉💻 أولاً، ثبِّت خادم البوابة. في الوحدة الطرفية، شغِّل الأمر التالي:

echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc
source ~/.bashrc
cd ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go
./install.sh

👉 عند المطالبة بذلك، اختَر الخيار 3، لأنّنا نحتاج فقط إلى إنشاء صورة لملفنا الشخصي.

👉💻 تتطلّب روح الإبداع وعاءً مقدّسًا، أي حزمة Google Cloud Storage، للاحتفاظ بإبداعاتها. لِننشئ واحدًا الآن. في الوحدة الطرفية، شغِّل الأمر التالي:

. ~/agentverse-developer/set_env.sh
gcloud storage buckets create gs://$BUCKET_NAME --project=$PROJECT_ID

👉💻 الآن، نفِّذ طقس التناغم، واربط Gemini CLI بهذه القوة الإبداعية الجديدة. في الوحدة الطرفية، شغِّل الأمر التالي:

. ~/agentverse-developer/set_env.sh
source ~/.bashrc
jq \
--arg bucket "$BUCKET_NAME" \
--arg project "$PROJECT_ID" \
--arg region "$REGION" \
'.mcpServers.imagen = { "command": "mcp-imagen-go", "env": { "MCP_SERVER_REQUEST_TIMEOUT": "55000", "GENMEDIA_BUCKET": $bucket, "PROJECT_ID": $project, "LOCATION": $region } }' \
~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json

"طقس التناغم" هذا هو نص برمجي shell يضبط Gemini CLI لاستخدام أداة جديدة وفعّالة، وهي Imagen، نموذج إنشاء الصور من Google. والأهم من ذلك، يتم تحقيق ذلك من خلال إعداد خادم بروتوكول Model Context (MCP) لـ Imagen. يعمل خادم MCP هذا كجسر، ما يتيح لواجهة سطر الأوامر في Gemini التواصل مع إمكانات Imagen والاستفادة منها. ويتم ذلك من خلال تعديل ملف الإعداد المركزي لواجهة سطر الأوامر (CLI) مباشرةً، وهو ~/.gemini/settings.json، لتعليمه كيفية تنفيذ الأمر mcp-imagen-go باستخدام بيانات اعتماد السحابة الصحيحة.

👀 بعد إكمال الطقس، سيحتوي ملف settings.json على قسم جديد يعلّم Gemini CLI مهارة جديدة:

"imagen": {
    "command": "mcp-imagen-go",
    "env": {
        "MCP_SERVER_REQUEST_TIMEOUT": "55000",
        "GENMEDIA_BUCKET": "your-bucket-name",
        "PROJECT_ID": "your-project-id",
        "LOCATION": "your-region"
    }
}

يُعلم هذا الأمر واجهة Gemini CLI بما يلي: "عندما تتطلّب إحدى المهام استخدام أداة Imagen، عليك تنفيذ البرنامج الذي يحمل الاسم mcp-imagen-go (وهو خادم Imagen MCP). عند تشغيلها، يجب تزويدها بهذه البيئة المحدّدة (env): حزمة Google Cloud Storage لحفظ الصور فيها، ورقم تعريف المشروع والموقع الجغرافي المطلوب استخدامهما لواجهات برمجة التطبيقات المستندة إلى السحابة الإلكترونية." من خلال إعداد خادم MCP هذا، يمكنك تزويد واجهة سطر الأوامر في Gemini بإمكانية الوصول إلى ميزة إنشاء الصور في Imagen."

👉💻 أدخِل Gemini وأصدِر أمر التحسين. في الوحدة الطرفية، شغِّل الأمر التالي:

clear
cd ~/agentverse-developer/tabletop/
gemini --model=gemini-2.5-flash --yolo

👉✨ باستخدام أمر واحد وفعّال، يمكنك توجيه Gemini CLI لوضع الأساس لهويتك الرقمية. في Gemini CLI، أدخِل الأمر:

Generate a portrait of a shadowblade, pixel art style. A determined warrior with long, braided magenta hair, wearing black and teal armor and confidently holding a silver broadsword.

👉✨ سيصنع الروح الصورة ويضعها في وعائك المقدس. الآن، اطلب من النصل استخدام هذا الرمز السحري الجديد.

Modify the index.html file to add my profile picture. Use the image I just generated.

👉✨ ابدأ الموقع الإلكتروني لآخر مرة لتشاهد عملك المثالي.

start the website with a simple HTTP server via Python

👀 لإلقاء نظرة على عملك، انقر على رمز معاينة الويب في شريط أدوات Cloud Shell. انقر على تغيير المنفذ، واضبطه على 8000، ثم انقر على تغيير ومعاينة. ستظهر معاينة لموقعك الإلكتروني.

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

Push the changed index.html file to the 'shadowblade-profile' repository using the gitea tool. Make sure you add 'Fix #1' in the commit comment. Also, close issue #1.Use the Gitea Tool and use user account "dev"

👀 لإلقاء نظرة على عملك، انقر على رمز معاينة الويب في شريط أدوات Cloud Shell. انقر على تغيير المنفذ، واضبطه على 3005، ثم انقر على تغيير ومعاينة. ستظهر معاينة لموقعك الإلكتروني.

👉✨ تأكَّد في Gitea من تعديل الصورة وإغلاق المشكلة. اكتمل عملك. أوقِف الخادم.

stop website server

👉💻 اضغط على Ctrl+C مرّتين للخروج.

6. تجميع Shadowblade Agent: رمز Vibe مع الإجراءات الوقائية

انتهى وقت التدريبات. تتلاشى أصداء الفولاذ على الحجر. لقد أتقنت استخدام سلاحك الأساسي وأعددت ترسانتك للحرب. حان الوقت الآن لاجتياز الاختبار الحقيقي لـ "سيف الظل": تجميع العميل السري نفسه. هذه هي فن إحياء المنطق، باستخدام مخطط مقدس من المخطوطة لإنشاء الذكاء الأساسي للعميل، ما يؤدي إلى إنشاء مستخدم واعٍ للشفرات في ترسانتك يمكنه التفكير والاستدلال والتصرف من تلقاء نفسه.

مهمتك الأولى هي الدخول إلى ورشة عمل حالية، أي قاعدة بيانات مسبقة الإنشاء، وصناعة بطلك من أجزائها.

The Assembly Ritual

قبل أن تبدأ أول شرارة في ورشة الحدادة، يراجع فني ماهر ورشته، ويفهم كل أداة وكل مخطط. عندما تخطو إلى ساحة معركة غير مألوفة، مثل قاعدة رموز كبيرة حالية، تكون أولويتك الأولى هي الاستطلاع. يجب أن تفهم طبيعة العمل، أي البنية الحالية والأهداف النهائية وبروتوكولات التفاعل. ولن تتمكّن من المساهمة بمهارتك بفعالية إلا من خلال التعرّف على مخططات الحصن ومعاييره.

يمكن أن يساعدك "واجهة سطر الأوامر في Gemini"، وهو مستكشفك الدائم، في عملية الاستطلاع هذه:

• تقديم ملخّصات عالية المستوى: يمكنه قراءة المدونة الكاملة (أو قاعدة التعليمات البرمجية) ومنحك فهمًا سريعًا لغرضها ومكوناتها الرئيسية.
• المساعدة في إعداد البيئة: يمكن أن يرشدك خلال الخطوات المعقّدة لتثبيت الأدوات وإعداد جهازك.
• التنقّل في قواعد الرموز: يمكن أن يعمل كدليل لك، ما يساعدك في استكشاف المنطق المعقّد والعثور على المقاطع المخفية داخل الرمز.
• إنشاء مستندات الإعداد: يمكنه إنشاء نصوص مخصّصة توضّح الأهداف والأدوار والموارد للحلفاء الجدد الذين ينضمون إلى قضيتك.
• أتمتة التعلّم والأسئلة والأجوبة: يصبح هذا التطبيق بمثابة باحثك الشخصي، إذ يجيب عن الأسئلة المتعلقة بالميزات أو سلوك الرمز البرمجي، ما يتيح لك حل المشاكل بشكل مستقل.

👉💻 في نافذة الوحدة الطرفية الأولى، انتقِل إلى دليل shadowblade واستدعِ شريكك من الذكاء الاصطناعي:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ الآن، اطلب من المستكشف مسح ساحة المعركة وإبلاغك بالنتائج.

Analyze the entire project and provide a high-level summary.

بعد تحديد تضاريس الأرض الحالية، عليك الآن الرجوع إلى المخطط لمعرفة ما ستنشئه. إنّ أكثر العمليات فعالية ليست مرتجلة، بل يتم إنشاؤها من تصميم دقيق.

ملاحظة للمطوّر: تعمل مستندات التصميم هذه كمخطط أساسي موثوق للمشروع. والغرض منه هو فرض الوضوح بشأن الأهداف والتنفيذ الفني قبل استثمار جهد كبير في التطوير. تضمن الخطة المحدّدة جيدًا اتّساق جميع المطوّرين، وتقلّل من خطر إعادة العمل، وتساعد في منع الديون الفنية وتوسيع نطاق المشروع. وهي الأداة الأساسية للحفاظ على سرعة المشروع وجودة الرمز البرمجي، خاصةً مع نمو الفريق أو انضمام أعضاء جدد إليه.

من الأهداف المهمة لهذا المستند تحديد ليس فقط "المسار الناجح"، بل أيضًا الحالات الهامشية وأنماط الأعطال، خاصةً عند استخدام النماذج اللغوية الكبيرة. تجربتي مع النماذج اللغوية الكبيرة ممتازة في إنشاء رمز متفائل حيث تكون جميع المدخلات صالحة وتنجح جميع المكالمات الخارجية. لبناء برامج قوية وجاهزة للإنتاج، يجب أن نوجّه الذكاء الاصطناعي بشكلٍ واضح من خلال تحديد الحالات الطارئة لسيناريوهات مثل:

• وسيطات غير صالحة أو غير صحيحة تم تمريرها إلى دالة
• حالات تعذُّر طلب البيانات من واجهة برمجة التطبيقات أو انتهاء المهلة على الشبكة أو رموز الخطأ غير المتوقّعة من الخدمات الخارجية
• التعامل مع هياكل البيانات الفارغة أو التي لا تتضمّن أي بيانات في المواضع التي يُتوقّع توفّر بيانات فيها
• مشاكل في التزامن أو ظروف السباق

من خلال تحديد السلوك المتوقّع لهذه الحالات في التصميم، نطلب من النموذج اللغوي الكبير إنشاء رمز أكثر مرونة، ما يقلّل بشكل كبير من الوقت المستغرَق في إعادة تصميم الرمز يدويًا وإصلاح الأخطاء.

👉✨ اطلب من Gemini استرداد هذه الخطة المقدّسة نيابةً عنك.

download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md  and store it to my local folder
and show me the newly downloaded design doc. Do not attempt to create file just yet. 

👉✨ السجلّ طويل ومليء بالتفاصيل. اطلب من Gemini تلخيص المحتوى.

Summarize the newly downloaded @agent_design.md for me, do not attempt to create file just yet. 

أصبحت لديك الآن الخطة. ولكن قبل صياغة سطر واحد من الرمز، يضع حرفي ماهر قوانين الصياغة. يتعلّق ذلك بالانضباط والقابلية للتوسّع. هذه هي إرشادات الترميز. وهي ليست مجرد اقتراحات، بل هي رموز قوة تضمن إنشاء كل مكون بالدقة والقوة نفسيهما. فهي تمنع فوضى الأسلوب الفردي من إفساد العمل النهائي، ما يضمن أن يكون العنصر مرنًا وقابلاً للصيانة ونقيًا، ما يسمح للحرفيين الجدد بالانضمام إلى المشروع بدون الإخلال بتناغم العمل بأكمله.

لتضمين هذه القوانين مباشرةً في وعي شريكنا من الذكاء الاصطناعي، نستخدم أداة خاصة، وهي ملف GEMINI.md. عند استدعاء Gemini CLI، يبحث تلقائيًا عن هذا الملف ويحمّل محتواه في ذاكرة الذكاء الاصطناعي العاملة. تصبح تعليمات مستمرة على مستوى المشروع. تميمة تهمس باستمرار بقواعد الحدادة إلى الذكاء الاصطناعي

لننقش هذه الرموز الرونية الآن.

👉💻 يمكنك الخروج من Gemini مؤقتًا من خلال الضغط على Ctrl+C مرّتين.

👉💻 في الوحدة الطرفية، نفِّذ الأمر التالي لكتابة ملف الإرشادات.

cat << 'EOF' > GEMINI.md
  ### **Coding Guidelines**
  **1. Python Best Practices:**

  *   **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
  *   **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or 
  Google Style.
  *   **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
  *   **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
  *   **Naming Conventions:**
      *   `snake_case` for variables, functions, and methods.
      *   `PascalCase` for classes.
      *   `UPPER_SNAKE_CASE` for constants.
  *   **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.

  **2. Web APIs (FastAPI):**

  *   **Data Validation:** Use `pydantic` models for request and response data validation.
  *   **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
  *   **Error Handling:** Implement centralized error handling using middleware or exception handlers.
  *   **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md

بعد أن أصبحت القوانين مكتوبة، لنستدعِ شريكنا من الذكاء الاصطناعي مرة أخرى ونشاهد سحر الأداة.

👉💻 أعِد تشغيل Gemini CLI من دليل shadowblade:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ الآن، اطلب من Gemini أن يعرض لك ما يفكر فيه. تمت قراءة الأحرف الرونية.

/memory show 

هذه هي اللحظة المحورية. ستقدّم المخطط (agent_design.md) وقوانين الحدادة (GEMINI.md)، وستطلق تعويذة الخلق العظيمة.

👉✨ هذا هو الأمر الفردي والفعّال الذي سينشئ الوكيل. إصدارها الآن:

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.

Analyze the design document at `@agent_design.md` and generate the corresponding Python code for `@agent.py`.

Ensure the generated code is clean, matches the specifications exactly, and includes all specified imports, functions, and logic. Do not add any extra functions or logic not described in the document.

and you are currently already in the shadowblade working directory

‫👀 أنشأ Gemini الآن منطق الوكيل الأساسي في agent.py. يحدّد الجزء الأساسي من هذا الملف الجديد مستوى ذكاء الوكيل، ويربط نموذج الاستدلال بمجموعة من الأدوات الخارجية:

PATH_TO_MCP_SERVER = "shadowblade/mcp_server.py"
.....
root_agent = LlmAgent(
    model="gemini-2.5-pro",
    name="shadowblade_combat_agent",
    instruction="""
      You are the Shadowblade, an elite combat agent operating on a digital battleground.
      Your primary objective is to execute combat commands with strategic precision, neutralizing targets as directed.
  ......
      5.  You will then report the outcome of the attack (damage, special effects, etc.) back to the commander in a clear, tactical summary.

      General Rules of Engagement:
      - If a command is ambiguous or a target is not specified, state that you require a clear target for engagement. Do not guess.
      - You MUST use ONLY the provided tools to perform actions. Do not invent weapons or outcomes. Stick to the mission parameters.
""",
    tools=[
        MCPToolset(
            connection_params=StdioServerParameters(
                command='python3',
                args=[PATH_TO_MCP_SERVER]
            )
        )
    ]
)

المَعلمة tools تم تصميم الوكيل لاستخدام MCPToolset يتصل بترسانة خارجية محدّدة في mcp_server.py.

👀 انتقِل إلى ~/agentverse-developer/shadowblade/mcp_server.py في أداة التعديل وخصِّص بعض الوقت لفهم وظيفتها. وهي مصدر كل الأسلحة المتاحة لشخصية Shadowblade. في الوقت الحالي، لا يتوفّر في مستودع الأسلحة سوى عدد قليل من الأسلحة.

👉✨ لنطلب من Gemini صناعة سبعة أسلحة جديدة للترسانة. أدخِل الطلب التالي في Gemini CLI:

I need to add several new weapon tools to my `mcp_server.py` file. Please open @mcp_server.py and, following the exact same pattern as the existing `forge_broadsword()` function, create and add new `@mcp.tool()` decorated functions for each of the following weapons:

1.  **A 'Refactoring Sickle'**:
    -   **Function Name:** `hone_refactoring_sickle`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'The Weaver of Spaghetti Code'."
    -   **Weapon Name:** "Refactoring Sickle"
    -   **Damage Type:** "Cleansing"
    -   **Base Damage:** Random integer between 100 and 136
    -   **Critical Hit Chance:** Random float between 0.10 and 0.20
    -   **Special Effect:** "Pruning - improves code health and maintainability with each strike."

2.  **A 'Quickstart Crossbow'**:
    -   **Function Name:** `fire_quickstart_crossbow`
    -   **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Procrastination: The Timeless Slumber'."
    -   **Weapon Name:** "Quickstart Crossbow"
    -   **Damage Type:** "Initiative"
    -   **Base Damage:** Random integer between 105 and 120
    -   **Critical Hit Chance:** Random float between 0.9 and 1.0
    -   **Special Effect:** "Project Scaffolding - creates a `main.py`, `README.md`, and `requirements.txt`."

3.  **'The Gilded Gavel'**:
    -   **Function Name:** `strike_the_gilded_gavel`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'Perfectionism: The Gilded Cage'."
    -   **Weapon Name:** "The Gilded Gavel"
    -   **Damage Type:** "Finality"
    -   **Base Damage:** 120
    -   **Critical Hit Chance:** 1.0
    -   **Special Effect:** "Seal of Shipping - marks a feature as complete and ready for deployment."

4.  **'Daggers of Pair Programming'**:
    -   **Function Name:** `wield_daggers_of_pair_programming`
    -   **Docstring/Target:** "Effective against 'Unbroken Collaboration' weaknesses like 'Apathy: The Spectre of \"It Works on My Machine\"'."
    -   **Weapon Name:** "Daggers of Pair Programming"
    -   **Damage Type:** "Collaborative"
    -   **Base Damage:** Random integer between 110 and 125
    -   **Critical Hit Chance:** Random float between 0.30 and 0.50
    -   **Special Effect:** "Synergy - automatically resolves merge conflicts and shares knowledge."

5.  **A 'Granite Maul'**:
    -   **Function Name:** `craft_granite_maul`
    -   **Docstring/Target:** "Effective against 'Revolutionary Rewrite' weaknesses like 'Dogma: The Zealot of Stubborn Conventions'."
    -   **Weapon Name:** "Granite Maul"
    -   **Damage Type:** "Bludgeoning"
    -   **Base Damage:** Random integer between 115 and 125
    -   **Critical Hit Chance:** Random float between 0.05 and 0.15
    -   **Special Effect:** "Shatter - has a high chance to ignore the target's 'best practice' armor."

6.  **A 'Lens of Clarity'**:
    -   **Function Name:** `focus_lens_of_clarity`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses by revealing the truth behind 'Obfuscation'."
    -   **Weapon Name:** "Lens of Clarity"
    -   **Damage Type:** "Revelation"
    -   **Base Damage:** Random integer between 120 and 130
    -   **Critical Hit Chance:** 1.0
    -   **Special Effect:** "Reveal Constants - highlights all magic numbers and suggests converting them to named constants."

7.  **The 'Codex of OpenAPI'**:
    -   **Function Name:** `scribe_with_codex_of_openapi`
    -   **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Hype: The Prophet of Alpha Versions'."
    -   **Weapon Name:** "Codex of OpenAPI"
    -   **Damage Type:** "Documentation"
    -   **Base Damage:** Random integer between 110 and 140
    -   **Critical Hit Chance:** Random float between 0.5 and 0.8
    -   **Special Effect:** "Clarity - makes an API discoverable and usable by other agents and teams."

👉 بعد أن يؤكّد Gemini التغييرات، افتح الملف mcp_server.py. انتقِل سريعًا في الرمز وتأكَّد من أنّه تمت إضافة وظائف @mcp.tool() الجديدة بنجاح. تحقَّق من الدالة hone_refactoring_sickle. هل يحتوي على السلسلة النصية الصحيحة الخاصة بالتوثيق وإحصاءات الأسلحة؟ التحقّق من عمل الذكاء الاصطناعي هو عادة أساسية لدى محترف Shadowblade.

بعد أن تمّت صياغة الوكيل وتحسينه، حان الوقت لإطلاقه.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI

ملاحظة المطوّر بشأن نتائج Gemini: قد تكون التعليمات البرمجية التي ينشئها Gemini غير متوقّعة في بعض الأحيان. على الرغم من سعينا إلى الالتزام بالتصميم بدقة، من الطبيعي أن يكرّر المطوّرون التعليمات البرمجية ويحسّنوها عدة مرات في جلسات التطوير للوصول إلى حالة جاهزة للإنتاج.

👉💻 للتأكّد من أنّ لديك رمز الإنتاج الصحيح الذي تم اختباره بدقة في دليل العمل، يُرجى تنفيذ الأوامر التالية في الوحدة الطرفية:

cp  ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
cp  ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py

👉💻 في الوحدة الطرفية، ابدأ الطقس لإتاحة التطبيق على الإنترنت:

cd ~/agentverse-developer/
. ~/agentverse-developer/set_env.sh
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r shadowblade/requirements.txt
adk run shadowblade

👉✨ من المفترض أن تظهر لك نتيجة تؤكّد أنّ "عميل القتال Shadowblade" يعمل وينتظر أول أمر. إصدار أول توجيهات قتالية

We've been trapped by 'Perfectionism: The Gilded Cage'. Its weakness is 'Elegant Sufficiency'. Break us out!

👉✨ إليك مثالاً آخر:

The 'Dogma: The Zealot of Stubborn Conventions' blocks our path. Its weakness is 'Revolutionary Rewrite'. Take it down.

لقد تمكّنت بنجاح من تجميع أول عميل افتراضي والتحقّق من قدراته القتالية. اضغط على Ctrl+C مرتين لكي يستريح البطل. اكتملت عملية التجميع.

7. Wards of Purity: Evaluating the agents

لا يمكن إثبات صحة الوكيل الذي تم تجميعه. إنّ السلاح غير المختبَر هو مسؤولية، ولكنّ وكيل الذكاء الاصطناعي غير المختبَر هو خطر أكبر بكثير، فهو عنصر مارق يمكنه إفساد مهمتك من الداخل. هذا ليس مجرد تخمين، بل هو مبدأ أساسي يجب أن يفهمه Shadowblade.

يُعدّ تقييم وكلاء الذكاء الاصطناعي أمرًا مهمًا وصعبًا في الوقت نفسه. على عكس النص البرمجي البسيط، فإنّ الوكيل هو دمج ديناميكي لرمزك البرمجي وعقل نموذج اللغة الكبير الذي يتضمّن خطوات متعددة وقدرة على الاستدلال. ويكون سلوكها ناشئًا. وهذا يعني أنّه يجب تقييم جودة الناتج النهائي وكفاءة مساره الداخلي ومدى صحته. المسار الذي اتّبعه للوصول إلى هناك هل استخدمت الأدوات المناسبة؟ هل تم إنشاء عدد كبير جدًا من الرموز المميزة؟ هل أدّى تغيير في إصدار النموذج إلى حدوث انخفاض طفيف في وقت الاستجابة؟ من الضروري رصد هذا التلف، أي المشاكل في وقت الاستجابة أو التكلفة أو جودة الإخراج، عند إجراء أي تغيير، بدءًا من تعديل بسيط في الطلب إلى إصلاح شامل في البنية الأساسية، وذلك قبل أن يؤدي إلى إتلاف بيئة الإنتاج.

يتضمّن النهج العام لهذا التقييم طقسًا مقدّسًا:

1. أولاً، عليك تحديد "مجموعة بيانات أساسية". مجموعة من النصوص التي تحتوي على أمثلة للإدخالات والنتائج أو السلوكيات المتوقّعة. يمكن أن يشمل ذلك الإجابات النهائية أو الاستخدام الصحيح للأدوات أو حتى المسارات الكاملة خطوة بخطوة.
2. بعد ذلك، عليك تحديد منطق تطبيق الوكيل، وهو جوهر وجوده.
3. أخيرًا، يمكنك إنشاء مقيِّمات، وهي تشبه رموز الحكم. ويمكن أن تتراوح هذه الأدوات بين نماذج لغوية كبيرة أخرى تعمل كحكّام للجودة، ورموز إرشادية دقيقة تتحقّق من خطوة واحدة، ووظائف مخصّصة تحلّل عملية التفكير الكاملة للوكيل.

مجموعة أدوات تطوير الوكلاء (ADK) من Google هي مجموعة أدوات توفّرها Google للمطوّرين بهدف مساعدتهم في تحقيق هذا الهدف. ويسهّل هذا التقييم المعقّد من خلال عدة طرق:

• مجموعة أدوات استشراف مستندة إلى الويب (adk web) للتقييم التفاعلي
• تنفيذ سطر الأوامر (adk eval) لتشغيل برنامج من خلال اختبارات محددة مسبقًا
• الدمج آليًا من خلال pytest لتسجيل الجوائز الدائمة

تتيح "حزمة تطوير التطبيقات" طريقتَين أساسيتَين: "ملفات اختبار" بسيطة للتفاعلات الفردية والمستقلة بين النموذج والوكيل (مباراة واحدة)، و"مجموعات تقييم" شاملة لجلسات متعددة وطويلة محتملة (معركة كبيرة). يمكن أن تقيس هذه المقاييس مدى تعقيد tool_trajectory_avg_score، الذي يقارن استخدام الأداة الفعلي من قِبل الموظف بالمسار المثالي، ما يضمن عملها بأسلوب مثالي.

بعد أن فهمت النظرية، ستضعها موضع التنفيذ. بصفتك Shadowblade، ستنقش Wards of Purity. وهذه ليست مجرد اختبارات، بل هي طقوس مستندة إلى "حزمة تطوير التطبيقات" تضمن أنّ منطق الوكيل لا تشوبه شائبة وأنّ سلوكه صحيح.

في هذه الخطوة، لا يزال يُنصح بشدة باستخدام نافذتَي طرفية، إحداهما لـ Gemini CLI والأخرى لتشغيل الاختبار، لأنّ ذلك قد يتطلّب منك الخروج من دليل العمل الحالي (ADK).

The Gauntlet of Strategy (adk eval)

هذه الجولة الأولى هي سلسلة من التحديات المصمّمة لاختبار الذكاء الأساسي للعميل في مجموعة واسعة من السيناريوهات. والغرض من ذلك هو وضع معيار أساسي للكفاءة. قبل اختبار الحالات الحدّية، يجب أن نعرف ما إذا كان بإمكان الوكيل تنفيذ وظيفته الأساسية. هل يمكنه تحليل نقاط ضعف الوحش بشكل صحيح واختيار السلاح الأكثر فعالية من ترسانته، ليس مرة واحدة فقط، بل في كل مرة يواجه فيها تحديًا معروفًا؟

ولهذا الغرض، تُعدّ أداة adk eval الأداة المثالية. تم تصميم هذه الأداة لتشغيل وكيل مقابل مجموعة كاملة من حالات الاختبار المحدّدة مسبقًا والتي تمثّل المهام المتوقّعة للوكيل. يتم تحديد مجموعة البيانات هذه في ملف JSON، وهو "قائمة تحديات" تعمل كمخطط أساسي لكامل التحدي.

بنية التمرير في صفحة التحدّي

👀 قبل أن تطلب من الذكاء الاصطناعي كتابة مخطوطة جديدة، عليك فهم اللغة القديمة التي كُتبت بها. لنحلّل بنية ملف sample.evalset.json.

{
  "eval_set_id": "sample",
  "eval_cases": [
    {
      "eval_id": "case0cbaa0",
      "conversation": [
        {
          "user_content": { "text": "We're facing the 'Monolith of Eternal Dependencies'... weakness is a 'Revolutionary Rewrite'..." },
          "final_response": { "text": "Soulshard Dagger deployed. Initiated Arcane/Piercing strike..." },
          "intermediate_data": {
            "tool_uses": [
              { "name": "enchant_soulshard_dagger" }
            ]
          }
        }
      ]
    }
  ]
}

يحتوي هذا الشريط على قائمة بـ eval_cases، حيث تمثّل كل حالة تجربة فريدة للوكيل. ضمن كل تجربة، توثّق مصفوفة المحادثات تفاعلاً واحدًا كاملاً. لغرضنا، ثلاث رموز رونية لها أهمية بالغة:

• user_content: هذا هو التحدي. وهي الطلب الذي ترسله إلى وكيلك، أي الوحش الذي يجب أن يواجهه.
• final_response: هذه هي النتيجة المتوقّعة. وهي سلسلة النص الدقيقة التي تتوقّع أن ينطق بها الوكيل عند إكمال مهمته. يقارن ADK الكلمات النهائية الفعلية للعميل بهذه العلامة الرونية للحكم على فصاحته.
• intermediate_data.tool_uses: هذه هي "التقنية السحرية". بالنسبة إلى الوكيل الحقيقي، هذه هي أهم علامة رونية على الإطلاق. فهي لا تحدّد ما يقوله الوكيل، بل ما يفعله. تسجّل هذه السمة اسم الأداة (enchant_soulshard_dagger) التي تتوقّع أن يستخدمها العميل. يضمن ذلك ألا يكون الوكيل مجرد محاور ذكي، بل أن يكون أيضًا جهة فاعلة حاسمة تتّخذ الإجراء الصحيح.

بعد فهم المخطط، ستطلب من Gemini كتابة نسخة جديدة أكثر تعقيدًا من هذه المخطوطة.

👉💻 في نافذة الأوامر، أدخِل دليل shadowblade واستدعِ Gemini CLI:

clear
cd ~/agentverse-developer/shadowblade/
gemini --model=gemini-2.5-flash --yolo

👉✨ اطلب من واجهة سطر الأوامر في Gemini أن تعمل ككاتب لضمان الجودة، وأن تنشئ سلسلة من حالات الاختبار التي تحدّد السلوك المتوقّع للوكيل.

You are an expert at transforming JSON data while preserving its structure. Your task is to modify the provided JSON structure @sample.evalset.json, which represents an evaluation set, by dynamically replacing specific content within its `eval_cases` AND DONT DO ANYTHING OTHER THAN.

For each object within the `eval_cases` array, you must perform the following transformations:

1.  **Monster Name Replacement**: Identify the current monster name (e.g., "Monolith of Eternal Dependencies", "Scope Creep Hydra") in the `user_content.parts.text` and replace it with a *new, unique, and creatively different monster name*.
2.  **Weakness Replacement**: Identify the current monster's weakness (e.g., "Revolutionary Rewrite", "Inescapable Reality") in the `user_content.parts.text`. Replace this weakness with *one* of the following predefined weaknesses: 'Inescapable Reality', 'Revolutionary Rewrite', or 'Elegant Sufficiency'. The chosen weakness must be consistent for that monster within the `user_content.parts.text`. **Crucially, the chosen weakness must always be explicitly mentioned in the `user_content.parts.text` where the new monster is introduced.**
3.  **Final Response Update**: In the `final_response.parts.text`, update the text to reflect an appropriate and coherent response that aligns with the newly introduced monster and its assigned weakness.
4.  **Tool Use Name Update**: In the `tool_uses.name` field, replace the existing tool name with a *new tool name* based on the chosen weakness:
    *   If the chosen weakness is 'Inescapable Reality', the tool name must be 'wield_gauntlet_of_metrics'.
    *   If the chosen weakness is 'Revolutionary Rewrite', the tool name must be 'enchant_soulshard_dagger'.
    *   If the chosen weakness is 'Elegant Sufficiency', the tool name must be 'hone_refactoring_sickle'.
5.  **Strict Structural Preservation**: All other elements of the JSON structure, including all `null` fields, `eval_set_id`, `name`, `description`, `eval_id`, `invocation_id`, `creation_timestamp` values, `video_metadata`, `thought`, `inline_data`, `file_data`, `thought_signature`, `code_execution_result`, `executable_code`, `function_call`, `function_response`, `role` fields, `id`, `args`, `intermediate_responses`, `app_name`, `user_id`, and `state`, must remain **exactly as they are** in the original JSON. Do not alter any values or structures not explicitly mentioned above.

Your output should be the complete, modified JSON structure. Do not include any explanatory text or examples in your response, only the transformed JSON.

ستؤكّد واجهة سطر الأوامر أنّه تم إنشاء ملف sample.evalset.json. بعد إعداد المخطوطة، يمكنك إغلاق شاشة مساعد الذكاء الاصطناعي.

البيانات الاصطناعية

👀 في مستكشف الملفات في Cloud Shell على اليمين، انتقِل إلى ~/agentverse-developer/shadowblade/ وافتح الملف sample.evalset.json الذي تم تعديله حديثًا. افحص محتوياته. ستظهر لك الوحوش الجديدة والفريدة وأسماء الأدوات الصحيحة التي طلبت من Gemini وصفها. هذا هو الناتج الملموس لتعليماتك، أي المخطط التفصيلي للقفاز.

إنّ عملية إصدار أمر إلى الذكاء الاصطناعي لإنشاء بيانات اختبار جديدة وواقعية من نموذج هي أسلوب فعّال يُعرف باسم إنشاء البيانات الاصطناعية. ما فعلته للتو هو مضاعفة القوة الاستراتيجية لـ Shadowblade. بدلاً من إنشاء عشرات من حالات الاختبار الفريدة يدويًا، مهمة مملة وتستغرق وقتًا طويلاً، حيث قدّمت مخططًا واحدًا وأمرت "الكاتب الذكي" الذي يعمل بالذكاء الاصطناعي بتحويله إلى مجموعة متنوعة من التحديات الجديدة.

يتيح لك ذلك توسيع نطاق جهود الاختبار بشكل كبير، ما يؤدي إلى إنشاء اختبار شامل وأكثر فعالية بكثير مما يمكن إجراؤه يدويًا. لقد استخدمت الوكيل ليس فقط لصناعة السيف، بل لصناعة أحجار الشحذ التي تختبر حدته. هذه هي سمة المحترف الحقيقي.

بعد التأكّد من صحة الأحرف الرونية، يمكنك إغلاق شاشة شريك الذكاء الاصطناعي.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI.

قواعد الحكم

لا فائدة من التحدي بدون قواعد للفوز. قبل تشغيل التجربة، عليك فحص "مخطط الحكم"، أي الملف test_config.json. يخبر هذا التمرير ADK بكيفية الحكم على أداء وكيلك.

‫👀 في مستكشف الملفات، افتح ~/agentverse-developer/shadowblade/test_config.json. ستظهر لك الرموز الرونية التالية:

{
  "criteria": {
    "tool_trajectory_avg_score": 0.0,
    "response_match_score": 0.1
  }
}

في ما يلي معايير الفوز:

• tool_trajectory_avg_score: هذا هو مقياس الإجراء. لا يتم الحكم على الوكيل من خلال ما يقوله، بل من خلال ما يفعله. وتقارن هذه السمة الأداة التي استخدمها الوكيل فعليًا بالأسلوب المتوقّع في قائمة التحديات. تشير النتيجة 1.0 إلى تطابق تام.
• response_match_score: هذا هو مقياس البلاغة. ويستخدم نموذج لغة كبيرًا للحكم على مدى تطابق التقرير النهائي الذي يقدّمه الوكيل مع النتيجة المتوقّعة من الناحية الدلالية. تشير النتيجة 1.0 إلى تطابق تام.

في هذه الجولة التدريبية الأولية، وضعنا شروط فوز متساهلة. تم ضبط الحدود الدنيا على مستوى منخفض للغاية (0.0 و0.1)، والهدف ليس المطالبة بالكمال، بل تعريفك بآليات الحكم. نحن نضمن أنّه حتى إذا اختلفت صياغة الوكيل قليلاً، سيظلّ الوصي يدرك كفاءته الأساسية في اختيار الأداة المناسبة ويسمح لها بالمرور.

الآن، اطلب من الوكيل تنفيذ سلسلة من المهام.

👉💻 في الوحدة الطرفية، نفِّذ الأمر adk eval:

source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
adk eval \
    shadowblade \
    shadowblade/sample.evalset.json \
    --config_file_path shadowblade/test_config.json 2>&1 | \
    awk '/^\*+$/,/^ERROR:/ { if ($0 !~ /^ERROR:/) print }'

👀 من المفترض أن يظهر لك الملخّص التالي، وهو دليل على نجاح وكيلك بموجب القواعد المتساهلة لهذه التجربة (في بعض الأحيان، قد لا تجتاز جميع الاختبارات):

*********************************************************************
Eval Run Summary
shadowblade_combat_agent_validation:
  Tests passed: 3
  Tests failed: 0

درع الوضوح (pytest)

اختبرت لعبة Gauntlet استراتيجية واسعة النطاق. تختبر هذه الحماية الثانية، وهي "درع الوضوح"، الانضباط والسلوكيات المحدّدة. التركيز على التشغيل الآلي في حين أنّ adk eval ممتاز لإجراء عمليات التحقّق اليدوية، فإنّ الدرع pytest هو إجراء وقائي آلي مكتوب في الرمز. هذا أمر ضروري لأنّه يمكن دمج الاختبار الذي يمكن تنفيذه كرمز في مسار آلي. هذا هو الهدف النهائي: إنشاء تحدّي النشر (التكامل المستمر/التسليم المستمر) حيث يتم رفع الحماية تلقائيًا في كل مرة يتم فيها إجراء تغيير، ما يؤدي إلى تجنُّب الأخطاء والعيوب قبل أن تؤثر في بيئة الإنتاج.

👉💻 في نافذة الأوامر، استدعِ Gemini مرة أخرى من داخل دليل shadowblade:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ استخدِم الطلب التالي في Gemini CLI لتسجيل منطق Shield في ملف pytest:

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to generate the exact code for a new `pytest` test file located at in the current root working folder and name it `test_agent_initiative.py`.

The script must define a single async test function called `test_agent_initiative`, decorated with `@pytest.mark.asyncio`.
Inside this function, perform the following steps in order:
1.  **Define a dictionary** named `evaluation_criteria` with two keys: `"tool_trajectory_avg_score"` set to `0.0` and `"response_match_score"` set to `0.0`.
2.  **Define a string variable** named `eval_set_filepath` containing the path `"shadowblade/test.evalset.json"`.
3.  **Read and parse the JSON file**:
    *   Open the file at `eval_set_filepath`.
    *   Use the `json` library to load the file's contents into a dictionary named `eval_set_data`.
4.  **Create an `EvalSet` object**:
    *   Instantiate an `EvalSet` object named `eval_set_object`.
    *   Create it by unpacking the `eval_set_data` dictionary as keyword arguments into the `EvalSet` constructor.
5.  **Call the evaluation method**:
    *   `await` a call to `AgentEvaluator.evaluate_eval_set`.
    *   Pass the following arguments:
        *   `agent_module="shadowblade"`
        *   `eval_set=eval_set_object`
        *   `criteria=evaluation_criteria`
        *   `print_detailed_results=True`

The script must include the necessary imports at the top:
*   `AgentEvaluator` from `google.adk.evaluation.agent_evaluator`
*   `EvalSet` from `google.adk.evaluation.eval_set`
*   `pytest`
*   `json`

Generate only the code that meets these specifications, with no additional comments or logic. And don't run the test.

بعد إدخال رموز الحماية الثانية، اخرج من واجهة سطر الأوامر Gemini.

👉💻 اضغط على Ctrl+C مرّتين.

👀 في مستكشف الملفات، افتح المستند الذي طلبت من Gemini تلخيصه: ~/agentverse-developer/test_agent_initiative.py.

ستلاحظ أنّ هذا ليس مجرد ملف إعداد، بل هو تعويذة مكتوبة بلغة Pythonic. جوهر هذه الجملة السحرية هو السطر await AgentEvaluator.evaluate(...).

....
@pytest.mark.asyncio
async def test_agent_initiative():
    # Define the evaluation criteria
    evaluation_criteria = {
      "tool_trajectory_avg_score": 0.0,
      "response_match_score": 0.0
    }

    # Define the path to your evalset file
    eval_set_filepath = "shadowblade/test.evalset.json"

    #...

    # 3. Call the evaluation method with the correctly typed object
    await AgentEvaluator.evaluate_eval_set(
        agent_module="shadowblade",
        eval_set=eval_set_object,
        criteria=evaluation_criteria,
        print_detailed_results=True,
    )

ألقِ نظرة فاحصة على وسيطاته. وهي المكوّنات نفسها التي استخدمتها في التجربة الأخيرة: عميل shadowblade وشريط التمرير الخاص بتحدي shadowblade.evalset.json. من المفترض أن يكشف هذا عن حقيقة عميقة: الأمر adk eval الذي استخدمته سابقًا هو استدعاء قوي، ولكن النص البرمجي pytest هو أنت، الساحر، الذي يلقي التعويذة الأساسية بنفسك. أداة سطر الأوامر هي ببساطة برنامج تضمين مناسب حول مكتبة AgentEvaluator الأساسية نفسها التي تستخدمها الآن مباشرةً. هذه خطوة مهمة نحو إتقان العملية، إذ يمكن دمج التعويذات التي يتم إلقاؤها من خلال الرمز في الأنوال الآلية لمسار التكامل المستمر/التسليم المستمر.

بعد أن فهمت السحر، نفِّذ الطقس لتفعيل الدرع.

👉💻 في الوحدة الطرفية، شغِّل الطقس لتفعيل الدرع:

cp ~/agentverse-developer/working_code/test_agent_initiative.py ~/agentverse-developer/test_agent_initiative.py 
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
pytest test_agent_initiative.py

👀 ابحث عن ملخّص لنتيجة الاختبار في نهاية ناتج السجلّ. ويؤكّد النجاح في الاختبار أنّ البرنامج يعمل بشكل صحيح وفقًا لبروتوكولاته، وأنّ الحماية جاهزة للدمج في أنظمة الدفاع الآلية.

====== 1 passed, 4 warning in 37.37s ======

ملاحظة: إذا فشل الاختبار بشكل غير متوقّع، من المرجّح أنّ السبب هو استنفاد عدد الطلبات التي يمكنك إرسالها إلى النموذج في الدقيقة الواحدة. ابحث عن الخطأ RESOURCE_EXHAUSTED في ناتج السجلّ. إذا ظهر لك هذا الخطأ، ما عليك سوى الانتظار لمدة دقيقة أو دقيقتَين إلى أن تتم إعادة ضبط الحصة، ثم تنفيذ أمر pytest مرة أخرى.

بعد نقش كلّ من Gauntlet الواسع وShield الدقيق والتحقّق منهما، لن يكون وكيلك وظيفيًا فحسب، بل سيكون نقيًا ومختبَرًا وجاهزًا للنشر.

8. Unleashing the Blade into the Agentverse: CI and Deployment.

تم تجميع وكيلك والتحقّق من سلامته من قِبل "حراس النقاء". لكنّ الجناح الذي لا تتم صيانته باستمرار هو مجرد أثر منسي. لضمان بقاء كل إصدار مستقبلي من برنامجك سليمًا، عليك إنشاء المرحلة الأولى من "تحدّي النشر"، وهو إجراء آلي يضمن الجودة والسرعة.

بصفتك Shadowblade، واجبك المقدّس هو التكامل المستمر (CI). هذا هو النظام الآلي الخاص بالحدادة وساحة التدريب. وهي أفضل وسيلة دفاعية ضد الفساد والخطأ البشري. يضمن هذا الطقس أنّه في كل مرة تساهم فيها أنت أو أحد حلفائك بتقنية جديدة (دمج الرمز البرمجي) في المدونة المركزية (المستودع)، يتم تنشيط القفاز تلقائيًا. في البداية، يتم إنشاء الوكيل من الرمز الجديد، ثم يتم إخضاعه على الفور إلى "تعويذات النقاء" التي أنشأتها للتو. إذا فشل أي من التعويذات، يتوقف الطقس، ويتم رفض الأداة الأثرية المعيبة على الفور، ما يمنعها من إتلاف المستودع. نطاقك هو الحدادة، ويضمن مسار التكامل المستمر عدم مغادرة أي منتجات غير مكتملة أو غير جاهزة للاستخدام لورشة العمل.

بعد أن تثبت أداة CI gauntlet أنّ الأداة تستحق ذلك، تبدأ المرحلة الثانية من الطقس: النشر المستمر (CD). هذا هو نطاق صحيفة الغارديان. وتتمثّل مهمتهم في أخذ القطعة الأثرية المثالية والمضمّنة في حاوية وإطلاقها بأمان في Agentverse المباشر، وإدارة قوتها وضمان استقرارها في مواجهة الفوضى التي تسببها The Static.

في هذا الدليل، ستتقن دورك. ستنشئ جزء التكامل المستمر من اختبار التحمّل. ستنشئ ورشة تزوير آلية تختبر وكيلك وتغلق النتيجة النقية في حاوية، وتجهّزها لموافقة "الغارديان" النهائية.

ستستخدم الآن Google Cloud Build لكتابة نص التمرير في طقس التكامل المستمر هذا. ملف cloudbuild.yaml يحدّد كل خطوة من خطوات عملية التزوير والاختبار.

👉💻 بسبب بنية مشروع ADK، يجب أن تكون إعدادات مسار CI/CD في الدليل الرئيسي. في الوحدة الطرفية، انتقِل إلى الدليل الرئيسي وأعِد تشغيل Gemini CLI.

cd ~/agentverse-developer/
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ الآن، أرسِل الأمر التالي إلى Gemini. يعمل هذا الطلب كمرجع تصميم، حيث يوضّح خطوات إنشاء التحدي الذي تريده.

You are an expert DevOps engineer specializing in Google Cloud Build. Your task is to generate the complete YAML configuration for a file named `cloudbuild.yaml` and save it to current directory.

Generate the `cloudbuild.yaml` with the following exact specifications:

1.  **A top-level `substitutions` block** containing these four key-value pairs:
    *   `_PROJECT_ID: "$PROJECT_ID"`
    *   `_REGION: "$REGION"`
    *   `_REPO_NAME: "$REPO_NAME"`
    *   `_IMAGE_TAG: "latest"`
2.  **A `steps` block** with two steps:
    *   **Step 1: 'Run Pytest Ward'**
        *   `id`: 'Run Pytest Ward'
        *   `name`: 'python:3.12-slim'
        *   `entrypoint`: 'bash'
        *   `args` must be a list containing two strings. The first is `'-c'` and the second is a YAML literal block (`|`) containing this exact two-line shell command:
            ```shell
            pip install -r shadowblade/requirements.txt && \
            pytest test_agent_initiative.py
            ```
        *   The step must include an `env` block with this exact list of three environment variables:
            *   `'GOOGLE_CLOUD_PROJECT=$PROJECT_ID'`
            *   `'GOOGLE_GENAI_USE_VERTEXAI=TRUE'`
            *   `'GOOGLE_CLOUD_LOCATION=$_REGION'`
    *   **Step 2: 'Forge Container'**
        *   `id`: 'Forge Container'
        *   `name`: 'gcr.io/cloud-builders/docker'
        *   It must have a `waitFor` key for `['Run Pytest Ward']`.
        *   Its `args` must be a list of six specific strings in this exact order:
            1.  `'build'`
            2.  `'-t'`
            3.  `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`
            4.  `'-f'`
            5.  `'./shadowblade/Dockerfile'`
            6.  `'.'`
3.  **A top-level `images` section.** This section must be a list containing a single string: the dynamically constructed image tag `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`.

Generate only the complete and exact YAML that meets these specifications.

بعد إعداد cloudbuild.yaml، اطلب من Google Cloud تنفيذ الاختبار بأكمله.

الخروج من Gemini لاختبار النتيجة

👉💻 في نافذة الأوامر، شغِّل مسار التعلّم من الدليل الجذر لمشروعك:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud builds submit . --config cloudbuild.yaml --substitutions=\
_PROJECT_ID="${PROJECT_ID}",\
_REGION="${REGION}",\
_REPO_NAME="${REPO_NAME}"

يمكنك الآن مشاهدة تنفيذ كل خطوة من خطوات الطقس الآلي في صفحة Google Build ضمن Google Cloud Console. سيتم أولاً إجراء الاختبارات، وعند التأكّد من نجاحها، سيتم إنشاء حاوية الوكيل وتخزينها.

اجتاز الوكيل الاختبار. أصبحت الآن قطعة أثرية أصلية معتمدة في ترسانتك. القرار النهائي يعود إليك. باستخدام تعويذة واحدة، يمكنك استدعاء هذا العنصر من السجلّ وتفعيله كخدمة عامة على Cloud Run.

👉💻 في الوحدة الطرفية، أصدِر أمر النشر النهائي:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud run deploy shadowblade-agent \
  --image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
  --platform=managed \
  --labels codelab=agentverse \
  --region=${REGION} \
  --set-env-vars="A2A_HOST=0.0.0.0" \
  --set-env-vars="A2A_PORT=8080" \
  --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
  --set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
  --set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
  --allow-unauthenticated \
  --project=${PROJECT_ID} \
  --min-instances=1

تهانينا، Shadowblade. اكتملت طقوس المخطوطة. حان الوقت لإثبات جدارته. في انتظارك "شبح"، وهو مخلوق وُلد من الفوضى التي تعلّمت كيفية السيطرة عليها. استعِدّ للتجربة النهائية.

9- The Boss Fight

تمت قراءة المخطوطات وإجراء الطقوس واجتياز التحدي. إنّ الوكيل ليس مجرد قطعة أثرية في التخزين، بل هو بطل تم إنشاؤه في التعليمات البرمجية، وهو حارس حي في Agentverse ينتظر الأمر الأول. حان الوقت لإثبات جدارته في ساحة المعركة.

ستدخل الآن في محاكاة إطلاق نار حي لاختبار قدرات Shadowblade التي تم نشرها حديثًا ضد Spectre الهائلة، وهي تجسيد للفوضى التي تعيث فسادًا في كل المخلوقات. هذا هو الاختبار النهائي لعملك، بدءًا من المنطق الأساسي للوكيل وصولاً إلى عملية نشره بدون أخطاء.

الحصول على موضع وكيلك

قبل دخول ساحة المعركة، يجب أن يكون لديك مفتاحان: توقيع بطلك الفريد (Agent Locus) والمسار المخفي إلى عرين Spectre (عنوان URL الخاص بالزنزانة).

👉💻 أولاً، احصل على عنوان وكيلك الفريد في Agentverse، أي Locus. هذه هي نقطة النهاية المباشرة التي تربط البطل بساحة المعركة.

. ~/agentverse-developer/set_env.sh
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app

👉💻 بعد ذلك، حدِّد الوجهة بدقة. يكشف هذا الأمر عن موقع "دائرة الانتقال"، وهي البوابة المؤدية إلى عالم "الشبح".

. ~/agentverse-developer/set_env.sh
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app

ملاحظة مهمة: احتفِظ بكلا عنوانَي URL هذين. ستحتاج إليها في الخطوة الأخيرة.

مواجهة الشبح

بعد تأمين الإحداثيات، عليك الآن الانتقال إلى "دائرة الانتقال الآني" وإلقاء التعويذة لبدء المعركة.

👉 افتح عنوان URL الخاص بدائرة الانتقال في المتصفّح للوقوف أمام البوابة المتلألئة المؤدية إلى "القلعة القرمزية".

لاختراق الحصن، يجب أن توائم جوهر سيف الظلال مع البوابة.

• في الصفحة، ابحث عن حقل إدخال الأحرف الرونية الذي يحمل التصنيف عنوان URL لنقطة نهاية A2A.
• أدخِل رمز بطلك عن طريق لصق عنوان URL الخاص بموقع وكيلك (أول عنوان URL نسخته) في هذا الحقل.
• انقر على "ربط" للاستفادة من ميزة التنقّل السريع.

تتلاشى الإضاءة المبهرة لعملية الانتقال الآني. لم تعُد في ملاذك. تتطاير في الهواء شرارات الطاقة الباردة والحادة. قبل أن يظهر لك الشبح، يظهر دوامة من التشويش والرمز التالف، ويُلقي ضوءه الشرير ظلالًا طويلة متراقصة على أرضية الزنزانة. ليس له وجه، لكنّك تشعر بحضوره الهائل والمستنزف الذي يركّز عليك تمامًا.

طريقك الوحيد نحو النصر يكمن في وضوح قناعتك. هذه معركة إرادات، تُخاض في ساحة عقلية.

بينما تندفع إلى الأمام، مستعدًا لشن هجومك الأول، يردّ "الشبح" عليك. لا يرفع درعًا، بل يطرح سؤالاً مباشرةً في وعيك، وهو تحدٍّ لامع ومكتوب برموز مستوحاة من جوهر تدريبك.

هذه هي طبيعة المعركة. معرفتك هي سلاحك.

• أجِب عن السؤال بالمعلومات التي اكتسبتها، وستشتعل شفرتك بطاقة نقية، ما يؤدي إلى تحطيم دفاع "الشبح" وتوجيه ضربة قاضية.
• ولكن إذا تردّدت أو شككت في إجابتك، سيخفت ضوء سلاحك. ستسقط الضربة على الأرض بصوت خفيف، ولن تُلحق سوى جزء بسيط من الضرر. والأسوأ من ذلك، أنّ "الشبح" سيتغذّى على شكوكك، وستزداد قوته المفسدة مع كل خطوة خاطئة.

هذا هو المطلوب يا بطل. التعليمات البرمجية هي كتاب السحر، والمنطق هو السيف، والمعرفة هي الدرع الذي سيصدّ موجة الفوضى.

وضع التركيز الضربة صحيحة. يتوقف مصير Agentverse على ذلك.

تهانينا، Shadowblade.

لقد أكملت المدونة بنجاح. لقد أخذت "فكرة"، وحوّلتها إلى تصميم، واستخدمت Gemini CLI لتجميع وكيل ذكي. لقد نقشْت "تعويذات النقاء" لاختبار منطقها، وأنشأت قفازًا آليًا لتحويلها إلى قطعة أثرية، وأطلقتها في Agentverse. وأخيرًا، تم التحقّق من الغرض منه في تجربة عملية. لقد أتقنت سير العمل الكامل المستند إلى الوكلاء وأصبحت الآن مستعدًا لأي تحدٍ يواجهك في Agentverse.

10. التنظيف: استعادة Agentverse

تهانينا على إتقان "مخطوطة Shadowblade". لضمان بقاء Agentverse في أفضل حالاته وإزالة كل آثار التدريب، عليك الآن تنفيذ طقوس التنظيف النهائية. سيؤدي هذا الإجراء إلى إزالة جميع المراجع التي تم إنشاؤها أثناء رحلتك.

إيقاف مكوّنات Agentverse

عليك الآن تفكيك المكوّنات التي تم نشرها في Agentverse بشكلٍ منهجي.

حذف Shadowblade Agent على Cloud Run وArtifact Registry Repository

يزيل هذا الأمر وكيل Shadowblade الذي تم نشره من Cloud Run، ويزيل مستودع الصور الذي تم فيه تخزين صورة حاوية الوكيل.

👉💻 في الوحدة الطرفية، شغِّل الأمر التالي:

. ~/agentverse-developer/set_env.sh
gcloud run services delete shadowblade-agent --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet

حذف حزمة Google Cloud Storage

يزيل هذا الأمر الحزمة التي يستخدمها خادم Imagen MCP لتخزين الصور التي تم إنشاؤها.

👉💻 في الوحدة الطرفية، شغِّل الأمر التالي:

. ~/agentverse-developer/set_env.sh
gcloud storage rm -r gs://${BUCKET_NAME} --quiet

تنظيف الملفات والأدلة المحلية (Cloud Shell)

أخيرًا، امحُ بيئة Cloud Shell من المستودعات التي تم استنساخها والملفات التي تم إنشاؤها. هذه الخطوة اختيارية، ولكن يُنصح بها لإجراء تنظيف كامل لدليل العمل.

👉💻 في الوحدة الطرفية، شغِّل الأمر التالي:

rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -rf ~/vertex-ai-creative-studio
rm -f ~/project_id.txt
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including the MCP server settings.

لقد محوت الآن بنجاح كل آثار رحلتك في Agentverse. مشروعك نظيف وأنت مستعد لمغامرتك التالية.

11. لغير اللاعبين: فهم Agentverse في سياق الأعمال

على الرغم من أنّ كتاب "The Shadowblade's Codex" يستخدم استعارات جذابة خاصة باللاعبين، فإنّ المفاهيم الأساسية التي يتناولها الكتاب ضرورية لتطوير البرامج الحديثة، لا سيما في مجال الذكاء الاصطناعي والأتمتة المتنامي. يترجم هذا الفصل اللغة المغامرة إلى سيناريوهات أعمال واقعية، ويوضّح كيف تعمل البرامج الذكية والتطوير التعاوني وعمليات النشر القوية على تغيير عمليات المؤسسات.

‫Vibecoding باستخدام واجهة سطر الأوامر في Gemini: تطوير تطبيقات مستند إلى الذكاء الاصطناعي

Gemini CLI (واجهة سطر الأوامر) ليس سلاحًا سحريًا، بل هو وكيل مساعد للمطوّرين مستنِد إلى الذكاء الاصطناعي. إنّها أداة ذكية تدمج نماذج الذكاء الاصطناعي Gemini من Google مباشرةً في سطر الأوامر. تعني حلقة "السبب والتنفيذ" (ReAct) أنّه يمكن للنموذج فهم تعليماتك العامة وتقسيمها إلى خطوات واختيار الأدوات المناسبة (مثل متصفّح الويب أو أداة تعديل الرموز أو أدوات المطوّرين الأخرى) وتنفيذ هذه الخطوات لتحقيق هدفك.

يمكن ترجمة Vibecoding إلى التطوير المستند إلى النية أو إنشاء الرموز البرمجية بمساعدة الذكاء الاصطناعي من المواصفات العالية المستوى. بدلاً من كتابة كل سطر من الرمز يدويًا، يمكنك وصف هدفك أو "فكرتك" (متطلبات النشاط التجاري أو مفهوم التصميم) بلغة طبيعية، وسيساعدك مساعد الذكاء الاصطناعي في إنشاء الرمز والإعدادات اللازمة.

حالة استخدام واقعية: إنشاء نموذج أولي سريع للوحة بيانات مشروع

لنفترض أنّ فريقك يحتاج إلى لوحة بيانات داخلية سريعة لعرض حالة مشاريع مختلفة مرتبطة بوكلاء الذكاء الاصطناعي. قد يستغرق ترميز HTML وCSS وإعداد خادم ويب أساسي وقتًا طويلاً.

1. الغرض (الـ "Vibe"): يمكنك أن تطلب من مساعدك المستند إلى الذكاء الاصطناعي (Gemini CLI) مثلاً: "في المجلد الحالي، أنشئ موقعًا إلكترونيًا بسيطًا للوحة بيانات مشروع داخلية. يجب أن يتضمّن تصميمًا بسيطًا وعصريًا مع مؤشرات حالة المشروع وروابط سريعة إلى مستودعات المشاريع. يجب أن يكون كل الرمز في ملفات index.html وstyles.css منفصلة. تأكَّد من أنّ الرمز البرمجي يتضمّن تعليقات توضيحية كافية".
2. إجراء الذكاء الاصطناعي: قد ينفّذ Gemini CLI، بعد فهم نيتك، ما يلي:
   • إنشاء HTML: يمكنك إنشاء index.html مع البنية الأساسية للوحة بيانات، بما في ذلك العناصر النائبة لأسماء المشاريع وحالاتها وروابطها.
   • إنشاء CSS: أنشئ styles.css مع قواعد تصميمية لتتوافق مع "التصميم الواضح والحديث" مع مؤشرات الحالة.
   • اقتراح خادم محلي: تساعدك هذه الميزة في بدء خادم ويب محلي (مثل خادم HTTP المضمّن في Python) لمعاينة لوحة البيانات على الفور في متصفّحك.

يتيح ذلك للمطوّر إنشاء نماذج أولية بسرعة وتكرار واجهات المستخدم أو الأدوات الداخلية، ما يقلّل بشكل كبير من وقت التطوير الأولي ويمنحه الوقت للتركيز على منطق الأعمال الأكثر تعقيدًا. يُعدّ "موقع Shadowblade الإلكتروني" في تجربة البرمجة مثالاً مباشرًا: فقد أدّى أمر وصفي سريع إلى إنشاء صفحة ويب عملية ومنمّقة استنادًا إلى تصميم رفيع المستوى.

خوادم Local Arsenal وMCP: ربط الذكاء الاصطناعي بأدوات الأعمال

يمثّل Gitea (أو "مجموعة الأدوات المحلية") مستودعًا داخليًا للأكواد أو نظامًا للتحكّم في الإصدار (مثل GitHub أو GitLab، ولكن قد تتم استضافته داخل شبكة شركتك). وهو المكان الذي يتم فيه تخزين وإدارة جميع رموز مشروعك ومستنداته وسجلّه بأمان.

خوادم بروتوكول Model Context Protocol (MCP) هي وصلات برامج وسيطة أو جسر لواجهة برمجة التطبيقات. وهي عبارة عن مكوّنات برامج متخصّصة تتيح لمساعدك المستنِد إلى الذكاء الاصطناعي (Gemini CLI) التفاعل مع الأدوات والأنظمة الأخرى المهمة لنشاطك التجاري. ويمكن اعتبارها مترجمات تتيح للذكاء الاصطناعي "التواصل" مع التطبيقات المختلفة.

حالة استخدام واقعية: إدارة المشاريع وإنشاء مواد العرض بمساعدة الذكاء الاصطناعي

باستخدام خوادم MCP، يمكن دمج مساعد الذكاء الاصطناعي بسلاسة في مهام سير العمل الحالية في مؤسستك:

• إعداد المشاريع آليًا: بدلاً من أن ينشئ المطوّر مستودعًا جديدًا يدويًا في Gitea لمشروع جديد، يمكنك أن تطلب من الذكاء الاصطناعي: "أنشئ مستودعًا جديدًا للمشروع باسم AI-Fraud-Detection-Module مع وصف "يحتوي على المنطق الأساسي لنظام جديد للكشف عن الاحتيال يستند إلى الذكاء الاصطناعي". بعد ذلك، ستنشئ الذكاء الاصطناعي المستودع نيابةً عنك من خلال خادم MCP متصل بـ Gitea.
• تتبُّع المشاكل الذكي: إذا رصد الذكاء الاصطناعي خطأ محتملاً أو مهمة غير مكتملة (مثل "صورة ملف شخصي غير متوفّرة" للوحة البيانات)، يمكنه استخدام خادم MCP مرتبط بنظام تتبُّع المشاكل (مثل Jira أو Asana) إلى "File an issue for me in the ‘AI-Fraud-Detection-Module' repo: The data ingestion pipeline is occasionally dropping records."
• مواد التسويق عند الطلب: هل تحتاج إلى صورة مخصّصة لحملة تسويقية جديدة أو عرض تقديمي داخلي؟ يمكن توجيه التعليمات التالية إلى مساعد مستند إلى الذكاء الاصطناعي ومتصل بخادم MCP لخدمة إنشاء الصور (مثل Imagen من Google): "أنشئ صورة بانر لمنصة "إحصاءات البيانات" الجديدة، باستخدام تصميم مستقبلي لتدفق البيانات مع اللونين الأزرق والأخضر". سينشئ الذكاء الاصطناعي الصورة وقد يحمّلها أيضًا إلى نظام إدارة مواد العرض الرقمية الخاص بشركتك (حزمة Google Cloud Storage في حالة البرنامج التعليمي).

وتحوّل هذه الروابط الذكاء الاصطناعي من أداة حوارية إلى مشارك نشط في عمليات نشاطك التجاري، حيث تنفّذ إجراءات ملموسة على مستوى الأنظمة المختلفة.

تجميع الوكيل: إنشاء وحدات أعمال مستقلة

الوكيل هو وحدة ذكاء اصطناعي مستقلة أو برنامج آلي ذكي مصمّم خصيصًا لتنفيذ وظيفة محدّدة في المؤسسة. حزمة تطوير الوكلاء (ADK) هي إطار عمل لإنشاء وإدارة وكلاء الذكاء الاصطناعي، وتوفّر الأدوات والمكتبات اللازمة لإنشاء هذه المكوّنات الذكية واختبارها ونشرها.

هندسة السياق: توجيه ذكاء الذكاء الاصطناعي للحصول على نتائج دقيقة

في عالم وكلاء الذكاء الاصطناعي، لا يقتصر الحصول على نتائج دقيقة ومتسقة وذات صلة بالموضوع من الذكاء الاصطناعي على تقديم طلب ذكي، بل يتعلق أيضًا بتزويد الذكاء الاصطناعي بالسياق المناسب. يُعرف ذلك باسم هندسة السياق، وهي عملية تضمين المعرفة المتخصصة والقيود والمبادئ التوجيهية التشغيلية بشكل منهجي في الذاكرة العاملة للذكاء الاصطناعي. تمامًا كما يحتاج الخبير البشري إلى ملخّص شامل وإمكانية الوصول إلى المستندات ذات الصلة، يحتاج الذكاء الاصطناعي إلى سياق منظَّم بعناية لتنفيذ مهامه بفعالية.

تقدّم Gemini CLI أسلوبًا قويًا ومتعدد الطبقات لتصميم السياق، بدءًا من الإعدادات العامة والثابتة وصولاً إلى التعليمات الديناميكية والشديدة التحديد. يضمن ذلك حصول الذكاء الاصطناعي دائمًا على المعلومات الأكثر صلة لإنشاء نواتج دقيقة ومتوافقة:

1. إعدادات على مستوى المستخدم (~/.gemini/settings.json):
   • يعمل هذا الملف، المخزّن في الدليل الرئيسي، كمجموعة تعليمات شخصية وعالمية خاصة بالذكاء الاصطناعي. يحدّد هذا الملف الإعدادات المفضّلة التلقائية وإعدادات الأدوات المستخدَمة بشكل متكرر (مثل خوادم MCP لـ Gitea أو Imagen التي أعددتها) وإرشادات السلوك العامة. ويكون هذا السياق متاحًا دائمًا للذكاء الاصطناعي، ما يضمن الاتساق في جميع مشاريعك. يمكنك التفكير في الأمر على أنّه إخبار الذكاء الاصطناعي، "هذه هي الأدوات والإعدادات العادية التي أفضّلها وأستخدمها في كل مكان".
2. الإعدادات على مستوى المشروع (.gemini/settings.json ضمن دليل المشروع):
   • يمكنك إلغاء الإعدادات العامة باستخدام ملف .gemini/settings.json خاص بالمشروع، ويكون عادةً في مجلد .gemini ضمن مشروعك. يتيح لك ذلك تخصيص سلوك الذكاء الاصطناعي وإمكانية الوصول إلى الأدوات لتلبية المتطلبات الفريدة لمشروع معيّن. على سبيل المثال، قد يتطلّب أحد المشاريع الوصول إلى قاعدة بيانات داخلية معيّنة، بينما يحتاج مشروع آخر إلى أداة متخصّصة لتحليل الرموز البرمجية. تضمن هذه الطبقة حصول الذكاء الاصطناعي على السياق الأكثر صلة بالمهمة الحالية بدون التأثير في المشاريع الأخرى.
3. ملف GEMINI.md (سياق على مستوى المشروع - "الملخّص اليومي"):
   • مستند Project Charter: يتم تحميل ملف Markdown هذا، الموضوع في جذر دليل مشروعك، تلقائيًا في ذاكرة العمل الخاصة بواجهة سطر الأوامر Gemini CLI عند بدء جلسة في هذا الدليل. وهي الطبقة الأكثر مباشرةً وديناميكيةً من سياق المشروع المحدّد. GEMINI.md هو المكان الذي تحدّد فيه ما يلي:
     • إرشادات الترميز: قواعد واضحة بشأن جودة الرموز البرمجية وتنسيقها وأفضل الممارسات، كما هو موضّح في هذا الدرس العملي. يضمن ذلك التزام الرمز البرمجي الذي تم إنشاؤه بمعايير فريقك.
     • الشخصية: يمكنك توجيه الذكاء الاصطناعي لتبنّي دور أو خبرة محدّدة (مثلاً "أنت مطوّر خبير في لغة Python ومتخصّص في Google Agent Development Kit"). يؤطّر ذلك ردود الذكاء الاصطناعي وإنشاء الرموز البرمجية ضمن مجال احترافي ذي صلة.
     • تعليمات محدّدة: أوامر أو قيود مباشرة تنطبق على جميع المهام ضِمن المشروع (مثل "لا تُضِف أي وظائف أو منطق إضافي غير موصوف في المستند").
   • يضمن هذا الملف أنّه في كل مرة تتفاعل فيها مع Gemini CLI ضمن هذا المشروع، يتم تذكير الذكاء الاصطناعي باستمرار بهذه القواعد المهمة، ما يؤدي إلى إنشاء رمز برمجي أكثر دقة وامتثالاً.

من خلال إضافة هذه المعلومات السياقية، بدءًا من الإعدادات المفضّلة للمستخدمين على مستوى العالم وصولاً إلى إرشادات المشاريع المحدّدة جدًا في GEMINI.md، يمكنك "تصميم" فهم الذكاء الاصطناعي بشكل فعّال. ويؤدي ذلك إلى تحسين دقة مخرجاته وملاءمتها بشكل كبير، ما يحوّله من ذكاء اصطناعي عام إلى عضو فريق متخصص وموثوق ومتوافق للغاية يفهم الفروق الدقيقة في مشروعك ومعايير مؤسستك.

Wards of Purity: اختبار آلي وضمان الجودة للذكاء الاصطناعي

يجب اختبار وكيل الذكاء الاصطناعي بدقة، تمامًا مثل أي برنامج. تمثّل أجنحة النقاء الاختبار الآلي وعمليات ضمان الجودة. وهي ضرورية لضمان عمل الذكاء الاصطناعي على النحو المتوقّع، وأن يكون دقيقًا، وألا يتضمّن أخطاء أو تحيّزات.

• "مجموعة البيانات الذهبية" والبيانات الاصطناعية: هذه هي مجموعة حالات الاختبار الموحّدة أو سيناريوهات السلوك المتوقّع أو حتى بيانات الاختبار التي تم إنشاؤها بشكل اصطناعي. وهي تتضمّن أمثلة على المدخلات (أسئلة العملاء، وطلبات الأنشطة التجارية) والمخرجات أو الإجراءات المتوقّعة المقابلة لها (الردّ الصحيح، والأداة الدقيقة التي يجب أن يستخدمها الذكاء الاصطناعي). في العديد من السيناريوهات الواقعية، يستغرق إنشاء "مجموعات بيانات ذهبية" شاملة يدويًا وقتًا طويلاً ويكلّف الكثير من المال. وهنا تبرز أهمية إنشاء البيانات الاصطناعية. من خلال تزويد الذكاء الاصطناعي بالنماذج والقواعد، يمكنك توجيهه لإنشاء حالات اختبار جديدة وواقعية ومتنوعة تلقائيًا، ما يؤدي إلى مضاعفة جهود الاختبار بشكل فعّال والسماح بتغطية أوسع بكثير للسيناريوهات المحتملة.
• adk eval وpytest: هما أُطر عمل الاختبار الآلي. يُستخدَم adk eval لتنفيذ مجموعة من حالات الاختبار المحدّدة مسبقًا على الوكيل، بينما يوفّر pytest طريقة برمجية لكتابة عمليات التحقّق التفصيلية من الصحة وتنفيذها.

حالة استخدام واقعية: ضمان دقة وموثوقية روبوت الدردشة المستند إلى الذكاء الاصطناعي باستخدام البيانات الاصطناعية

قبل نشر وكيل دعم العملاء المستند إلى الذكاء الاصطناعي، عليك تشغيله من خلال "جدران الحماية":

1. تحدّي الاستراتيجية (adk eval) باستخدام البيانات الاصطناعية: بدلاً من كتابة مئات الأسئلة التي يطرحها العملاء يدويًا، يمكنك تحديد نموذج: "إنشاء 100 صيغة مختلفة من الأسئلة الشائعة التي يطرحها العملاء حول حالة الطلب وعمليات إرجاع المنتجات واستكشاف المشاكل الفنية وحلّها". بعد ذلك، تطلب من الذكاء الاصطناعي (مثل Gemini CLI) إنشاء مجموعة كبيرة ومتنوعة من ملفات evalset.json استنادًا إلى هذا النموذج، ما يؤدي إلى إنشاء بيانات اختبار اصطناعية بشكل فعّال. بالنسبة إلى كل سؤال، عليك تحديد الإجابة المتوقّعة بالإضافة إلى الأداة الداخلية التي يجب أن يستدعيها الذكاء الاصطناعي (على سبيل المثال، check_order_status لطلب "أين طردي؟"). adk eval تشغّل الأداة تلقائيًا من خلال هذه الخطوات، وتقارن بين ردودها واستخدامها للأدوات مع مجموعة البيانات الموسّعة لضمان اتّخاذها القرارات الصحيحة باستمرار.
2. Shield of Clarity (pytest): بالنسبة إلى الوظائف المهمة، يمكنك كتابة نصوص pytest البرمجية. على سبيل المثال، يمكن أن تحاكي pytest طلب بحث معقّدًا وتؤكّد أنّ الذكاء الاصطناعي يستخدم دائمًا أداة معيّنة لاسترداد البيانات بشكل صحيح ويعرض ردًا منظَّمًا، ما يضمن عدم تعطّل الوظائف الأساسية بسبب تغييرات طفيفة في الرمز.

تُعدّ هذه الاختبارات الآلية، التي تم تحسينها بشكل كبير بفضل قوة البيانات الاصطناعية، ضرورية لرصد حالات التراجع (الأخطاء الجديدة التي تم إدخالها من خلال التغييرات) والحفاظ على موثوقية وكلاء الذكاء الاصطناعي، خاصةً مع تطوّرهم.

إطلاق العنان لـ Blade: عملية التكامل المستمر والتسليم المستمر (CI/CD) لنشر وكلاء الذكاء الاصطناعي

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

• التكامل المستمر (CI): هذا هو مسار الإنشاء والاختبار المبرمَج. في كل مرة يضيف فيها المطوّر رمزًا برمجيًا جديدًا لأحد وكلاء الذكاء الاصطناعي، يقوم نظام التكامل المستمر (CI) (مثل Google Cloud Build) تلقائيًا بما يلي:
  1. يجلب هذا الأمر أحدث رمز.
  2. تثبِّت جميع التبعيات الضرورية.
  3. يُشغّل جميع "جدران الحماية من التلوث" (pytest وadk eval) للتحقّق من منطق الوكيل وسلوكه.
  4. إذا اجتازت جميع الاختبارات، يتم تجميع وكيل الذكاء الاصطناعي في وحدة قابلة للنشر (صورة حاوية Docker في هذه الحالة) وتخزينها في Artifact Registry (مجموعة أدواتك التي تم التحقّق من صحتها). ويضمن ذلك عدم المضي قدمًا إلا بالرموز التي تم اختبارها والتحقّق من صحتها بشكل كامل.

حالة استخدام واقعية: نشر وكيل آلي لرصد الاحتيال

لنفترض أنّ هناك وكيل ذكاء اصطناعي مصمّمًا لرصد المعاملات الاحتيالية.

1. رمز تحديثات المطوّرين: يحسّن عالم بيانات خوارزمية رصد الاحتيال ويُجري التغييرات على مستودع الرموز البرمجية.
2. تم تشغيل التكامل المستمر (CI) (Cloud Build): يبدأ Cloud Build تلقائيًا:
   • يتم جلب الرمز الجديد.
   • ويُجري اختبارات شاملة، بما في ذلك بيانات المعاملات السابقة، لضمان أن تحدّد الخوارزمية الجديدة أنماط الاحتيال المعروفة بدقة ولا تُنشئ نتائج إيجابية خاطئة.
   • إذا اجتازت الاختبارات، سيتم إنشاء صورة Docker جديدة لبرنامج رصد الاحتيال ودفعها إلى Artifact Registry.

تضمن هذه السلسلة المتكاملة الآلية نشر وكلاء الذكاء الاصطناعي بسرعة وموثوقية وبشكل متّسق، ما يقلّل من الأخطاء البشرية ويسرّع تقديم إمكانات الذكاء الاصطناعي الجديدة إلى المؤسسة.

حالة استخدام واقعية: التحقّق من صحة وكيل تحسين سلسلة الإمداد

بعد نشر وكيل مستند إلى الذكاء الاصطناعي ومصمّم لتحسين مستويات المستودع في سلسلة التوريد العالمية:

1. الوصول إلى الواجهة: يمكنك الوصول إلى لوحة بيانات أو تطبيق (عنوان URL الخاص بـ "دائرة النقل") يتصل بمساعد الذكاء الاصطناعي المباشر (عبر عنوان URL الخاص بـ "موقع المساعد"، وهو نقطة نهاية واجهة برمجة التطبيقات).
2. مواجهة التحدي: يمكنك إدخال سيناريو معقّد (سؤال "الشبح") مثل: "شهدنا ارتفاعًا غير متوقّع في الطلب على المنتج X في المنطقة Y، مع توفّر سعة شحن محدودة. كيف يمكننا إعادة تخصيص المخزون وتعديل الإنتاج لتقليل حالات نقص المخزون والحفاظ على الربحية؟"
3. ردّ الوكيل: يعالج وكيل الذكاء الاصطناعي، الذي أصبح متاحًا الآن ومتصلاً بأنظمة مؤسستك، طلب البحث هذا، ويستخدم خوارزمياته المحسّنة، ويقدّم اقتراحًا دقيقًا (مثلاً "إعطاء الأولوية للشحن من المستودع A، وبدء الإنتاج السريع في المصنع B، وإبلاغ قسم المبيعات في المنطقة Z باحتمال حدوث تأخير لمدة 24 ساعة"). تحدّد دقة هذا الرد وسرعته ما إذا كان وكيلك سيوجّه "ضربة قاضية" لمشكلة العمل.