تطبيق متعدّد الوكلاء مع ADK وAgent Engine وAlloyDB

1. نظرة عامة

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

عندما يتضمّن تطبيقك عدة وكلاء يعملون معًا بشكل مستقل ومتكامل حسب الحاجة لتحقيق الغرض الأكبر من التطبيق، ويكون كل وكيل على دراية مستقلة ومسؤولاً عن مجال تركيز معيّن، يصبح تطبيقك نظامًا متعدد الوكلاء.

حزمة تطوير الوكلاء (ADK)

حزمة تطوير الوكلاء (ADK) هي إطار عمل مرن ونمطي لتطوير وكلاء الذكاء الاصطناعي وتفعيلهم. تتيح "حزمة تطوير الوكلاء" إنشاء تطبيقات متطورة من خلال دمج عدة مثيلات وكلاء مميزة في نظام متعدد الوكلاء (MAS).

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

نقاط يجب مراعاتها عند إنشاء نظام متعدّد الوكلاء

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

ثانيًا، كيفية جمعها معًا باستخدام وكيل رئيسي لتوجيه كل ردّ وفهمه.

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

ما ستنشئه

لننشئ نظامًا متعدد الوكلاء للتعامل مع عمليات تجديد المطابخ. هذا ما سنفعله، إذ سننشئ نظامًا يتضمّن 3 برامج وكيلة.

وكيل اقتراحات التجديد
Permits and Compliance Check Agent
Order Status Check Agent

"وكيل اقتراح التجديد" لإنشاء مستند اقتراح تجديد المطبخ

وكيل التصاريح والامتثال، لتولّي المهام المتعلقة بالتصاريح والامتثال

Order Status Check Agent، للتحقّق من حالة طلب المواد من خلال العمل على قاعدة بيانات إدارة الطلبات التي أعددناها في AlloyDB

سيكون لدينا وكيل رئيسي ينسّق عمل هؤلاء الوكلاء استنادًا إلى المتطلبات.

المتطلبات

متصفّح، مثل Chrome أو Firefox
مشروع Google Cloud تم تفعيل الفوترة فيه

2. قبل البدء

إنشاء مشروع

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

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

فعِّل Cloud Shell من خلال النقر على هذا الرابط. يمكنك التبديل بين Cloud Shell Terminal (لتنفيذ أوامر السحابة الإلكترونية) والمحرّر (لإنشاء المشاريع) من خلال النقر على الزر المناسب من Cloud Shell.
بعد الاتصال بـ Cloud Shell، يمكنك التأكّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:

gcloud auth list

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

gcloud config list project

إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:

gcloud config set project <YOUR_PROJECT_ID>

تأكَّد من توفّر الإصدار 3.9 أو الإصدارات الأحدث من Python.
فعِّل واجهات برمجة التطبيقات التالية من خلال تنفيذ الأوامر التالية:

gcloud services enable artifactregistry.googleapis.com \cloudbuild.googleapis.com \run.googleapis.com \aiplatform.googleapis.com

راجِع المستندات لمعرفة أوامر gcloud وطريقة استخدامها.

3- النموذج الأوّلي

يمكنك تخطّي هذه الخطوة إذا قررت استخدام نموذج Gemini 2.5 Pro للمشروع.

انتقِل إلى Google AI Studio. ابدأ بكتابة طلبك. إليك طلبي:

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

عدِّل المَعلمات واضبطها على الجانب الأيسر للحصول على أفضل استجابة.

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

لقد اخترنا Gemini 2.5 Pro. هذا نموذج مفكِّر، ما يعني أنّنا نحصل على المزيد من الرموز المميزة للناتج، في هذه الحالة ما يصل إلى 65 ألف رمز مميز، لإجراء تحليلات طويلة وإنشاء مستندات مفصّلة. تظهر "فقاعة التفكير" من Gemini عند تفعيل Gemini 2.5 Pro الذي يتضمّن إمكانات استدلال أصلية ويمكنه استيعاب طلبات طويلة السياق.

