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

مجموعة أدوات 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).

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

باختصار:

تتوفّر "أدوات MCP" كبرنامج ثنائي أو صورة حاوية، أو يمكنك إنشاؤها من المصدر.
وهي تعرض مجموعة من الأدوات التي يمكنك ضبطها من خلال ملف 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=1.13.1
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/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.

kind: source
name: my-bq-source
type: bigquery
project: YOUR_PROJECT_ID
---
kind: tool
name: search_release_notes_bq
type: bigquery-sql
source: my-bq-source
description: Use this tool to get information on Google Cloud Release Notes.
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;
---
kind: toolset
name: my_bq_toolset
tools:
  - 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 --config "tools.yaml"

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

2026-09-26T12:58:14.590825+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6" 
2026-09-26T12:58:14.59319+05:30 INFO "Initialized 1 sources: my-bq-source" 
2026-09-26T12:58:14.593198+05:30 INFO "Initialized 0 authServices: " 
2026-09-26T12:58:14.593201+05:30 INFO "Initialized 0 embeddingModels: " 
2026-09-26T12:58:14.59323+05:30 INFO "Initialized 1 tools: search_release_notes_bq" 
2026-09-26T12:58:14.593235+05:30 INFO "Initialized 0 prompts: " 
2026-09-26T12:58:14.593236+05:30 INFO "Initialized 0 resources: " 
2026-09-26T12:58:14.593238+05:30 INFO "Initialized 0 resource templates: " 
2026-09-26T12:58:14.593244+05:30 INFO "Initialized 2 groups: my_bq_toolset, default" 
2026-09-26T12:58:14.593259+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-26T12:58:14.593266+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-26T12:58:14.593365+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 --tools-file "tools.yaml" --ui

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

Flag --tools-file has been deprecated, please use --config instead
2026-09-26T12:59:21.662102+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6" 
2026-09-26T12:59:21.663076+05:30 INFO "Initialized 1 sources: my-bq-source" 
2026-09-26T12:59:21.663084+05:30 INFO "Initialized 0 authServices: " 
2026-09-26T12:59:21.663087+05:30 INFO "Initialized 0 embeddingModels: " 
2026-09-26T12:59:21.663101+05:30 INFO "Initialized 1 tools: search_release_notes_bq" 
2026-09-26T12:59:21.663104+05:30 INFO "Initialized 0 prompts: " 
2026-09-26T12:59:21.663107+05:30 INFO "Initialized 0 resources: " 
2026-09-26T12:59:21.663109+05:30 INFO "Initialized 0 resource templates: " 
2026-09-26T12:59:21.663116+05:30 INFO "Initialized 2 groups: default, my_bq_toolset" 
2026-09-26T12:59:21.663124+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-26T12:59:21.663132+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-26T12:59:21.663242+05:30 INFO "Server ready to serve!" 
2026-09-26T12:59:21.663249+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) وسيتم عرض صفحة لتجربتها. بما أنّه لا توجد مَعلمات يجب تقديمها، يمكنك ببساطة النقر على تشغيل الأداة للاطّلاع على النتيجة. في ما يلي نموذج لعملية تنفيذ:

9. كتابة الوكيل باستخدام حزمة 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 لإنشاء بنية أساسية لتطبيق Google Cloud Release Notes Agent من خلال الأمر adk create مع اسم التطبيق **(gcp_releasenotes_agent_app)**كما هو موضّح أدناه.

adk create gcp_releasenotes_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 /Users/romin/my-agents/gcp_releasenotes_agent_app:
- .env
- .gitignore
- __init__.py
- agent.py

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

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

GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

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

بهذا نكون قد أكملنا عملية إنشاء البنية الأساسية لإنشاء وكيل أساسي باستخدام "حزمة تطوير الوكلاء" (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-3.8-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 --config "tools.yaml"

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

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

$ adk run gcp_releasenotes_agent_app/
Running agent gcp_releasenotes_agent, type exit to exit.
[user]: Hello
[gcp_releasenotes_agent]: Hello! I am your Google Cloud Release Notes assistant. How can I help you today? Feel free to ask about recent updates, feature releases, deprecations, or announcements across Google Cloud products.
[user]: get me the google cloud release notes
[gcp_releasenotes_agent]: Here are the latest highlights from the Google Cloud Release Notes:
---

### **AI & Machine Learning**
* **Gemini Enterprise**: 
  * **Gemini 3.8 Flash** is now Generally Available (GA) and enabled by default in `global`, `us`, and `eu` regions.
* **Gemini Enterprise Agent Platform**: 
  * **Gemini 3.8 Live** is now GA, bringing improved voice quality, model reliability, and agent orchestration.
  * **Meta's Muse Spark 1.3** is in Preview (reasoning model with tool calling, MCP support, and 1M context window).
* **CX Agent Studio**: 
  * **Agent as a tool** is now GA.
  * Added **Composite models** for enterprise voice agents.
  * Introduced **Supervisor agents** to monitor active agent performance.
  * Added **Agent-to-agent (A2A) protocol tools** and integrations for WhatsApp, Instagram, and SecureCo.
* **Model Armor**: Prompt injection, jailbreak detection, and Responsible AI filters are now supported in Melbourne (`australia-southeast2`).
---

### **Compute & Infrastructure**
* **Compute Engine**: Standard snapshots deleted accidentally or maliciously are now retained in the **Recycle Bin for 3 days** before permanent erasure (Preview).
* **Confidential VM**: Support for **Intel TDX on `c4-standard-*`** machine types is now GA.
* **SAP on Google Cloud**: Certified the **X5 series** of memory-optimized bare metal machine types (Intel Granite Rapids CPU platform) for SAP HANA and SAP NetWeaver.
* **Cloud Workstations**: Cloud Workstations is now a covered product under the Google Cloud HIPAA BAA.
---

### **Containers & Networking**
* **Google Kubernetes Engine (GKE)**: **GKE ambient networking** is now in Preview (allowlist), providing a sidecarless, Layer 4 service mesh using Gateway API on GKE Dataplane V2.
* **Cloud Service Mesh**: Maintenance and security patch releases available for in-cluster versions `1.30.4-asm.14`, `1.29.7-asm.18`, and `1.28.10-asm.40`.
---

### **Data Analytics & Databases**
* **BigQuery**: In BigQuery Studio, the query editor results table now freezes row numbers on the left during horizontal scrolling (GA).
* **Memorystore for Valkey**: Valkey version 9.1 is now GA.
* **Looker**: Deployment of version 26.16; includes a long-polling concurrency guard, tile-level filter controls (Preview), and an OAuth authorization warning dialog.
* **Data Studio / Looker Studio**: 
  * Added private IP connectivity for Cloud SQL PostgreSQL databases.
..
..
..

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

11. تهانينا

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