إنشاء تطبيق متعدّد الوكلاء باستخدام مجموعة أدوات MCP لـ AlloyDB وADK

1. نظرة عامة

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

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

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

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

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

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

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

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

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

ما ستنشئه

لننشئ نظامًا متعدد الوكلاء للتعامل مع عمليات تجديد المطابخ باستخدام MCP Toolbox على AlloyDB وADK.

1. وكيل اقتراحات التجديد
2. Permits and Compliance Check Agent
3. التحقّق من حالة الطلب (أداة تستخدم MCP Toolbox لقواعد البيانات)

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

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

Order Status Check Agent، للتحقّق من حالة طلب المواد من خلال العمل على قاعدة بيانات إدارة الطلبات التي أعددناها في AlloyDB ولكن بالنسبة إلى جزء قاعدة البيانات هذا، سنستخدم MCP Toolbox for AlloyDB لتنفيذ منطق استرجاع حالة الطلبات.

2. MCP

‫MCP هو اختصار لـ Model Context Protocol، وهو معيار مفتوح طوّرته شركة Anthropic ويوفر طريقة متسقة لوكلاء الذكاء الاصطناعي للاتصال بالأدوات والخدمات والبيانات الخارجية. وهي تعمل بشكل أساسي كمعيار مشترك لتطبيقات الذكاء الاصطناعي، ما يسمح لها بالتفاعل بسلاسة مع مصادر البيانات والأدوات المختلفة.

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

MCP Toolbox for Databases

خادم MCP Toolbox for Databases من Google هو خادم MCP مفتوح المصدر لقواعد البيانات. تم تصميمه مع مراعاة الجودة المناسبة للمؤسسات والإنتاج. تتيح لك تطوير الأدوات بسهولة أكبر وبسرعة أكبر وبشكل أكثر أمانًا من خلال التعامل مع التعقيدات، مثل تجميع الاتصالات والمصادقة وغير ذلك.

السماح لوكلائك بالوصول إلى البيانات في قاعدة البيانات كيف؟

تطوير مبسط: يمكنك دمج الأدوات في برنامجك الآلي باستخدام أقل من 10 أسطر من الرموز البرمجية، وإعادة استخدام الأدوات بين برامج آلية أو أُطر متعددة، ونشر إصدارات جديدة من الأدوات بسهولة أكبر.

أداء أفضل: أفضل الممارسات، مثل تجميع الاتصالات والمصادقة وغير ذلك

أمان محسّن: مصادقة مدمجة للوصول إلى بياناتك بشكل أكثر أمانًا

إمكانية تتبُّع البيانات الشاملة: مقاييس وتتبُّع جاهزة للاستخدام مع دعم مدمج لـ OpenTelemetry

يجب التنويه إلى أنّ هذا الإجراء كان متاحًا قبل إطلاق برنامج "شركاء المحتوى المميّزين"!!!

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

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

المتطلبات

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

3- قبل البدء

إنشاء مشروع

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

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

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

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

7. فعِّل واجهات برمجة التطبيقات التالية من خلال تنفيذ الأوامر التالية:

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

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

4. إعداد ADK

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

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

python -m venv .venv

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

source .venv/bin/activate

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

pip install google-adk

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

3. من "وحدة طرفية Cloud Shell"، نفِّذ الأوامر التالية واحدًا تلو الآخر لإنشاء مجلدات الجذر والمشروع:

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

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

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

6. رمز المصدر

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

from . import agent

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

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

في ملف agent.py، نستورد التبعيات اللازمة، ونسترجع مَعلمات الإعداد من ملف ‎ .env، ونحدّد root_agent الذي يستخدم أداة واحدة لاستدعاء أداة صندوق الأدوات.

3. انتقِل إلى ملف requirements.txt وعدِّله باستخدام المحتوى التالي:

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt

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

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

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

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

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

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

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

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

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

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

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