اطّلِع على مقتطف الردّ أدناه:

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

كرِّر العملية مع خيارات نماذج مختلفة إلى أن تشعر بالرضا عن النتيجة. ولكن أقول لك لماذا عليك إجراء كل ذلك بينما يتوفّر لديك Gemini 2.5 :)

على أي حال، جرِّب الآن رؤية الفكرة تنبض بالحياة من خلال طلب مختلف:

Add flat and circular light accessories above the island area for my current kitchen in the attached image.

أرفِق رابطًا يؤدي إلى صورة مطبخك الحالي (أو أي صورة نموذجية لمطبخ). غيِّر النموذج إلى "Gemini 2.0 Flash Preview Image Generation" لتتمكّن من إنشاء الصور.

حصلت على الناتج التالي:

هذه هي قوة Gemini.

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

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

4. إعداد ADK

إنشاء بيئة افتراضية وتفعيلها (يُنصح به)

من Cloud Shell Terminal، أنشئ بيئة افتراضية:

python -m venv .venv

تفعيل البيئة الافتراضية:

source .venv/bin/activate

تثبيت "حزمة تطوير التطبيقات"

pip install google-adk

5- بنية المشروع

من نافذة الأوامر الطرفية في Cloud Shell، أنشئ دليلًا في موقع مشروعك المطلوب.

mkdir agentic-apps
cd agentic-apps
mkdir renovation-agent

انتقِل إلى المحرّر في Cloud Shell وأنشِئ بنية المشروع التالية من خلال إنشاء الملفات (ستكون فارغة في البداية):

renovation-agent/
        __init__.py
        agent.py
        .env
        requirements.txt

6. رمز المصدر

انتقِل إلى "init.py" وعدِّله باستخدام المحتوى التالي:

from . import agent

انتقِل إلى agent.py وعدِّل الملف باستخدام المحتوى التالي من المسار التالي:

https://github.com/AbiramiSukumaran/adk-renovation-agent/blob/main/agent.py

في ملف agent.py، نستورد العناصر التابعة الضرورية، ونسترجع مَعلمات الإعداد من ملف ‎ .env، ونحدّد root_agent الذي ينسّق الوكلاء الفرعيين الثلاثة الذين أردنا إنشاءهم في هذا التطبيق. تتوفّر عدة أدوات تساعد في الوظائف الأساسية والداعمة لهذه الوكلاء الفرعيين.

تأكَّد من توفّر حزمة Cloud Storage

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

https://cloud.google.com/storage/docs/creating-buckets#console

أدخِل اسم الحزمة "next-demo-store". إذا اخترت اسمًا آخر، تذكَّر تعديل قيمة STORAGE_BUCKET في ملف ‎ .env (في خطوة إعداد متغيرات البيئة).

