مجموعة أدوات MCP لقواعد البيانات: إتاحة مجموعات بيانات BigQuery لعملاء MCP

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستستخدم MCP Toolbox for Databases لإتاحة مجموعات بيانات BigQuery.

خلال هذا الدرس العملي، ستتّبع نهجًا خطوة بخطوة على النحو التالي:

تحديد مجموعة بيانات BigQuery معيّنة ("ملاحظات إصدار Google Cloud") من برنامج مجموعات بيانات BigQuery العامة
إعداد خادم MCP Toolbox for Databases الذي يتصل بمجموعة بيانات BigQuery
تطوير وكيل باستخدام Agent Development Kit (ADK) يستفيد من MCP Toolbox للإجابة عن طلبات البحث التي يقدّمها المستخدم حول "ملاحظات الإصدار" في Google Cloud

المهام التي ستنفذها

إعداد MCP Toolbox for Databases لعرض "ملاحظات الإصدار" من Google Cloud، وهي مجموعة بيانات متاحة للجميع على BigQuery، كواجهة MCP لعملاء MCP الآخرين (بيئات التطوير المتكاملة والأدوات وما إلى ذلك)

ما ستتعلمه

استكشاف مجموعات البيانات العامة في BigQuery واختيار مجموعة بيانات معيّنة
إعداد MCP Toolbox for Databases لمجموعة بيانات BigQuery العامة التي نريد إتاحتها لعملاء MCP
تصميم وكيل وتطويره باستخدام Agent Development Kit (ADK) للإجابة عن طلبات المستخدمين
جرِّب Agent وMCP Toolbox for Databases في البيئة المحلية.

المتطلبات

متصفّح الويب Chrome
بيئة تطوير Python على الجهاز

2. قبل البدء

إنشاء مشروع

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

صورة زر تفعيل Cloud Shell

بعد الاتصال بـ 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- مجموعة بيانات "ملاحظات الإصدارات من Google" وعملاء MCP

أولاً، لنلقِ نظرة على ملاحظات الإصدار في Google Cloud التي يتم تعديلها بانتظام على صفحة الويب الرسمية الخاصة بملاحظات الإصدار في Google Cloud، والتي تظهر لقطة شاشة لها أدناه:

يمكنك الاشتراك في عنوان URL الخاص بالخلاصة، ولكن ماذا لو كان بإمكاننا ببساطة طرح سؤال في "الدردشة مع الوكيل" حول ملاحظات الإصدار هذه؟ ربما يكون طلب بحث بسيط مثل "أريد تلقّي آخر الأخبار حول ملاحظات الإصدار في Google Cloud".

4. MCP Toolbox for Databases

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

تساعدك Toolbox في إنشاء أدوات الذكاء الاصطناعي التوليدي التي تتيح للوكلاء الوصول إلى البيانات في قاعدة البيانات. توفّر مجموعة الأدوات ما يلي:

تطوير مبسط: يمكنك دمج الأدوات في وكيلك باستخدام أقل من 10 أسطر من الرمز البرمجي، وإعادة استخدام الأدوات بين وكلاء أو أُطر متعددة، ونشر إصدارات جديدة من الأدوات بسهولة أكبر.
أداء أفضل: أفضل الممارسات، مثل تجميع الاتصالات والمصادقة وغير ذلك
أمان محسّن: مصادقة مدمجة للوصول إلى بياناتك بشكل أكثر أمانًا
إمكانية تتبُّع البيانات الشاملة: مقاييس وتتبُّع جاهزان للاستخدام مع دعم مدمج لأداة OpenTelemetry
تسهّل عليك أداة Toolbox ربط قواعد البيانات بأي مساعدات مستنِدة إلى الذكاء الاصطناعي ومتوافقة مع MCP، حتى تلك المضمّنة في بيئة التطوير المتكاملة (IDE).

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

لتلخيص الأمر بكلمات بسيطة:

تتوفّر أداة MCP Toolbox كبرنامج ثنائي أو صورة حاوية، أو يمكنك إنشاؤها من المصدر.
وهي تعرض مجموعة من الأدوات التي يمكنك ضبطها من خلال ملف tools.yaml. يمكن اعتبار الأدوات على أنّها مرتبطة بمصادر بياناتك. يمكنك الاطّلاع على مصادر البيانات المختلفة التي تتوافق معها، مثل AlloyDB وBigQuery وما إلى ذلك.
بما أنّ مجموعة الأدوات هذه تتوافق الآن مع MCP، يتوفّر لديك تلقائيًا نقطة نهاية لخادم MCP يمكن أن تستخدمها الوكلاء (بيئات التطوير المتكاملة)، أو يمكنك استخدامها أثناء تطوير تطبيقات الوكلاء باستخدام أُطر عمل مختلفة، مثل "حزمة تطوير الوكلاء" (ADK).

