إنشاء وكيل ADK لخدمة "ذكاء الموقع الجغرافي" باستخدام خوادم MCP لخدمتَي BigQuery و"خرائط Google"

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستنشئ وكيلاً باستخدام "حزمة تطوير الوكلاء" (ADK) المستندة إلى Gemini 3.1 Pro. سيتم تزويد الوكيل بأدوات من خادمَي MCP بعيدَين (تستضيفهما Google) للوصول بشكل آمن إلى BigQuery من أجل الحصول على بيانات ديمغرافية وبيانات الأسعار والمبيعات، وإلى "خرائط Google" من أجل تحليل المواقع الجغرافية الفعلية والتحقّق منها.

ينسّق الوكيل الطلبات بين المستخدم وخدمات Google Cloud لحلّ مشاكل الأعمال المتعلقة بمجموعة بيانات مخبز وهمي.

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

إعداد البيانات: أنشئ مجموعة بيانات أساسية للمخبز في BigQuery.
تطوير الوكيل: يمكنك إنشاء وكيل ذكي باستخدام "حزمة تطوير الوكلاء" (ADK).
دمج الأدوات: تزويد الوكيل بوظائف BigQuery و"خرائط Google" من خلال خادم MCP
تحليل السوق: تفاعَل مع الوكيل لتقييم مؤشرات السوق ومدى تشبّعه.

المتطلبات

متصفّح ويب، مثل Chrome
مشروع Google Cloud تم تفعيل الفوترة فيه أو حساب Gmail

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين من جميع المستويات، بما في ذلك المبتدئين. ستستخدم واجهة سطر الأوامر في Google Cloud Shell ورمز Python لتطوير حزمة تطوير الوكلاء (ADK). ليس عليك أن تكون خبيرًا في Python، ولكنّ فهمًا أساسيًا لطريقة قراءة الرموز البرمجية سيساعدك في فهم المفاهيم.

2. قبل البدء

إنشاء مشروع على Google Cloud

في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.

تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع.

بدء Cloud Shell

Cloud Shell هي بيئة سطر أوامر تعمل في Google Cloud ومحمّلة مسبقًا بالأدوات اللازمة.

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

بعد الاتصال بـ Cloud Shell، شغِّل الأمر التالي للتحقّق من مصادقتك في Cloud Shell:

gcloud auth list

نفِّذ الأمر التالي للتأكّد من إعداد مشروعك لاستخدامه مع gcloud:

gcloud config get project

تأكَّد من أنّ المشروع هو ما تتوقّعه، ثم نفِّذ الأمر أدناه لضبط رقم تعريف مشروعك:

export PROJECT_ID=$(gcloud config get project)

3- الحصول على الرمز

إنشاء نسخة طبق الأصل من المستودع

أنشئ نسخة طبق الأصل من المستودع إلى بيئة Cloud Shell:

git clone https://github.com/google/mcp.git

انتقِل إلى دليل العرض التوضيحي:

cd mcp/examples/launchmybakery

المصادقة

نفِّذ الأمر التالي للمصادقة باستخدام حسابك على Google Cloud. هذا الإذن مطلوب لكي تتمكّن "حزمة تطوير التطبيقات" من الوصول إلى BigQuery.

gcloud auth application-default login

اتّبِع التعليمات لإكمال عملية المصادقة.

4. ضبط البيئة وBigQuery

تشغيل نصوص الإعداد البرمجية

شغِّل نص إعداد البيئة البرمجي. يتيح هذا النص البرمجي واجهات BigQuery وGoogle Maps API، وينشئ ملف .env يحتوي على رقم تعريف مشروعك ومفتاح Maps API.

chmod +x setup/setup_env.sh
./setup/setup_env.sh

تشغيل نص إعداد BigQuery البرمجي يعمل هذا النص البرمجي على أتمتة عملية إنشاء حزمة Cloud Storage وتحميل البيانات وتوفير مجموعة بيانات وجداول BigQuery.

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

بعد اكتمال البرنامج النصي، من المفترض أن يتم إنشاء مجموعة بيانات mcp_bakery وتعبئتها بالجداول التالية:

البيانات الديمغرافية: بيانات الإحصاء السكاني وخصائص السكان حسب الرمز البريدي
bakery_prices: أسعار المنافسين وتفاصيل المنتجات المختلفة من المخبوزات
sales_history_weekly: أداء المبيعات الأسبوعي (الكمية والأرباح) حسب المتجر والمنتج
foot_traffic: نتائج تقديرية لعدد الزيارات إلى المتجر حسب الرمز البريدي والوقت من اليوم