لإعداد إذن الوصول إلى الحزمة، انتقِل إلى وحدة تحكّم Cloud Storage وإلى حزمة التخزين (في حالتنا، اسم الحزمة هو "next-demo-storage": https://console.cloud.google.com/storage/browser/next-demo-storage.

انتقِل إلى "الأذونات" -> "عرض الجهات الرئيسية" -> "منح إذن الوصول". اختَر "الجهات الرئيسية" على أنّها "allUsers" و"الدور" على أنّه "مستخدم عنصر التخزين".

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.

إنشاء قائمة بالتبعيات

أدرِج جميع التبعيات في ملف requirements.txt. يمكنك نسخ هذا الرمز من المستودع.

شرح لرمز المصدر الخاص بنظام الوكلاء المتعدّدين

يحدّد ملف agent.py بنية وسلوك نظامنا المتعدد الوكلاء الخاص بتجديد المطبخ باستخدام "حزمة تطوير الوكلاء" (ADK). لنلقِ نظرة على المكوّنات الرئيسية:

تعريفات الوكيل

RenovationProposalAgent

هذا الوكيل مسؤول عن إنشاء مستند اقتراح تجديد المطبخ. يمكنك اختياريًا إدخال مَعلمات، مثل حجم المطبخ والنمط المطلوب والميزانية والإعدادات المفضّلة للعميل. واستنادًا إلى هذه المعلومات، يستخدم نموذجًا لغويًا كبيرًا (LLM) من Gemini 2.5 لإنشاء عرض تفصيلي. بعد ذلك، يتم تخزين الاقتراح الذي تم إنشاؤه في حزمة Google Cloud Storage.

PermitsAndComplianceCheckAgent

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

OrderingAgent

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

الوكيل الرئيسي (المنسّق)

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

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

تدفّق البيانات والمفاهيم الأساسية

يبدأ المستخدم طلبًا من خلال واجهة ADK (إما الجهاز الطرفي أو واجهة مستخدم الويب).

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

النماذج اللغوية الكبيرة (LLMs)

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

Google Cloud Storage

يُستخدَم لتخزين مستندات اقتراح التجديد التي تم إنشاؤها. عليك إنشاء حزمة ومنح الأذونات اللازمة للوكلاء للوصول إليها.

‫Cloud Run (اختياري)

يستخدم OrderingAgent دالة Cloud Run للتفاعل مع AlloyDB. توفّر Cloud Run بيئة بدون خادم لتنفيذ الرموز البرمجية استجابةً لطلبات HTTP.

AlloyDB

إذا كنت تستخدم OrderingAgent، عليك إعداد قاعدة بيانات AlloyDB لتخزين معلومات الطلبات. سنتناول تفاصيل ذلك في القسم التالي بعنوان "إعداد قاعدة البيانات".

ملف ‎.env

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

7. إعداد قاعدة البيانات

في إحدى الأدوات التي يستخدمها ordering_agent، والتي تُسمى "check_status"، نصل إلى قاعدة بيانات الطلبات في AlloyDB للحصول على حالة الطلبات. في هذا القسم، سنعمل على إعداد مجموعة ومثيل قاعدة بيانات AlloyDB.

إنشاء مجموعة ومثيل

انتقِل إلى صفحة AlloyDB في Cloud Console. تتمثّل إحدى الطرق السهلة للعثور على معظم الصفحات في Cloud Console في البحث عنها باستخدام شريط البحث في وحدة التحكّم.
اختَر إنشاء مجموعة من تلك الصفحة:

ستظهر لك شاشة مشابهة للشاشة أدناه. أنشئ مجموعة ومثيل بالقيم التالية (تأكَّد من تطابق القيم في حال استنساخ الرمز البرمجي للتطبيق من المستودع):

معرّف المجموعة: "vector-cluster"
كلمة المرور: "alloydb"
‫PostgreSQL 15 / أحدث إصدار يُنصح به
المنطقة: "us-central1"
الشبكات: "default"

عند اختيار الشبكة الافتراضية، ستظهر لك شاشة مثل الشاشة أدناه.

انقر على إعداد الاتصال.

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

احرص على تغيير رقم تعريف المثيل (الذي يمكنك العثور عليه عند إعداد المجموعة أو المثيل) إلى

vector-instance: إذا لم تتمكّن من تغييره، تذكَّر استخدام معرّف مثيلك في جميع المراجع القادمة.

يُرجى العِلم أنّ إنشاء المجموعة سيستغرق حوالي 10 دقائق. بعد إتمام العملية بنجاح، من المفترض أن تظهر لك شاشة تعرض نظرة عامة على المجموعة التي أنشأتها للتو.

نقل البيانات

حان الوقت الآن لإضافة جدول يتضمّن بيانات حول المتجر. انتقِل إلى AlloyDB، واختَر المجموعة الأساسية، ثم AlloyDB Studio:

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

اسم المستخدم : "postgres"
قاعدة البيانات : "postgres"
كلمة المرور : "alloydb"

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

ستُدخل أوامر AlloyDB في نوافذ المحرّر، باستخدام الخيارات "تشغيل" و"تنسيق" و"محو" حسب الحاجة.

إنشاء جدول

يمكنك إنشاء جدول باستخدام عبارة DDL أدناه في AlloyDB Studio:

-- Table DDL for Procurement Material Order Status

CREATE TABLE material_order_status (
    order_id VARCHAR(50) PRIMARY KEY,
    material_name VARCHAR(100) NOT NULL,
    supplier_name VARCHAR(100) NOT NULL,
    order_date DATE NOT NULL,
    estimated_delivery_date DATE,
    actual_delivery_date DATE,
    quantity_ordered INT NOT NULL,
    quantity_received INT,
    unit_price DECIMAL(10, 2) NOT NULL,
    total_amount DECIMAL(12, 2),
    order_status VARCHAR(50) NOT NULL, -- e.g., "Ordered", "Shipped", "Delivered", "Cancelled"
    delivery_address VARCHAR(255),
    contact_person VARCHAR(100),
    contact_phone VARCHAR(20),
    tracking_number VARCHAR(100),
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    quality_check_passed BOOLEAN,  -- Indicates if the material passed quality control
    quality_check_notes TEXT,        -- Notes from the quality control check
    priority VARCHAR(20),            -- e.g., "High", "Medium", "Low"
    project_id VARCHAR(50),          -- Link to a specific project
    receiver_name VARCHAR(100),        -- Name of the person who received the delivery
    return_reason TEXT,               -- Reason for returning material if applicable
    po_number VARCHAR(50)             -- Purchase order number
);

إدراج السجلات

انسخ عبارة طلب البحث insert من النص البرمجي database_script.sql المذكور أعلاه إلى المحرّر.

انقر على تشغيل.

بعد أن أصبحت مجموعة البيانات جاهزة، لننشئ تطبيق Java Cloud Run Functions لاستخراج الحالة.

إنشاء دالة Cloud Run بلغة Java لاستخراج معلومات حالة الطلب

يمكنك إنشاء دالة Cloud Run من هنا: https://console.cloud.google.com/run/create?deploymentType=function
اضبط اسم الدالة على check-status واختَر Java 17 كوقت تشغيل.
يمكنك ضبط المصادقة على "السماح بعمليات الاستدعاء غير المصادَق عليها" لأنّه تطبيق تجريبي.
اختَر Java 17 كوقت تشغيل و"أداة التعديل المضمّنة" للرمز المصدر.
في هذه المرحلة، سيتم تحميل رمز العنصر النائب في أداة التعديل.

استبدال رمز العنصر النائب

غيِّر اسم ملف Java إلى "ProposalOrdersTool.java" واسم الفئة إلى "ProposalOrdersTool".
استبدِل رمز العنصر النائب في ProposalOrdersTool.java وpom.xml بالرمز من الملفات ذات الصلة في المجلد "دالة Cloud Run" في هذا المستودع.
في ProposalOrdersTool.java، ابحث عن سطر الرمز التالي، واستبدِل قيم العناصر النائبة بقيم من إعداداتك:

String ALLOYDB_INSTANCE_NAME = "projects/<<YOUR_PROJECT_ID>>/locations/us-central1/clusters/<<YOUR_CLUSTER>>/instances/<<YOUR_INSTANCE>>";

انقر على "إنشاء".
سيتم إنشاء وظيفة Cloud Run ونشرها.

خطوة مهمة:

بعد النشر، وللسماح لوظيفة Cloud Function بالوصول إلى مثيل قاعدة بيانات AlloyDB، سننشئ موصِّل VPC.

بعد إعداد عملية النشر، من المفترض أن تتمكّن من رؤية الدوال في وحدة تحكّم "وظائف Google Cloud Run". ابحث عن الدالة التي تم إنشاؤها حديثًا (check-status)، وانقر عليها، ثم انقر على تعديل ونشر مراجعات جديدة (يتم تحديدها من خلال رمز التعديل (القلم) في أعلى وحدة تحكّم Cloud Run Functions)، وغيِّر ما يلي:

انتقِل إلى علامة التبويب "الاتصال بالشبكات" (Networking):

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

أدخِل اسمًا لموصِّل VPC وتأكَّد من أنّ المنطقة هي نفسها منطقة مثيلك. اترك قيمة "الشبكة" على الوضع التلقائي واضبط "الشبكة الفرعية" على "نطاق IP مخصّص" مع نطاق IP 10.8.0.0 أو نطاق مشابه متوفّر.
وسِّع SHOW SCALING SETTINGS وتأكَّد من ضبط الإعدادات على ما يلي بالضبط:

انقر على إنشاء، ومن المفترض أن يظهر هذا الموصل في إعدادات الخروج الآن.
اختَر الموصّل الذي تم إنشاؤه حديثًا.
اختَر توجيه كل حركة البيانات من خلال موصّل شبكة VPC هذا.
انقر على التالي ثم على نشر.
بعد نشر Cloud Function المعدَّلة، من المفترض أن تظهر نقطة النهاية التي تم إنشاؤها.
يمكنك اختبارها من خلال النقر على الزر TEST في أعلى وحدة تحكّم Cloud Run Functions وتنفيذ الأمر الناتج في "وحدة Cloud Shell الطرفية".
نقطة النهاية التي تم نشرها هي عنوان URL الذي عليك تعديله في المتغيّر CHECK_ORDER_STATUS_ENDPOINT في ملف ‎ .env.

8. إعداد النموذج

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

احصل على مفتاح واجهة برمجة التطبيقات من Google AI Studio.
في الخطوة التالية التي يتم فيها إعداد ملف ‎ .env، استبدِل <<your API KEY>> بقيمة مفتاح واجهة برمجة التطبيقات الفعلي.

9- إعداد متغيّرات ENV

اضبط قيم المَعلمات في ملف ‎ .env الخاص بالنموذج في هذا المستودع. في حالتي، يحتوي ملف ‎ .env على المتغيرات التالية:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION=us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT=<<your project id>>
PROJECT_ID=<<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET=next-demo-store <<or your storage bucket name>>
CHECK_ORDER_STATUS_ENDPOINT=<<YOUR_ENDPOINT_TO_CLOUD FUNCTION_TO_READ_ORDER_DATA_FROM_ALLOYDB>>

استبدِل العناصر النائبة بقيمك.

10. تشغيل الوكيل

باستخدام نافذة الأوامر، انتقِل إلى الدليل الرئيسي لمشروع الوكيل:

cd renovation-agent

تثبيت جميع الحِزم التابعة

pip install -r requirements.txt

يمكنك تنفيذ الأمر التالي في وحدة Cloud Shell الطرفية لتنفيذ الوكيل:

adk run .

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

adk web

جرِّب الطلبات التالية:

user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement. I have no other specification.

11. النتيجة

@ نظام متعدد الوكلاء لتنفيذ مهام تجديد المطابخ

12. النشر في Agent Engine

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

# Agent Engine Deployment:
# Create a remote app for our multiagent with agent Engine.
# This may take 1-2 minutes to finish.
# Uncomment the below segment when you're ready to deploy.

app = AdkApp(
    agent=root_agent,
    enable_tracing=True,
)

vertexai.init(
    project=PROJECT_ID,
    location=GOOGLE_CLOUD_LOCATION,
    staging_bucket=STAGING_BUCKET,
)

remote_app = agent_engines.create(
    app,
    requirements=[
        "google-cloud-aiplatform[agent_engines,adk]>=1.88",
        "google-adk",
        "pysqlite3-binary",
        "toolbox-langchain==0.1.0",
        "pdfplumber",
        "google-cloud-aiplatform",
        "cloudpickle==3.1.1",
        "pydantic==2.10.6",
        "pytest",
        "overrides",
        "scikit-learn",
        "reportlab",
        "google-auth",
        "google-cloud-storage",
    ],
)
# Deployment to Agent Engine related code ends

نفِّذ agent.py من داخل مجلد المشروع مرة أخرى باستخدام الأمر التالي:

>> cd adk-renovation-agent

>> python agent.py

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

'projects/123456789/locations/us-central1/reasoningEngines/123456'

يمكنك اختبار الوكيل الذي تم نشره باستخدام الرمز التالي من خلال إضافة ملف جديد باسم " test.py".

import vertexai
from vertexai.preview import reasoning_engines
from vertexai import agent_engines
import os
import warnings
from dotenv import load_dotenv
load_dotenv() 


GOOGLE_CLOUD_PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"]
GOOGLE_CLOUD_LOCATION = os.environ["GOOGLE_CLOUD_LOCATION"]
GOOGLE_API_KEY = os.environ["GOOGLE_API_KEY"]
GOOGLE_GENAI_USE_VERTEXAI=os.environ["GOOGLE_GENAI_USE_VERTEXAI"]
AGENT_NAME = "adk_renovation_agent"
MODEL_NAME = "gemini-2.5-pro-preview-03-25" 
warnings.filterwarnings("ignore")
PROJECT_ID = GOOGLE_CLOUD_PROJECT

reasoning_engine_id = "<<YOUR_DEPLOYED_ENGINE_ID>>"

vertexai.init(project=PROJECT_ID, location="us-central1")
agent = agent_engines.get(reasoning_engine_id)
print("**********************")
print(agent)
print("**********************")


for event in agent.stream_query(
    user_id="test_user",
    message="I want you to check order status.",
):
    print(event)

في الرمز أعلاه، استبدِل قيمة العنصر النائب "<<YOUR_DEPLOYED_ENGINE_ID>>" ونفِّذ الأمر "python test.py"، وستكون جاهزًا لتنفيذ هذا الأمر للتفاعل مع نظام متعدد الوكلاء تم نشره باستخدام Agent Engine، وستكون جاهزًا لتجديد مطبخك.

13. خيارات النشر بسطر واحد

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

إلى Cloud Run:

البنية:

adk deploy cloud_run \
--project=<<YOUR_PROJECT_ID>> \
--region=us-central1 \
--service_name=<<YOUR_SERVICE_NAME>> \
--app_name=<<YOUR_APP_NAME>> \
--with_ui \
./<<YOUR_AGENT_PROJECT_NAME>>

في هذه الحالة:

adk deploy cloud_run \
--project=<<YOUR_PROJECT_ID>> \
--region=us-central1 \
--service_name=renovation-agent \
--app_name=renovation-app \
--with_ui \
./renovation-agent

يمكنك استخدام نقطة النهاية التي تم نشرها لعمليات الدمج اللاحقة.

إلى Agent Engine:

البنية:

adk deploy agent_engine \
  --project <your-project-id> \
  --region us-central1 \
  --staging_bucket gs://<your-google-cloud-storage-bucket> \
  --trace_to_cloud \
  path/to/agent/folder

في هذه الحالة:

adk deploy agent_engine --project <<YOUR_PROJECT_ID>> --region us-central1 --staging_bucket gs://<<YOUR_BUCKET_NAME>> --trace_to_cloud renovation-agent

من المفترض أن يظهر لك وكيل جديد في واجهة مستخدم Agent Engine ضمن Google Cloud Console. يمكنك الرجوع إلى هذه المدونة لمزيد من التفاصيل.

14. تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذه المشاركة، اتّبِع الخطوات التالية:

في Google Cloud Console، انتقِل إلى صفحة إدارة الموارد.
في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف.
في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.

15. تهانينا

تهانينا! لقد أنشأت أول وكيل لك وتفاعلت معه بنجاح باستخدام حزمة نشر الوكلاء (ADK).