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

إنشاء نظام متعدد الوكلاء باستخدام ADK ونشره في Agent Runtime والبدء باستخدام بروتوكول A2A

1. هدف هذه الميزة الاختبارية

في هذا الدرس العملي، ستنشئ تطبيقًا متعدد الوكلاء باستخدام حزمة تطوير الوكلاء (ADK) التي تنشئ صورة استنادًا إلى طلبك وتقيّمها مقارنةً بطلبك. إذا لم تستوفِ الصورة المتطلبات الموضّحة في الطلب على نحوٍ مرضٍ، سيواصل الوكيل إنشاء الصور إلى أن يتم إنشاء الصورة التي تستوفي متطلباتك. لكل وكيل من هؤلاء الوكلاء غرض واحد، ويتعاون الوكلاء مع بعضهم البعض لتحقيق الهدف العام. ستتعرّف على كيفية اختبار التطبيق محليًا ونشره في Agent Runtime.

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

فهم أساسيات حزمة تطوير الوكلاء (ADK) والتعرّف على كيفية إنشاء نظام متعدد الوكلاء
تعرَّف على كيفية نشر الوكلاء واستخدامهم بسهولة في Agent Runtime.
فهم أساسيات بروتوكول A2A
تعرَّف على كيفية استخدام بروتوكول A2A وحزمة تطوير الوكلاء (ADK) معًا لإنشاء وكلاء مفتوحين.

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

انتقِل إلى وحدة تحكّم Google Cloud Platform من خلال النقر على الرابط التالي وحدة تحكّم Google Cloud Platform.
إذا لم يكن لديك مشروع يمكنك استخدامه، عليك إنشاء مشروع جديد في وحدة تحكّم Google Cloud Platform. اختَر المشروع من أداة اختيار المشاريع (أعلى يمين Google Cloud Console). إذا لم يكن لديك مشروع، يُرجى اتّباع هذه الخطوات لإنشاء مشروع جديد. بعد إنشاء مشروع جديد، يُرجى اختياره.

الشكل 2: يتيح لك النقر على المربّع بجانب شعار Google Cloud اختيار مشروعك. تأكَّد من اختيار مشروعك.

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

gcloud auth list

إذا تعذّر عليك تذكُّر معرّف مشروعك، يمكنك إدراج جميع معرّفات المشاريع باستخدام

gcloud projects list

انسخ رقم تعريف المشروع واستخدِم الأمر التالي لضبطه

gcloud config set project <YOUR_PROJECT_ID>

نفِّذ الأمر التالي في Cloud Shell لتأكيد مشروعك

gcloud config list project

3- تفعيل واجهات برمجة التطبيقات

علينا تفعيل بعض خدمات واجهة برمجة التطبيقات لتشغيل هذا المختبر. نفِّذ الأمر التالي في Cloud Shell.

gcloud services enable aiplatform.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com

لمحة عن واجهات برمجة التطبيقات

تتيح واجهة برمجة التطبيقات لمنصة وكيل Gemini Enterprise ‏ (aiplatform.googleapis.com) الوصول إلى منصة وكيل Gemini Enterprise، ما يسمح لتطبيقك بالتفاعل مع نماذج Gemini لإنشاء النصوص وجلسات المحادثة واستدعاء الدوال.
تتيح لك واجهة Cloud Resource Manager API (cloudresourcemanager.googleapis.com) إدارة البيانات الوصفية لمشاريعك على Google Cloud آليًا، مثل رقم تعريف المشروع واسمه، وهو ما غالبًا ما تتطلّبه الأدوات وحِزم تطوير البرامج الأخرى للتحقّق من هوية المشروع وأذوناته.

4. مقدمة حول حزمة Agent Development Kit

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