تأكَّد من إنشاء مجموعة البيانات والجداول من خلال الانتقال إلى وحدة تحكّم BigQuery في مشروعك على Google Cloud:

5- تثبيت "حزمة تطوير التطبيقات"

بعد أن أصبحت البنية الأساسية جاهزة، لننشئ بيئة Python افتراضية ونثبّت الحِزم المطلوبة لحزمة تطوير التطبيقات (ADK).

إنشاء بيئة افتراضية:

python3 -m venv .venv

فعِّل البيئة الافتراضية:

source .venv/bin/activate

ثبِّت حزمة تطوير التطبيقات (ADK) باتّباع الخطوات التالية:

pip install google-adk==1.28.0

انتقِل إلى دليل الوكلاء:

cd adk_agent/

6. فحص تطبيق ADK

انقر على الزر فتح المحرّر (Open Editor) في Cloud Shell لفتح Cloud Shell Editor وعرض المستودع الذي تم استنساخه ضمن الدليل mcp/examples/launchmybakery.

تم توفير رمز الوكيل في دليل adk_agent/. لنستكشف بنية الحلّ:

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

الملفات الرئيسية في mcp_bakery_app:

agent.py: المنطق الأساسي الذي يحدّد الوكيل وأدواته والنموذج (النسخة الحصرية من Gemini 3.1 Pro).
‫tools.py: يحتوي على أي تعريفات أدوات مخصّصة.
.env: يحتوي على إعدادات مشروعك والأسرار (مثل مفاتيح واجهة برمجة التطبيقات) التي تم إنشاؤها بواسطة نص الإعداد البرمجي.

1. تهيئة مجموعة أدوات MCP:

الآن، افتح adk_agent/mcp_bakery_app/tools.py في "المحرّر" لفهم كيفية بدء مجموعات أدوات MCP.

لتمكين الوكيل من التواصل مع BigQuery و"خرائط Google"، علينا ضبط إعدادات بروتوكول Model Context Protocol (MCP).

ينشئ الرمز اتصالات آمنة بخوادم MCP البعيدة التابعة لـ Google باستخدام StreamableHTTPConnectionParams.

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools

مجموعة أدوات "خرائط Google": تضبط هذه المجموعة عملية الربط بخادم MCP الخاص بـ "خرائط Google" باستخدام مفتاح واجهة برمجة التطبيقات.
مجموعة أدوات BigQuery: تعمل هذه الدالة على ضبط عملية الربط بخادم BigQuery MCP. يستخدم google.auth لاسترداد بيانات اعتماد Cloud تلقائيًا، وينشئ رمز OAuth Bearer المميز، ويدرجه في عنوان التفويض.

2. تعريف الوكيل:

الآن، افتح adk_agent/mcp_bakery_app/agent.py في "المحرّر" لمعرفة كيفية تحديد الوكيل.

يتم ضبط قيمة LlmAgent مبدئيًا باستخدام نموذج gemini-3.1-pro-preview.

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3.1-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)

تعليمات النظام: يتم تزويد الوكيل بتعليمات محدّدة لدمج الإحصاءات من كلّ من BigQuery (للبيانات) و"خرائط Google" (لتحليل المواقع الجغرافية).
الأدوات: يتم تعيين كل من maps_toolset وbigquery_toolset للوكيل، ما يمنحه إذن الوصول إلى إمكانات كلتا الخدمتين.

يلتزم الوكيل بالتعليمات والأدوات المحدّدة في المستودع. يمكنك إجراء تغييرات على التعليمات لمعرفة تأثيرها في سلوك الوكيل.

7. ابدأ محادثة مع وكيلك.

ارجع إلى الوحدة الطرفية في Cloud Shell وشغِّل الأمر التالي للانتقال إلى الدليل adk_agent (إذا لم يسبق لك إجراء ذلك):

cd adk_agent/

نفِّذ الأمر التالي لبدء واجهة مستخدم الويب الخاصة بـ "حزمة تطوير التطبيقات". يؤدي هذا الأمر إلى تشغيل خادم ويب خفيف الوزن لاستضافة تطبيق الدردشة:

adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

بعد بدء تشغيل الخادم، سيظهر لك ما يلي في Cloud Shell:

+-----------------------------------------------------------------------------+
| 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)

يتوفّر لك خياران للوصول إلى واجهة مستخدم ADK:

الخيار 1: النقر على الرابط المحلي انقر على الرابط http://127.0.0.1:8000 الذي يظهر في نافذة Cloud Shell.

الخيار 2: استخدام ميزة "معاينة الويب"

انقر على الزر معاينة الويب في أعلى يسار نافذة Cloud Shell.
اختَر تغيير المنفذ.
أدخِل 8000 كرقم المنفذ وانقر على تغيير ومعاينة.

