1. مقدمة
في هذا الدرس التطبيقي حول الترميز، ستنشئ وكيلاً باستخدام حزمة تطوير الوكلاء (ADK) التي تستخدم MCP Toolbox for Databases.
خلال هذا الدرس العملي، ستتّبع نهجًا خطوة بخطوة على النحو التالي:
- وفِّر قاعدة بيانات PostgreSQL على Cloud SQL تحتوي على قاعدة بيانات الفنادق والبيانات النموذجية.
- إعداد MCP Toolbox for Databases، الذي يوفّر إمكانية الوصول إلى البيانات
- تصميم وكيل وتطويره باستخدام Agent Development Kit (ADK) الذي سيستخدم MCP Toolbox للإجابة عن طلبات المستخدمين
- استكشاف خيارات لاختبار "الوكيل" وMCP Toolbox for Databases محليًا وعلى Google Cloud من خلال خدمة Cloud Run
المهام التي ستنفذها
- تصميم وكيل وبرمجته ونشره للإجابة عن طلبات المستخدمين بشأن الفنادق في موقع جغرافي معيّن أو البحث عن فنادق حسب الاسم
ما ستتعلمه
- توفير قاعدة بيانات PostgreSQL على Cloud SQL وتعبئتها ببيانات نموذجية
- إعداد MCP Toolbox for Databases لمثيل قاعدة بيانات PostgreSQL على Cloud SQL
- تصميم وكيل وتطويره باستخدام Agent Development Kit (ADK) للإجابة عن طلبات المستخدمين
- جرِّب Agent وMCP Toolbox for Databases في البيئة المحلية.
- (اختياري) نشر الوكيل وMCP Toolbox for Databases في Google Cloud
المتطلبات
- متصفّح الويب Chrome
- حساب Gmail
- مشروع على السحابة الإلكترونية تم تفعيل الفوترة فيه
يستخدم هذا الدرس التطبيقي حول الترميز، المصمّم للمطوّرين من جميع المستويات (بما في ذلك المبتدئين)، لغة Python في التطبيق النموذجي. ومع ذلك، لا يُشترط معرفة لغة Python، وستكون القدرة الأساسية على قراءة الرموز البرمجية كافية لفهم المفاهيم المقدَّمة.
2. قبل البدء
إنشاء مشروع
- في Google Cloud Console، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا جديدًا في صفحة اختيار المشاريع.
- تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع
- ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud ومحمّلة مسبقًا بأداة bq. انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud".
- بعد الاتصال بـ Cloud Shell، يمكنك التأكّد من أنّك قد تم التحقّق من هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:
gcloud auth list
- نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك.
gcloud config list project
- إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:
gcloud config set project <YOUR_PROJECT_ID>
- فعِّل واجهات برمجة التطبيقات المطلوبة من خلال الأمر الموضّح أدناه. قد تستغرق هذه العملية بضع دقائق، لذا يُرجى الانتظار.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudfunctions.googleapis.com \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com
عند تنفيذ الأمر بنجاح، من المفترض أن تظهر لك رسالة مشابهة للرسالة الموضّحة أدناه:
Operation "operations/..." finished successfully.
يمكنك بدلاً من استخدام أمر gcloud، استخدام وحدة التحكّم من خلال البحث عن كل منتج أو استخدام هذا الرابط.
إذا فاتك أي واجهة برمجة تطبيقات، يمكنك تفعيلها في أي وقت أثناء عملية التنفيذ.
راجِع المستندات لمعرفة أوامر gcloud وطريقة استخدامها.
3- إنشاء مثيل Cloud SQL
سنستخدم مثيلاً من Google Cloud SQL لـ PostgreSQL لتخزين بيانات الفنادق. Cloud SQL for PostgreSQL هي خدمة قواعد بيانات مُدارة بالكامل تساعدك في إعداد قواعد بيانات PostgreSQL الارتباطية وصيانتها وإدارتها على Google Cloud Platform.
نفِّذ الأمر التالي في Cloud Shell لإنشاء الجهاز الظاهري:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
يستغرق تنفيذ هذا الأمر من 3 إلى 5 دقائق تقريبًا. بعد تنفيذ الأمر بنجاح، من المفترض أن يظهر لك ناتج يشير إلى اكتمال الأمر، بالإضافة إلى معلومات مثيل Cloud SQL مثل NAME وDATABASE_VERSION وLOCATION وما إلى ذلك.
4. إعداد قاعدة بيانات الفنادق
مهمتنا الآن هي إنشاء بعض البيانات النموذجية لـ "وكيل الفندق".
انتقِل إلى صفحة Cloud SQL في Cloud Console.من المفترض أن يظهر لك hoteldb-instance جاهزًا وتم إنشاؤه. انقر على اسم المثيل (hoteldb-instance) كما هو موضّح أدناه:
من القائمة اليمنى في Cloud SQL، انتقِل إلى خيار القائمة Cloud SQL Studio كما هو موضّح أدناه:
سيُطلب منك تسجيل الدخول إلى Cloud SQL Studio الذي سنقدّم من خلاله بعض أوامر SQL. اختَر postgres لخيار "قاعدة البيانات"، واستخدِم القيمة postgres لكلّ من "المستخدم" و"كلمة المرور". انقر على AUTHENTICATE.
لنبدأ بإنشاء جدول الفنادق وفقًا للمخطط الموضّح أدناه. في أحد أجزاء "المحرّر" في Cloud SQL Studio، نفِّذ عبارة SQL التالية:
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
لنملأ الآن جدول الفنادق ببيانات نموذجية. نفِّذ عبارة SQL التالية:
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
لنتأكّد من صحة البيانات من خلال تنفيذ استعلام SELECT SQL كما هو موضّح أدناه:
SELECT * FROM hotels;
من المفترض أن يظهر لك عدد من السجلات في جدول الفنادق كما هو موضّح أدناه:
لقد أكملنا عملية إعداد آلة Cloud SQL الافتراضية وأنشأنا بياناتنا النموذجية. في القسم التالي، سنعمل على إعداد MCP Toolbox for Databases.
5- إعداد MCP Toolbox for Databases
MCP Toolbox for Databases هو خادم MCP مفتوح المصدر لقواعد البيانات، وقد تم تصميمه مع مراعاة الجودة المناسبة للمؤسسات والإنتاج. تتيح لك تطوير الأدوات بسهولة أكبر وبسرعة أكبر وبشكل أكثر أمانًا من خلال التعامل مع التعقيدات، مثل تجميع الاتصالات والمصادقة وغير ذلك.
تساعدك Toolbox في إنشاء أدوات الذكاء الاصطناعي التوليدي التي تتيح للوكلاء الوصول إلى البيانات في قاعدة البيانات. توفّر مجموعة الأدوات ما يلي:
- تطوير مبسط: يمكنك دمج الأدوات في الوكيل بأقل من 10 أسطر من الرمز البرمجي، وإعادة استخدام الأدوات بين وكلاء أو أُطر عمل متعددة، وتفعيل إصدارات جديدة من الأدوات بسهولة أكبر.
- أداء أفضل: أفضل الممارسات، مثل تجميع الاتصالات والمصادقة وغير ذلك
- أمان محسّن: مصادقة مدمجة للوصول إلى بياناتك بشكل أكثر أمانًا
- إمكانية تتبُّع البيانات الشاملة: مقاييس وتتبُّع جاهزان للاستخدام مع دعم مدمج لـ OpenTelemetry
تقع أداة Toolbox بين إطار عمل التنسيق في تطبيقك وقاعدة البيانات، وتوفّر مستوى تحكّم يُستخدم لتعديل الأدوات أو توزيعها أو استدعائها. تُبسّط هذه الخدمة إدارة أدواتك من خلال توفير موقع مركزي لتخزين الأدوات وتعديلها، ما يتيح لك مشاركة الأدوات بين الموظفين والتطبيقات وتعديلها بدون الحاجة إلى إعادة نشر تطبيقك.
يمكنك ملاحظة أنّ إحدى قواعد البيانات المتوافقة مع MCP Toolbox for Databases هي Cloud SQL، وقد وفّرنا هذه القاعدة في القسم السابق.
تثبيت "مجموعة الأدوات"
افتح "وحدة Cloud Shell الطرفية" وأنشئ مجلدًا باسم mcp-toolbox.
mkdir mcp-toolbox
انتقِل إلى مجلد mcp-toolbox باستخدام الأمر الموضّح أدناه:
cd mcp-toolbox
ثبِّت الإصدار الثنائي من MCP Toolbox for Databases من خلال النص البرمجي الموضّح أدناه. الأمر الموضّح أدناه مخصّص لنظام التشغيل Linux، ولكن إذا كنت تستخدم نظام التشغيل Mac أو Windows، تأكَّد من تنزيل الملف الثنائي الصحيح. اطّلِع على صفحة الإصدارات لنظام التشغيل والبنية ونزِّل الملف الثنائي الصحيح.
export VERSION=1.13.1
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
لدينا الآن نسخة ثنائية من مجموعة الأدوات جاهزة للاستخدام. لنتأكّد من أنّنا أعددنا ملف toolbox الثنائي بشكلٍ صحيح وأنّه يشير إلى الإصدار الصحيح.
أدخِل الأمر التالي لتحديد إصدار "مجموعة الأدوات":
./toolbox -v
تتمثل الخطوة التالية في إعداد مجموعة الأدوات باستخدام مصادر البيانات والإعدادات الأخرى.
إعداد ملف tools.yaml
الطريقة الأساسية لإعداد Toolbox هي من خلال ملف tools.yaml. أنشئ ملفًا باسم tools.yaml في المجلد نفسه، أي mcp-toolbox، ويظهر محتواه أدناه.
يمكنك استخدام برنامج nano المتوفّر في Cloud Shell. أما أمر nano فهو: "nano tools.yaml".
تذكَّر استبدال القيمة YOUR_PROJECT_ID برقم تعريف مشروعك على Google Cloud.
kind: source
name: my-cloud-sql-source
type: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: postgres
---
kind: tool
name: search-hotels-by-name
type: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
---
kind: tool
name: search-hotels-by-location
type: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
---
kind: toolset
name: my_first_toolset
tools:
- search-hotels-by-name
- search-hotels-by-location
في ما يلي وصف موجز للملف:
- تمثّل
Sourcesمصادر البيانات المختلفة التي يمكن أن تتفاعل معها إحدى الأدوات. يمثّل المصدر مصدر بيانات يمكن للأداة التفاعل معه. يمكنك تعريفSourcesكخريطة في قسم المصادر ضمن ملف tools.yaml. عادةً، يحتوي إعداد المصدر على أي معلومات مطلوبة للاتصال بقاعدة البيانات والتفاعل معها. في حالتنا، أعددنا مصدرًا واحدًا يشير إلى مثيل Cloud SQL for PostgreSQL مع بيانات الاعتماد. لمزيد من المعلومات، يُرجى الرجوع إلى مرجع المصادر. - تحدِّد
Toolsالإجراءات التي يمكن أن يتّخذها الوكيل، مثل القراءة والكتابة في مصدر. تمثّل الأداة إجراءً يمكن أن يتّخذه الوكيل، مثل تنفيذ عبارة SQL. يمكنك تعريفToolsكخريطة في قسم الأدوات في ملف tools.yaml. عادةً، تتطلّب الأداة مصدرًا لتنفيذ الإجراءات. في حالتنا، نحدّد أداتَين:search-hotels-by-nameوsearch-hotels-by-locationونحدّد المصدر الذي تعمل عليه، بالإضافة إلى SQL والمَعلمات. لمزيد من المعلومات، يُرجى الرجوع إلى مرجع الأدوات. - أخيرًا، لدينا
Toolset، الذي يتيح لك تحديد مجموعات من الأدوات التي تريد أن تتمكّن من تحميلها معًا. يمكن أن يكون ذلك مفيدًا لتحديد مجموعات مختلفة استنادًا إلى الوكيل أو التطبيق. في حالتنا، لدينا مجموعة أدوات واحدة باسمmy_first_toolset، تحتوي على الأداتَين اللتين حدّدناهما.
احفظ ملف tools.yaml في محرّر النصوص nano باتّباع الخطوات التالية:
- اضغط على
Ctrl + O(الأمر "حفظ" (Write Out)). - سيُطلب منك تأكيد "اسم الملف المطلوب الكتابة إليه". ما عليك سوى الضغط على
Enter. - اضغط الآن على
Ctrl + Xللخروج.
تشغيل خادم MCP Toolbox for Databases
نفِّذ الأمر التالي (من مجلد mcp-toolbox) لبدء الخادم:
./toolbox --config "tools.yaml"
من المفترض أن يظهر لك ناتج يشير إلى أنّ الخادم تمكّن من الاتصال بمصادر البيانات وحمّل مجموعة الأدوات والأدوات. في ما يلي نموذج للناتج:
2026-09-26T14:00:35.898358+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6"
2026-09-26T14:00:39.571556+05:30 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-09-26T14:00:39.571634+05:30 INFO "Initialized 0 authServices: "
2026-09-26T14:00:39.571648+05:30 INFO "Initialized 0 embeddingModels: "
2026-09-26T14:00:39.571728+05:30 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2026-09-26T14:00:39.571745+05:30 INFO "Initialized 0 prompts: "
2026-09-26T14:00:39.571756+05:30 INFO "Initialized 0 resources: "
2026-09-26T14:00:39.571767+05:30 INFO "Initialized 0 resource templates: "
2026-09-26T14:00:39.571851+05:30 INFO "Initialized 2 groups: my_first_toolset, default"
2026-09-26T14:00:39.571905+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses."
2026-09-26T14:00:39.571939+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains."
2026-09-26T14:00:39.572261+05:30 INFO "Server ready to serve!"
يتم تشغيل خادم MCP Toolbox تلقائيًا على المنفذ 5000. إذا تبيّن لك أنّ المنفذ 5000 مستخدَم حاليًا، يمكنك استخدام منفذ آخر (مثل 7000) وفقًا للأمر الموضّح أدناه. يُرجى استخدام 7000 بدلاً من المنفذ 5000 في الأوامر اللاحقة.
./toolbox --config "tools.yaml" --port 7000
لنستخدم Cloud Shell لاختبار ذلك.
انقر على "معاينة الويب" في Cloud Shell كما هو موضّح أدناه:
انقر على تغيير المنفذ واضبط المنفذ على 5000 كما هو موضّح أدناه، ثم انقر على "تغيير ومعاينة".
من المفترض أن يظهر الناتج التالي:
اختبار الأدوات من خلال واجهة مستخدم MCP Toolbox for Databases
توفر "مجموعة الأدوات" واجهة مرئية (واجهة مستخدم "مجموعة الأدوات") للتفاعل مباشرةً مع الأدوات من خلال تعديل المَعلمات وإدارة العناوين وتنفيذ الطلبات، وكل ذلك ضمن واجهة مستخدم بسيطة على الويب.
إذا أردت تجربة ذلك، يمكنك تنفيذ الأمر السابق الذي استخدمناه لتشغيل Toolbox Server مع الخيار --ui.
لإجراء ذلك، أوقِف النسخة السابقة من خادم MCP Toolbox for Databases التي قد تكون قيد التشغيل وأدخِل الأمر التالي:
./toolbox --config "tools.yaml" --ui
من المفترض أن يظهر لك ناتج يشير إلى أنّ الخادم تمكّن من الاتصال بمصادر البيانات وحمّل مجموعة الأدوات والأدوات. يتم تقديم نموذج للناتج أدناه، وستلاحظ أنّه سيشير إلى أنّ واجهة مستخدم Toolbox تعمل.
2026-09-26T14:01:17.208487+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6"
2026-09-26T14:01:20.823447+05:30 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-09-26T14:01:20.82353+05:30 INFO "Initialized 0 authServices: "
2026-09-26T14:01:20.823545+05:30 INFO "Initialized 0 embeddingModels: "
2026-09-26T14:01:20.823629+05:30 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2026-09-26T14:01:20.823649+05:30 INFO "Initialized 0 prompts: "
2026-09-26T14:01:20.82366+05:30 INFO "Initialized 0 resources: "
2026-09-26T14:01:20.823671+05:30 INFO "Initialized 0 resource templates: "
2026-09-26T14:01:20.823745+05:30 INFO "Initialized 2 groups: my_first_toolset, default"
2026-09-26T14:01:20.823795+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses."
2026-09-26T14:01:20.823829+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains."
2026-09-26T14:01:20.824193+05:30 INFO "Server ready to serve!"
2026-09-26T14:01:20.824231+05:30 INFO "Toolbox UI is up and running at: http://127.0.0.1:5000/ui"
انقر على عنوان URL الخاص بواجهة المستخدم وتأكَّد من أنّ لديك
/ui
في نهاية عنوان URL (إذا كنت تنفّذ هذا الإجراء في Cloud Shell، ستؤدي عملية إعادة التوجيه في المتصفّح إلى عدم ظهور /ui في النهاية). سيؤدي ذلك إلى عرض واجهة مستخدم كما هو موضّح أدناه:
انقر على خيار "الأدوات" على يمين الصفحة لعرض الأدوات التي تم إعدادها، وفي حالتنا، يجب أن تكون اثنتين، أي search-hotels-by-name وsearch-hotels-by-location، كما هو موضّح أدناه:
ما عليك سوى النقر على إحدى الأدوات (search-hotels-by-location)، وسيتم عرض صفحة يمكنك من خلالها اختبار الأداة عن طريق تقديم قيم المَعلمات المطلوبة، ثم النقر على تشغيل الأداة للاطّلاع على النتيجة. في ما يلي نموذج لعملية تنفيذ:
إذا أعدنا النظر في الرسم البياني السابق (كما هو موضّح أدناه)، نكون قد انتهينا من إعداد قاعدة البيانات وخادم MCP، وأمامنا مساران:
- للتعرّف على كيفية ضبط خادم MCP في محطة طرفية أو بيئة تطوير متكاملة (IDE) تستخدم الذكاء الاصطناعي، انتقِل إلى الخطوة 6. سنتناول في هذا القسم كيفية دمج خادم MCP Toolbox في
Gemini CLI. - للتعرّف على كيفية استخدام
Agent Development Kit (ADK) using Python، وكيفية كتابة وكلاء خاصين بك يمكنهم استخدام MCP Server Toolbox كأداة، وكيفية الإجابة عن الأسئلة المتعلّقة بمجموعة البيانات، انتقِل إلى الخطوتَين 7 و8.
6. دمج MCP Toolbox في Antigravity CLI
Antigravity CLI هي واجهة مستخدم خفيفة الوزن في Terminal User Interface (TUI) لـ Antigravity. توفّر هذه الأداة إمكانات بالذكاء الاصطناعي الوكيل الأساسية نفسها التي يوفّرها Antigravity (مثل الاستدلال المتعدّد الخطوات والتعديل على ملفات متعددة واستخدام الأدوات وسجلّ المحادثات) مباشرةً في نافذة الأوامر. ويمكنك استخدامها في مهام تتضمّن الترميز وأخرى لا تتضمّنه. وهو يتضمّن أدوات متنوعة، بالإضافة إلى إمكانية استخدام خوادم MCP.
بما أنّ لدينا MCP Server يعمل، سيكون هدفنا في هذا القسم هو ضبط MCP Toolbox for Databases Server في Antigravity CLI ثم استخدام Antigravity CLI للتواصل مع بياناتنا.
ستكون خطوتنا الأولى هي التأكّد من أنّك شغّلت "مجموعة الأدوات" في إحدى نوافذ Cloud Shell. بافتراض أنّك تستخدم المنفذ التلقائي 5000، ستتوفّر واجهة MCP Server على نقطة النهاية التالية: http://localhost:5000/mcp.
افتح نافذة طرفية جديدة وأنشئ مجلدًا باسم my-gemini-cli-project على النحو التالي. انتقِل إلى المجلد my-gemini-cli-project أيضًا.
mkdir my-agy-cli-project
cd my-agy-cli-project
أدخِل الأمر التالي لإضافة خادم MCP إلى قائمة خوادم MCP التي تم إعدادها في Antigravity CLI.
agy mcp add "MCPToolbox" "http://localhost:5000/mcp"
يمكنك الاطّلاع على قائمة خوادم MCP الحالية التي تم ضبطها في Antigravity CLI باستخدام الأمر التالي:
agy mcp list
من المفترض أن يظهر لك MCPToolbox الذي أعددناه مع علامة اختيار خضراء بجانبه، ما يشير إلى أنّ Gemini CLI تمكّن من الاتصال بخادم MCP.
NAME TYPE STATUS COMMAND/URL
MCPToolbox http enabled http://localhost:5000/mcp
قبل إطلاق Gemini CLI، قد تحتاج إلى ضبط متغيرات البيئة التالية لمساعدة Gemini CLI في توجيه طلباتك إلى النموذج الصحيح.
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=global
من الجهاز نفسه، تأكَّد من أنّك في المجلد my-agy-cli-project. شغِّل Antigravity CLI باستخدام الأمر agy.
سيؤدي ذلك إلى فتح واجهة Antigravity CLI. يمكنك استخدام الأمر /mcp للاطّلاع على قائمة بخوادم MCP والأدوات. في ما يلي مثال على الناتج:
MCP Servers
Plugins (~/.gemini/config/plugins)
> ✓ MCPToolbox Tools: search-hotels-by-location, search-hotels-by-name
يمكنك الآن تقديم أيّ من الطلبات التالية:
Which hotels are there in Basel?Tell me more about the Hyatt Regency?
ستلاحظ أنّ طلبات البحث أعلاه ستؤدي إلى اختيار Antigravity CLI للأداة المناسبة من MCPToolbox. سيطلب منك منح الإذن بتنفيذ الأداة. امنح التطبيق الإذن اللازم وستلاحظ أنّه يعرض النتائج من قاعدة البيانات.
7. كتابة الوكيل باستخدام حزمة Agent Development Kit (ADK)
تثبيت "حزمة تطوير الوكلاء" (ADK)
افتح علامة تبويب جديدة في Cloud Shell وأنشئ مجلدًا باسم my-agents على النحو التالي. انتقِل إلى المجلد my-agents أيضًا.
mkdir my-agents
cd my-agents
لننشئ الآن بيئة Python افتراضية باستخدام venv على النحو التالي:
python -m venv .venv
فعِّل البيئة الافتراضية باتّباع الخطوات التالية:
source .venv/bin/activate
ثبِّت حِزم ADK وMCP Toolbox لقواعد البيانات بالإضافة إلى تبعية Langchain على النحو التالي:
pip install google-adk toolbox-core
ستتمكّن الآن من استدعاء الأداة المساعدة adk على النحو التالي.
adk
ستظهر لك قائمة بالأوامر.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
conformance Conformance testing tools for ADK.
create Creates a new app in the current folder with prepopulated...
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
eval_set Manage Eval Sets.
migrate ADK migration commands.
optimize Optimizes the root agent instructions using the GEPA...
run Runs an agent.
telemetry Manage telemetry settings.
test Runs pytest on agent test JSON files under the specified...
web Starts a FastAPI server with Web UI for agents.
إنشاء أول تطبيق وكيل
سنستخدم الآن adk لإنشاء بنية أساسية لتطبيق Hotel Agent من خلال الأمر adk create مع اسم التطبيق **(hotel_agent_app)**كما هو موضّح أدناه.
adk create hotel_agent_app
اتّبِع الخطوات واختَر ما يلي:
- اختَر نموذج
gemini-3.8-flashلاختيار نموذج للوكيل الأساسي. - اختَر
Vertex AIللواجهة الخلفية. - سيظهر معرّف مشروع Google التلقائي. انقر على هذا الخيار.
- سيتم عرض منطقة مشروع Google Cloud الحالي. تأكَّد من كتابة
global.
Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2
1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_PROJECT_ID]:
Enter Google Cloud region [us-central1]: global
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app:
- .env
- .gitignore
- __init__.py
- agent.py
لاحظ المجلد الذي تم فيه إنشاء نموذج تلقائي والملفات المطلوبة لـ "الوكيل". يمكنك الاطّلاع على الملفات من خلال الأمر ls -al في الوحدة الطرفية في الدليل <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app.
أولاً، يجب إنشاء ملف .env. تم إنشاء هذا الملف مسبقًا كما ذكرنا، ويمكنك الاطّلاع على محتواه الموضّح أدناه:
GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
تشير القيم إلى أنّنا سنستخدم Gemini من خلال Vertex AI مع القيم الخاصة برقم تعريف مشروع Google Cloud والموقع الجغرافي.
بعد ذلك، لدينا ملف __init__.py الذي يحدّد المجلد كوحدة نمطية ويتضمّن عبارة واحدة تستورد الوكيل من ملف agent.py.
from . import agent
أخيرًا، لنلقِ نظرة على الملف agent.py. يظهر المحتوى أدناه:
from google.adk.agents.llm_agent import Agent
root_agent = Agent(
model='gemini-3.8-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
هذا هو أبسط وكيل يمكنك كتابته باستخدام حزمة ADK. من صفحة مستندات ADK، الوكيل هو وحدة تنفيذ مستقلة مصمَّمة للعمل بشكل مستقل لتحقيق أهداف محدّدة. يمكن للوكلاء تنفيذ المهام والتفاعل مع المستخدمين واستخدام الأدوات الخارجية والتنسيق مع الوكلاء الآخرين.
على وجه التحديد، يستخدم LLMAgent، المعروف باسم Agent، النماذج اللغوية الكبيرة (LLM) كمحرّك أساسي لفهم اللغة الطبيعية والاستدلال والتخطيط وإنشاء الردود وتحديد كيفية المتابعة أو الأدوات التي يجب استخدامها بشكل ديناميكي، ما يجعلها مثالية للمهام المرنة التي تركز على اللغة. يمكنك الاطّلاع على مزيد من المعلومات حول "وكلاء النماذج اللغوية الكبيرة" هنا.
لنعدّل الرمز الخاص بـ agent.py على النحو التالي:
from google.adk.agents.llm_agent import Agent
root_agent = Agent(
model='gemini-3.8-flash',
name='root_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
اختبار تطبيق Agent App على الجهاز المحلي
من نافذة المحطة الطرفية الحالية، أدخِل الأمر التالي. تأكَّد من أنّك في المجلد الرئيسي (my-agents) الذي يحتوي على المجلد hotel_agent_app.
adk web
في ما يلي نموذج للتنفيذ:
...
INFO: Started server process [61397]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
انقر على الرابط الأخير، وسيؤدي ذلك إلى فتح وحدة تحكّم على الويب لاختبار الوكيل. من المفترض أن يظهر لك ما يلي في المتصفّح كما هو موضّح أدناه:
لاحظ أنّه في أعلى يمين الشاشة، تم تحديد hotel_agent_app. يمكنك الآن بدء محادثة مع الوكيل. قدِّم بضع طلبات للاستفسار عن المدن. في ما يلي مثال على محادثة:
يمكنك إيقاف العملية التي يتم تشغيلها في نافذة Cloud Shell الطرفية (Ctrl-C).
يمكنك تجربة الوكيل بطريقة بديلة من خلال الأمر adk run كما هو موضّح أدناه من المجلد my-agents.
adk run hotel_agent_app
جرِّب الأمر ويمكنك التحدّث مع الوكيل من خلال سطر الأوامر (الوحدة الطرفية). اكتب exit لإغلاق المحادثة.
8. ربط "الوكيل" بالأدوات
بعد أن تعرّفنا على كيفية كتابة وكيل واختباره محليًا، سنربط هذا الوكيل بالأدوات. في سياق "حزمة تطوير التطبيقات"، تمثّل "الأداة" إمكانية محدّدة يتم توفيرها لوكيل الذكاء الاصطناعي، ما يتيح له تنفيذ الإجراءات والتفاعل مع العالم الخارجي بما يتجاوز إمكاناته الأساسية في إنشاء النصوص والاستدلال.
في حالتنا، سنزوّد الوكيل الآن بالأدوات التي أعددناها في MCP Toolbox for Databases.
عدِّل ملف agent.py باستخدام الرمز التالي. يُرجى العِلم أنّنا نستخدم المنفذ التلقائي 5000 في الرمز، ولكن إذا كنت تستخدم رقم منفذ بديل، يُرجى استخدامه.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-3.8-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
يمكننا الآن اختبار الوكيل الذي سيجلب بيانات حقيقية من قاعدة بيانات PostgreSQL التي تم إعدادها باستخدام MCP Toolbox for Databases.
لإجراء ذلك، اتّبِع التسلسل التالي:
في إحدى نوافذ Cloud Shell، شغِّل MCP Toolbox for Databases. قد يكون التطبيق قيد التشغيل حاليًا على جهازك على المنفذ 5000 كما اختبرناه سابقًا. إذا لم يكن كذلك، نفِّذ الأمر التالي (من مجلد mcp-toolbox) لبدء الخادم:
./toolbox --config "tools.yaml"
من المفترض أن يظهر لك ناتج يشير إلى أنّ الخادم تمكّن من الاتصال بمصادر البيانات وحمّل مجموعة الأدوات والأدوات.
بعد بدء تشغيل خادم MCP بنجاح، شغِّل الوكيل في نافذة طرفية أخرى كما فعلنا سابقًا باستخدام الأمر adk run (من المجلد my-agents) الموضّح أدناه. يمكنك أيضًا استخدام الأمر adk web إذا أردت ذلك.
$ adk run hotel_agent_app/
...
Running agent hotel_agent, type exit to exit.
[user]: what can you do for me?
[hotel_agent]: I can help you search for and find information about hotels! Specifically, I can:
* **Find hotels in a specific city or location:** Look up available hotels, sorted by price from least to most expensive.
* **Search for hotels by name:** Get details on a specific hotel you're interested in.
Feel free to tell me where you're planning to stay or which hotel you'd like to look up!
[user]: I would like to search for hotels?
[hotel_agent]: I'd be happy to help!
Where are you planning to travel, or is there a specific hotel name you have in mind?
[user]: I am planning to travel to Basel
[hotel_agent]: Here are the hotels available in **Basel**, listed from least to most expensive:
1. **Holiday Inn Basel**
* **Price Tier:** Upper Midscale
* **Available Dates:** April 9, 2024 – April 24, 2024
2. **Hyatt Regency Basel**
* **Price Tier:** Upper Upscale
* **Available Dates:** April 2, 2024 – April 20, 2024
3. **Hilton Basel**
* **Price Tier:** Luxury
* **Available Dates:** April 20, 2024 – April 22, 2024
Would you like more details about any of these hotels, or do you have specific travel dates in mind?
[user]:
. . .
لاحظ أنّ "الوكيل" يستخدم الآن الأداتين اللتين أعددناهما في MCP Toolbox لقواعد البيانات (search-hotels-by-name وsearch-hotels-by-location) ويقدّم لنا الخيارات الصحيحة. وبعد ذلك، يمكنه استرداد البيانات بسلاسة من قاعدة بيانات مثيل PostgreSQL وتنسيق الردّ وفقًا لذلك.
بهذا نكون قد أكملنا عملية التطوير والاختبار المحليين لـ "وكيل الفندق" الذي أنشأناه باستخدام "حزمة تطوير الوكلاء" (ADK) والذي تم تشغيله باستخدام الأدوات التي أعددناها في MCP Toolbox لقواعد البيانات.
9. (اختياري) نشر MCP Toolbox لقواعد البيانات والوكيل على Cloud Run
في القسم السابق، استخدمنا وحدة طرفية Cloud Shell لتشغيل خادم MCP Toolbox واختبرنا الأدوات باستخدام Agent. كان هذا البرنامج يعمل على الجهاز في بيئة Cloud Shell.
يمكنك نشر كلّ من خادم MCP Toolbox والوكيل على خدمات Google Cloud التي يمكنها استضافة هذه التطبيقات.
استضافة خادم MCP Toolbox على Cloud Run
أولاً، يمكننا البدء بخادم MCP Toolbox واستضافته على Cloud Run. سيمنحنا ذلك نقطة نهاية عامة يمكننا دمجها مع أي تطبيق آخر و/أو تطبيقات "الوكيل" أيضًا. تتوفر تعليمات استضافة هذا التطبيق على Cloud Run هنا. سنوضّح الخطوات الرئيسية الآن.
ابدأ تشغيل "وحدة طرفية Cloud Shell" جديدة أو استخدِم "وحدة طرفية Cloud Shell" حالية. انتقِل إلى المجلد mcp-toolbox الذي يتضمّن الملف الثنائي toolbox والملف tools.yaml.
نفِّذ الأوامر التالية (يتم تقديم شرح لكل أمر):
اضبط المتغيّر 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. نتأكّد أيضًا من أنّ حساب الخدمة هذا لديه الأدوار الصحيحة، أي القدرة على الوصول إلى Secret Manager والتواصل مع Cloud SQL.
gcloud iam service-accounts create toolbox-identity
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/cloudsql.client
سنحمّل ملف tools.yaml كبيانات سرية، وبما أنّه علينا تثبيت مجموعة الأدوات في Cloud Run، سنستخدم أحدث صورة حاوية لمجموعة الأدوات ونضبطها في المتغيّر IMAGE.
gcloud secrets create tools --data-file=tools.yaml
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="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
من المفترض أن تبدأ هذه الخطوة عملية نشر خادم Toolbox باستخدام 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
يمكنك الآن الانتقال إلى Service URL المذكور أعلاه في المتصفّح. يجب أن تعرض الرسالة "Hello World" التي رأيناها سابقًا.
يمكنك أيضًا الانتقال إلى Cloud Run من Google Cloud Console وستظهر لك خدمة Toolbox ضِمن قائمة الخدمات في Cloud Run.
ملاحظة: إذا أردت مواصلة تشغيل Hotel Agent محليًا مع الربط بخدمة Cloud Run التي تم نشرها حديثًا، عليك إجراء تغيير واحد فقط في ملف my-agents/hotel_agent_app/agent.py.
بدلاً من ما يلي:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
غيِّرها إلى عنوان URL الخاص بالخدمة في خدمة Cloud Run كما هو موضّح أدناه:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
اختبِر تطبيق "الوكيل" باستخدام adk run أو adk web كما رأينا سابقًا.
نشر تطبيق Hotel Agent على Cloud Run
الخطوة الأولى هي التأكّد من إجراء التغيير في my-agents/hotel_agent_app/agent.py كما هو موضّح أعلاه للإشارة إلى عنوان URL لخدمة Toolbox التي تعمل على Cloud Run وليس المضيف المحلي.
في نافذة Cloud Shell Terminal جديدة أو جلسة Terminal حالية، تأكَّد من أنّك في بيئة Python الافتراضية الصحيحة التي أعددناها سابقًا.
أولاً، لننشئ ملف requirements.txt في المجلد my-agents/hotel_agent_app كما هو موضّح أدناه:
google-adk
toolbox-core
انتقِل إلى المجلد my-agents ولنضبط متغيرات البيئة التالية أولاً:
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel_agent_app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
Export GOOGLE_GENAI_USE_ENTERPRISE=1
أخيرًا، لننشُر تطبيق Agent على Cloud Run من خلال الأمر adk deploy cloud_run كما هو موضّح أدناه. إذا طُلب منك السماح باستدعاءات غير مصادَق عليها للخدمة، يُرجى تقديم القيمة "y" في الوقت الحالي.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
سيؤدي ذلك إلى بدء عملية نشر تطبيق Hotel Agent على Cloud Run. سيتم تحميل المصادر وتعبئتها في حاوية Docker، ثم نشرها في Artifact Registry، وبعد ذلك نشر الخدمة على Cloud Run. قد تستغرق هذه العملية بضع دقائق، لذا يُرجى الانتظار.
من المفترض أن تظهر لك رسالة مشابهة للرسالة أدناه:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250905_132636
Copying agent source code...
Copying agent source code completed.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250905_132636/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_PROJECT_ID] region [us-central1]
- Building and deploying... Uploading sources.
- Uploading sources...
. Building Container...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/d1f7e76b-0587-4bb6-b9c0-bb4360c07aa0?project=415
458962931]. f
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00003-hrl] has been deployed and is serving 100 percent of traffic.
Service URL: <YOUR_CLOUDRUN_APP_URL>
INFO: Display format: "none"
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250905_132636
بعد اكتمال عملية النشر بنجاح، سيتم تزويدك بقيمة لعنوان URL الخاص بالخدمة، ويمكنك بعد ذلك الوصول إليه في المتصفّح لعرض تطبيق الويب نفسه الذي أتاح لك الدردشة مع موظف الفندق، كما رأينا سابقًا في عملية الإعداد المحلية.
10. تنظيف
لتجنُّب تحصيل رسوم مستمرة من حسابك على Google Cloud، من المهم حذف الموارد التي أنشأناها خلال ورشة العمل هذه. سنحذف مثيل Cloud SQL، وإذا كنت قد نشرت Toolbox و"تطبيق الفنادق" على Cloud Run، سنحذف هاتين الخدمتين أيضًا.
تأكَّد من ضبط متغيّرات البيئة التالية بشكل صحيح، وفقًا لمشروعك ومنطقتك:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
يحذف الأمران التاليان خدمات Cloud Run التي نشرناها:
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
يحذف الأمر التالي مثيل Cloud SQL:
gcloud sql instances delete hoteldb-instance
11. تهانينا
تهانينا، لقد أنشأت بنجاح وكيل سفر باستخدام "حزمة تطوير الوكلاء" (ADK) التي تستخدم أداة MCP Toolbox لقواعد البيانات. تعرّفت أيضًا على كيفية ربط الوكلاء بقواعد البيانات الخاصة بك، ويمكنك اختياريًا تثبيت "الوكيل" و"صندوق الأدوات" على Cloud Run.