تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

إذا لم يكن لديك مشروع يمكنك استخدامه، عليك إنشاء مشروع جديد في وحدة تحكّم Google Cloud Platform.
في هذا التمرين العملي، سنستخدم GCP Cloud Shell لتنفيذ مهامنا. افتح Cloud Shell واضبط المشروع باستخدام Cloud Shell.
افتح GCP Cloud Shell بالنقر هنا، Cloud Shell . إذا ظهرت النافذة المنبثقة "تفويض Shell"، انقر عليها لتفويض Cloud Shell Editor.
يمكنك التحقّق مما إذا كان المشروع قد تمّت مصادقته من قبل باستخدام الأمر التالي في نافذة Cloud Shell الطرفية.

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

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

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

3- مقدمة عن "حزمة تطوير Agent"

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

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

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

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

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

4. مقدمة حول "محرك وكلاء Vertex AI"

‫Vertex AI Agent Engine هي خدمة مُدارة بالكامل لنشر الوكلاء في Google Cloud. باستخدام محرك وكلاء Vertex AI، يمكن للمطوّرين تطوير وكلاء الذكاء الاصطناعي مفتوح المصدر وتخصيصهم ونشرهم وتقديمهم وإدارتهم( حزمة تطوير الوكلاء (ADK) وLangChain وLangGraph وCrewAI وAutoGen وغير ذلك الكثير!) على Vertex AI.

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

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

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

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

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

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

5- مقدمة عن A2A

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

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

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

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

تم تصميم النظام باستخدام وكيل رئيسي يُسمى 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

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

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

إعداد علامة تبويب "محرّر Cloud Shell"

انقر على هذا الرابط للانتقال مباشرةً إلى محرّر Cloud Shell
انقر على متابعة.
عندما يُطلب منك تفويض Cloud Shell، انقر على تفويض.
خلال بقية هذا المختبر، يمكنك العمل في هذه النافذة كبيئة تطوير متكاملة (IDE) باستخدام "محرّر Cloud Shell" و"وحدة طرفية Cloud Shell".
افتح نافذة Terminal جديدة باستخدام Terminal>New Terminal في "محرّر Cloud Shell". سيتم تنفيذ جميع الأوامر أدناه في هذه الوحدة الطرفية.

تنزيل وتثبيت حزمة تطوير التطبيقات (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 لإنشاء بيئة بايثون (يجب تشغيلها في "وحدة تحكّم محرر 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. يمكنك أيضًا إنشاء الحزمة باستخدام أمر gsutil. منح Agent Engine إذن الوصول إلى 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
gsutil mb gs://${PROJECT_ID}-imagescoring-bucket

#Now lets give Agent Engine 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 Engine 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=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="imagen-3.0-generate-002"
GENAI_MODEL="gemini-2.5-flash"
EOF

اطّلِع على بنية الوكيل في رمز المصدر، بدءًا من agent.py . يحتوي هذا الوكيل على الوكيل الجذر الذي سيتم ربطه بالوكلاء الآخرين.
ارجع إلى الدليل الأعلى multiagenthandson في الوحدة الطرفية ونفِّذ الأمر التالي لتشغيل الوكيل محليًا (التشغيل في "وحدة طرفية في محرر Cloud Shell").

#go to the directory multiagenthandson
cd ~/imagescoring/multiagenthandson
# Run the following command to run agents locally
adk web

الشكل 4

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

اختَر image_scoring من القائمة المنسدلة في أعلى يمين الصفحة (راجِع الشكل 5). لننشئ بعض الصور الآن. من المفترض أن تجد الصور في حزمة Google Cloud Storage أيضًا. جرِّب الطلبات التالية أو طلباتك الخاصة.
مناظر طبيعية جبلية هادئة عند غروب الشمس
قط يركب دراجة

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

8. النشر في Agent Engine

الآن، ننشر الوكيل في Agent Engine. Agent Engine هي خدمة مُدارة بالكامل لنشر الوكلاء في Google Cloud Platform. يتوافق Agent Engine مع ADK (Agent Development Kit)، لذا يمكن نشر الوكلاء الذين تم إنشاؤهم باستخدام ADK (Agent Development Kit) في Agent Engine.

أنشئ ملف 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

أنشئ الحزمة. علينا تجميع تطبيقنا في حزمة Python .whl. سنستخدم 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

سنجهّز الآن البرنامج النصي الخاص بالنشر. سينشر النص البرمجي الخاص بالنشر خدمة وكيل تسجيل النقاط للصور أو محرك الوكيل. يُرجى تأكيد محتوى deploy.py داخل المجلد deploy كما هو موضّح أدناه (استخدِم "اللوحة الجانبية لمحرّر 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

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

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

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

REASONING_ENGINE_ID = "projects/xxx/locations/us-central1/reasoningEngines/xxx"  # TODO: Change this

من المجلد العلوي multiagenthandson، نفِّذ الأمر التالي. من المفترض أن تحصل على نتيجة مثل الشكل 4. بعد اكتمال التنفيذ، من المفترض أن تتمكّن من رؤية (Run in Cloud Shell Editor Terminal).

#go to multiagenthandson folder
cd ~/imagescoring/multiagenthandson

#execute remote_test.py
python3 -m testclient.remote_test

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

9- إنشاء وكيل A2A

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

تعرَّف على أساسيات بروتوكول 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 Editor مع المحتوى التالي.

{
 "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 Editor، وهو نقطة الدخول إلى وكيل A2A. يجب أن يتضمّن ما يلي:

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 المحدّدة.

10. تَنظيم

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

احذف خادم محرك وكلاء Vertex AI الذي أنشأناه للتو. انتقِل إلى Vertex AI من خلال كتابة Vertex AI في شريط البحث في Google Cloud Console. انقر على محرك الوكيل على يمين الصفحة.يمكنك حذف الوكيل من خلال النقر على "حذف".

الشكل 8

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

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

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

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

11. الخاتمة

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

ملخّص

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

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

مراجع مفيدة