سنركّز في مشاركة المدونة هذه على المجالات الموضّحة أدناه:

باختصار، سننشئ إعدادًا في MCP Toolbox for Databases يعرف كيفية الربط بمجموعة بيانات BigQuery. بعد ذلك، سنطوّر وكيلًا باستخدام Agent Development Kit (ADK) يتكامل مع نقطة نهاية MCP Toolbox ويسمح لنا بإرسال طلبات بحث بلغة طبيعية للاستفسار عن مجموعة البيانات. يمكنك التفكير في الأمر على أنّه تطبيق قائم على الذكاء الاصطناعي تقوم بتطويره ويعرف كيفية التفاعل مع مجموعة بيانات BigQuery، ويُجري بعض طلبات البحث.

5- مجموعة بيانات BigQuery لملاحظات إصدار Google Cloud

برنامج مجموعات البيانات العامة في Google Cloud هو برنامج يتيح مجموعة من مجموعات البيانات لتطبيقاتك. إحدى مجموعات البيانات هذه هي قاعدة بيانات "ملاحظات إصدار Google Cloud". توفّر لك مجموعة البيانات هذه المعلومات نفسها المتوفّرة في صفحة الويب الرسمية لملاحظات الإصدار في Google Cloud، وهي متاحة كمجموعة بيانات يمكن الاستعلام عنها بشكل علني.

كاختبار، أتحقّق ببساطة من صحة مجموعة البيانات من خلال تنفيذ طلب بحث بسيط موضّح أدناه:

SELECT
       product_name,description,published_at
     FROM
       `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
     WHERE
       DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
     GROUP BY product_name,description,published_at
     ORDER BY published_at DESC

يؤدي ذلك إلى عرض قائمة بالسجلات من مجموعة بيانات "ملاحظات الإصدار" التي تم نشرها خلال آخر 7 أيام.

يمكنك استبدال ذلك بأي مجموعة بيانات أخرى من اختيارك وطلبات البحث والمَعلمات ذات الصلة التي تريدها. كل ما علينا فعله الآن هو إعداد ذلك كمصدر بيانات وأداة في MCP Toolbox for Databases. لنرى كيف يمكننا إجراء ذلك.

6. تثبيت MCP Toolbox for Databases

افتح نافذة طرفية على جهازك المحلي وأنشئ مجلدًا باسم mcp-toolbox.

mkdir mcp-toolbox

انتقِل إلى مجلد mcp-toolbox باستخدام الأمر الموضّح أدناه:

cd mcp-toolbox

ثبِّت الإصدار الثنائي من MCP Toolbox for Databases باستخدام النص البرمجي الموضّح أدناه. الأمر الوارد أدناه مخصّص لنظام التشغيل Linux، ولكن إذا كنت تستخدم نظام التشغيل Mac أو Windows، تأكَّد من تنزيل الملف الثنائي الصحيح. اطّلِع على صفحة الإصدارات لنظام التشغيل والبنية ونزِّل الملف الثنائي الصحيح.

export VERSION=0.23.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

لدينا الآن نسخة ثنائية من مجموعة الأدوات جاهزة للاستخدام. تتمثل الخطوة التالية في إعداد مجموعة الأدوات باستخدام مصادر البيانات والإعدادات الأخرى.

7. ضبط إعدادات MCP Toolbox for Databases

الآن، علينا تحديد مجموعة بيانات وأدوات BigQuery في ملف tools.yaml المطلوب من MCP Toolbox for Database. الملف tools.yaml هو الطريقة الأساسية لإعداد Toolbox.

أنشئ ملفًا باسم tools.yaml في المجلد نفسه، أي mcp-toolbox، ويظهر محتواه أدناه.

يمكنك استخدام محرر nano المتوفّر في Cloud Shell. أمر nano هو: "nano tools.yaml".

تذكَّر استبدال القيمة YOUR_PROJECT_ID برقم تعريف مشروعك على Google Cloud.

sources:
 my-bq-source:
   kind: bigquery
   project: YOUR_PROJECT_ID

tools:
 search_release_notes_bq:
   kind: bigquery-sql
   source: my-bq-source
   statement: |
    SELECT
     product_name,description,published_at
    FROM
      `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
    WHERE
     DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
    GROUP BY product_name,description,published_at
    ORDER BY published_at DESC
   description: |
    Use this tool to get information on Google Cloud Release Notes.

