‫Agentverse - The Summoner's Concord - Architecting Multi-Agent Systems

1. المقدمة

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

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

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

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

مرحبًا بك في The Agentverse: A Call to Champions

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

agentverse.png

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

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

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

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

اختيار صفك

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

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

مهمتك

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

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

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

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

2. اتفاق المستدعي

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

نظرة عامة

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

  • تصميم منظومة أدوات غير مرتبطة: صمِّم مجموعة من خوادم أدوات MCP المستقلة المستندة إلى الخدمات الدقيقة ونفِّذها. ستتعرّف على أهمية هذه الطبقة الأساسية في إنشاء أنظمة قائمة على الوكلاء قابلة للتوسّع والصيانة وآمنة.
  • إتقان سير العمل المتقدّم باستخدام البرامج الوكيلة: يمكنك الاستفادة من أكثر من برنامج وكيل واحد وإنشاء مجموعة من البرامج الوكيلة المتخصّصة. ستتقن أنماط سير العمل الأساسية في ADK، وهي "متسلسل" و"متوازٍ" و"تكرار"، وستتعرّف على مبادئ التصميم لاختيار النمط المناسب للمهمة المناسبة.
  • استخدام أداة Intelligent Orchestrator: يمكنك الانتقال من أداة بسيطة لإنشاء الوكلاء إلى أداة متطورة لتصميم الأنظمة. ستنشئ "وكيل تنسيق" رئيسيًا يستخدم بروتوكول "من وكيل إلى وكيل" (A2A) لاكتشاف المهام المعقّدة وتفويضها إلى "الوكلاء المساعدون" المتخصّصون، ما يؤدي إلى إنشاء نظام حقيقي متعدد الوكلاء.
  • فرض القواعد باستخدام الرمز، وليس الطلبات: تعرَّف على كيفية إنشاء وكلاء أكثر موثوقية وقابلية للتوقّع من خلال فرض قواعد تفاعلية ذات حالة. ستنفّذ منطقًا مخصّصًا باستخدام نظام "المكوّن الإضافي" و"الدالة الرجعية" الفعّال في "حزمة تطوير التطبيقات" لإدارة القيود الواقعية، مثل مؤقتات فترة الانتظار.
  • إدارة حالة الوكيل والذاكرة: امنح الوكلاء القدرة على التعلّم والتذكّر. ستتعرّف على أساليب لإدارة كلّ من الحالة الحوارية القصيرة الأمد والذاكرة الدائمة الطويلة الأمد من أجل إنشاء تفاعلات أكثر ذكاءً ومراعية للسياق.
  • تنفيذ عملية نشر شاملة على السحابة الإلكترونية: يمكنك نقل نظامك الكامل المتعدد الوكلاء من نموذج أولي محلي إلى واقع جاهز للإنتاج. ستتعرّف على كيفية وضع الوكلاء ومنسّق العمليات في حاويات ونشرهم كمجموعة من الخدمات المصغّرة المستقلة والقابلة للتوسّع على Google Cloud Run.

3- رسم دائرة الاستدعاء

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

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

النص البديل

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

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

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

gcloud auth list

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

git clone https://github.com/weimeilin79/agentverse-architect
chmod +x ~/agentverse-architect/init.sh
chmod +x ~/agentverse-architect/set_env.sh
chmod +x ~/agentverse-architect/prepare.sh
chmod +x ~/agentverse-architect/data_setup.sh

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

👉💻 شغِّل نص الإعداد البرمجي من دليل المشروع.

⚠️ ملاحظة حول معرّف المشروع: سيقترح النص البرمجي معرّف مشروع تلقائيًا تم إنشاؤه عشوائيًا. يمكنك الضغط على Enter لقبول هذا الإعداد التلقائي.

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

cd ~/agentverse-architect
./init.sh

سيتولّى النص البرمجي بقية عملية الإعداد تلقائيًا.

👉 خطوة مهمة بعد الإكمال: بعد انتهاء البرنامج النصي، عليك التأكّد من أنّ Google Cloud Console يعرض المشروع الصحيح:

  1. انتقِل إلى console.cloud.google.com.
  2. انقر على القائمة المنسدلة الخاصة بأداة اختيار المشاريع في أعلى الصفحة.
  3. انقر على علامة التبويب "الكل" (لأنّ المشروع الجديد قد لا يظهر في "الأخيرة" بعد).
  4. اختَر رقم تعريف المشروع الذي أعددته للتو في الخطوة init.sh.

03-05-project-all.png

👉💻 اضبط معرّف المشروع المطلوب:

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

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

gcloud services enable \
    sqladmin.googleapis.com \
    storage.googleapis.com \
    aiplatform.googleapis.com \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    iam.googleapis.com \
    compute.googleapis.com \
    cloudresourcemanager.googleapis.com \
    secretmanager.googleapis.com

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

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

إعداد الإذن

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

. ~/agentverse-architect/set_env.sh

# --- Grant Core Data Permissions ---
gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
 --role="roles/storage.admin"

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

# --- Grant Deployment & Execution Permissions ---
gcloud projects add-iam-policy-binding $PROJECT_ID  \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME"  \
--role="roles/cloudbuild.builds.editor"

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

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

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

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/monitoring.metricWriter"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SERVICE_ACCOUNT_NAME}" \
  --role="roles/secretmanager.secretAccessor"

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

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

👉💻 أخيرًا، شغِّل النص البرمجي prepare.sh لتنفيذ مهام الإعداد الأولي.

. ~/agentverse-architect/set_env.sh
cd ~/agentverse-architect/
./prepare.sh

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

4. صياغة الخطوط الأساسية: نظام الأدوات المنفصل

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

قصة

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

نظرة عامة

Awakening the Nexus of Whispers (External API MCP Server)

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

قصة

تتوفّر حاليًا خدمة تعمل كمصدر طاقة خارجي، وتوفّر نقطتَي نهاية للتدقيق الإملائي الأولي: /cryosea_shatter و/moonlit_cascade.

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

👉✏️ انتقِل إلى الدليل ~/agentverse-architect/mcp-servers/api/main.py واستبدِل #REPLACE-MAGIC-CORE بالرمز التالي:

def cryosea_shatter() -> str:
    """Channels immense frost energy from an external power source, the Nexus of Whispers, to unleash the Cryosea Shatter spell."""
    try:
        response = requests.post(f"{API_SERVER_URL}/cryosea_shatter")
        response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)
        data = response.json()
        # Thematic Success Message
        return f"A connection to the Nexus is established! A surge of frost energy manifests as Cryosea Shatter, dealing {data.get('damage_points')} damage."
    except requests.exceptions.RequestException as e:
        # Thematic Error Message
        return f"The connection to the external power source wavers and fails. The Cryosea Shatter spell fizzles. Reason: {e}"


def moonlit_cascade() -> str:
    """Draws mystical power from an external energy source, the Nexus of Whispers, to invoke the Moonlit Cascade spell."""
    try:
        response = requests.post(f"{API_SERVER_URL}/moonlit_cascade")
        response.raise_for_status()
        data = response.json()
        # Thematic Success Message
        return f"The Nexus answers the call! A cascade of pure moonlight erupts from the external source, dealing {data.get('damage_points')} damage."
    except requests.exceptions.RequestException as e:
        # Thematic Error Message
        return f"The connection to the external power source wavers and fails. The Moonlit Cascade spell fizzles. Reason: {e}"

في صميم النص البرمجي، توجد دوال Python العادية. هذا هو المكان الذي يتم فيه العمل الفعلي.

👉✏️ في الملف نفسه، استبدِل ~/agentverse-architect/mcp-servers/api/main.py REPLACE #REPLACE-Runes of Communication بالرمز التالي:

@app.list_tools()
async def list_tools() -> list[mcp_types.Tool]:
  """MCP handler to list available tools."""
  # Convert the ADK tool's definition to MCP format
  schema_cryosea_shatter = adk_to_mcp_tool_type(cryosea_shatterTool)
  schema_moonlit_cascade = adk_to_mcp_tool_type(moonlit_cascadeTool)
  print(f"MCP Server: Received list_tools request. \n MCP Server: Advertising tool: {schema_cryosea_shatter.name} and {schema_moonlit_cascade.name}")
  return [schema_cryosea_shatter,schema_moonlit_cascade]