لقطة شاشة توضّح كيفية فتح واجهة مستخدم ADK

تفاعَل مع "الوكيل" من خلال طرح الأسئلة التالية في واجهة مستخدم الويب. من المفترض أن تظهر لك الأدوات ذات الصلة التي يتم استدعاؤها.

البحث عن الحي (Macro): "أريد أن أفتح مخبزًا في دبي. ابحث عن الرمز البريدي الذي سجّل أعلى معدّل عدد الزيارات إلى المتجر في الصباح.

على الوكيل استخدام أدوات مثل get_table_info وexecute_sql لطلب البحث في جدول foot_traffic في BigQuery.

التحقّق من صحة الموقع الجغرافي (على مستوى صغير): "هل يمكنك البحث عن "مخابز" في الرمز البريدي هذا لمعرفة ما إذا كان مشبعًا؟"

يجب أن يستخدم الوكيل search places الأدوات في مجموعة أدوات "خرائط Google" للإجابة عن هذا السؤال.

ننصحك بتجربتها. اطّلِع على هذه الأسئلة النموذجية لمعرفة كيفية عمل وكيل ADK:

"أريد افتتاح موقع رابع للمخبز في لوس أنجلوس. أحتاج إلى حيّ يشهد نشاطًا مبكرًا. ابحث عن الرمز البريدي الذي سجّل أعلى نتيجة في مقياس عدد الزيارات إلى المتجر في الصباح".
"هل يمكنك البحث عن "مخابز" في هذا الرمز البريدي لمعرفة ما إذا كان السوق مشبعًا؟ إذا كان هناك الكثير منها، ابحث عن مقاهي "القهوة المختصة"، حتى أتمكّن من تحديد موقعي بالقرب منها لجذب الزبائن."
حسنًا، أريد أن أقدّم هذا المنتج كعلامة تجارية فاخرة. ما هو الحد الأقصى للسعر الذي يتم تحصيله مقابل رغيف خبز مخمّر في منطقة لوس أنجلوس الحضرية؟"
"أريد الآن توقّعات الإيرادات لشهر ديسمبر 2025. الاطّلاع على سجلّ مبيعاتي وأخذ البيانات من متجري الأفضل أداءً بشأن "رغيف خبز العجين المخمّر" أريد الحصول على توقّعات لشهر ديسمبر 2025 لتقدير الكمية التي سأبيعها. بعد ذلك، احسب إجمالي الإيرادات المتوقّعة باستخدام سعر أقل قليلاً من السعر المميز الذي عثرنا عليه (لنستخدِم 18 دولارًا أمريكيًا)".
هذا المبلغ يكفي لدفع الإيجار. أخيرًا، لننتحقق من الخدمات اللوجستية. ابحث عن أقرب مستودع "Restaurant Depot" إلى المنطقة المقترَحة وتأكَّد من أنّ وقت القيادة لا يزيد عن 30 دقيقة لإعادة التخزين اليومي".

عند الانتهاء من اختبار وكيلك، يمكنك إيقاف واجهة الويب الخاصة بـ ADK من خلال الضغط على Ctrl+C في نافذة Cloud Shell.

8. تنظيف

لتجنُّب الرسوم المستمرة على حسابك على Google Cloud، احذف الموارد التي تم إنشاؤها أثناء هذا الدرس التطبيقي حول الترميز.

شغِّل النص البرمجي الخاص بالتنظيف. سيؤدي هذا النص البرمجي إلى حذف مجموعة بيانات BigQuery وحزمة Cloud Storage ومفاتيح واجهة برمجة التطبيقات التي تم إنشاؤها أثناء عملية الإعداد.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9- تهانينا

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

من خلال الربط بين بيانات "المؤسسة" في BigQuery وسياق الموقع الجغرافي الفعلي من خرائط Google، أنشأت أداة فعّالة قادرة على تقديم استدلال معقّد بشأن الأعمال، وكل ذلك من خلال بروتوكول Model Context (MCP) وGemini.

الإنجازات:

البنية الأساسية كرمز: لقد وفّرت مجموعة بيانات باستخدام أدوات Google Cloud CLI.
دمج MCP: ربطتَ وكيل الذكاء الاصطناعي بخادمَي MCP بعيدَين ومختلفَين (BigQuery و"خرائط Google") بدون كتابة برامج تضمين معقّدة لواجهة برمجة التطبيقات.
الاستدلال الموحّد: أنشأت وكيلاً واحدًا قادرًا على الجمع بشكل استراتيجي بين الإحصاءات من مجالَين مختلفَين لحلّ مشكلة تجارية.