toolsets:
 my_bq_toolset:
   - search_release_notes_bq

في ما يلي نبذة عن الملف:

تمثّل المصادر مصادر البيانات المختلفة التي يمكن أن تتفاعل معها إحدى الأدوات. يمثّل "المصدر" مصدر بيانات يمكن أن تتفاعل معه إحدى الأدوات. يمكنك تعريف المصادر كخريطة في قسم المصادر ضمن ملف tools.yaml. عادةً، سيحتوي إعداد المصدر على أي معلومات مطلوبة للاتصال بقاعدة البيانات والتفاعل معها. في حالتنا، حدّدنا مصدر BigQuery my-bq-source ويجب تقديم رقم تعريف مشروع Google Cloud. لمزيد من المعلومات، يُرجى الرجوع إلى مرجع المصادر.
تحدّد الأدوات الإجراءات التي يمكن أن يتّخذها الوكيل، مثل القراءة والكتابة في مصدر معيّن. تمثّل الأداة إجراءً يمكن أن يتّخذه الوكيل، مثل تنفيذ عبارة SQL. يمكنك تعريف "الأدوات" كخريطة في قسم الأدوات في ملف tools.yaml. عادةً، تتطلّب الأداة مصدرًا لتنفيذ الإجراءات. في حالتنا، نحدّد أداة واحدة search_release_notes_bq. يشير ذلك إلى مصدر BigQuery my-bq-source الذي حدّدناه في الخطوة الأولى. يتضمّن أيضًا البيان والتعليمات التي ستستخدمها برامج وكيل الذكاء الاصطناعي. لمزيد من المعلومات، يُرجى الرجوع إلى مرجع الأدوات.
أخيرًا، لدينا "مجموعة الأدوات" التي تتيح لك تحديد مجموعات من الأدوات التي تريد أن تتمكّن من تحميلها معًا. يمكن أن يكون ذلك مفيدًا لتحديد مجموعات مختلفة استنادًا إلى الوكيل أو التطبيق. في حالتنا، لدينا تعريف لمجموعة أدوات حدّدنا فيه حاليًا أداة واحدة حالية فقط search_release_notes_bq حدّدناها. يمكنك الحصول على أكثر من مجموعة أدوات واحدة، والتي تتضمّن مجموعة من الأدوات المختلفة.

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

يمكنك الاطّلاع على المزيد من تفاصيل الإعداد ( المصدر والأدوات) في إعدادات مصدر بيانات BigQuery في MCP Toolbox for Databases.

8. اختبار MCP Toolbox for Databases

لقد نزّلنا "الأدوات" وأعددناها باستخدام الملف tools.yaml في المجلد mcp-toolbox. لننفّذها على الجهاز أولاً.

نفِّذ الأمر التالي:

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

عند التنفيذ بنجاح، من المفترض أن يظهر بدء تشغيل الخادم مع نموذج للناتج يشبه النموذج أدناه:

2025-12-09T08:27:02.777619+05:30 INFO "Initialized 1 sources: my-bq-source" 
2025-12-09T08:27:02.777695+05:30 INFO "Initialized 0 authServices: " 
2025-12-09T08:27:02.777707+05:30 INFO "Initialized 1 tools: search_release_notes_bq" 
2025-12-09T08:27:02.777716+05:30 INFO "Initialized 2 toolsets: my_bq_toolset, default" 
2025-12-09T08:27:02.777719+05:30 INFO "Initialized 0 prompts: " 
2025-12-09T08:27:02.777723+05:30 INFO "Initialized 1 promptsets: default" 
2025-12-09T08:27:02.77773+05:30 WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag to prevent DNS rebinding attacks" 
2025-12-09T08:27:02.777839+05:30 INFO "Server ready to serve!"

يعمل خادم MCP Toolbox تلقائيًا على المنفذ 5000. إذا تبيّن لك أنّ المنفذ 5000 مستخدَم حاليًا، يمكنك استخدام منفذ آخر (مثل 7000) وفقًا للأمر الموضّح أدناه. يُرجى استخدام 7000 بدلاً من المنفذ 5000 في الأوامر اللاحقة.

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

لنستخدم Cloud Shell لاختبار ذلك.

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

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

من المفترض أن يظهر الناتج التالي:

في عنوان URL للمتصفّح، أضِف ما يلي إلى نهاية عنوان URL:

/api/toolset

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

{
  "serverVersion": "0.22.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
  "tools": {
    "search_release_notes_bq": {
      "description": "Use this tool to get information on Google Cloud Release Notes.\n",
      "parameters": [],
      "authRequired": []
    }
  }
}

