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

لمحة عن هذا الدرس التطبيقي حول الترميز

تاريخ التعديل الأخير: يونيو 16, 2025

تأليف: Author: Abirami Sukumaran

1. نظرة عامة

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

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

مجموعة تطوير موظّفي الدعم (ADK)

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

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

نقاط يجب أخذها في الاعتبار في ما يتعلّق بالأنظمة المتعدّدة الوكلاء

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

الخطوة الثانية: كيفية جمعها مع موظّف دعم رئيسي لتوجيه كلّ ردّ وفهم معناه

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

ما ستُنشئه

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

وكيل عروض التجديد
وكيل التحقّق من التصاريح والامتثال
موظّف دعم للتحقق من حالة الطلب

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

موظّف تراخيص وامتثال، لرعاية المهام المتعلّقة بالتراخيص والامتثال

وكيل التحقّق من حالة الطلب، للتحقّق من حالة طلب المواد من خلال العمل على قاعدة بيانات إدارة الطلبات التي تم إعدادها في AlloyDB

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

المتطلبات

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

2. قبل البدء

إنشاء مشروع

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

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

فعِّل Cloud Shell بالنقر على هذا الرابط. يمكنك التبديل بين Cloud Shell Terminal (لتشغيل أوامر السحابة الإلكترونية) وEditor (لإنشاء المشاريع) من خلال النقر على الزر المقابل من 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 المصادر أيضًا.

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

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

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

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

حصلت على هذا الناتج:

هذه هي قوة Gemini.

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

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

4. إعداد حزمة ADK

إنشاء بيئة افتراضية وتفعيلها (إجراء مقترَح)

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

python -m venv .venv

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

source .venv/bin/activate

تثبيت حزمة ADK

pip install google-adk

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

من Terminal في 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 (في خطوة إعداد متغيّرات 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. يمكنك نسخ هذا من repo.

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

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

تعريفات موظّفي الدعم

RenovationProposalAgent

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

PermitsAndComplianceCheckAgent

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

OrderingAgent

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

الوكيل الجذر (المنسق)

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

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

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

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

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

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

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

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. إعداد قاعدة البيانات

في إحدى الأدوات التي يستخدمها وكيل_الشراء، والتي تُسمى "التحقّق_من_الحالة"، يمكننا الوصول إلى قاعدة بيانات الطلبات في 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 Function" في هذا المستودع.
في ProposalOrdersTool.java، ابحث عن السطر التالي من التعليمات البرمجية، واستبدِل قيم العناصر النائبة بقيم من الإعدادات:

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

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

خطوة مهمة:

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

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

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

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

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

انقر على إنشاء، ومن المفترض أن يظهر هذا الموصّل في إعدادات الخروج الآن.
اختَر الموصّل الذي تم إنشاؤه حديثًا.
اختَر توجيه جميع الزيارات من خلال موصِّل VPC هذا.
انقر على التالي ثم على نشر.
بعد نشر Cloud Function المعدَّلة، من المفترض أن تظهر لك نقطة النهاية التي تم إنشاؤها.
من المفترض أن تتمكّن من اختبارها من خلال النقر على الزر TEST (اختبار) في أعلى وحدة تحكّم وظائف Cloud Run وتنفيذ الأمر الناتج في Cloud Shell Terminal.
نقطة النهاية المنشورة هي عنوان 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:

adk web

يمكنك إجراء الاختبار باستخدام الطلبات التالية:

user>> 

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

11. النتيجة

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

12. النشر في "محرك موظّف الدعم"

بعد أن اختبرت نظام موظّفي الدعم المتعدّدين وتأكدّت من أنّه يعمل بشكل جيد، لنجعله غير مستند إلى خادم ومتاحًا على السحابة الإلكترونية لكي يستخدمه أي مستخدم أو تطبيق. أزِل التعليقات من مقتطف الرمز البرمجي أدناه في 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"، وسيكون بإمكانك تنفيذ هذا الإجراء للتفاعل مع نظام متعدّد الوكلاء تم نشره في "محرك الوكيل"، وسيكون بإمكانك تجديد مطبخك.

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

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

إلى محرك موظّفي الدعم:

البنية:

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

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

14. تَنظيم

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

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

15. تهانينا

تهانينا! لقد نجحت في إنشاء موظّف الدعم الأول والتفاعل معه باستخدام ADK.

الإبلاغ عن خطأ