لمحة عن هذا الدرس التطبيقي حول الترميز
1. نظرة عامة
الوكيل هو برنامج مستقل يتواصل مع نموذج الذكاء الاصطناعي لتنفيذ عملية مستندة إلى الأهداف باستخدام الأدوات والسياق المتوفّرَين لديه، وهو قادر على اتّخاذ قرارات مستقلة تستند إلى الحقائق.
عندما يتضمّن تطبيقك موظّفي دعم متعدّدين يعملون معًا بشكل مستقل وجماعي على النحو المطلوب لتلبية الغرض الأكبر منه، مع أنّ كل موظّف دعم لديه معرفة مستقلة ويكون مسؤولاً عن مجال تركيز معيّن، يصبح تطبيقك نظام موظّفي دعم متعدّدين.
مجموعة تطوير موظّفي الدعم (ADK)
مجموعة تطوير موظّفي الدعم (ADK) هي إطار عمل مرن ومكوّن من وحدات لتطوير موظّفي الدعم المستندين إلى الذكاء الاصطناعي ونشرهم. تتيح ADK إنشاء تطبيقات متقدّمة من خلال إنشاء مثيلات متعدّدة ومميّزة للوكيل في نظام متعدّد الوكلاء (MAS).
في ADK، نظام الوكلاء المتعدّدين هو تطبيق يتعاون فيه وكلاء مختلفون أو ينسقون لتحقيق هدف أكبر، وغالبًا ما يشكّلون تسلسلاً هرميًا. توفّر لك بنية تطبيقك هذه مزايا كبيرة، بما في ذلك الوحدات المحسّنة والتخصص وإمكانية إعادة الاستخدام وسهولة الصيانة والقدرة على تحديد مسارات التحكّم منظَّمة باستخدام وكلاء سير العمل المخصّصين.
نقاط يجب أخذها في الاعتبار في ما يتعلّق بالأنظمة المتعدّدة الوكلاء
أولاً، من المهم أن يكون لديك فهم وسبب مناسبَين للتخصص لكل موظّف. — "هل تعرف سبب حاجتك إلى موظّف دعم فرعي محدّد لإجراء ما"، عليك تحديد ذلك أولاً.
الخطوة الثانية: كيفية جمعها مع موظّف دعم رئيسي لتوجيه كلّ ردّ وفهم معناه
ثالثًا، هناك أنواع متعدّدة من عمليات توجيه موظّفي الدعم التي يمكنك العثور عليها هنا في هذه المستندات. حدِّد الطريقة التي تناسب مسار تطبيقك. بالإضافة إلى ذلك، عليك تحديد السياقات والحالات المختلفة التي تحتاج إليها للتحكّم في سير عمل نظام متعدّد الوكلاء.
ما ستُنشئه
لننشئ نظامًا متعدّد الوكلاء للتعامل مع عمليات تجديد المطابخ باستخدام أدوات MCP لـ AlloyDB وADK.
- وكيل عروض التجديد
- وكيل التحقّق من التصاريح والامتثال
- التحقّق من حالة الطلب (أداة تستخدِم مجموعة أدوات MCP لقواعد البيانات)
وكيل اقتراحات التجديد، لإنشاء مستند اقتراح تجديد المطبخ
موظّف تراخيص وامتثال، لرعاية المهام المتعلّقة بالتراخيص والامتثال
وكيل التحقّق من حالة الطلب، للتحقّق من حالة طلب المواد من خلال العمل على قاعدة بيانات إدارة الطلبات التي تم إعدادها في AlloyDB ولكن بالنسبة إلى جزء قاعدة البيانات هذا، سنستخدم مجموعة أدوات MCP لـ AlloyDB لتنفيذ منطق استرداد حالة الطلبات.
2. MCP
اختصار MCP يشير إلى Model Context Protocol، وهو معيار مفتوح تم تطويره من قِبل Anthropic يقدّم طريقة متّسقة لتفاعل موظّفي الذكاء الاصطناعي مع الأدوات والخدمات والبيانات الخارجية. ويعمل هذا المعيار بشكل أساسي كمعيار شائع لتطبيقات الذكاء الاصطناعي، ما يتيح لها التفاعل بسلاسة مع مصادر البيانات والأدوات المختلفة.
- ويستخدم هذا النموذج نموذج العميل والخادم، حيث تعمل تطبيقات الذكاء الاصطناعي (المضيفون) على تشغيل برنامج MCP Client الذي يتواصل مع خوادم MCP.
- عندما يحتاج موظّف دعم الذكاء الاصطناعي إلى الوصول إلى أداة أو بيانات معيّنة، يرسل طلبًا منظّمًا إلى برنامج MCP، الذي يعيد توجيهه إلى خادم MCP المناسب.
- السماح لنماذج الذكاء الاصطناعي بالوصول إلى البيانات والأدوات الخارجية بدون الحاجة إلى رمز مخصّص لكل عملية دمج
- تبسيط عملية إنشاء موظّفي الدعم ومسارات العمل المعقّدة استنادًا إلى النماذج اللغوية الكبيرة (LLM)
مجموعة أدوات "مركز عملائي" لقواعد البيانات
أداة MCP Toolbox لقواعد البيانات من Google هي خادم MCP مفتوح المصدر لقواعد البيانات. تم تصميمه على مستوى المؤسسة وبجودة الإنتاج. ويتيح لك تطوير الأدوات بسهولة أكبر وأسرع وأمان أكبر من خلال التعامل مع التعقيدات، مثل تجميع الاتصالات والمصادقة وغير ذلك.
السماح لموظّفي الدعم بالوصول إلى البيانات في قاعدة بياناتك الطريقة
التطوير المبسّط: يمكنك دمج الأدوات مع موظّف الدعم في أقل من 10 أسطر من الرموز البرمجية، وإعادة استخدام الأدوات بين موظّفي الدعم أو أطر العمل المتعددة، ونشر إصدارات جديدة من الأدوات بسهولة أكبر.
أداء أفضل: أفضل الممارسات، مثل تجميع الاتصالات والمصادقة وغير ذلك
أمان مُحسَّن: مصادقة مدمجة للوصول إلى بياناتك بأمان أكبر
إمكانية المراقبة من البداية إلى النهاية: مقاييس وتتبُّع فوريَين مع دعم مضمّن لـ OpenTelemetry
يجب الإشارة إلى أنّ هذا الطلب سبق إنشاء "برنامج شركاء المحتوى".
تقع "مجموعة أدوات MCP لقواعد البيانات" بين إطار عمل تنسيق تطبيق الوكيل وقاعدة بياناتك، ما يوفر خطة تحكّم تُستخدَم لتعديل الأدوات أو توزيعها أو تشغيلها. ويبسّط هذا الإجراء إدارة أدواتك من خلال تزويدك بموقع مركزي لتخزين الأدوات وتعديلها، ما يتيح لك مشاركة الأدوات بين موظّفي الدعم والتطبيقات وتعديل هذه الأدوات بدون إعادة نشر تطبيقك بالضرورة.
سيكون لدينا موظّف دعم رئيسي ينظّم موظّفي الدعم هؤلاء استنادًا إلى المتطلبات.
المتطلبات
3. قبل البدء
إنشاء مشروع
- في 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>
- فعِّل واجهات برمجة التطبيقات التالية من خلال تنفيذ الأوامر التالية:
gcloud services enable artifactregistry.googleapis.com \cloudbuild.googleapis.com \run.googleapis.com \aiplatform.googleapis.com \alloydb.googleapis.com
- تأكَّد من توفُّر الإصدار 3.9 من Python أو الإصدارات الأحدث.
- راجِع المستندات لمعرفة أوامر gcloud وكيفية استخدامها.
4. إعداد حزمة ADK
- إنشاء بيئة افتراضية وتفعيلها (إجراء مقترَح)
من Cloud Shell Terminal، أنشئ بيئة افتراضية:
python -m venv .venv
فعِّل البيئة الافتراضية:
source .venv/bin/activate
- تثبيت حزمة ADK
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
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). - أنشئها في الموقع الجغرافي us-central1.
- لإعداد إمكانية الوصول إلى الحزمة، انتقِل إلى وحدة تحكّم 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.
7. إعداد قاعدة البيانات
في إحدى الأدوات التي يستخدمها وكيل_الشراء، والتي تُسمى "التحقّق_من_الحالة"، يمكننا الوصول إلى قاعدة بيانات الطلبات في AlloyDB للحصول على حالة الطلبات. في هذا القسم، سننشئ مجموعة مثيل قاعدة بيانات AlloyDB.
إنشاء مجموعة ومثيل
- انتقِل إلى صفحة AlloyDB في Cloud Console. إنّ البحث عن معظم الصفحات في Cloud Console باستخدام شريط البحث في وحدة التحكّم هو طريقة سهلة للعثور عليها.
- اختَر إنشاء مجموعة من هذه الصفحة:
- ستظهر لك شاشة مثل الشاشة أدناه. أنشئ مجموعة ومثيلًا بالقيم التالية (تأكَّد من تطابق القيم في حال كنت تُنشئ نسخة طبق الأصل من رمز التطبيق من المستودع):
- معرّف المجموعة: "
vector-cluster" - كلمة المرور: "
alloydb" - متوافق مع PostgreSQL 16 / يُنصح باستخدام أحدث إصدار
- المنطقة: "
us-central1" - التواصل: "
default"
- عند اختيار الشبكة التلقائية، ستظهر لك شاشة مثل الشاشة أدناه.
انقر على إعداد عملية الربط.
- من هناك، اختَر "استخدام نطاق IP مخصّص تلقائيًا" ثم انقر على "متابعة". بعد مراجعة المعلومات، انقر على "إنشاء اتصال".
6- ملاحظة مهمة: تأكَّد من تغيير رقم تعريف المثيل (الذي يمكنك العثور عليه في وقت ضبط المجموعة أو المثيل) إلى
vector-instance. إذا لم تتمكّن من تغييره، تذكَّر استخدام رقم تعريف المثيل في جميع الإحالات القادمة.
- استعدادًا لإعداد Toolbox، لنبدأ بتفعيل الاتصال بعنوان IP العلني في مثيل AlloyDB حتى تتمكّن الأداة الجديدة من الوصول إلى قاعدة البيانات.
- انتقِل إلى قسم "إمكانية الاتصال بعنوان IP المتاح للجميع"، ضَع علامة في مربّع الاختيار "تفعيل عنوان IP المتاح للجميع" وأدخِل عنوان IP لجهاز Cloud Shell.
- للحصول على عنوان IP لجهاز Cloud Shell، انتقِل إلى Cloud Shell Terminal وأدخِل ifconfig. من النتيجة، حدِّد عنوان inet الخاص بـ eth0 واستبدِل آخر رقمين بـ 0.0 مع حجم قناع "/16". على سبيل المثال، سيظهر على النحو التالي: "XX.XX.0.0/16" حيث يكون XX أرقامًا.
- الصِق عنوان IP هذا في مربّع نص "الشبكات" للشبكات الخارجية المعتمَدة في صفحة تعديل المثيل.
- بعد إعداد شبكتك، يمكنك مواصلة إنشاء مجموعتك. انقر على 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" لقواعد البيانات كي تعمل بمثابة مستوى التحكّم في جميع تفاعلات قاعدة بيانات الطلبات في AlloyDB.
8. مجموعة أدوات MCP لإعداد قواعد البيانات
يقع "صندوق الأدوات" بين إطار عمل تنسيق تطبيقك وقاعدة بياناتك، ما يوفر خطة تحكّم تُستخدَم لتعديل الأدوات أو توزيعها أو تشغيلها. ويبسّط هذا الإجراء إدارة أدواتك من خلال تزويدك بموقع مركزي لتخزين الأدوات وتعديلها، ما يتيح لك مشاركة الأدوات بين موظّفي الدعم والتطبيقات وتعديل هذه الأدوات بدون إعادة نشر تطبيقك بالضرورة.
يمكنك ملاحظة أنّ إحدى قواعد البيانات المتوافقة مع Toolbox لقواعد البيانات في "مركز إدارة العملاء" هي AlloyDB، وبما أنّنا سبق أن وفّرنا هذه القاعدة في القسم السابق، لنبدأ في إعداد Toolbox.
- انتقِل إلى Cloud Shell Terminal وتأكَّد من اختيار مشروعك وعرضه في طلب المحطة الطرفية. نفِّذ الأمر التالي من وحدة تحكّم Cloud Shell للانتقال إلى دليل مشروعك:
cd adk-renovation-agent
- نفِّذ الأمر التالي لتنزيل أداة الأدوات وتثبيتها في المجلد الجديد:
# 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
- انتقِل إلى محرِّر 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;
في جزء طلب البحث (راجِع مَعلمة "statement" أعلاه)، ما نحصل عليه هو قيمة الحقل order_status فقط عندما يتطابق اسم المادة مع نص بحث المستخدم.
لنلقِ نظرة على ملف tools.yaml.
تمثّل المصادر مصادر البيانات المختلفة التي يمكن للأداة التفاعل معها. يمثّل المصدر مصدر بيانات يمكن للأداة التفاعل معه. يمكنك تعريف "المصادر" على أنّها خريطة في قسم "المصادر" من ملف tools.yaml. ستتضمّن إعدادات المصدر عادةً أي معلومات مطلوبة للربط بقاعدة البيانات والتفاعل معها.
تحدِّد الأدوات الإجراءات التي يمكن للموظف اتّخاذها، مثل القراءة والكتابة في مصدر. تمثّل الأداة إجراءً يمكن لموظّف الدعم اتّخاذه، مثل تشغيل عبارة SQL. يمكنك تحديد "الأدوات" كخريطة في قسم "الأدوات" من ملف tools.yaml. عادةً ما تتطلّب الأداة مصدرًا لإجراء إجراء بشأنه.
لمزيد من التفاصيل حول ضبط tools.yaml، يُرجى الرجوع إلى هذه الوثائق.
لنبدأ بتشغيل مجموعة أدوات MCP لخادم قواعد البيانات.
شغِّل الأمر التالي (من مجلد mcp-toolbox) لبدء تشغيل الخادم:
./toolbox --tools-file "tools.yaml"
الآن، إذا فتحت الخادم في وضع معاينة الويب على السحابة الإلكترونية، من المفترض أن يظهر لك خادم Toolbox مفعّلاً باستخدام أداتك الجديدة التي تحمل الاسم get-order-data.
يتم تشغيل خادم MCP Toolbox تلقائيًا على المنفذ 5000. لنستخدم Cloud Shell لاختبار ذلك.
انقر على "معاينة الويب" في Cloud Shell كما هو موضّح أدناه:
انقر على "تغيير المنفذ" واضبط المنفذ على 5000 كما هو موضّح أدناه، ثم انقر على "تغيير" و"معاينة".
من المفترض أن يؤدي ذلك إلى ظهور النتيجة التالية:
توضّح حزمة أدوات MCP لقواعد البيانات حزمة تطوير برامج Python كي تتمكّن من التحقّق من صحة الأدوات واختبارها، ويمكن الاطّلاع على مستندات هذه الحزمة هنا. سنتخطّى ذلك وننتقل مباشرةً إلى "مجموعة تطوير موظّفي الدعم" (ADK) في القسم التالي الذي سيستخدم هذه الأدوات.
لننشر Toolbox على Cloud Run
أولاً، يمكننا البدء بخادم MCP Toolbox واستضافته على Cloud Run. سيمنحنا ذلك نقطة نهاية عامة يمكننا دمجها مع أي تطبيق آخر و/أو تطبيقات موظّفي الدعم أيضًا. يمكنك الاطّلاع على تعليمات استضافة هذا التطبيق على Cloud Run هنا. سنوضّح الخطوات الرئيسية الآن.
- افتح وحدة طرفية جديدة في Cloud Shell أو استخدِم وحدة طرفية حالية في Cloud Shell. انتقِل إلى مجلد المشروع الذي يتضمّن ملف toolbox binary وملف tools.yaml، وفي هذه الحالة adk-renovation-agent.
- اضبط المتغيّر PROJECT_ID للإشارة إلى رقم تعريف مشروعك على Google Cloud.
export PROJECT_ID="<<YOUR_GOOGLE_CLOUD_PROJECT_ID>>"
- تفعيل خدمات Google Cloud التالية
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
- لننشئ حساب خدمة منفصلاً سيكون بمثابة هوية لخدمة Toolbox التي سننشرها على Google Cloud Run.
gcloud iam service-accounts create toolbox-identity
- نحن نحرص أيضًا على أن يكون لحساب الخدمة هذا الأدوار الصحيحة، أي إمكانية الوصول إلى 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
- سنحمّل ملف 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
- الخطوة الأخيرة في أمر النشر المألوف إلى 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
يمكنك الآن استخدام الأداة التي تم نشرها حديثًا في تطبيقك المخصّص للعملاء.
لنربط أداة "صندوق الأدوات" بموظف الدعم.
لقد أنشأنا مصدرًا لنظامنا المتعدد الوكلاء. لنعدّل ذلك لتضمين أداة جديدة في "مجموعة أدوات MCP" لقواعد البيانات التي نشرناها للتو في Cloud Run.
- عدِّل ملف requirements.txt باستخدام المصدر من المستودع:
نحن بصدد تضمين التبعيات الخاصة بـ MCP Toolbox for Databases في requirements.txt
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt
- عدِّل ملف agent.py باستخدام الرمز من المستودع:
نحن بصدد تضمين الأداة التي تستدعي نقطة نهاية مجموعة الأدوات لجلب بيانات الطلب لمادة معيّنة تم طلبها.
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py
9. إعداد النموذج
تستند قدرة موظّف الدعم على فهم طلبات المستخدمين وإنشاء الردود إلى نموذج لغوي كبير (LLM). على موظّف الدعم إجراء مكالمات آمنة بخدمة LLM الخارجية هذه، ما يتطلّب بيانات اعتماد المصادقة. في حال عدم توفّر مصادقة صالحة، سترفض خدمة LLM طلبات الوكيل، ولن يتمكّن الوكيل من العمل.
- احصل على مفتاح واجهة برمجة التطبيقات من Google AI Studio.
- في الخطوة التالية التي يتم فيها إعداد ملف .env، استبدِل
<<your API KEY>>بقيمة مفتاح واجهة برمجة التطبيقات الفعلية.
10. إعداد متغيّرات 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>>
استبدِل العناصر النائبة بقيمك.
11. تشغيل الوكيل
- باستخدام وحدة التحكّم الطرفي، انتقِل إلى الدليل الرئيسي لمشروع موظّف الدّعم:
cd renovation-agent
- ثبِّت التبعيّات:
pip install -r requirements.txt
- يمكنك تنفيذ الأمر التالي في وحدة Cloud Shell الطرفية لتشغيل الوكيل:
adk run .
- يمكنك تنفيذ ما يلي لتشغيله في واجهة مستخدم ويب تم توفيرها من خلال ADK:
adk web
- يمكنك إجراء الاختبار باستخدام الطلبات التالية:
user>>
Hello. Check order status for Cement Bags.
13. تَنظيم
لتجنُّب تحصيل رسوم من حسابك على Google Cloud مقابل الموارد المستخدَمة في هذه المشاركة، اتّبِع الخطوات التالية:
- في وحدة تحكّم Google Cloud، انتقِل إلى صفحة إدارة الموارد.
- في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف.
- في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.
14. تهانينا
تهانينا! لقد نجحت في إنشاء تطبيق متعدّد الوكلاء باستخدام ADK و"مجموعة أدوات MCP لقواعد البيانات". لمزيد من المعلومات، يُرجى الرجوع إلى مستندات المنتج: مجموعة تطوير موظّفي الدعم ومجموعة أدوات MCP لقواعد البيانات.