الأنظمة المتعددة الوكلاء: يمكنك إنشاء تطبيقات معيارية وقابلة للتوسّع من خلال دمج عدة وكلاء متخصصين في تسلسل هرمي. تفعيل التنسيق والتفويض المعقّدين
نظام متكامل من الأدوات المتطوّرة: يمكنك تزويد الوكلاء بإمكانات متنوّعة، مثل استخدام أدوات مُعدّة مسبقًا (البحث، وتنفيذ التعليمات البرمجية، وما إلى ذلك)، أو إنشاء وظائف مخصّصة، أو دمج أدوات من أُطر عمل الوكلاء التابعة لجهات خارجية (LangChain وCrewAI)، أو حتى استخدام وكلاء آخرين كأدوات.
التنظيم المرن: يمكنك تحديد سير العمل باستخدام وكلاء سير العمل (SequentialAgent وParallelAgent وLoopAgent) لإنشاء مسارات يمكن توقّعها، أو الاستفادة من التوجيه الديناميكي المستند إلى النماذج اللغوية الكبيرة (عملية النقل LlmAgent) لتحقيق سلوك تكيفي.
تجربة مطوّرين متكاملة: يمكنك تطوير التطبيقات واختبارها وتصحيح أخطائها محليًا باستخدام واجهة سطر أوامر فعّالة وواجهة مستخدم تفاعلية للمطوّرين. فحص الأحداث والحالة وتنفيذ الوكيل خطوة بخطوة
التقييم المضمّن: يمكنك تقييم أداء الوكيل بشكل منهجي من خلال تقييم كلّ من جودة الردّ النهائي ومسار التنفيذ خطوة بخطوة مقارنةً بحالات الاختبار المحدّدة مسبقًا.
جاهز للنشر: يمكنك وضع وكلائك في حاويات ونشرهم في أي مكان، سواء تشغيلهم محليًا أو توسيع نطاقهم باستخدام Agent Runtime أو دمجهم في بنية أساسية مخصّصة باستخدام Cloud Run أو Docker.

في حين أنّ حِزم تطوير البرامج (SDK) أو أُطر الوكلاء الأخرى التي تستخدم الذكاء الاصطناعي التوليدي تتيح لك أيضًا الاستعلام عن النماذج وحتى تزويدها بالأدوات، يتطلّب التنسيق الديناميكي بين النماذج المتعددة قدرًا كبيرًا من العمل من جانبك.

تقدّم Agent Development Kit إطار عمل أعلى مستوى من هذه الأدوات، ما يتيح لك ربط عدة وكلاء ببعضهم البعض بسهولة لإنشاء سير عمل معقّد ولكن يسهل الحفاظ عليه.

الشكل 1: موضع حزمة تطوير الوكلاء (ADK)

5- مقدمة عن Agent Runtime

Agent Runtime هي خدمة مُدارة بالكامل لنشر الوكلاء في Google Cloud. باستخدام Agent Runtime، يمكن للمطوّرين تطوير وكلاء الذكاء الاصطناعي مفتوح المصدر وتخصيصهم ونشرهم وتقديمهم وإدارتهم( ADK (Agent Development Kit) وLangChain وLangGraph وCrewAI وAutoGen وغير ذلك) على منصة Gemini Enterprise Agent.

توفّر "بيئة تشغيل الوكيل" أيضًا خدمات للتعامل مع بيانات المستخدمين، والمعروفة أيضًا باسم ذاكرة الوكيل. يتوفّر حاليًا نوعان من خدمات الذاكرة.

الذاكرة قصيرة المدى: باستخدام جلسات Agent Engine، يمكنك تخزين سجلّ المحادثات الجارية (الحالة) وإدارته واسترجاعه ضمن جلسة واحدة كذاكرة قصيرة المدى.
الذاكرة طويلة الأمد: باستخدام بنك ذاكرة Agent Engine، يمكنك تخزين الذكريات (الحالة) وتحويلها واسترجاعها، لا سيما على مستوى جلسات متعددة كذكريات طويلة الأمد.

يمكنك أيضًا نشر الوكلاء في خدمات Google Cloud الأخرى، مثل Cloud Run أو GKE، ويُنصح باستخدام Agent Runtime في حالات الاستخدام التالية.

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

يمكنك أيضًا الجمع بين بيئة تشغيل الوكيل وبيئات تشغيل أخرى، مثل Cloud Run، لإنشاء بنية تطبيق مرنة. في ما يلي مثال على بنية مرجعية تستخدم خدمات مختلفة لإنشاء وكيل.

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