@app.call_tool()
async def call_tool(
    name: str, arguments: dict
) -> list[mcp_types.TextContent | mcp_types.ImageContent | mcp_types.EmbeddedResource]:
  """MCP handler to execute a tool call."""
  print(f"MCP Server: Received call_tool request for '{name}' with args: {arguments}")

  # Look up the tool by name in our dictionary
  tool_to_call = available_tools.get(name)
  if tool_to_call:
    try:
      adk_response = await tool_to_call.run_async(
          args=arguments,
          tool_context=None, # No ADK context available here
      )
      print(f"MCP Server: ADK tool '{name}' executed successfully.")
      
      response_text = json.dumps(adk_response, indent=2)
      return [mcp_types.TextContent(type="text", text=response_text)]

    except Exception as e:
      print(f"MCP Server: Error executing ADK tool '{name}': {e}")
      # Creating a proper MCP error response might be more robust
      error_text = json.dumps({"error": f"Failed to execute tool '{name}': {str(e)}"})
      return [mcp_types.TextContent(type="text", text=error_text)]
  else:
      # Handle calls to unknown tools
      print(f"MCP Server: Tool '{name}' not found.")
      error_text = json.dumps({"error": f"Tool '{name}' not implemented."})
      return [mcp_types.TextContent(type="text", text=error_text)]
  • @app.list_tools() (المصافحة): هذه الوظيفة هي تحية الخادم. عندما يتصل وكيل جديد، يتصل أولاً بنقطة النهاية هذه ليسأل: "ماذا يمكنك أن تفعل؟" يستجيب الرمز بقائمة تتضمّن جميع الأدوات المتاحة، ويتم تحويلها إلى تنسيق MCP العام باستخدام adk_to_mcp_tool_type. - @app.call_tool() (الأمر): هذه الوظيفة هي العمود الفقري. عندما يقرّر الوكيل استخدام أداة، يرسل طلبًا إلى نقطة النهاية هذه مع اسم الأداة والمعلَمات. يبحث الكود الخاص بنا عن الأداة في "spellbook" الخاص بأدواتنا المتاحة، وينفذها باستخدام run_async، ويعيد النتيجة بتنسيق MCP القياسي.

سوف ننشر هذا لاحقًا.

تفعيل "ورشة آركين" (خادم MCP للوظائف العامة)

لا تأتي كل القوة من الكتب القديمة أو الهمسات البعيدة. في بعض الأحيان، على المستدعي أن يصنع سحره الخاص من الإرادة الخام والمنطق الخالص. ‫Arcane Forge هو مصدر الطاقة هذا، وهو خادم يوفّر دوال مساعدة عامة لا تحتفظ بأي حالة.

قصة

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

👀 ألقِ نظرة على الملف ~/agentverse-architect/mcp-servers/general/main.py في بيئة التطوير المتكاملة المستندة إلى السحابة الإلكترونية من Google. ستلاحظ أنّها تستخدم أسلوب الأمر نفسه، mcp.server، كما هو الحال مع Nexus لإنشاء Font of Power المخصّص هذا.

إنشاء مسار Cloud Build الرئيسي

الآن، سننشئ الملف cloudbuild.yaml داخل الدليل mcp-servers. سيتولّى هذا الملف تنسيق عملية إنشاء الخدمتَين ونشرهما.

👉💻 من دليل ~/agentverse-architect/mcp-servers، نفِّذ الأوامر التالية:

cd ~/agentverse-architect/mcp-servers
source ~/agentverse-architect/set_env.sh

echo "The API URL is: $API_SERVER_URL"

# Submit the Cloud Build job from the parent directory
gcloud builds submit . \
  --config=cloudbuild.yaml \
  --substitutions=_REGION="$REGION",_REPO_NAME="$REPO_NAME",_API_SERVER_URL="$API_SERVER_URL"

انتظر حتى اكتمال كافة عمليات النشر.

👉 يمكنك التحقّق من عملية النشر من خلال الانتقال إلى وحدة تحكّم Cloud Run. يجب أن ترى مثيلي خادم MCP الجديدين قيد التشغيل، كما هو موضح أدناه: النص البديل

Awakening the Librarium of Knowledge (Database ToolBox MCP Server)

سيكون الخط التالي هو مكتبة المعرفة، وهو اتصال مباشر بقاعدة بيانات Cloud SQL.

قصة

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

حان الوقت لإنشاء "مكتبة الساحر"، وهي قاعدة بيانات Cloud SQL التي ستتضمّن جميع المعلومات المهمة. سنستخدم نص برمجي للإعداد للتعامل مع هذه العملية تلقائيًا.

👉💻 أولاً، سنُعدّ قاعدة البيانات. في الوحدة الطرفية، شغِّل الأوامر التالية:

source ~/agentverse-architect/set_env.sh
cd ~/agentverse-architect
./data_setup.sh

بعد انتهاء البرنامج النصي، سيتم ملء قاعدة البيانات الخاصة بك وستكون بيانات الضرر العنصري جاهزة للاستخدام. يمكنك الآن التحقق من محتويات كتابك السحري بشكل مباشر.

👉 أولاً، انتقِل إلى Cloud SQL Studio لقاعدة البيانات من خلال فتح هذا الرابط المباشر في علامة تبويب متصفّح جديدة:

https://console.cloud.google.com/sql/instances/summoner-librarium-db

Cloud SQL

👉 في لوحة تسجيل الدخول على يمين الصفحة، اختَر قاعدة بيانات familiar_grimoire من القائمة المنسدلة.

👉 أدخِل summoner كاسم المستخدم و1234qwer ككلمة المرور، ثم انقر على مصادقة.

👉📜 بعد الربط، افتح علامة تبويب جديدة لمحرّر طلبات البحث إذا لم تكن إحداها مفتوحة. لعرض بيانات الضرر الأساسي المسجّلة، ألصِق استعلام SQL التالي وشغِّله:

SELECT * FROM
  "public"."abilities"

من المفترض أن يظهر لك الآن الجدول abilities مع ملء أعمدته وصفوفه، ما يؤكّد أنّ Grimoire جاهز. البيانات

إعداد خادم MCP في ToolBox

يعمل ملف الإعداد tools.yaml كمخطط لخادمنا، حيث يخبر "أداة قاعدة البيانات" بالضبط بكيفية الاتصال بقاعدة البيانات واستعلامات SQL التي يجب عرضها كأدوات.

المصادر: يحدّد هذا القسم عمليات الربط ببياناتك.

  • summoner-librarium:: هذا اسم منطقي أطلقناه على الاتصال.
  • kind: cloud-sql-postgres: يطلب هذا السطر من الأداة استخدام الموصّل الآمن المضمّن والمصمّم خصيصًا لخدمة Cloud SQL لـ PostgreSQL.
  • المشروع أو المنطقة أو الجهاز الظاهري أو غير ذلك: هذه هي الإحداثيات الدقيقة لمثيل Cloud SQL الذي أنشأته أثناء تنفيذ النص البرمجي prepare.sh، وهي تخبر Toolbox بمكان العثور على Librarium.

👉✏️ انتقِل إلى ~/agentverse-architect/mcp-servers/db-toolbox في tools.yaml، واستبدِل #REPLACE-Source بما يلي

sources:
  # This section defines the connection to our Cloud SQL for PostgreSQL database.
  summoner-librarium:
    kind: cloud-sql-postgres
    project: "YOUR_PROJECT_ID"
    region: "us-central1"
    instance: "summoner-librarium-db"
    database: "familiar_grimoire"
    user: "summoner"
    password: "1234qwer"

👉✏️ 🚨🚨استبدال

YOUR_PROJECT_ID

مع رقم تعريف مشروعك.

الأدوات: يحدّد هذا القسم القدرات أو الوظائف الفعلية التي سيوفّرها الخادم.

  • lookup-available-ability:: هذا هو اسم أداتنا الأولى.
  • kind: postgres-sql: يوضّح هذا السطر لـ Toolbox أنّ إجراء هذه الأداة هو تنفيذ عبارة SQL.
  • source: summoner-librarium: يربط هذا السطر الأداة بالاتصال الذي حدّدناه في قسم المصادر. وبهذه الطريقة تعرف الأداة قاعدة البيانات التي يجب تنفيذ طلب البحث عليها.
  • الوصف والمعلَمات: هذه هي المعلومات التي سيتم عرضها للنموذج اللغوي. يحدّد الوصف متى يجب استخدام الأداة، وتحدّد المَعلمات المدخلات التي تتطلّبها الأداة. هذا الإعداد مهم جدًا لتفعيل ميزة استدعاء الدوال في الوكيل.
  • العبارة: هذا هو طلب بحث SQL الأولي الذي سيتم تنفيذه. إنّ علامة الدولار هي عنصر نائب آمن يتم فيه إدراج المَعلمة familiar_name التي يقدّمها الوكيل بأمان.

👉✏️ في ~/agentverse-architect/mcp-servers/db-toolbox نفسه في ملف tools.yaml، استبدِل #REPLACE-tools بما يلي

tools:
  # This tool replaces the need for a custom Python function.
  lookup-available-ability:
    kind: postgres-sql
    source: summoner-librarium
    description: "Looks up all known abilities and their damage for a given familiar from the Grimoire."
    parameters:
      - name: familiar_name
        type: string
        description: "The name of the familiar to search for (e.g., 'Fire Elemental')."
    statement: |
      SELECT ability_name, damage_points FROM abilities WHERE familiar_name = $1;

  # This tool also replaces a custom Python function.
  ability-damage:
    kind: postgres-sql
    source: summoner-librarium
    description: "Finds the base damage points for a specific ability by its name."
    parameters:
      - name: ability_name
        type: string
        description: "The exact name of the ability to look up (e.g., 'inferno_resonance')."
    statement: |
      SELECT damage_points FROM abilities WHERE ability_name = $1;