7. استعدادًا لإعداد Toolbox، لنبدأ بتفعيل إمكانية الاتصال بعنوان IP عام في مثيل AlloyDB حتى تتمكّن الأداة الجديدة من الوصول إلى قاعدة البيانات.
8. انتقِل إلى قسم "الاتصال بعنوان IP علني"، ضَع علامة في المربّع "تفعيل عنوان IP علني" وأدخِل عنوان IP لجهاز Cloud Shell.
9. للحصول على عنوان IP لجهاز Cloud Shell، انتقِل إلى "وحدة طرفية Cloud Shell" وأدخِل ifconfig. من النتيجة، حدِّد عنوان inet الخاص بـ eth0 واستبدِل آخر رقمَين بـ 0.0 مع حجم قناع "‎/16". على سبيل المثال، سيبدو على النحو التالي: "XX.XX.0.0/16" حيث XX هي أرقام.
10. ألصِق عنوان IP هذا في مربّع النص "الشبكات" ضمن "الشبكات الخارجية المسموح بها" في صفحة تعديل المثيل.

4. بعد إعداد شبكتك، يمكنك مواصلة إنشاء مجموعتك. انقر على CREATE CLUSTER (إنشاء مجموعة) لإكمال إعداد المجموعة كما هو موضّح أدناه:

يُرجى العِلم أنّ إنشاء المجموعة سيستغرق حوالي 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 المذكور أعلاه إلى المحرّر.

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

بعد أن أصبحت مجموعة البيانات جاهزة، لنقم بإعداد MCP Toolbox for Databases لتعمل كلوحة تحكّم في جميع تفاعلات "قاعدة بيانات الطلبات" في AlloyDB.

8. إعداد MCP Toolbox for Databases

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

يمكنك ملاحظة أنّ إحدى قواعد البيانات المتوافقة مع MCP Toolbox for Databases هي AlloyDB، وبما أنّنا قد أعددناها في القسم السابق، لننتقل إلى إعداد Toolbox.

1. انتقِل إلى "وحدة Cloud Shell الطرفية" وتأكَّد من اختيار مشروعك وعرضه في موجّه الوحدة الطرفية. نفِّذ الأمر التالي من "وحدة Cloud Shell الطرفية" للانتقال إلى دليل مشروعك:

cd adk-renovation-agent

2. نفِّذ الأمر أدناه لتنزيل مجموعة الأدوات وتثبيتها في مجلدك الجديد:

# see releases page for other versions
export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

3. انتقِل إلى "محرّر Cloud Shell" (لوضع تعديل الرمز) وأضِف ملفًا باسم "tools.yaml" في مجلد جذر المشروع.

sources:
    alloydb-orders:
        kind: "alloydb-postgres"
        project: "<<YOUR_PROJECT_ID>>"
        region: "us-central1"
        cluster: "<<YOUR_ALLOYDB_CLUSTER>>"
        instance: "<<YOUR_ALLOYDB_INSTANCE>>"
        database: "<<YOUR_ALLOYDB_DATABASE>>"
        user: "<<YOUR_ALLOYDB_USER>>"
        password: "<<YOUR_ALLOYDB_PASSWORD>>"

tools:
  get-order-data:
    kind: postgres-sql
    source: alloydb-orders
    description: Get the status of an order based on the material description.
    parameters:
      - name: description
        type: string
        description: A description of the material to search for its order status.
    statement: |
      select order_status from material_order_status where lower(material_name) like lower($1) 
      LIMIT 1;

في جزء طلب البحث (راجِع المَعلمة "عبارة" أعلاه)، نحن نستردّ قيمة الحقل حالة الطلب فقط عندما يتطابق اسم المادة مع نص بحث المستخدم.

لنتعرّف على ملف tools.yaml

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

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

لمزيد من التفاصيل حول ضبط ملف tools.yaml، يُرجى الرجوع إلى هذه المستندات.

لننفّذ خادم MCP Toolbox for Databases

نفِّذ الأمر التالي (من مجلد mcp-toolbox) لبدء الخادم:

./toolbox --tools-file "tools.yaml"

إذا فتحت الخادم الآن في وضع معاينة الويب على السحابة الإلكترونية، من المفترض أن تتمكّن من رؤية خادم "صندوق الأدوات" يعمل مع أداتك الجديدة التي تحمل الاسم get-order-data.

يتم تشغيل خادم MCP Toolbox تلقائيًا على المنفذ 5000. لنستخدم Cloud Shell لاختبار ذلك.

انقر على "معاينة الويب" في Cloud Shell كما هو موضّح أدناه:

انقر على "تغيير المنفذ" (Change port) واضبط المنفذ على 5000 كما هو موضّح أدناه، ثم انقر على "تغيير ومعاينة" (Change and Preview).

من المفترض أن يؤدي ذلك إلى ظهور الناتج التالي:

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

لننشُر Toolbox على Cloud Run

أولاً، يمكننا البدء بخادم MCP Toolbox واستضافته على Cloud Run. سيمنحنا ذلك نقطة نهاية عامة يمكننا دمجها مع أي تطبيق آخر و/أو تطبيقات "الوكيل" أيضًا. تتوفر تعليمات استضافة هذا التطبيق على Cloud Run هنا. سنستعرض الآن الخطوات الرئيسية.

1. ابدأ نافذة "وحدة طرفية" جديدة في Cloud Shell أو استخدِم نافذة حالية. انتقِل إلى مجلد المشروع الذي يتضمّن ملفات البرنامج الثنائي لـ toolbox وtools.yaml، وفي هذه الحالة adk-renovation-agent
2. اضبط المتغيّر PROJECT_ID للإشارة إلى رقم تعريف مشروعك على Google Cloud.

export PROJECT_ID="<<YOUR_GOOGLE_CLOUD_PROJECT_ID>>"

3. تفعيل خدمات Google Cloud التالية

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

4. لننشئ حساب خدمة منفصلاً سيعمل كمعرّف لخدمة Toolbox التي سننشرها على Google Cloud Run.

gcloud iam service-accounts create toolbox-identity

5. نحرص أيضًا على أن يكون لحساب الخدمة هذا الأدوار الصحيحة، أي القدرة على الوصول إلى Secret Manager والتواصل مع AlloyDB.

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/alloydb.client

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/serviceusage.serviceUsageConsumer

6. سنحمّل ملف tools.yaml كمفتاح سرّي:

gcloud secrets create tools --data-file=tools.yaml

إذا كان لديك رمز سري وتريد تعديل إصدار الرمز السري، نفِّذ ما يلي:

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

اضبط متغيّر بيئة على صورة الحاوية التي تريد استخدامها في Cloud Run:

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

7. الخطوة الأخيرة في أمر النشر المألوف إلى Cloud Run:

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

من المفترض أن تبدأ هذه الخطوة عملية نشر Toolbox Server باستخدام ملف tools.yaml الذي تم إعداده على Cloud Run. عند اكتمال عملية النشر بنجاح، من المفترض أن تظهر لك رسالة مشابهة لما يلي:

Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.                                                                                                                                                                                     
  OK Creating Revision...                                                                                                                                                                                             
  OK Routing traffic...                                                                                                                                                                                               
  OK Setting IAM Policy...                                                                                                                                                                                            
Done.                                                                                                                                                                                                                 
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app

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

لنربط أداة Toolbox بالوكيل.

لقد أنشأنا المصدر لتطبيق الوكيل. لنعدّل ذلك ليشمل أداة MCP Toolbox for Databases الجديدة التي نشرناها للتو في Cloud Run.

1. مراقبة ملف requirements.txt مع المصدر من المستودع:

نحن ندرج الاعتمادية الخاصة بـ MCP Toolbox for Databases في ملف requirements.txt.

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt

2. راقب ملف agent.py باستخدام الرمز من المستودع:

نحن نضمّن الأداة التي تستدعي نقطة نهاية صندوق الأدوات لجلب بيانات الطلبات الخاصة بمادة معيّنة تم طلبها.

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

9- إعداد النموذج

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

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

10. إعداد متغيّرات ENV

1. اضبط قيم المَعلمات في ملف .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>>

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

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

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

cd renovation-agent

3. ثبِّت التبعيّات:

pip install -r requirements.txt

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

adk run .

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

adk web

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

user>> 

Hello. Check order status for Cement Bags.

12. النتيجة

13. تَنظيم

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

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

14. تهانينا

تهانينا! لقد أنشأت بنجاح تطبيقًا متعدد الوكلاء باستخدام ADK وMCP Toolbox لقواعد البيانات. لمزيد من المعلومات، يُرجى الرجوع إلى مستندات المنتج: Agent Development Kit وMCP Toolbox لقواعد البيانات.