اختبار الأدوات من خلال واجهة مستخدم MCP Toolbox for Databases

توفر "مجموعة الأدوات" واجهة مرئية (واجهة مستخدم "مجموعة الأدوات") للتفاعل مباشرةً مع الأدوات من خلال تعديل المَعلمات وإدارة العناوين وتنفيذ الطلبات، وكل ذلك ضمن واجهة مستخدم بسيطة على الويب.

إذا كنت تريد تجربة ذلك، يمكنك تنفيذ الأمر السابق الذي استخدمناه لتشغيل Toolbox Server مع الخيار --ui.

لإجراء ذلك، أوقِف النسخة السابقة من خادم MCP Toolbox for Databases التي قد تكون قيد التشغيل، وأدخِل الأمر التالي:

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

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

2025-12-09T08:28:07.479989+05:30 INFO "Initialized 1 sources: my-bq-source" 
2025-12-09T08:28:07.480065+05:30 INFO "Initialized 0 authServices: " 
2025-12-09T08:28:07.480079+05:30 INFO "Initialized 1 tools: search_release_notes_bq" 
2025-12-09T08:28:07.480087+05:30 INFO "Initialized 2 toolsets: my_bq_toolset, default" 
2025-12-09T08:28:07.48009+05:30 INFO "Initialized 0 prompts: " 
2025-12-09T08:28:07.480094+05:30 INFO "Initialized 1 promptsets: default" 
2025-12-09T08:28:07.4801+05:30 WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag to prevent DNS rebinding attacks" 
2025-12-09T08:28:07.480214+05:30 INFO "Server ready to serve!" 
2025-12-09T08:28:07.480218+05:30 INFO "Toolbox UI is up and running at: http://127.0.0.1:5000/ui"

انقر على عنوان URL الخاص بواجهة المستخدِم وتأكَّد من توفّر /ui في نهاية عنوان URL. سيؤدي ذلك إلى عرض واجهة مستخدم كما هو موضّح أدناه:

انقر على خيار "الأدوات" (Tools) على يمين الصفحة لعرض الأدوات التي تمّت إعدادها، وفي حالتنا، يجب أن تكون أداة واحدة فقط، أي search_release_notes_bq، كما هو موضّح أدناه:

ما عليك سوى النقر على الأدوات (search_release_notes_bq) وسيتم عرض صفحة لتجربة الأداة. بما أنّه لا توجد مَعلمات يجب تقديمها، يمكنك ببساطة النقر على تشغيل الأداة للاطّلاع على النتيجة. في ما يلي نموذج لعملية التنفيذ:

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

9- كتابة الوكيل باستخدام حزمة تطوير الوكلاء (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:
  --help  Show this message and exit.

Commands:
  api_server  Starts a FastAPI server for agents.
  create      Creates a new app in the current folder with prepopulated agent template.
  deploy      Deploys agent to hosted environments.
  eval        Evaluates an agent given the eval sets.
  run         Runs an interactive CLI for a certain agent.
  web         Starts a FastAPI server with Web UI for agents.

إنشاء أول تطبيق وكيل

سنستخدم الآن adk لإنشاء بنية أساسية لتطبيق Google Cloud Release Notes Agent من خلال الأمر adk create مع اسم التطبيق **(gcp_releasenotes_agent_app)**كما هو موضّح أدناه.

adk create gcp_releasenotes_agent_app

اتّبِع الخطوات واختَر ما يلي:

نموذج Gemini لاختيار نموذج للوكيل الأساسي
اختَر Vertex AI للواجهة الخلفية.
سيتم عرض رقم تعريف مشروع Google التلقائي ومنطقتك. اختَر القيمة التلقائية نفسها.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)

Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 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_GOOGLE_PROJECT_ID]: 
Enter Google Cloud region [us-central1]: 

Agent created in ../my-agents/gcp_releasenotes_agent_app:
- .env
- __init__.py
- agent.py

لاحظ المجلد الذي تم فيه إنشاء نموذج تلقائي والملفات المطلوبة للوكيل.

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

GOOGLE_GENAI_USE_VERTEXAI=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 import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

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

على وجه التحديد، يستخدم LLMAgent، المعروف باسم Agent، النماذج اللغوية الكبيرة (LLM) كمحرّك أساسي لفهم اللغة الطبيعية والاستدلال والتخطيط وإنشاء الردود وتحديد كيفية المتابعة أو الأدوات التي يجب استخدامها بشكل ديناميكي، ما يجعلها مثالية للمهام المرنة التي تركز على اللغة. مزيد من المعلومات حول وكلاء النماذج اللغوية الكبيرة

