إنشاء وكيل سفر باستخدام أدوات حزمة MCP لقواعد البيانات وحزمة تطوير موظّفي الدعم (ADK)

إنشاء وكيل سفر باستخدام "مجموعة أدوات MCP لقواعد البيانات" وحزمة تطوير تطبيقات موظّفي الدعم (ADK)

لمحة عن هذا الدرس التطبيقي حول الترميز

تاريخ التعديل الأخير: مايو 20, 2025

تأليف: Romin Irani, Jack Wotherspoon

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستُنشئ وكيلًا باستخدام مجموعة تطوير موظّفي الدعم (ADK) التي تستخدِم مجموعة أدوات MCP لقواعد البيانات.

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

1. وفِّر قاعدة بيانات Cloud SQL لـ PostgreSQL تتضمّن قاعدة بيانات الفنادق وعينات البيانات.
2. إعداد أدوات MCP لقواعد البيانات التي تتيح الوصول إلى البيانات
3. تصميم وتطوير موظّف دعم باستخدام حزمة تطوير موظّف الدعم (ADK) التي ستستخدم مجموعة أدوات MCP للإجابة عن طلبات المستخدمين
4. استكشِف خيارات اختبار أدوات Agent وMCP لقواعد البيانات على الجهاز المحلي وعلى Google Cloud من خلال خدمة Cloud Run.

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

• تصميم وإنشاء ونشر موظّف دعم سيجيب عن طلبات بحث المستخدمين عن الفنادق في موقع جغرافي معيّن أو سيبحث عن الفنادق حسب الاسم

ما ستتعرّف عليه

• توفير قاعدة بيانات Cloud SQL لنظام PostgreSQL وملؤها بعيّنات البيانات
• إعداد أدوات MCP لقواعد البيانات في مثيل قاعدة بيانات Cloud SQL لـ PostgreSQL
• تصميم موظّف دعم وتطويره باستخدام حزمة تطوير موظّفي الدعم (ADK) للإجابة عن طلبات المستخدمين
• اختبِر "صندوق أدوات قاعدة البيانات" الخاص بـ "مساعِد Google" و"مركز عملائي" في البيئة المحلية.
• (اختياريًا) يمكنك نشر مجموعة أدوات Agent وMCP لقواعد البيانات في Google Cloud.

المتطلبات

• متصفّح الويب Chrome
• حساب Gmail
• مشروع على Cloud مفعّلة فيه الفوترة

تم تصميم هذا المختبر البرمجي للمطوّرين من جميع المستويات (بما في ذلك المبتدئين)، ويستخدم لغة Python في نموذج تطبيقه. ومع ذلك، لا يُشترط معرفة Python لفهم المفاهيم المعروضة.

2. قبل البدء

إنشاء مشروع

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

4. بعد الاتصال بخدمة Cloud Shell، عليك التحقّق من أنّك سبق أن تم مصادقة حسابك وأنّ المشروع قد تم ضبطه على معرّف مشروعك باستخدام الأمر التالي:

gcloud auth list

5. شغِّل الأمر التالي في Cloud Shell للتأكّد من أنّ الأمر gcloud يعرف مشروعك.

gcloud config list project

6. إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:

gcloud config set project <YOUR_PROJECT_ID>