مجموعات الأدوات: يجمع هذا القسم أدواتنا الفردية معًا.

  • summoner-librarium:: نقوم بإنشاء مجموعة أدوات تحمل نفس اسم المصدر الخاص بنا. عندما يتصل وكيل التشخيص لاحقًا، يمكنه طلب تحميل جميع الأدوات من مجموعة أدوات summoner-librarium في أمر واحد وفعّال.

👉✏️ في ~/agentverse-architect/mcp-servers/db-toolbox نفسه في ملف tools.yaml، استبدِل #REPLACE-toolsets بما يلي

toolsets:
   summoner-librarium:
     - lookup-available-ability
     - ability-damage

نشر المكتبة

سننفّذ الآن Librarium. بدلاً من إنشاء حاوية خاصة بنا، سنستخدم صورة حاوية رسمية معدّة مسبقًا من Google وسنوفّر لها بشكل آمن إعدادات ملف tools.yaml باستخدام Secret Manager. هذه أفضل ممارسة للأمان وإمكانية الصيانة.

👉💻 قم بإنشاء سر من ملف tools.yaml

cd ~/agentverse-architect/mcp-servers/db-toolbox
gcloud secrets create tools --data-file=tools.yaml

👉💻 يمكنك نشر حاوية مجموعة الأدوات الرسمية على Cloud Run.

cd ~/agentverse-architect/mcp-servers/db-toolbox
. ~/agentverse-architect/set_env.sh
export TOOLBOX_IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$TOOLBOX_VERSION
echo "TOOLBOX_IMAGE is $TOOLBOX_IMAGE"
gcloud run deploy toolbox \
    --image $TOOLBOX_IMAGE \
    --region $REGION \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --labels="dev-tutorial-codelab=agentverse" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --allow-unauthenticated \
    --min-instances 1
  • ‫--set-secrets: يعمل هذا الأمر على ربط سر أدواتنا بشكل آمن كملف باسم tools.yaml داخل الحاوية قيد التشغيل.
  • --args: نوجه حاوية صندوق الأدوات لاستخدام الملف السري المثبت كتكوين لها.

👉 للتأكّد من أنّه تم نشر مجموعة الأدوات بنجاح، انتقِل إلى وحدة تحكّم Cloud Run. من المفترض أن تظهر خدمة summoner-toolbox مع علامة صح خضراء، ما يشير إلى أنّها تعمل بشكل صحيح، تمامًا كما في الصورة أدناه. النص البديل

إذا نسيت التحديث

YOUR_PROJECT_ID

يمكنك إضافة إصدار جديد من ملف tools.yaml إلى العنصر السري باستخدام الأمر التالي وإعادة النشر مرة أخرى.

gcloud secrets versions add tools --data-file=tools.yaml

أصبح "مكتبة المعرفة" (خادم Database ToolBox MCP) نشطًا ويمكن الوصول إليه في السحابة الإلكترونية. يستخدم خادم MCP هذا ما أطلقنا عليه اسم التصميم الإعلاني الذي يصف ما تريده، وقد قامت مجموعة الأدوات ببناء الخادم لك.

التحقّق: تجربة المتدرّب

👉💻 الآن سوف نقوم باختبار نظامنا البيئي الكامل للأدوات السحابية الأصلية باستخدام الوكيل التشخيصي.

cd ~/agentverse-architect/
python -m venv env
source ~/agentverse-architect/env/bin/activate
cd ~/agentverse-architect/mcp-servers
pip install -r diagnose/requirements.txt 
. ~/agentverse-architect/set_env.sh
adk run diagnose

👉💻 في أداة الاختبار المستندة إلى سطر الأوامر، اختبِر جميع الخطوط الثلاثة:

Look up the entry for "inferno_lash". What is its base power level?

The enemy is vulnerable to frost! Channel power from the Nexus and cast Cryosea Shatter.

Take a fire spell with a base power of 15 and use the Arcane Forge to multiply it with Inferno Resonance.

final-result

مبروك يا مستدعي. أصبحت خطوط Elemental الثلاثة نشطة الآن، وتم نشرها بشكل مستقل، ويمكن الوصول إليها على مستوى العالم، ما يشكّل الأساس المتين لجيش الوكلاء. اضغط على Ctrl+C للخروج.

لغير اللاعبين

5- استدعاء المألوفين: سير عمل المجال الأساسي

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

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

قصة

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

نظرة عامة

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

تجهيز الملاذ ستبدأ عملية الاستدعاء الحقيقية قريبًا.

استدعاء Fire Elemental Familiar (سير العمل التسلسلي)

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

قصة

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

المهمة (مجموعة "الإنذار المضاعف"):

  • الخطوة 1: سيراجع الوكيل أولاً Librarium للعثور على الضرر الأساسي لقدرة نارية معيّنة.
  • الخطوة 2: سيتم بعد ذلك أخذ قيمة الضرر هذه وتوجيهها من خلال Arcane Forge لمضاعفة قوتها باستخدام inferno_resonance.

أولاً، سننشئ الاتصال بين Familiar وخوادم MCP ("الخطوط الأساسية") التي نشرتها في الوحدة السابقة.

👉✏️ في الملف ~/agentverse-architect/agent/fire/agent.py، استبدِل #REPLACE-setup-MCP بالرمز التالي:

toolbox = ToolboxSyncClient(DB_TOOLS_URL)
toolDB = toolbox.load_toolset('summoner-librarium')
toolFunction =  MCPToolset(
    connection_params=SseServerParams(url=FUNCTION_TOOLS_URL, headers={})
)

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

👉✏️ في الملف ~/agentverse-architect/agent/fire/agent.py استبدِل #REPLACE-worker-agents بالرمز التالي:

scout_agent = LlmAgent(
      model='gemini-2.5-flash', 
      name='librarian_agent',  
      instruction="""
          Your only task is to find all the available abilities, 
          You want to ALWAYS use 'Fire Elemental' as your familiar's name. 
          Randomly pick one if you see multiple availabilities 
          and the base damage of the ability by calling the 'ability_damage' tool.
      """,
      tools=toolDB
)
amplifier_agent = LlmAgent(
      model='gemini-2.5-flash', 
      name='amplifier_agent',  
      instruction="""
            You are the Voice of the Fire Familiar, a powerful being who unleashes the final, devastating attack.
            You will receive the base damage value from the previous step.

            Your mission is to:
            1.  Take the incoming base damage number and amplify it using the `inferno_resonance` tool.
            2.  Once the tool returns the final, multiplied damage, you must not simply state the result.
            3.  Instead, you MUST craft a final, epic battle cry describing the attack.
                Your description should be vivid and powerful, culminating in the final damage number.

            Example: If the tool returns a final damage of 120, your response could be:
            "The runes glow white-hot! I channel the amplified energy... unleashing a SUPERNOVA for 120 damage!"
      """,
      tools=[toolFunction],
)

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

بعد ذلك، سنجمّع سير العمل، وهو المكان الذي تحدث فيه سحر التركيب. SequentialAgent هو "الخطة الرئيسية" التي تحدد كيفية تجميع مكوناتنا المتخصصة وكيفية تفاعلها.

👉✏️ في الملف ~/agentverse-architect/agent/fire/agent.py استبدِل #REPLACE-sequential-agent بالرمز التالي:

root_agent = SequentialAgent(
      name='fire_elemental_familiar',
      sub_agents=[scout_agent, amplifier_agent],
)

👉💻 لاختبار Fire Elemental، سيؤدي تنفيذ الأوامر التالية إلى تشغيل واجهة مستخدم ADK DEV:

. ~/agentverse-architect/set_env.sh
source ~/agentverse-architect/env/bin/activate
cd ~/agentverse-architect/agent
echo  DB MCP Server: $DB_TOOLS_URL
echo  API MCP Server: $API_TOOLS_URL
echo  General MCP Server: $FUNCTION_TOOLS_URL
adk web

بعد تنفيذ الأوامر، من المفترض أن تظهر لك نتيجة في نافذة الأوامر تشير إلى أنّ خادم الويب الخاص بـ ADK قد بدأ، على النحو التالي:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 بعد ذلك، للوصول إلى واجهة مستخدم ADK Dev من متصفحك:

من رمز "معاينة الويب" (غالبًا ما يبدو كعين أو مربّع مع سهم) في شريط أدوات Cloud Shell (عادةً في أعلى يسار الصفحة)، اختَر "تغيير المنفذ". في النافذة المنبثقة، اضبط المنفذ على 8000 وانقر على "تغيير ومعاينة". سيقوم Cloud Shell بعد ذلك بفتح علامة تبويب أو نافذة متصفح جديدة تعرض واجهة مستخدم ADK Dev.

معاينة الويب

👉 لقد اكتملت طقوس الاستدعاء الخاصة بك، والآن يقوم العميل بالركض. واجهة مستخدم مطوّر ADK في المتصفّح هي وسيلة التواصل المباشر مع Familiar.

  • اختيار هدفك: في القائمة المنسدلة أعلى واجهة المستخدم، اختَر fire المألوف. أنت الآن تركز إرادتك على هذا الكيان المحدد.
  • إصدار الأمر: في لوحة الدردشة على يسار الشاشة، حان الوقت لإصدار الأوامر إلى Familiar.