6. مقدمة عن A2A

بروتوكول Agent2Agent (A2A) هو معيار مفتوح مصمّم لإتاحة التواصل والتعاون السلس والآمن بين وكلاء الذكاء الاصطناعي المستقلين من أُطر ومورّدين ومجالات مختلفة.

التشغيل التفاعلي الشامل: تتيح A2A للوكلاء العمل معًا بغض النظر عن التكنولوجيات الأساسية التي يستخدمونها، ما يعزّز منظومة متكاملة متعددة الوكلاء. وهذا يعني أنّ البرامج التي أنشأتها شركات مختلفة على منصات مختلفة يمكنها التواصل والتنسيق.
اكتشاف الإمكانات: يمكن للوكلاء الإعلان عن إمكاناتهم باستخدام "بطاقات الوكيل" (مستندات JSON) التي تصف هويتهم وميزات A2A المتوافقة ومهاراتهم ومتطلبات المصادقة. يسمح ذلك للوكلاء الآخرين باكتشاف الوكيل الأنسب لمهمة معيّنة واختياره.
الأمان التلقائي: الأمان هو مبدأ أساسي. تتضمّن A2A آليات مصادقة وتفويض على مستوى المؤسسة، وتستخدِم معايير مثل HTTPS/TLS وJWT وOIDC ومفاتيح واجهة برمجة التطبيقات لضمان التفاعلات الآمنة وحماية البيانات الحساسة.
التوافق مع أنواع المحتوى المختلفة: يتوافق البروتوكول مع أنواع مختلفة من المحتوى، بما في ذلك النصوص والمقاطع الصوتية والفيديوهات، بالإضافة إلى النماذج التفاعلية وإطارات iframe المضمّنة. تتيح هذه المرونة للوكلاء تبادل المعلومات بالتنسيق الأنسب للمهمة والمستخدم.
إدارة المهام المنظَّمة: يحدّد نموذج A2A بروتوكولات واضحة لتفويض المهام ومراقبتها وإكمالها. يتيح تجميع المهام ذات الصلة وإدارتها على مستوى برامج وكلاء مختلفة باستخدام معرّفات مهام فريدة. يمكن أن تنتقل المهام خلال دورات حياة محدّدة (مثل، تم إرسالها، قيد التنفيذ، مكتملة).
التنفيذ غير الشفاف: من الميزات المهمة أنّ الوكلاء لا يحتاجون إلى الكشف عن عمليات الاستدلال الداخلية أو الذاكرة أو الأدوات المحددة لوكلاء آخرين. وهي تعرض فقط الخدمات التي يمكن استدعاؤها، ما يعزّز من إمكانية التقسيم إلى وحدات والخصوصية.
استخدام المعايير الحالية: تستفيد A2A من تكنولوجيات الويب المعروفة، مثل HTTP وServer-Sent Events (SSE) للبث في الوقت الفعلي وJSON-RPC لتبادل البيانات المنظَّمة، ما يسهّل عملية الدمج مع البنية الأساسية الحالية لتكنولوجيا المعلومات.
التواصل غير المتزامن: تم تصميم البروتوكول مع مراعاة التواصل غير المتزامن كأولوية، ما يسهّل تقدّم المهام بمرونة ويتيح إرسال إشعارات فورية بشأن التحديثات حتى في حال عدم الحفاظ على اتصال دائم.

7. بنية الوكيل

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

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

الشكل 3: مسار الوكلاء بشكل عام

قائمة بجميع الوكلاء

