1. مقدمة
في هذا الدرس التطبيقي حول الترميز، ستنشئ وكيلاً باستخدام حزمة تطوير الوكلاء (ADK) التي تستخدم أداة MCP لقواعد البيانات.
خلال هذا الدرس العملي، ستتّبع نهجًا خطوة بخطوة على النحو التالي:
- وفِّر قاعدة بيانات Cloud SQL for PostgreSQL التي ستتضمّن قاعدة بيانات الفنادق والبيانات النموذجية.
- إعداد "مجموعة أدوات MCP" لقواعد البيانات التي تتيح الوصول إلى البيانات
- تصميم وكيل وتطويره باستخدام "حزمة تطوير الوكيل" (ADK) التي ستستفيد من "مجموعة أدوات MCP" للإجابة عن طلبات المستخدم.
- استكشاف خيارات لاختبار "أداة Agent" و"مجموعة أدوات MCP لقواعد البيانات" محليًا وعلى Google Cloud من خلال خدمة Cloud Run
المهام التي ستنفذها
- تصميم وكيل وبرمجته ونشره للإجابة عن طلبات المستخدمين بشأن الفنادق في موقع جغرافي معيّن أو البحث عن فنادق حسب الاسم
ما ستتعلمه
- توفير قاعدة بيانات Cloud SQL for PostgreSQL وتعبئتها ببيانات نموذجية
- إعداد "مجموعة أدوات MCP لقواعد البيانات" لمثيل قاعدة بيانات Cloud SQL for PostgreSQL
- تصميم وكيل وتطويره باستخدام "حزمة تطوير الوكيل" (ADK) للإجابة عن طلبات المستخدمين
- جرِّب "أداة الوكيل" و"صندوق أدوات MCP لقواعد البيانات" في البيئة المحلية.
- (اختياري) نشر Agent وMCP Toolbox لقواعد البيانات في Google Cloud
المتطلبات
- متصفّح الويب Chrome
- حساب Gmail
- مشروع على السحابة الإلكترونية تم تفعيل الفوترة فيه
يستخدم هذا الدرس العملي، المصمّم للمطوّرين من جميع المستويات (بما في ذلك المبتدئين)، لغة Python في التطبيق النموذجي. ومع ذلك، لا يُشترط معرفة لغة Python، وستكون القدرة الأساسية على قراءة الرموز البرمجية كافية لفهم المفاهيم المقدَّمة.
2. قبل البدء
إنشاء مشروع
- في Google Cloud Console، في صفحة اختيار المشروع، اختَر أو أنشِئ مشروعًا على Google Cloud.
- تأكَّد من تفعيل الفوترة لمشروعك على 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 لقواعد البيانات".
5- إعداد "صندوق أدوات MCP" لقواعد البيانات
أداة MCP لقواعد البيانات هي خادم MCP مفتوح المصدر لقواعد البيانات، وقد تم تصميمها مع مراعاة الجودة المناسبة للمؤسسات والإنتاج. تتيح لك تطوير الأدوات بسهولة أكبر وبسرعة أكبر وبشكل أكثر أمانًا من خلال التعامل مع التعقيدات، مثل تجميع الاتصالات والمصادقة وغير ذلك.
تساعدك "مجموعة الأدوات" في إنشاء أدوات الذكاء الاصطناعي التوليدي التي تتيح لعملائك الوصول إلى البيانات في قاعدة بياناتك. توفّر مجموعة الأدوات ما يلي:
- تطوير مبسط: يمكنك دمج الأدوات في برنامجك الآلي بأقل من 10 أسطر من الرموز البرمجية، وإعادة استخدام الأدوات بين برامج آلية أو أُطر متعددة، ونشر إصدارات جديدة من الأدوات بسهولة أكبر.
- أداء أفضل: أفضل الممارسات، مثل تجميع الاتصالات والمصادقة وغير ذلك
- أمان محسّن: مصادقة مدمجة للوصول إلى بياناتك بشكل أكثر أمانًا
- إمكانية المراقبة الشاملة: مقاييس وتتبُّع جاهزان للاستخدام مع إمكانية مدمجة لاستخدام OpenTelemetry
تقع "مجموعة الأدوات" بين إطار عمل التنسيق في تطبيقك وقاعدة البيانات، وتوفّر مستوى تحكّم يُستخدم لتعديل الأدوات أو توزيعها أو استدعائها. فهو يسهّل إدارة أدواتك من خلال توفير موقع مركزي لتخزين الأدوات وتعديلها، ما يتيح لك مشاركة الأدوات بين الوكلاء والتطبيقات وتعديل هذه الأدوات بدون الحاجة إلى إعادة نشر تطبيقك.
يمكنك ملاحظة أنّ إحدى قواعد البيانات المتوافقة مع "أداة MCP لقواعد البيانات" هي Cloud SQL، وقد وفّرنا هذه القاعدة في القسم السابق.
تثبيت "مجموعة الأدوات"
افتح "وحدة Cloud Shell" الطرفية وأنشئ مجلدًا باسم mcp-toolbox.
mkdir mcp-toolbox
انتقِل إلى مجلد mcp-toolbox باستخدام الأمر الموضّح أدناه:
cd mcp-toolbox
ثبِّت إصدار MCP Toolbox for Databases الثنائي من خلال النص البرمجي الموضّح أدناه. الأمر الوارد أدناه مخصّص لنظام التشغيل Linux، ولكن إذا كنت تستخدم نظام التشغيل Mac أو Windows، تأكَّد من تنزيل الملف الثنائي الصحيح. اطّلِع على صفحة الإصدارات لنظام التشغيل والبنية ونزِّل الملف الثنائي الصحيح.
export VERSION=0.13.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
لدينا الآن النسخة الثنائية من مجموعة الأدوات جاهزة للاستخدام. الخطوة التالية هي إعداد مجموعة الأدوات باستخدام مصادر البيانات والإعدادات الأخرى.
إعداد ملف tools.yaml
الطريقة الأساسية لإعداد Toolbox هي من خلال ملف tools.yaml. أنشئ ملفًا باسم tools.yaml في المجلد نفسه، أي mcp-toolbox، ويظهر محتواه أدناه.
يمكنك استخدام محرّر النصوص nano المتوفّر في Cloud Shell. أما أمر nano فهو: "nano tools.yaml".
تذكَّر استبدال القيمة YOUR_PROJECT_ID برقم تعريف مشروعك على Google Cloud.
sources:
my-cloud-sql-source:
kind: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: "postgres"
tools:
search-hotels-by-name:
kind: 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 || '%';
search-hotels-by-location:
kind: 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;
toolsets:
my_first_toolset:
- 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، تحتوي على الأداتَين اللتين حدّدناهما.
تشغيل "مجموعة أدوات MCP لخادم قواعد البيانات"
نفِّذ الأمر التالي (من مجلد mcp-toolbox) لبدء الخادم:
./toolbox --tools-file "tools.yaml"
من المفترض أن يظهر لك ناتج يشير إلى أنّ الخادم تمكّن من الاتصال بمصادر البيانات وحمّل مجموعة الأدوات والأدوات. في ما يلي نموذج للناتج:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z 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.13.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location. Result is sorted by price from least to most expensive.",
"parameters": [
{
"name": "location",
"type": "string",
"required": true,
"description": "The location of the hotel.",
"authSources": []
}
],
"authRequired": []
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"required": true,
"description": "The name of the hotel.",
"authSources": []
}
],
"authRequired": []
}
}
}
اختبار الأدوات من خلال واجهة مستخدم MCP Toolbox for Databases
توفر "مجموعة الأدوات" واجهة مرئية (واجهة مستخدم "مجموعة الأدوات") للتفاعل مباشرةً مع الأدوات من خلال تعديل المَعلمات وإدارة العناوين وتنفيذ الطلبات، وكل ذلك ضمن واجهة مستخدم بسيطة على الويب.
إذا أردت تجربة ذلك، يمكنك تنفيذ الأمر السابق الذي استخدمناه لتشغيل Toolbox Server مع الخيار --ui.
لإجراء ذلك، أوقِف النسخة السابقة من خادم MCP Toolbox for Databases التي قد تكون قيد التشغيل وأدخِل الأمر التالي:
./toolbox --tools-file "tools.yaml" --ui
من المفترض أن يظهر لك ناتج يشير إلى أنّ الخادم تمكّن من الاتصال بمصادر البيانات وحمّل مجموعة الأدوات والأدوات. يتم تقديم نموذج للناتج أدناه، وستلاحظ أنّه سيشير إلى أنّ واجهة مستخدم "مجموعة الأدوات" تعمل.
2025-09-08T02:44:11.561572538Z INFO "Initialized 1 sources."
2025-09-08T02:44:11.561966395Z INFO "Initialized 0 authServices."
2025-09-08T02:44:11.562060934Z INFO "Initialized 2 tools."
2025-09-08T02:44:11.562105678Z INFO "Initialized 2 toolsets."
2025-09-08T02:44:11.568209923Z INFO "Server ready to serve!"
2025-09-08T02:44:11.568259411Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui"
انقر على عنوان URL الخاص بواجهة المستخدِم وتأكَّد من أنّ لديك /ui في نهاية عنوان URL. سيؤدي ذلك إلى عرض واجهة مستخدم كما هو موضّح أدناه:
انقر على خيار "الأدوات" (Tools) على يمين الصفحة لعرض الأدوات التي تم إعدادها. في حالتنا، يجب أن تكون هناك أداتان، أي search-hotels-by-name وsearch-hotels-by-location، كما هو موضّح أدناه:
ما عليك سوى النقر على إحدى الأدوات (search-hotels-by-location)، وسيتم عرض صفحة يمكنك من خلالها تجربة الأداة عن طريق تقديم قيم المَعلمات المطلوبة، ثم النقر على تشغيل الأداة للاطّلاع على النتيجة. في ما يلي نموذج لعملية التنفيذ:
يصف "مجموعة أدوات MCP لقواعد البيانات" أيضًا طريقة Pythonic للتحقّق من صحة الأدوات واختبارها، ويمكنك الاطّلاع على هذه الطريقة هنا. سنتخطّى ذلك وسننتقل مباشرةً إلى "حزمة تطوير الوكيل" (ADK) في القسم التالي الذي سيستخدم هذه الأدوات.
6. كتابة الوكيل باستخدام "حزمة تطوير الوكيل" (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 for Databases بالإضافة إلى تبعية 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.
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 لإنشاء بنية أساسية لتطبيق Hotel Agent من خلال الأمر adk create مع اسم التطبيق **(hotel-agent-app)**كما هو موضّح أدناه.
adk create hotel-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_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel-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. من صفحة مستندات ADK صفحة، الوكيل هو وحدة تنفيذ مستقلة مصمَّمة للعمل بشكل مستقل لتحقيق أهداف معيّنة. يمكن للوكلاء تنفيذ المهام والتفاعل مع المستخدمين واستخدام أدوات خارجية والتنسيق مع وكلاء آخرين.
على وجه التحديد، يستخدم LLMAgent، المعروف باسم Agent، النماذج اللغوية الكبيرة (LLM) كمحرّك أساسي لفهم اللغة الطبيعية، والتفكير، والتخطيط، وإنشاء الردود، وتحديد كيفية المتابعة أو الأدوات التي يجب استخدامها بشكل ديناميكي، ما يجعلها مثالية للمهام المرنة التي تركز على اللغة. يمكنك الاطّلاع على مزيد من المعلومات حول "وكلاء النماذج اللغوية الكبيرة" هنا.
لنعدّل رمز agent.py على النحو التالي:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='hotel_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.',
)
اختبار تطبيق "الوكيل" على الجهاز
من نافذة الوحدة الطرفية الحالية، أدخِل الأمر التالي. تأكَّد من أنّك في المجلد الرئيسي (my-agents) الذي يحتوي على المجلد hotel-agent-app.
adk web
في ما يلي نموذج للتنفيذ:
INFO: Started server process [1478]
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 لإغلاق المحادثة.
7. ربط "الوكيل الذكي" بالأدوات
بعد أن تعرّفنا على كيفية كتابة وكيل واختباره محليًا، سنربط هذا الوكيل بالأدوات. في سياق "مجموعة أدوات تطوير تطبيقات الذكاء الاصطناعي"، تمثّل "الأداة" إمكانية محدّدة يتم توفيرها لبرنامج وكيل يعمل بالذكاء الاصطناعي، ما يتيح له تنفيذ الإجراءات والتفاعل مع العالم خارج نطاق قدراته الأساسية على إنشاء النصوص والاستدلال.
في حالتنا، سنزوّد "الوكيل" الآن بالأدوات التي أعددناها في "صندوق أدوات MCP" لقواعد البيانات.
عدِّل ملف 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-2.5-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 لقواعد البيانات".
لإجراء ذلك، اتّبِع التسلسل التالي:
في إحدى وحدات Cloud Shell الطرفية، شغِّل "أدوات MCP لقواعد البيانات". من المحتمل أن يكون قيد التشغيل على جهازك المحلي على المنفذ 5000 كما اختبرنا سابقًا. إذا لم يكن الأمر كذلك، نفِّذ الأمر التالي (من مجلد mcp-toolbox) لبدء الخادم:
./toolbox --tools_file "tools.yaml"
من المفترض أن يظهر لك ناتج يشير إلى أنّ الخادم تمكّن من الاتصال بمصادر البيانات وحمّل مجموعة الأدوات والأدوات. في ما يلي نموذج للناتج:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
بعد بدء تشغيل خادم MCP بنجاح، شغِّل Agent في نافذة طرفية أخرى كما فعلنا سابقًا باستخدام الأمر adk run (من المجلد my-agents) الموضّح أدناه. يمكنك أيضًا استخدام الأمر adk web إذا أردت ذلك.
$ adk run hotel-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 hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
لاحظ أنّ "الوكيل" يستخدم الآن الأداتَين اللتَين أعددناهما في "مجموعة أدوات MCP لقواعد البيانات" (search-hotels-by-name وsearch-hotels-by-location) ويقدّم لنا الخيارات الصحيحة. وبعد ذلك، يمكنه استرداد البيانات بسلاسة من قاعدة بيانات مثيل PostgreSQL وتنسيق الردّ وفقًا لذلك.
بهذا نكون قد أكملنا عملية التطوير والاختبار المحليين لـ "وكيل الفندق" الذي أنشأناه باستخدام "حزمة تطوير الوكلاء" (ADK) والذي تم تشغيله باستخدام الأدوات التي أعددناها في "مجموعة أدوات MCP لقواعد البيانات".
8. (اختياري) نشر "أدوات MCP لقواعد البيانات" و"الوكيل" على Cloud Run
في القسم السابق، استخدمنا وحدة Cloud Shell الطرفية لتشغيل خادم MCP Toolbox واختبرنا الأدوات باستخدام "الوكيل". كان هذا البرنامج يعمل على الجهاز في بيئة Cloud Shell.
يمكنك نشر كلّ من خادم MCP Toolbox وAgent على خدمات Google Cloud التي يمكنها استضافة هذه التطبيقات.
استضافة خادم "مجموعة أدوات MCP" على 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 كبيانات سرية، وبما أنّه علينا تثبيت Toolbox في Cloud Run، سنستخدم أحدث صورة حاوية لـ Toolbox ونضبطها في المتغيّر 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="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
من المفترض أن تبدأ هذه الخطوة عملية نشر خادم "أدوات المطوّرين" باستخدام 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" التي رأيناها سابقًا. بالإضافة إلى ذلك، يمكنك أيضًا الانتقال إلى عنوان URL التالي للاطّلاع على الأدوات المتاحة:
SERVICE URL/api/toolset
يمكنك أيضًا الانتقال إلى Cloud Run من وحدة تحكّم Google Cloud، وستظهر لك خدمة 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 أو جلسة "وحدة طرفية" حالية، تأكَّد من أنّك في بيئة 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_VERTEXAI=True
أخيرًا، لننشئ تطبيق Agent Application على 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 الخاص بالخدمة، ويمكنك بعد ذلك الوصول إليه في المتصفّح لعرض تطبيق الويب نفسه الذي سمح لك بالدردشة مع موظف الفندق، كما رأينا سابقًا في الإعداد المحلي.
9- تنظيف
لتجنُّب تحصيل رسوم مستمرة من حسابك على Google Cloud، من المهم حذف الموارد التي أنشأناها خلال ورشة العمل هذه. سنحذف مثيل Cloud SQL، وإذا كنت قد نشرت "مجموعة الأدوات" و"تطبيق الفنادق" على 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
10. تهانينا
تهانينا، لقد أنشأت بنجاح وكيلاً باستخدام "حزمة تطوير الوكيل" (ADK) التي تستخدم "مجموعة أدوات MCP لقواعد البيانات".