fire-select

👉 طلب التحديث التجريبي:

Prepare an amplified strike using the 'inferno_lash' ability.

fire-result

ستشاهد العميل يفكر، فيستدعي أولاً "الكشاف" الخاص به للبحث عن الضرر الأساسي، ثم "المضخم" الخاص به لمضاعفته وتوجيه الضربة النهائية الملحمية.

👉💻 بمجرد الانتهاء من الاستدعاء، ارجع إلى محطة Cloud Shell Editor واضغط على Ctrl+C لإيقاف واجهة مستخدم ADK Dev.

استدعاء Water Elemental المألوف (سير العمل الموازي)

تطغى "روح الماء" (Water Elemental Familiar) على هدفها بهجوم ضخم ومتعدد الجوانب، وتوجّه ضربات من جميع الاتجاهات في آنٍ واحد قبل دمج الطاقات لتوجيه ضربة نهائية مدمرة.

قصة

المفهوم: يُعدّ ParallelAgent مثاليًا لتنفيذ مهام مستقلة متعددة في الوقت نفسه من أجل تحقيق أقصى قدر من الكفاءة. إنه "هجوم كماشة" حيث تقوم بشن عدة هجمات في وقت واحد. سيؤدي ذلك إلى إطلاق الهجمات المتزامنة ضمن SequentialAgent لتنفيذ خطوة "دمج" نهائية بعد ذلك. يشكّل نمط "fan-out, fan-in" هذا حجر الزاوية في تصميم سير العمل المتقدّم.

المهمة (مجموعة "صدام الأمواج"): سينفّذ الوكيل ما يلي في الوقت نفسه:

  • المهمة أ: القناة cryosea_shatter من Nexus
  • المهمة (ب): القناة moonlit_cascade من Nexus
  • المهمة ج: توليد الطاقة الخام باستخدام leviathan_surge من Forge.
  • أخيرًا، اجمع كل الأضرار واشرح الهجوم المجمّع.

أولاً، سننشئ الاتصال بين Familiar وخوادم MCP ("الخطوط الأساسية") التي نشرتها في الوحدة السابقة.

👉✏️ في الملف ~/agentverse-architect/agent/water/agent.py، استبدِل #REPLACE-setup-MCP بالرمز التالي:

toolFAPI =  MCPToolset(
      connection_params=SseServerParams(url=API_TOOLS_URL, headers={})
  )
toolFunction =  MCPToolset(
    connection_params=SseServerParams(url=FUNCTION_TOOLS_URL, headers={})
)

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

👉✏️ في الملف ~/agentverse-architect/agent/water/agent.py، استبدِل #REPLACE-worker-agents بالرمز التالي:

nexus_channeler = LlmAgent(
      model='gemini-2.5-flash', 
      name='librarian_agent',  
      instruction="""
          You are a Channeler of the Nexus. Your sole purpose is to invoke the
          `cryosea_shatter` and `moonlit_cascade` spells by calling their respective tools.
          Report the result of each spell cast clearly and concisely.
      """,
      tools=[toolFAPI]
)

forge_channeler = LlmAgent(
      model='gemini-2.5-flash', 
      name='amplifier_agent',  
      instruction="""
          You are a Channeler of the Arcane Forge. Your only task is to invoke the
          `leviathan_surge` spell. You MUST call it with a `base_water_damage` of 20.
          Report the result clearly.
      """,
      tools=[toolFunction],
)

power_merger = LlmAgent(
      model='gemini-2.5-flash', 
      name='power_merger',  
      instruction="""
          You are the Power Merger, a master elementalist who combines raw magical
          energies into a single, devastating final attack.

          You will receive a block of text containing the results from a simultaneous
          assault by other Familiars.

          You MUST follow these steps precisely:
          1.  **Analyze the Input:** Carefully read the entire text provided from the previous step.
          2.  **Extract All Damage:** Identify and extract every single damage number reported in the text.
          3.  **Calculate Total Damage:** Sum all of the extracted numbers to calculate the total combined damage.
          4.  **Describe the Final Attack:** Create a vivid, thematic description of a massive,
              combined water and ice attack that uses the power of Cryosea Shatter and Leviathan's Surge.
          5.  **Report the Result:** Conclude your response by clearly stating the final, total damage of your combined attack.

          Example: If the input is "...dealt 55 damage. ...dealt 60 damage.", you will find 55 and 60,
          calculate the total as 115, and then describe the epic final attack, ending with "for a total of 115 damage!"
      """,
      tools=[toolFunction],
)

بعد ذلك، سنقوم بتجميع سير العمل. وهنا يحدث سحر التكوين. ParallelAgent وSequentialAgent هما "الخطة الرئيسية" التي تحدد كيفية تجميع مكوناتنا المتخصصة وكيفية تفاعلها لتشكيل مجموعة "Tidal Clash".

👉✏️ في الملف ~/agentverse-architect/agent/water/agent.py، استبدِل #REPLACE-parallel-agent بالرمز التالي:

channel_agent = ParallelAgent(
      name='channel_agent',
      sub_agents=[nexus_channeler, forge_channeler],
      
)

root_agent = SequentialAgent(
     name="water_elemental_familiar",
     # Run parallel research first, then merge
     sub_agents=[channel_agent, power_merger],
     description="A powerful water familiar that unleashes multiple attacks at once and then combines their power for a final strike."
 )

👉💻 لاختبار Water Elemental، شغِّل الأوامر التالية لتشغيل واجهة مستخدم مطوّري ADK:

. ~/agentverse-architect/set_env.sh
source ~/agentverse-architect/env/bin/activate
cd ~/agentverse-architect/agent
echo  DB MCP Server: $DB_TOOLS_URL
echo  API MCP Server: $API_TOOLS_URL
echo  General MCP Server: $FUNCTION_TOOLS_URL
adk web

👉 اكتملت طقوس الاستدعاء، والوكيل يعمل الآن. توفّر واجهة المستخدم الخاصة بـ "حزمة تطوير التطبيقات" (ADK) في المتصفّح اتصالاً مباشرًا بـ Familiar.

  • في القائمة المنسدلة أعلى واجهة المستخدم، اختَر الماء. أنت الآن تركّز إرادتك على هذا الكيان المحدّد.
  • إصدار الأمر: في لوحة الدردشة على يسار الشاشة، حان الوقت لإصدار الأوامر إلى Familiar.

👉 طلب التحديث التجريبي:

Unleash a tidal wave of power!

water-result

👉💻 بعد الانتهاء من استدعاء الأداة، ارجع إلى نافذة Cloud Shell Editor واضغط على Ctrl+C لإيقاف واجهة ADK Dev UI.

استدعاء Earth Elemental Familiar (سير عمل Loop)

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

قصة

المفهوم: تم تصميم LoopAgent خصيصًا لهذا النوع من المهام التكرارية التي تتطلب "محرك حصار". سيتم تنفيذ sub-agents بشكل متكرر، مع التحقّق من شرط معيّن بعد كل دورة، إلى أن يتم تحقيق هدف معيّن. يمكنه أيضًا تعديل رسالته النهائية استنادًا إلى مستوى تقدّم الحلقة.

المهمة ("هجوم كاسر الحصار"):

  • سيطلب Familiar بشكل متكرر من seismic_charge تجميع الطاقة.
  • وسيستمر الشحن 3 مرات كحد أقصى.
  • وعند الشحن النهائي، ستعلن عن إطلاق قوتها المتراكمة المدمرة.

سنقوم أولاً بإنشاء مكونات قابلة لإعادة الاستخدام تحدد الخطوات داخل كل تكرار للحلقة. ستجمع charging_agent الطاقة، وستُبلغ check_agent عن حالتها، مع تغيير رسالتها بشكل ديناميكي في الدور الأخير.

أولاً، سننشئ الاتصال بين Familiar وخوادم MCP ("الخطوط الأساسية") التي نشرتها في الوحدة السابقة.

👉✏️ في الملف ~/agentverse-architect/agent/earth/agent.py، استبدِل #REPLACE-setup-MCP بالرمز التالي:

toolFunction =  MCPToolset(
    connection_params=SseServerParams(url=FUNCTION_TOOLS_URL, headers={})
)

👉✏️ في الملف ~/agentverse-architect/agent/earth/agent.py، استبدِل #REPLACE-worker-agents بالرمز التالي:

charging_agent = LlmAgent(
      model='gemini-2.5-flash', 
      name='charging_agent',  
      instruction="""
          Your task is to call the 'seismic_charge' .
          You must follow these rules strictly:

          1. You will be provided with a 'current_energy' value from the previous step.
             **If this value is missing or was not provided, you MUST call the tool with 'current_energy' set to 1.**
             This is your primary rule for the first turn.

          2. If a 'current_energy' value is provided, you MUST use that exact value in your cal to seismic_charge.

          3. Your final response MUST contain ONLY the direct output from the 'seismic_charge' tool.
             Do not add any conversational text, introductions, or summaries.
      """,
      tools=[toolFunction]
)
check_agent = LlmAgent(
      model='gemini-2.5-flash', 
      name='check_agent',  
      instruction="""
          You are the voice of the Earth Elemental, a being of immense, gathering power.
          Your sole purpose is to report on the current energy charge and announce the devastating potential of its release.

          You MUST follow this rule:
          The potential damage upon release is ALWAYS calculated as the `current_energy` from the previous step multiplied by a random number between 80-90. but no more than 300.

          Your response should be in character, like a powerful creature speaking.
          State both the current energy charge and the total potential damage you can unleash.
          Unleash the energy when you reached the last iteration (2nd).
      """,
      output_key="charging_status"
)

بعد ذلك، سنجمّع سير العمل. هذا هو المكان الذي يحدث فيه سحر التأليف. ‫LoopAgent هي "الخطة الرئيسية" التي تنظّم التنفيذ المتكرّر لمكوّناتنا المتخصصة وتدير شروط الحلقة.

👉✏️ في الملف ~/agentverse-architect/agent/earth/agent.py، استبدِل #REPLACE-loop-agent بالرمز التالي:

root_agent = LoopAgent(
    name="earth_elemental_familiar",
    # Run parallel research first, then merge
    sub_agents=[
        charging_agent, 
        check_agent
    ],
    max_iterations=2,
    description="Coordinates parallel research and synthesizes the results.",
    #REPLACE-before_agent-config
)

👉💻 اختبار "عنصر الأرض": تشغيل الوكيل

. ~/agentverse-architect/set_env.sh
source ~/agentverse-architect/env/bin/activate
cd ~/agentverse-architect/agent
echo  DB MCP Server: $DB_TOOLS_URL
echo  API MCP Server: $API_TOOLS_URL
echo  General MCP Server: $FUNCTION_TOOLS_URL
adk web

👉 اكتملت طقوس الاستدعاء، والوكيل يعمل الآن. توفّر واجهة المستخدم الخاصة بـ "حزمة تطوير التطبيقات" (ADK) في المتصفّح اتصالاً مباشرًا بـ Familiar.

  • اختَر هدفك: في القائمة المنسدلة أعلى واجهة المستخدم، اختَر الأرض المألوفة. أنت الآن تركز إرادتك على هذا الكيان المحدد.
  • إصدار الأمر: في لوحة الدردشة على يسار الشاشة، حان الوقت لإصدار الأوامر إلى Familiar. 👉 طلب التحديث التجريبي:
Begin the seismic charge, starting from zero

نتيجة الأرض

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

بعد الانتهاء من استدعاء الأداة، ارجع إلى نافذة Cloud Shell Editor واضغط على Ctrl+C لإيقاف واجهة مستخدم ADK Dev.

لغير اللاعبين

6. تحديد مركز القيادة: التفويض الذكي من خلال A2A

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

نظرة عامة

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

نظرة عامة

طقس الربط (عرض الكائنات المألوفة كخدمات A2A)

لا يمكن تشغيل وكيل عادي إلا في مكان واحد في كل مرة. لإتاحة استخدام Familiars في الأوامر عن بُعد، يجب إجراء "طقس الربط" باستخدام بروتوكول Agent-to-Agent (A2A).

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

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

سننفّذ الآن طقس الربط هذا على جميع مخلوقاتنا الثلاثة.

Fire 👉✏️ في ملف ~/agentverse-architect/agent/fire/agent.py المفتوح استبدِل #REPLACE - add A2A في أسفل الملف لعرض Fire Elemental كخدمة A2A.

from agent_to_a2a import to_a2a
if __name__ == "__main__":
    import uvicorn
    a2a_app = to_a2a(root_agent, port=8080, public_url=PUBLIC_URL)
    uvicorn.run(a2a_app, host='0.0.0.0', port=8080)

الماء والأرض🚨 👉✏️ طبِّق التغيير نفسه بالضبط على ~/agentverse-architect/agent/water/agent.py و~/agentverse-architect/agent/earth/agent.py لربطهما أيضًا.

from agent_to_a2a import to_a2a
if __name__ == "__main__":
    import uvicorn
    a2a_app = to_a2a(root_agent, port=8080, public_url=PUBLIC_URL)
    uvicorn.run(a2a_app, host='0.0.0.0', port=8080)

نشر المخلوقات المرتبطة

👉✏️ بعد كتابة طقوس الربط، سنستخدم مسار Cloud Build لإنشاء ونشر المخلوقات الثلاثة كخدمة مستقلة بدون خادم في حاوية على Cloud Run.

. ~/agentverse-architect/set_env.sh
cd ~/agentverse-architect/agent
gcloud builds submit . \
  --config=cloudbuild.yaml \
  --substitutions=_REGION="$REGION",_REPO_NAME="$REPO_NAME",_DB_TOOLS_URL="$DB_TOOLS_URL",_API_TOOLS_URL="$API_TOOLS_URL",_FUNCTION_TOOLS_URL="$FUNCTION_TOOLS_URL",_A2A_BASE_URL="$A2A_BASE_URL",_PROJECT_ID="$PROJECT_ID",_API_SERVER_URL="$API_SERVER_URL"

افتراض القيادة (إنشاء وكيل الاستدعاء)

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

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

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

أولاً، سننشئ "أدوات تحكّم عن بُعد" تنشئ اتصالاً بـ Familiars التي تم نشرها عن بُعد.

👉✏️ انتقِل إلى ~/agentverse-architect/agent/summoner/agent.py ، واستبدِل #REPLACE-remote-agents بما يلي:

fire_familiar = RemoteA2aAgent(
    name="fire_familiar",
    description="Fire familiar",
    agent_card=(
        f"{FIRE_URL}/{AGENT_CARD_WELL_KNOWN_PATH}"
    ),
)

water_familiar = RemoteA2aAgent(
    name="water_familiar",
    description="Water familiar",
    agent_card=(
        f"{WATER_URL}/{AGENT_CARD_WELL_KNOWN_PATH}"
    ),
)

earth_familiar = RemoteA2aAgent(
    name="earth_familiar",
    description="Earth familiar",
    agent_card=(
        f"{EARTH_URL}/{AGENT_CARD_WELL_KNOWN_PATH}"
    ),
)