الوكيل	Purpose	الوكلاء الفرعيون
image_scoring (الوكيل الرئيسي)	هذا هو الوكيل الأساسي الذي يدير سير العمل بشكل عام. يتم تشغيل image_generation_scoring_agent وchecker_agent بشكل متكرّر في حلقة إلى أن يتم استيفاء شرط الإنهاء.	image_generation_scoring_agent checker_agent_instance
‫image_generation_scoring_agent (وكيل فرعي لـ image_scoring)	هذا الوكيل مسؤول عن المنطق الأساسي لإنشاء الصور وتقييمها. وينفّذ سلسلة من ثلاثة وكلاء فرعيين لتحقيق ذلك.	image_generation_prompt_agent image_generation_agent scoring_images_prompt
‫checker_agent_instance (وكيل فرعي لـ image_scoring)	يتحقّق هذا الوكيل مما إذا كان يجب مواصلة عملية تسجيل الصور أو إنهاؤها. تستخدم هذه الدالة أداة check_tool_condition لتقييم شرط الإنهاء.	-
‫checker_agent_instance (وكيل فرعي لـ image_scoring)	هذا الوكيل خبير في إنشاء طلبات لإنشاء الصور. يأخذ هذا النموذج نصًا مدخلاً وينشئ طلبًا مفصّلاً مناسبًا لنموذج إنشاء الصور.	-
‫image_generation_prompt_agent (وكيل فرعي من image_generation_scoring_agent)	هذا الوكيل خبير في إنشاء طلبات لإنشاء الصور. يستقبل هذا النموذج نصًا ويحوّله إلى طلب مفصّل مناسب لنموذج إنشاء الصور.	-
‫scoring_images_prompt (وكيل فرعي من image_generation_scoring_agent):	هذا الوكيل خبير في تقييم الصور ومنحها نقاطًا استنادًا إلى معايير مختلفة. يأخذ الصورة التي تم إنشاؤها ويمنحها درجة.	-

قائمة بجميع الأدوات المستخدَمة

الأداة	الوصف	وكيل المستخدم
check_tool_condition	تتحقّق هذه الأداة ممّا إذا تم استيفاء شرط إنهاء الحلقة أو تم بلوغ الحدّ الأقصى لعدد التكرارات. إذا كان أيّ من هذين الشرطين صحيحًا، سيتوقف التكرار.	checker_agent_instance
generate_images	تنشئ هذه الأداة صورًا باستخدام نموذج Imagen 3. يمكنه أيضًا حفظ الصور التي تم إنشاؤها في حزمة Google Cloud Storage.	image_generation_agent
get_policy	تجلب هذه الأداة سياسة من ملف JSON. تستخدم image_generation_prompt_agent هذه السياسة لإنشاء طلب إنشاء الصور، وتستخدمها scoring_images_prompt لتقييم الصور.	image_generation_agent
get_image	تحمّل هذه الأداة عنصر الصورة الذي تم إنشاؤه حتى يمكن تقييمه.	scoring_images_prompt
set_score	تضبط هذه الأداة النتيجة الإجمالية للصورة التي تم إنشاؤها في حالة الجلسة.	scoring_images_prompt

8. تثبيت "حزمة تطوير التطبيقات" وإعداد البيئة

في هذا الدرس العملي، سنستخدم Cloud Shell لتنفيذ المهام.

إعداد علامة تبويب "محرِّر Cloud Shell" (يمكنك تخطّي هذه الخطوة إذا كان "محرِّر Cloud Shell" مفتوحًا)

انتقِل إلى وحدة تحكّم Google Cloud Platform من خلال النقر على الرابط التالي وحدة تحكّم Google Cloud Platform.
إذا لم يكن لديك مشروع يمكنك استخدامه، عليك إنشاء مشروع جديد في وحدة تحكّم Google Cloud Platform. اختَر المشروع من أداة اختيار المشاريع (أعلى يمين Google Cloud Console). إذا لم يكن لديك مشروع، يُرجى اتّباع هذه الخطوات لإنشاء مشروع جديد. بعد إنشاء مشروع جديد، يُرجى اختياره.

الشكل 2: يتيح لك النقر على المربّع بجانب شعار Google Cloud اختيار مشروعك. تأكَّد من اختيار مشروعك.

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

gcloud auth list

إذا تعذّر عليك تذكُّر معرّف مشروعك، يمكنك إدراج جميع معرّفات المشاريع باستخدام

gcloud projects list

انسخ رقم تعريف المشروع واستخدِم الأمر التالي لضبطه

gcloud config set project <YOUR_PROJECT_ID>

نفِّذ الأمر التالي في Cloud Shell لتأكيد مشروعك