7. فعِّل واجهات برمجة التطبيقات المطلوبة من خلال الأمر الموضَّح أدناه. قد تستغرق هذه العملية بضع دقائق، لذا يُرجى الانتظار.

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 \
--cpu=2 \
--memory=8GiB \
--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-22', '2024-04-20', 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-24', '2024-04-05', B'0'),
 (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
 (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
 (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
 (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', 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');

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

SELECT * FROM hotels;

من المفترض أن يظهر لك عدد من السجلات في جدول الفنادق كما هو موضّح أدناه:

لقد أكملنا عملية إعداد مثيل Cloud SQL وأنشأنا عيّنة البيانات. في القسم التالي، سنعمل على إعداد "مجموعة أدوات MCP" لقواعد البيانات.

5. إعداد "صندوق أدوات MCP" لقواعد البيانات

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

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

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

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

يمكنك ملاحظة أنّ إحدى قواعد البيانات المتوافقة مع أدوات MCP لقواعد البيانات هي Cloud SQL، وقد وفّرنا هذه القاعدة في القسم السابق.

تثبيت "مجموعة الأدوات"

افتح Cloud Shell Terminal وأنشئ مجلدًا باسم mcp-toolbox.

mkdir mcp-toolbox

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

cd mcp-toolbox

ثبِّت الإصدار الثنائي من أدوات MCP Toolbox لقواعد البيانات من خلال النص البرمجي الوارد أدناه:

export VERSION=0.3.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.
   parameters:
     - name: location
       type: string
       description: The location of the hotel.
   statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';

toolsets:
   my_first_toolset:
     - search-hotels-by-name
     - search-hotels-by-location

لنلقِ نظرة على الملف بشكل موجز:

1. يمثّل Sources مصادر البيانات المختلفة التي يمكن للأدوات التفاعل معها. يمثّل المصدر مصدر بيانات يمكن للأداة التفاعل معه. يمكنك تحديد Sources كخريطة في قسم sources من ملف tools.yaml. ستتضمّن إعدادات المصدر عادةً أي معلومات مطلوبة للربط بقاعدة البيانات والتفاعل معها. في حالتنا، أعددنا مصدرًا واحدًا يشير إلى مثيل Cloud SQL لـ PostgreSQL باستخدام بيانات الاعتماد. لمزيد من المعلومات، يُرجى الرجوع إلى مرجع المصادر.
2. تحدِّد Tools الإجراءات التي يمكن للموظف اتخاذها، مثل القراءة والكتابة في مصدر. تمثّل الأداة إجراءً يمكن لموظّف الدعم اتّخاذه، مثل تشغيل عبارة SQL. يمكنك تحديد Tools كخريطة في قسم tools من ملف tools.yaml. عادةً ما تتطلّب الأداة مصدرًا لإجراء إجراء. في حالتنا، نحدّد أداتَين: search-hotels-by-name وsearch-hotels-by-location ونحدّد المصدر الذي يتمّ الإجراء عليه، بالإضافة إلى لغة الاستعلامات البنيوية والمَعلمات. لمزيد من المعلومات، يُرجى الرجوع إلى مرجع الأدوات.
3. أخيرًا، لدينا Toolset، الذي يتيح لك تحديد مجموعات من الأدوات التي تريد تحميلها معًا. يمكن أن يكون ذلك مفيدًا لتحديد مجموعات مختلفة استنادًا إلى موظّف الدّعم أو التطبيق. في حالتنا، لدينا مجموعة أدوات واحدة تُسمى my_first_toolset، وتتضمّن الأداتَين اللتين حدّدناهما.

تشغيل مجموعة أدوات MCP لخادم قواعد البيانات

شغِّل الأمر التالي (من مجلد mcp-toolbox) لبدء تشغيل الخادم:

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

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

./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources." 
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices." 
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools." 
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets." 
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!" 

يتم تشغيل خادم MCP Toolbox تلقائيًا على المنفذ 5000. لنستخدم Cloud Shell لاختبار ذلك.

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

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

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

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

/api/toolset

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

{
  "serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
  "tools": {
    "search-hotels-by-location": {
      "description": "Search for hotels based on location.",
      "parameters": [
        {
          "name": "location",
          "type": "string",
          "description": "The location of the hotel.",
          "authSources": []
        }
      ]
    },
    "search-hotels-by-name": {
      "description": "Search for hotels based on name.",
      "parameters": [
        {
          "name": "name",
          "type": "string",
          "description": "The name of the hotel.",
          "authSources": []
        }
      ]
    }
  }
}

توضّح حزمة أدوات 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 لقواعد البيانات" على النحو التالي:

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 لإنشاء إطار عمل لتطبيق "موظّف خدمة الفندق" من خلال الأمر adk create مع اسم التطبيق **(hotel-agent-app)**كما هو موضّح أدناه.

adk create hotel-agent-app

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

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

Choose a model for the root agent:
1. gemini-2.0-flash-001
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 [gcp-experiments-349209]: 
Enter Google Cloud region [us-central1]: 

Agent created in /home/romin/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.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

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

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

لنعدِّل الرمز البرمجي للرمز agent.py على النحو التالي:

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.0-flash-001',
    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 [5015]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

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

لاحِظ أنّه في أعلى يمين الصفحة، تم تحديد hotel-agent-app. يمكنك الآن بدء المحادثة مع موظّف الدعم. قدِّم بعض الطلبات للاستفسار عن المدن. في ما يلي مثال على محادثة:

يمكنك إيقاف العملية التي تعمل في وحدة تحكّم Cloud Shell الطرفية (Ctrl-C).

هناك طريقة بديلة لاختبار "وكيل الدعم" وهي من خلال الأمر adk run كما هو موضّح أدناه من مجلد my-agents.

adk run hotel-agent-app

جرِّب الأمر ويمكنك التواصل مع موظّف الدعم من خلال سطر الأوامر (وحدة التحكّم). اكتب exit لإغلاق المحادثة.

7. ربط موظّف الدعم بالأدوات

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

في حالتنا، سنزوّد موظّف الدعم الآن بالأدوات التي أعددنا إعداداتها في "مجموعة أدوات MCP" لقواعد البيانات.

عدِّل ملف agent.py باستخدام الرمز البرمجي التالي:

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.0-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، ابدأ Toolbox لإدارة الخدمات السحابية (MCP) لقواعد البيانات. من المحتمل أن يكون التطبيق قيد التشغيل على الجهاز على المنفذ 5000 كما اختبرناه سابقًا. إذا لم يكن الأمر كذلك، نفِّذ الأمر التالي (من مجلد mcp-toolbox) لبدء تشغيل الخادم:

./toolbox --tools_file "tools.yaml"

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

./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources." 
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices." 
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools." 
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets." 
2025-04-23T14:32:29.565510068Z 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 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. نحن نحرص أيضًا على أن يكون لحساب الخدمة هذا الأدوار الصحيحة، أي إمكانية الوصول إلى أداة "إدارة الأسرار" والتواصل مع 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

من المفترض أن يؤدي ذلك إلى بدء عملية نشر خادم 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 المدرَجة أعلاه في المتصفّح. من المفترض أن يتم عرض رسالة "مرحبًا بالجميع" التي رأيناها سابقًا. بالإضافة إلى ذلك، يمكنك أيضًا الانتقال إلى عنوان 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 كما رأينا سابقًا.

نشر تطبيق "موظف الدعم في الفندق" على 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_VERTEXAI=True

أخيرًا، لننشر تطبيق "موظّف الدعم" على 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

سيؤدي ذلك إلى بدء عملية نشر تطبيق "موظّف خدمة الفندق" في Cloud Run. سيتم تحميل المصادر وتجميعها في حاوية Docker ودفعها إلى Artifact Registry ثم نشر الخدمة على Cloud Run. قد تستغرق هذه العملية بضع دقائق، لذا يُرجى الانتظار.

من المفترض أن تظهر لك رسالة مشابهة للرسالة أدناه:

Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
|  Building and deploying... Uploading sources.                                                                                                                                                                       
  |  Uploading sources...                                                                                                                                                                                             
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/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].                                  
  OK Creating Revision...                                                                                                                                                                                             
  OK Routing traffic...                                                                                                                                                                                               
Done.                                                                                                                                                                                                                 
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623

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

9. تهانينا

نشكرك على إنشاء وكيل باستخدام حزمة تطوير الوكيل (ADK) التي تستخدِم مجموعة أدوات MCP لقواعد البيانات.

المستندات المرجعية

• مجموعة تطوير تطبيقات الوكيل
• مجموعة أدوات "إدارة العملاء المتعددين" لقواعد البيانات
• Cloud SQL for PostgreSQL