بهذا نكون قد أكملنا عملية إنشاء البنية الأساسية لإنشاء وكيل أساسي باستخدام "حزمة تطوير الوكلاء" (ADK). سنربط الآن "الوكيل" بـ "مجموعة أدوات MCP"، ليتمكّن من استخدام هذه الأداة للإجابة عن طلبات المستخدم (في هذه الحالة، ستكون ملاحظات إصدار Google Cloud).

10. ربط الوكيل بالأدوات

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

في حالتنا، سنزوّد الوكيل الآن بالأدوات التي أعددناها في 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 all the tools
tools = toolbox.load_toolset('my_bq_toolset')

root_agent = Agent(
    name="gcp_releasenotes_agent",
    model="gemini-2.5-flash",
    description=(
        "Agent to answer questions about Google Cloud Release notes."
    ),
    instruction=(
        "You are a helpful agent who can answer user questions about the Google Cloud Release notes. Use the tools to answer the question"
    ),
    tools=tools,
)

يمكننا الآن اختبار "الوكيل" الذي سيجلب بيانات حقيقية من مجموعة بيانات BigQuery التي تمّت إعدادها باستخدام MCP Toolbox for Databases.

لإجراء ذلك، اتّبِع التسلسل التالي:

في إحدى نوافذ Cloud Shell، شغِّل MCP Toolbox for Databases. من المحتمل أن يكون قيد التشغيل على جهازك المحلي على المنفذ 5000 كما اختبرنا سابقًا. إذا لم يكن كذلك، نفِّذ الأمر التالي (من مجلد mcp-toolbox) لبدء الخادم:

./toolbox --tools_file "tools.yaml"

من المفترض أن يظهر لك ناتج يشير إلى أنّ الخادم تمكّن من الاتصال بمصادر البيانات وحمّل مجموعة الأدوات والأدوات.

بعد بدء تشغيل خادم MCP بنجاح، شغِّل Agent في نافذة طرفية أخرى باستخدام الأمر adk run (من المجلد my-agents) الموضّح أدناه. يمكنك أيضًا استخدام الأمر adk web إذا أردت ذلك.

$ adk run gcp_releasenotes_agent_app/

Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent gcp_releasenotes_agent, type exit to exit.

[user]: get me the google cloud release notes


[gcp_releasenotes_agent]: Here are the Google Cloud Release Notes.

Google SecOps SOAR: Release 6.3.49 is being rolled out to the first phase of regions. This release contains internal and customer bug fixes. Published: 2025-06-14

Compute Engine: Dynamic NICs let you add or remove network interfaces to or from an instance without having to restart or recreate the instance. You can also use Dynamic NICs when you need more network interfaces. The maximum number of vNICs for most machine types in Google Cloud is 10; however, you can configure up to 16 total interfaces by using Dynamic NICs. Published: 2025-06-13

Compute Engine: General purpose C4D machine types, powered by the fifth generation AMD EPYC processors (Turin) and Google Titanium, are generally available. Published: 2025-06-13

Google Agentspace: Google Agentspace Enterprise: App-level feature management. As an Agentspace administrator, you can choose to turn the following features on or off for your end users in the web app: Agents gallery, Prompt gallery, No-code agent, NotebookLM Enterprise. Published: 2025-06-13

Cloud Load Balancing: Cloud Load Balancing supports load balancing to multi-NIC instances that use Dynamic NICs. This capability is in Preview. Published: 2025-06-13

Virtual Private Cloud: Dynamic Network Interfaces (NICs) are available in Preview. Dynamic NICs let you update an instance to add or remove network interfaces without having to restart or recreate the instance. Published: 2025-06-13

Security Command Center: The following Event Threat Detection detectors for Vertex AI have been released to Preview:
- `Persistence: New Geography for AI Service`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Admin Activity`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Data Access`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Admin Activity`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Data Access`
- `Privilege Escalation: Anomalous Impersonation of Service Account for AI Admin Activity`
- `Persistence: New AI API Method`
......
......

لاحظ أنّ "الوكيل" يستخدم الأداة التي تم إعدادها في MCP Toolbox for Databases (search_release_notes_bq) ويسترد البيانات من مجموعة بيانات BigQuery وينسّق الردّ وفقًا لذلك.

11. تهانينا

تهانينا، لقد أعددت MCP Toolbox for Databases بنجاح وأعددت مجموعة بيانات BigQuery للوصول إليها من داخل عملاء MCP.