gcloud config list project

تنزيل حزمة تطوير التطبيقات (ADK) وعيّنات الرموز البرمجية لهذه الميزة الاختبارية وتثبيتهما

نفِّذ الأوامر التالية لاستنساخ الرمز المصدر المطلوب من GitHub وتثبيت المكتبات اللازمة. نفِّذ الأوامر في "الوحدة الطرفية" التي تم فتحها في "محرِّر Cloud Shell".

#create the project directory
mkdir ~/imagescoring
cd ~/imagescoring

#clone the code in the local directory
git clone https://github.com/haren-bh/multiagenthandson.git

سنستخدم uv لإنشاء بيئة Python (يجب تشغيلها في "وحدة تحكّم محرر Cloud Shell"):

#Install uv if you do not have installed yet
pip install uv

#Create the virtual environment
uv venv .adkvenv

source .adkvenv/bin/activate

#go to the project directory
cd ~/imagescoring/multiagenthandson

#install dependencies
uv pip install -r pyproject.toml

إذا لم يكن لديك حزمة تخزين في السحابة الإلكترونية، أنشِئ حزمة جديدة في Google Cloud Storage. يمكنك أيضًا إنشاء الحزمة باستخدام أمر gcloud. منح Agent Runtime إذن الوصول إلى Google Cloud Storage (التشغيل في نافذة المحرّر في Cloud Shell)

# First, make sure your PROJECT_ID variable is set
PROJECT_ID=$(gcloud config get-value project)

# Now, create the bucket with a unique name
# We'll use the project ID to help ensure uniqueness
gcloud storage buckets create gs://${PROJECT_ID}-imagescoring-bucket

#Now lets give Agent Runtime the permission to access Cloud Storage
# 1. Get the current Project ID (text) and Project Number (numeric)
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# 2. Construct the Reasoning Engine Service Account email
SA_EMAIL="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
# 3. Create Agent Runtime Service account if not already created
gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_NUMBER}

# 3. Grant GCS Access
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/storage.objectUser" --condition=None

في المحرّر، انتقِل إلى "عرض" (View) > "تبديل الملفات المخفية" (Toggle hidden files). وفي المجلد image_scoring، أنشئ ملف ‎ .env يتضمّن المحتوى التالي. أضِف التفاصيل المطلوبة، مثل اسم مشروعك وحزمة التخزين السحابي (Run in Cloud Shell Editor Terminal).

#go to image_scoring folder
cd ~/imagescoring/multiagenthandson/image_scoring

cat <<EOF>> .env
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
GOOGLE_CLOUD_LOCATION=global
AGENT_ENGINE_LOCATION=us-central1
GOOGLE_CLOUD_STORAGE_BUCKET=$(gcloud config get-value project)-imagescoring-bucket
GCS_BUCKET_NAME=$(gcloud config get-value project)-imagescoring-bucket
SCORE_THRESHOLD=40
IMAGEN_MODEL="gemini-3.1-flash-lite-image"
GENAI_MODEL="gemini-3.5-flash"
EOF

انتقِل إلى المجلد imagescoring/multiagenthandson/image_scoring في اللوحة الجانبية "المستكشف". انقر على ملف agent.py لفتحه والاطّلاع على بنية الوكيل. يحتوي هذا الوكيل على الوكيل الجذر الذي سيتم ربطه بالوكلاء الفرعيين الآخرين.

الشكل 4: بنية المجلد التي يمكن رؤيتها من اللوحة الجانبية في "المستكشف" يمكنك ببساطة النقر على ملف للاطّلاع على محتواه.

ارجع إلى الدليل الأعلى multiagenthandson في الوحدة الطرفية ونفِّذ الأمر التالي لتشغيل الوكيل محليًا (Run in Cloud Shell Editor Terminal).

#go to the directory multiagenthandson
cd ~/imagescoring/multiagenthandson
# Run the following command to run agents locally
adk web --host 0.0.0.0 --port 8080 --allow_origins "regex:https://.*8080-.*\.cloudshell\.dev"

الشكل 5: بدء تشغيل تطبيق ADK