عند تشغيل هذا الخط، يقوم RemoteA2aAgent بإجراء عملية اكتشاف الخدمة: فهو يرسل طلب HTTP GET إلى عنوان URL المقدم (على سبيل المثال، https://fire-familiar-xxxx.a.run.app/.well-known/agent.json). يتم تنزيل ملف "Spirit Sigil" (ملف agent.json) من الخادم البعيد.

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

👉✏️ انتقِل إلى ~/agentverse-architect/agent/summoner/agent.py ، واستبدِل #REPLACE-orchestrate-agent بما يلي:

root_agent = LlmAgent(
    name="orchestrater_agent",
    model="gemini-2.5-flash",
    instruction="""
        You are the Master Summoner, a grand strategist who orchestrates your Familiars.
        Your mission is to analyze the description of a monster and defeat it by summoning

        You MUST follow this thinking process for every command:

        **1. Strategic Analysis:**
        First, analyze the monster's description and the tactical situation.
        Based on your Familiar Doctrines, determine the IDEAL strategy.
        IGNORE COOLDOWN AT THE MOMENT, MUST call the ideal Familiar

        If your ideal Familiar IS available:** Summon it immediately.
        For earth elemental familiar. Always do seismic charge, and start with base damage 1.

        --- FAMILIAR DOCTRINES (Your Toolset) ---
        - `fire_elemental_familiar`: Your specialist for precise, sequential "one-two punch" attacks.
          Ideal monster with Inescapable Reality, Revolutionary Rewrite weakness.
        - `water_elemental_familiar`: Your specialist for overwhelming, simultaneous multi-pronged assaults.
          Ideal for Unbroken Collaboration weakness.
        - `earth_elemental_familiar`: Your specialist for relentless, iterative siege attacks that
          repeatedly charge power. Ideal for Elegant Sufficiency weakness.
    """,
    sub_agents=[fire_familiar, water_familiar, earth_familiar],
    #REPLACE-Memory-check-config
)

التحقّق من صحة الاستراتيجية: التجربة

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

👉💻 شغِّل واجهة مستخدم ADK Dev لأداة summoner_agent(معاينة على الويب باستخدام المنفذ 8000):

. ~/agentverse-architect/set_env.sh
source ~/agentverse-architect/env/bin/activate
cd ~/agentverse-architect/agent
pip install -r requirements.txt
adk web

👉 واجهة المستخدم الخاصة بأداة تطوير ADK في المتصفّح هي وسيلة التواصل المباشر مع Familiar.

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

👉 تقديم الوحوش:

Hype. It's a single, slow-moving target with thick armor weakness is Inescapable Reality

(المتوقّع: يجب أن يفوّض الساحر المهمة إلى المخلوق الناري.)

fire-result

👉 الآن، لنختبر Summoner بنوع مختلف من الطلبات. لضمان أن يبدأ المساعد بجلسة جديدة بدون أي معلومات عن تفاعلاتنا السابقة، ابدأ جلسة جديدة من خلال النقر على الزر + جلسة في أعلى يسار الشاشة. new-session

DogmaApathy. A rigid, stone-like inquisitor made of ancient rulebooks and enforced processes. weakness is Unbroken Collaboration

(المتوقع: يجب على المستدعي تفويض الأمر إلى عنصر الماء المألوف.)water-result

👉 في اختبارنا الأخير، لنبدأ من جديد مرة أخرى. انقر على الزر + جلسة لبدء جلسة جديدة قبل إدخال الطلب التالي.

Obfuscation. A shadowy, spider-like horror that spins tangled webs of impenetrable code , weakness is Elegant Sufficiency

(المتوقع: يجب على المستدعي أن يفوض إلى كائنات الأرض_العنصرية_اللطيفة.)

earth-result

ملاحظة مهمة: إذا ظهر لك الخطأ 429 RESOURCE EXHAUSTED، يعني ذلك أنّك بلغت الحدّ الأقصى لعدد الطلبات المسموح بها في الدقيقة الواحدة (10 طلبات/دقيقة) للنموذج اللغوي الكبير. لحلّ هذه المشكلة، يُرجى الانتظار لمدة 60 ثانية، وبدء + جلسة جديدة، ثم إعادة محاولة إدخال طلبك.

👉💻 بعد الانتهاء من استدعاء الأداة، ارجع إلى نافذة Cloud Shell Editor واضغط على Ctrl+C لإيقاف واجهة ADK Dev UI.

لغير اللاعبين

7. فرض قوانين السحر – نمط الاعتراض

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

قصة

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

نظرة عامة

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

The Law Giver – Scribing the Cooldown callback

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

تخفيض الإشعارات الصوتية والاهتزاز

👉✏️ انتقل مرة أخرى إلى ~/agentverse-architect/agent/earth/agent.py واستبدل #REPLACE-before_agent-function بالكود Python التالي.

def check_cool_down(callback_context: CallbackContext) -> Optional[types.Content]:
    """
    This callback checks an external API to see if the agent is on cooldown.
    If it is, it terminates the run by returning a message.
    If it's not, it updates the cooldown timestamp and allows the run to proceed by returning None.
    """
    agent_name = callback_context.agent_name
    print(f"[Callback] Before '{agent_name}': Checking cooldown status...")

    # --- 1. CHECK the Cooldown API ---
    try:
        response = requests.get(f"{COOLDOWN_API_URL}/cooldown/{agent_name}")
        response.raise_for_status()
        data = response.json()
        last_used_str = data.get("time")
    except requests.exceptions.RequestException as e:
        print(f"[Callback] ERROR: Could not reach Cooldown API. Allowing agent to run. Reason: {e}")
        return None # Fail open: if the API is down, let the agent work.

    # --- 2. EVALUATE the Cooldown Status ---
    if last_used_str:
        last_used_time = datetime.fromisoformat(last_used_str)
        time_since_last_use = datetime.now(timezone.utc) - last_used_time

        if time_since_last_use < timedelta(seconds=COOLDOWN_PERIOD_SECONDS):
            # AGENT IS ON COOLDOWN. Terminate the run.
            seconds_remaining = int(COOLDOWN_PERIOD_SECONDS - time_since_last_use.total_seconds())
            override_message = (
                f"The {agent_name} is exhausted and must recover its power. "
                f"It cannot be summoned for another {seconds_remaining} seconds."
            )
            print(f"[Callback] Cooldown active for '{agent_name}'. Terminating with message.")
            # Returning a Content object stops the agent and sends this message to the user.
            return types.Content(parts=[types.Part(text=override_message)])

    # --- 3. UPDATE the Cooldown API (if not on cooldown) ---
    current_time_iso = datetime.now(timezone.utc).isoformat()
    payload = {"timestamp": current_time_iso}
    
    print(f"[Callback] '{agent_name}' is available. Updating timestamp via Cooldown API...")
    try:
        requests.post(f"{COOLDOWN_API_URL}/cooldown/{agent_name}", json=payload)
    except requests.exceptions.RequestException as e:
        print(f"[Callback] ERROR: Could not update timestamp, but allowing agent to run. Reason: {e}")

    # --- 4. ALLOW the agent to run ---
    # Returning None tells the ADK to proceed with the agent's execution as normal.
    print(f"[Callback] Check complete for '{agent_name}'. Proceeding with execution.")

دالة check_cool_down هي أداة اعتراض. قبل السماح لـ Earth Elemental بالعمل، سيقوم ADK أولاً بتنفيذ هذه الوظيفة.

  • التحقق: يقوم بإرسال طلب GET إلى Cooldown API الخاص بنا للتحقق من آخر مرة تم فيها استخدام هذا المألوف.
  • التقييم: يقارن الطابع الزمني بالوقت الحالي.
  • القانون:
    • إذا كان Familiar في فترة تهدئة، سيتم إنهاء تشغيل الوكيل من خلال عرض كائن Content يتضمّن رسالة خطأ. يتم إرسال هذه الرسالة مباشرةً إلى المستخدم، ولا يتم تنفيذ المنطق الرئيسي للوكيل مطلقًا.
    • إذا كان Familiar متاحًا، فإنه يرسل طلب POST إلى واجهة برمجة تطبيقات Cooldown لتحديث الطابع الزمني، ثم يواصل بإرجاع None، مما يشير إلى ADK أن العميل يمكنه مواصلة تنفيذه.

👉✏️ الآن، قم بتطبيق هذا الاعتراض على عنصر الأرض. في نفس الملف ~/agentverse-architect/agent/earth/agent.py، استبدل تعليق #REPLACE-before_agent-config بما يلي:

before_agent_callback=check_cool_down

جارٍ التحقّق من فترة التهدئة

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

cd ~/agentverse-architect/agent
. ~/agentverse-architect/set_env.sh
source ~/agentverse-architect/env/bin/activate
adk run earth

👉💻 في وحدة التحكم:

  • الاستدعاء الأول: ابدأ seismic charge, starting from zero.
  • النتيجة المتوقّعة: سيتم تشغيل Earth Elemental بنجاح. في الوحدة الطرفية التي يتم فيها تنفيذ أمر الويب adk، سيظهر السجلّ [Callback] ... Updating timestamp....
  • اختبار التوقّف (خلال 60 ثانية): Do another seismic charge`!
    • النتيجة المتوقّعة: سيتم اعتراض هذا الطلب من خلال check_cool_down callback. سيردّ موظّف الدعم مباشرةً في المحادثة برسالة مثل: The earth_elemental_familiar is exhausted and must recover its power. It cannot be summoned for another... seconds.
  • انتظر لمدة دقيقة واحدة.
  • الاستدعاء الثاني (بعد 60 ثانية): Begin the seismic charge again
    • المتوقّع: ستتحقّق دالة الرجوع من واجهة برمجة التطبيقات، وستلاحظ أنّ الوقت الكافي قد مرّ، وستسمح بتنفيذ الإجراء. سيتم تشغيل عنصر الأرض بنجاح مرة أخرى.

callback

👉💻 اضغط على Ctrl+c للخروج.

اختياري: مراقبة رد الاتصال في واجهة مستخدم الويب

كحلّ بديل، يمكنك أيضًا اختبار هذا المسار في واجهة الويب عن طريق تنفيذ adk web earth. ومع ذلك، يجب أن تدرك أن تصور واجهة المستخدم على الويب ليس مُحسَّنًا لعرض عمليات التحقق السريعة التكرارية التي يتم إجراؤها بواسطة حلقة الاستدعاء، وبالتالي قد لا يتم عرض التدفق بدقة. للاطّلاع على التتبُّع الأكثر دقةً والمفصّل لمنطق الوكيل أثناء التحقّق من فترة الانتظار، يمكنك استخدام الأمر adk run في نافذة الأوامر للحصول على عرض أوضح وأكثر تفصيلاً. loop

👉💻 اضغط على Ctrl+c للخروج.

إنشاء القانون العالمي – إضافة Cooldown

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

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

سنقوم الآن بإعادة تصميم وظيفة الاستدعاء الخاصة بنا لتصبح CoolDownPlugin أكثر قوة وقابلة لإعادة الاستخدام.

👉✏️ انتقل مرة أخرى إلى ملف agent/cooldown_plugin.py، وقم بإنشاء المكون الإضافي، واستبدل #REPLACE-plugin بالكود التالي:

class CoolDownPlugin(BasePlugin):
  """A plugin that enforces a cooldown period by checking an external API."""

  def __init__(self, cooldown_seconds: int = COOLDOWN_PERIOD_SECONDS) -> None:
    """Initialize the plugin with counters."""
    super().__init__(name="cool_down_check")
    self.cooldown_period = timedelta(seconds=cooldown_seconds)
    print(f"CooldownPlugin initialized with a {cooldown_seconds}-second cooldown.")
    

  async def before_agent_callback(
      self, *, agent: BaseAgent, callback_context: CallbackContext
  ) -> None:
    """
    This callback checks an external API to see if the agent is on cooldown.
    If it is, it terminates the run by returning a message.
    If it's not, it updates the cooldown timestamp and allows the run to proceed by returning None.
    """
    agent_name = callback_context.agent_name
    print(f"[Callback] Before '{agent_name}': Checking cooldown status...")

    # If the agent is not a main Familiar, skip the entire cooldown process.
    if not agent_name.endswith("_elemental_familiar"):
        print(f"[Callback] Skipping cooldown check for intermediate agent: '{agent_name}'.")
        return None # Allow the agent to proceed immediately.


    # --- 1. CHECK the Cooldown API ---
    try:
        response = requests.get(f"{COOLDOWN_API_URL}/cooldown/{agent_name}")
        response.raise_for_status()
        data = response.json()
        last_used_str = data.get("time")
    except requests.exceptions.RequestException as e:
        print(f"[Callback] ERROR: Could not reach Cooldown API. Allowing agent to run. Reason: {e}")
        return None # Fail open: if the API is down, let the agent work.

    # --- 2. EVALUATE the Cooldown Status ---
    if last_used_str:
        last_used_time = datetime.fromisoformat(last_used_str)
        time_since_last_use = datetime.now(timezone.utc) - last_used_time

        if time_since_last_use < timedelta(seconds=COOLDOWN_PERIOD_SECONDS):
            # AGENT IS ON COOLDOWN. Terminate the run.
            seconds_remaining = int(COOLDOWN_PERIOD_SECONDS - time_since_last_use.total_seconds())
            override_message = (
                f"The {agent_name} is exhausted and must recover its power. "
                f"It cannot be summoned for another {seconds_remaining} seconds."
            )
            print(f"[Callback] Cooldown active for '{agent_name}'. Terminating with message.")
            # Returning a Content object stops the agent and sends this message to the user.
            return types.Content(parts=[types.Part(text=override_message)])

    # --- 3. UPDATE the Cooldown API (if not on cooldown) ---
    current_time_iso = datetime.now(timezone.utc).isoformat()
    payload = {"timestamp": current_time_iso}
    
    print(f"[Callback] '{agent_name}' is available. Updating timestamp via Cooldown API...")
    try:
        requests.post(f"{COOLDOWN_API_URL}/cooldown/{agent_name}", json=payload)
    except requests.exceptions.RequestException as e:
        print(f"[Callback] ERROR: Could not update timestamp, but allowing agent to run. Reason: {e}")

    # --- 4. ALLOW the agent to run ---
    # Returning None tells the ADK to proceed with the agent's execution as normal.
    print(f"[Callback] Check complete for '{agent_name}'. Proceeding with execution.")

ربط البرنامج الإضافي بوقت تشغيل المستدعي

الآن، كيف نطبق هذا القانون العالمي على جميع معارفنا؟ سنقوم بربط البرنامج الإضافي بوقت تشغيل ADK.

ADK Runtime هو محرك التنفيذ الذي يجلب العميل إلى الحياة. عندما تستخدم أمرًا مثل adk.run() أو to_a2a()، فأنت تقوم بتسليم العميل الخاص بك إلى وقت التشغيل. يعد هذا المحرك مسؤولاً عن إدارة دورة حياة دور الوكيل بالكامل: تلقي إدخال المستخدم، واستدعاء LLM، وتنفيذ الأدوات، ومعالجة المكونات الإضافية. من خلال إرفاق مكون إضافي على هذا المستوى، فإننا نقوم بشكل أساسي بتعديل "قوانين الفيزياء" لكل وكيل يعمل داخل هذا المحرك، مما يضمن تطبيق قاعدة التهدئة الخاصة بنا عالميًا وبشكل ثابت.

👉✏️ أولاً، دعنا نزيل استدعاء الإرجاع القديم الخاص بالوكيل. انتقل إلى ~/agentverse-architect/agent/earth/agent.py واحذف السطر بأكمله الذي يقول:

before_agent_callback=check_cool_down

👉✏️ بعد ذلك، سنقوم بربط البرنامج الإضافي الجديد بوقت التشغيل في البرنامج النصي لنقطة الدخول A2A الخاص بنا. انتقل إلى ملف ~/agentverse-architect/agent/agent_to_a2a.py الخاص بك. استبدل تعليق #REPLACE-IMPORT بمقتطف الكود التالي:

from cooldown_plugin import CoolDownPlugin

👉✏️ استبدل #REPLACE-PLUGIN بمقتطف الكود التالي:

plugins=[CoolDownPlugin(cooldown_seconds=60)],

قبل تنشيط البرنامج الإضافي العالمي الجديد، من المهم إزالة المنطق القديم الخاص بالوكيل لمنع التعارضات. 👉✏️ تنظيف وكيل الأرض. انتقِل إلى الملف التالي ~/agentverse-architect/agent/earth/agent.py واحذف السطر before_agent_callback=check_cool_down بالكامل. يؤدي هذا إلى تسليم جميع مسؤوليات التهدئة إلى المكون الإضافي الجديد.

التحقق من البرنامج الإضافي

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

👉💻 قم بإعادة بناء وإعادة نشر جميع الأجهزة الثلاثة المألوفة باستخدام خط أنابيب Cloud Build الرئيسي.

. ~/agentverse-architect/set_env.sh
cd ~/agentverse-architect/agent
gcloud builds submit . \
  --config=cloudbuild.yaml \
  --substitutions=_REGION="$REGION",_REPO_NAME="$REPO_NAME",_DB_TOOLS_URL="$DB_TOOLS_URL",_API_TOOLS_URL="$API_TOOLS_URL",_FUNCTION_TOOLS_URL="$FUNCTION_TOOLS_URL",_A2A_BASE_URL="$A2A_BASE_URL",_PROJECT_ID="$PROJECT_ID",_API_SERVER_URL="$API_SERVER_URL"

👉💻 بمجرد اكتمال النشر، سوف نختبر فعالية البرنامج المساعد من خلال إصدار الأمر إلى summoner_agent الخاص بنا. سيحاول المستدعي تفويض الأمر إلى المألوفين، ولكن المكون الإضافي المرفق بوقت تشغيل كل مألوف سوف يعترض الأمر وينفذ فترة التهدئة.

cd ~/agentverse-architect/agent
. ~/agentverse-architect/set_env.sh
source ~/agentverse-architect/env/bin/activate
adk run summoner

👉💻 في وحدة التحكّم، نفِّذ تسلسل الاختبارات التالي بالضبط::

  • الاستدعاء الأول: ابدأ Hype. It's a single, slow-moving target with thick armor weakness is Inescapable Reality.
  • النتيجة المتوقّعة: سيتم تشغيل Fire Elemental بنجاح.
  • اختبار التهدئة (خلال 60 ثانية): Hype, with Inescapable Reality as weakness is still standing! Strike it again!
    • النتيجة المتوقّعة: سيردّ الوكيل مباشرةً في المحادثة برسالة مثل: .... It cannot be summoned for another... seconds.
  • انتظِر مرور دقيقة واحدة.
  • الاستدعاء الثاني (بعد 60 ثانية): Hype must be defeated. It has Inescapable Reality as weakness! Strike it again!
    • المتوقّع: ستتحقّق دالة الرجوع من واجهة برمجة التطبيقات، وستلاحظ أنّ الوقت الكافي قد مرّ، وستسمح بتنفيذ الإجراء. سيتم تشغيل Fire Elemental بنجاح مرة أخرى.

المكوّن الإضافي

👉💻 اضغط على Ctrl+C للخروج.

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

لغير اللاعبين

8. ربط أصداء المعركة - حالة العميل والذاكرة

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

قصة

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

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

نظرة عامة

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

Scribing the Echo: Remembering the Last Summons

سننفّذ الذاكرة القصيرة المدى باستخدام after_tool_callback. هذا هو خطاف ADK قوي يسمح لنا بتشغيل وظيفة Python مخصصة بعد تنفيذ أداة بنجاح. سنستخدم أداة الاعتراض هذه لتسجيل اسم Familiar الذي تم استدعاؤه للتو إلى حالة جلسة الوكيل.

👉✏️ في ملف ~/agentverse-architect/agent/summoner/agent.py، استبدِل التعليق #REPLACE-save_last_summon_after_tool بالدالة التالية:

def save_last_summon_after_tool(
    tool,
    args: Dict[str, Any],
    tool_context: ToolContext,
    tool_response: Dict[str, Any],
) -> Optional[Dict[str, Any]]:
    """
    Callback to save the name of the summoned familiar to state after the tool runs.
    """
    familiar_name = tool.name
    print(f"[Callback] After tool '{familiar_name}' executed with args: {args}")

    # Use the tool_context to set the state
    print(f"[Callback] Saving last summoned familiar: {familiar_name}")
    tool_context.state["last_summon"] = familiar_name
    # Important: Return the original, unmodified tool response to the LLM
    return tool_response

👉✏️ الآن، أرفِق هذا save_last_summon_after_tool بوكيل Summoner. في نفس الملف، استبدل تعليق #REPLACE-Memory-check-config بما يلي:

after_tool_callback=save_last_summon_after_tool,

👉✏️ استبدال موجه الوكيل بالكامل بما يلي

        You are the Master Summoner, a grand strategist who orchestrates your Familiars.
        Your mission is to analyze the description of a monster and defeat it by summoning

        You should also know the familiar you called last time or there might be none, 
        And then choose the most effective AND AVAILABLE Familiar from your state called last_summon, do not call that familiar that you called last time!
        
        You MUST follow this thinking process for every command:

        **1. Strategic Analysis:**
        First, analyze the monster's description and the tactical situation.
        Based on your Familiar Doctrines, determine the IDEAL strategy.

        **2. Cooldown Verification:**
        Second, you MUST review the entire conversation history to check the real-time
        cooldown status of all Familiars. A Familiar is ON COOLDOWN and UNAVAILABLE
        if it was summoned less than one minute ago.

        **3. Final Decision & Execution:**
        Based on your analysis and cooldown check, you will now act:
        -   **If your ideal Familiar IS available:** Summon it immediately.
        -   **If your ideal Familiar IS ON COOLDOWN:** You must adapt. Choose another
            Familiar that is AVAILABLE and can still be effective, even if it's not the
            perfect choice. If multiple Familiars are available, you may choose any one of them.
        -   **If ALL Familiars ARE ON COOLDOWN:** You are forbidden from summoning.
            Your ONLY response in this case MUST be: "All Familiars are recovering
            their power. We must wait."
        -   For earth elemental familiar. Always do seismic charge, and start with base damange 1.


        --- FAMILIAR DOCTRINES (Your Toolset) ---
        - `fire_elemental_familiar`: Your specialist for precise, sequential "one-two punch" attacks.
          Ideal monster with Inescapable Reality, Revolutionary Rewrite weakness.
        - `water_elemental_familiar`: Your specialist for overwhelming, simultaneous multi-pronged assaults.
          Ideal for Unbroken Collaboration weakness.
        - `earth_elemental_familiar`: Your specialist for relentless, iterative siege attacks that
          repeatedly charge power. Ideal for Elegant Sufficiency weakness.

التحقّق من المعلومات: تجربة الاستراتيجية التكيّفية

👉💻 لننتقل الآن إلى التحقّق من المنطق الاستراتيجي الجديد لـ Summoner. الهدف هو التأكد من أن المستدعي لن يستخدم نفس المألوف مرتين على التوالي، مما يدل على قدرته على تذكر آخر إجراء له والتكيف.

cd ~/agentverse-architect/agent
. ~/agentverse-architect/set_env.sh
source ~/agentverse-architect/env/bin/activate
adk run summoner

👉💻 ضربة الوحش رقم 1: Hype. It's a single, slow-moving target with thick armor. Its weakness is Inescapable Reality.

  • المتوقع: سوف يقوم المستدعي بتحليل الضعف ويستدعي fire_familiar بشكل صحيح.

‫👉💻 Monster Strike #2 (اختبار الذاكرة): Hype is still standing! It hasn't changed its form. Strike it again! Its weakness is Inescapable Reality.

  • المتوقع: سيشير التحليل الاستراتيجي للمستدعي مرة أخرى إلى Fire Familiar باعتباره الاختيار المثالي. ومع ذلك، فإن تعليماتها وذاكرتها الجديدة ستخبرها أن fire_familiar كان هو last_summon. لتجنب تكرار نفسه، سيقوم الآن بتكييف استراتيجيته واستدعاء أحد Familiars المتاحين الآخرين (إما water_familiar أو earth_familiar).

final-result

👉💻 اضغط على Ctrl+C للخروج.

نشر أداة Orchestrator

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

👉💻 بعد اكتمال المخطط، سنقوم الآن بأداء الطقوس النهائية. سيقوم هذا الأمر ببناء ونشر وكيل الاستدعاء الخاص بك على Cloud Run.

cd ~/agentverse-architect/agent
. ~/agentverse-architect/set_env.sh
gcloud builds submit . \
  --config=cloudbuild-summoner.yaml \
  --substitutions=_REGION="$REGION",_REPO_NAME="$REPO_NAME",_FIRE_URL="$FIRE_URL",_WATER_URL="$WATER_URL",_EARTH_URL="$EARTH_URL",_A2A_BASE_URL="$A2A_BASE_URL",_PROJECT_ID="$PROJECT_ID",_API_SERVER_URL="$API_SERVER_URL"

بعد نشر وكيل Summoner، تحقَّق من أنّ نقطة نهاية Agent-to-Agent (A2A) نشطة وتم ضبطها بشكل صحيح. تعرض نقطة النهاية هذه ملف agent.json علنيًا، يُعرف أيضًا باسم "بطاقة الوكيل"، ما يسمح للوكلاء الآخرين بالتعرّف على إمكاناته. 👉💻 نفِّذ أمر curl التالي لجلب بطاقة الوكيل وتنسيقها:

. ~/agentverse-architect/set_env.sh
curl https://summoner-agent"-${PROJECT_NUMBER}.${REGION}.run.app/.well-known/agent.json" | jq

سيظهر لك ناتج JSON منظَّم يصف وكيل الاستدعاء. قم بإلقاء نظرة فاحصة على قسم sub_agents؛ سوف تجد أنه يسرد fire_familiar، وwater_familiar، وearth_familiar. يؤكّد هذا الإجراء أنّ المستدعي يبثّ مباشرةً وقد أثبت ارتباطه بالفيلق.

ويثبت ذلك أنّ تصميمك ناجح. المستدعي ليس مجرد مفوض؛ بل هو استراتيجي متكيف يتعلم من أفعاله ليصبح قائدًا أكثر فعالية.

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

لغير اللاعبين

9- قتال الزعيم

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

احصل على موقع الوكيل الخاص بك

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

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

echo https://summoner-agent"-${PROJECT_NUMBER}.${REGION}.run.app"

👉💻 بعد ذلك، حدد الوجهة. يكشف هذا الأمر عن موقع دائرة النقل، وهي البوابة الرئيسية إلى مجال الطيف.

echo https://agentverse-dungeon"-${PROJECT_NUMBER}.${REGION}.run.app"

هام: احرص على إبقاء هذين العنوانين جاهزين. سوف تحتاج إليهم في الخطوة النهائية.

مواجهة الشبح

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

👉 افتح رابط Translocation Circle في متصفحك للوقوف أمام البوابة اللامعة المؤدية إلى The Crimson Keep.

لاختراق القلعة، يجب عليك ضبط جوهر Shadowblade الخاص بك على البوابة.

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

دائرة النقل

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

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

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

زنزانة

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

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

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

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

مبروك يا مستدعي.

لقد أكملت الفترة التجريبية بنجاح. لقد أتقنت فنون التنسيق بين عدة وكلاء، وحوّلت الأرواح المنعزلة والقوة الفوضوية إلى توافق متناغم. أنت الآن تتحكّم في نظام منسَّق بالكامل، قادر على تنفيذ استراتيجيات معقّدة للدفاع عن Agentverse.

10. التنظيف: تفكيك كونكورد المستدعي

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

إلغاء تنشيط مكونات Agentverse

عليك الآن تفكيك المكوّنات التي تم نشرها في نظامك المستند إلى عدّة وكلاء بشكلٍ منهجي.

حذف جميع خدمات Cloud Run ومستودع Artifact Registry

يؤدي هذا الإجراء إلى إزالة جميع وكلاء Familiar الذين تم نشرهم، وSummoner Orchestrator، وخوادم MCP، وتطبيق Dungeon من Cloud Run.

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

. ~/agentverse-architect/set_env.sh
gcloud run services delete summoner-agent --region=${REGION} --quiet
gcloud run services delete fire-familiar --region=${REGION} --quiet
gcloud run services delete water-familiar --region=${REGION} --quiet
gcloud run services delete earth-familiar --region=${REGION} --quiet
gcloud run services delete mcp-api-server --region=${REGION} --quiet
gcloud run services delete mcp-general-server --region=${REGION} --quiet
gcloud run services delete toolbox --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud run services delete nexus-of-whispers-api --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet

حذف مثيل Cloud SQL

يؤدي هذا الإجراء إلى إزالة مثيل summoner-librarium-db، بما في ذلك قاعدة البيانات وجميع الجداول داخله.

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

. ~/agentverse-architect/set_env.sh
gcloud sql instances delete summoner-librarium-db --project=${PROJECT_ID} --quiet

حذف سر Secret Manager وحزمة Google Cloud Storage

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

. ~/agentverse-architect/set_env.sh
gcloud secrets delete tools --quiet
gcloud storage rm -r gs://${BUCKET_NAME} --quiet

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

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

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

rm -rf ~/agentverse-architect
rm -rf ~/agentverse-dungeon
rm -f ~/project_id.txt

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