اضغط على Ctrl+Click (CMD+Click على نظام التشغيل MacOS) على عنوان URL الخاص بـ http:// المعروض في الوحدة الطرفية لفتح برنامج واجهة المستخدم الرسومية المستند إلى المتصفّح في "حزمة تطوير التطبيقات". يجب أن يبدو مثل الشكل 5
اختَر image_scoring من القائمة المنسدلة في أعلى يمين الصفحة (راجِع الشكل 5). لننشئ بعض الصور الآن. من المفترض أن تجد الصور في حزمة Google Cloud Storage أيضًا. يمكنك النقر على قسم الصور المحفوظة للاطّلاع على الصور المحفوظة على جهازك. جرِّب الطلبات التالية أو طلباتك الخاصة.

مناظر طبيعية جبلية هادئة عند غروب الشمس
قط يركب دراجة

الشكل 6: مثال على الناتج

9. النشر في بيئة تشغيل الوكيل

الآن، ننشر الوكيل في Agent Engine. Agent Engine هي خدمة مُدارة بالكامل لنشر الوكلاء في GCP. يتوافق Agent Engine مع حزمة تطوير الوكلاء (ADK)، وبالتالي يمكن نشر الوكلاء الذين تم إنشاؤهم باستخدام حزمة تطوير الوكلاء (ADK) في Agent Engine.

قبل الانتقال إلى الخطوات أدناه في نافذة Cloud Shell Editor، أوقِف خادم ADK بالضغط على Ctrl+C.
أنشئ ملف requirements.txt باستخدام poetry. سيستخدم Poetry ملف pyproject.toml لإنشاء ملف requirements.txt. بعد تنفيذ الأمر، تحقَّق مما إذا تم إنشاء الملف requirements.txt (نفِّذ الأمر في "وحدة طرفية" في "محرّر Cloud Shell").

# Go to the parent folder containing pyproject.toml file
cd ~/imagescoring/multiagenthandson

# install poetry-plugin-export
uv pip install poetry-plugin-export

#Create requirements.txt file
python3 -m poetry export -f requirements.txt --output requirements.txt --without-hashes

أنشئ الحزمة. علينا تجميع تطبيقنا في حزمة .whl Python. سنستخدم poetry للقيام بذلك. بعد تنفيذ الأمر، تأكَّد من إنشاء مجلد dist وأنّه يحتوي على ملف .whl (نفِّذ الأمر في "وحدة طرفية" في "محرّر Cloud Shell").

# Go to the parent folder containing pyproject.toml file
cd ~/imagescoring/multiagenthandson

#Create python package, to create whl file
python3 -m poetry build

سنجهّز الآن البرنامج النصي الذي ينشر وكيل تسجيل الصور في خدمة Agent Engine. في الدليل deploy، ابحث عن deploy.py في اللوحة الجانبية لمحرّر Cloud Shell وانقر عليه لفتحه. يجب التحقّق من محتوى التطبيق باتّباع الخطوات التالية

import vertexai
from image_scoring.agent import root_agent
import os
import glob # To easily find the wheel file
from dotenv import load_dotenv

# Load environment variables from image_scoring/.env
env_path = os.path.join(os.path.dirname(__file__), "..", "image_scoring", ".env")
load_dotenv(env_path)

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1")
STAGING_BUCKET = f"gs://{os.getenv('GOOGLE_CLOUD_STORAGE_BUCKET')}"

from vertexai import agent_engines

client=vertexai.Client(
    project=PROJECT_ID,
    location=LOCATION,
)
remote_app = client.agent_engines.create(
    agent=root_agent,
    config={
        "display_name": "image-scoring",
        "staging_bucket": STAGING_BUCKET,
        "requirements": open(os.path.join(os.getcwd(), "requirements.txt")).readlines() + ["./dist/image_scoring-0.1.0-py3-none-any.whl"],
        "extra_packages": [
            "./dist/image_scoring-0.1.0-py3-none-any.whl",
        ],     "env_vars":{"GCS_BUCKET_NAME":os.getenv('GOOGLE_CLOUD_STORAGE_BUCKET')}
    }
)
print(f"DEBUG: AgentEngine attributes: {dir(remote_app)}")
try:
    print(remote_app.api_resource.name)
except AttributeError:
    print("Could not find resource_name, check DEBUG output above.")

يمكننا الآن تنفيذ النص البرمجي للنشر. انتقِل أولاً إلى المجلد الرئيسي multiagenthandson (نفِّذ الأمر في "وحدة تحرير Cloud Shell").

#go to multiagenthandson folder
cd ~/imagescoring/multiagenthandson

#run deploy script from the parent folder containing deploy.py
python3 -m deploy.deploy

بعد النشر، من المفترض أن يظهر لك محتوى مشابه لما يلي،

الشكل 7: مثال على الناتج

لنختبر الآن الوكيل الذي تم نشره. لاختبار محرك الوكيل الذي تم نشره عن بُعد، عليك أولاً نسخ موقع الوكيل من ناتج النشر في الجهاز. من المفترض أن يظهر العنصر بتنسيق يشبه التنسيق التالي: projects/xxx/locations/us-central1/reasoningEngines/xxx .
من دليل الجذر multiagenthandson، نفِّذ الأمر التالي في "وحدة Cloud Shell الطرفية".

#go to multiagenthandson folder
cd ~/imagescoring/multiagenthandson

#execute remote_test.py
python3 -m testclient.remote_test

أدخِل معرّف محرك الاستدلال، ويجب أن يكون على الشكل "projects/xxx/locations/us-central1/reasoningEngines/xxx"، ثم أدخِل طلبك لإنشاء صورتك. يمكنك تأكيد إخراج الصورة في مجلد التخزين السحابي.

الشكل 8: مثال على الناتج

10. إنشاء وكيل A2A

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

تعرَّف على أساسيات بروتوكول A2A.
تعرَّف على طريقة عمل بروتوكولَي ADK وA2A معًا.
تعرَّف على كيفية التفاعل مع بروتوكول A2A.

في هذا التمرين العملي، سنستخدم الرمز البرمجي في المجلد image_scoring_adk_a2a_server. قبل البدء في المهمة، يُرجى تغيير الدليل إلى هذا المجلد (التشغيل في "وحدة طرفية لمحرّر Cloud Shell").

#change directory to image_scoring_adk_a2a_server
cd ~/imagescoring/multiagenthandson/image_scoring_adk_a2a_server

#copy the env file
cp ~/imagescoring/multiagenthandson/image_scoring/.env remote_a2a/image_scoring

1. إنشاء بطاقة وكيل A2A

يتطلّب بروتوكول التواصل بين التطبيقات بطاقة وكيل تحتوي على جميع المعلومات حول الوكيل، مثل إمكانات الوكيل ودليل استخدام الوكيل وما إلى ذلك. بعد نشر وكيل التواصل بين التطبيقات، يمكن عرض بطاقة الوكيل باستخدام الرابط ".well-known/agent-card.json". يمكن للعملاء الرجوع إلى هذه المعلومات لإرسال الطلب إلى وكلاء الدعم.

انتقِل إلى الدليل remote_a2a/image_scoring وابحث عن ملف agents.json في اللوحة الجانبية محرّر Cloud Shell. انقر على الملف لفتحه وتأكَّد من أنّ المحتوى يتطابق مع ما يلي:

{
 "name": "image_scoring",
 "description": "Agent that generates images based on user prompts and scores their adherence to the prompt.",
 "url": "http://localhost:8001/a2a/image_scoring",
 "version": "1.0.0",
 "defaultInputModes": ["text/plain"],
 "defaultOutputModes": ["image/png", "text/plain"],
 "capabilities": {
   "streaming": true,
   "functions": true
 },
 "skills": [
   {
     "id": "generate_and_score_image",
     "name": "Generate and Score Image",
     "description": "Generates an image from a given text prompt and then evaluates how well the generated image adheres to the original prompt, providing a score.",
     "tags": ["image generation", "image scoring", "evaluation", "AI art"],
     "examples": [
       "Generate an image of a futuristic city at sunset",
       "Create an image of a cat playing a piano",
       "Show me an image of a serene forest with a hidden waterfall"
     ]
   }
 ]
}

‫2. إنشاء وكيل A2A داخل دليل الجذر image_scoring_adk_a2a_server، تأكَّد من توفّر الملف a2a_agent.py. يمكنك فتحها من خلال النقر على اسم الملف في اللوحة الجانبية لمحرِّر Cloud Shell. يعمل هذا الملف كنقطة دخول لوكيل A2A ويجب أن يتضمّن المحتوى التالي:

#change directory to image_scoring_adk_a2a_server
cd ~/imagescoring/multiagenthandson/image_scoring_adk_a2a_server

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

root_agent = RemoteA2aAgent(
   name="image_scoring",
   description="Agent to give interesting facts.",
   agent_card="http://localhost:8001/a2a/image_scoring/.well-known/agent.json",
  
   # Optional configurations
   timeout=300.0,          # HTTP timeout (seconds)
   httpx_client=None,      # Custom HTTP client
)

3. تشغيل وكيل A2A

أصبحنا الآن جاهزين لتشغيل وكيل المحادثة. لتشغيل الوكيل، نفِّذ الأمر التالي من داخل المجلد العلوي image_scoring_adk_a2a_server (يجب تشغيله في Cloud Shell Editor Terminal).

#following command runs the ADK agent as a2a agent
adk api_server --a2a --port 8001 remote_a2a

4. اختبار وكيل A2A

بعد تشغيل الوكيل، يمكننا الآن الانتقال إلى اختباره. أولاً، لننتقل إلى بطاقة الوكيل. افتح وحدة طرفية جديدة باستخدام Terminal>New Terminal (الوحدة الطرفية>وحدة طرفية جديدة) ونفِّذ الأمر التالي (Run in the newly opened Cloud Shell Editor Terminal).

#Execute the following 
curl http://localhost:8001/a2a/image_scoring/.well-known/agent.json

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

لنرسل الآن طلبًا إلى الوكيل. يمكننا استخدام curl لإرسال طلب إلى الوكيل (يجب تشغيله في "وحدة تحكّم محرّر Cloud Shell" التي تم فتحها حديثًا)،

curl -X POST   http://localhost:8001/a2a/image_scoring   -H 'Content-Type: application/json'   -d '{
    "id": "uuid-123",
    "params": {
      "message": {
        "messageId": "msg-456",
        "parts": [{"text": "Create an image of a cat"}],
        "role": "user"
      }
    }
  }'

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

‫11. تَنظيم

لننظِّم الآن ما أنشأناه للتو.

احذف خادم Agent Runtime الذي أنشأناه للتو. انتقِل إلى Gemini Enterprise Agent Platform من خلال كتابة Gemini Enterprise Agent Platform في شريط البحث في Google Cloud Console. انقر على محرك الوكيل على الجانب الأيمن.يمكنك حذف الوكيل من خلال النقر على "حذف".

الشكل 9: يمكنك حذف مثيلات Agent Runtime من Google Cloud Console

حذف الملفات في Cloud Shell

#Execute the following to delete the files
cd ~
rm -R ~/imagescoring

احذف الحزمة. يمكنك الانتقال إلى وحدة تحكّم Google Cloud Platform‏ (GCP) > Cloud Storage، واختيار حزمتك وحذفها.

الشكل 10: حذف الحزمة

‫12. الخاتمة

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

ملخّص

في هذا التمرين المعملي، تعلّمت ما يلي:

إنشاء تطبيق متعدد الوكلاء باستخدام حزمة تطوير الوكلاء (ADK)
نشر التطبيق في Agent Runtime
إنشاء وكيل يمكنه التواصل باستخدام بروتوكول A2A

مراجع مفيدة

من النموذج الأوّلي إلى الإصدار العلني

يشكّل هذا المختبر جزءًا من المسار التعليمي "الذكاء الاصطناعي الجاهز للإنتاج مع Google Cloud".

استكشِف المنهج الدراسي الكامل لسدّ الفجوة بين النموذج الأوّلي والإنتاج.
شارِك مستوى تقدّمك باستخدام الهاشتاغ ‎ #ProductionReadyAI.