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

1- مقدمة

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

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

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

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

المتطلبات

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

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

2. قبل البدء

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

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

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

بدء Cloud Shell

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

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

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

gcloud auth list

3. نفِّذ الأمر التالي للتأكّد من ضبط مشروعك لاستخدامه مع gcloud:

gcloud config get project

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

export PROJECT_ID=$(gcloud config get project)

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

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

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

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

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

cd mcp/examples/launchmybakery

المصادقة

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

gcloud auth application-default login

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

ملاحظة: لا تعيد حزمة تطوير البرامج (ADK) تلقائيًا تحميل الرمز المميز لبروتوكول OAuth 2.0. إذا استمرت جلسة المحادثة لأكثر من 60 دقيقة، قد تحتاج إلى إعادة المصادقة باستخدام الأمر أعلاه.

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

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

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

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

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

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

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

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

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

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

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

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

python3 -m venv .venv

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

source .venv/bin/activate

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

pip install google-adk

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

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.0 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: تعمل هذه الدالة على ضبط إعدادات الاتصال بخادم MCP في BigQuery. يستخدم google.auth لاسترداد بيانات اعتماد Cloud تلقائيًا، وينشئ رمز OAuth Bearer المميز، ويدرجه في عنوان Authorization.

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

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

يتم تهيئة LlmAgent باستخدام نموذج gemini-3-pro-preview.

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

root_agent = LlmAgent(
    model='gemini-3-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. يؤدي هذا الأمر إلى تشغيل خادم ويب خفيف الوزن لاستضافة تطبيق الدردشة:

adk web

بعد بدء تشغيل الخادم، يمكنك الدردشة مع وكيلك من خلال النقر على عنوان URL المقدَّم لتشغيل "واجهة ADK على الويب".

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

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

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

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

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

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

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

8. تنظيف

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

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

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

9- تهانينا

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

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

الإنجازات:

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

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

• استخدام خادم BigQuery MCP
• استخدام خادم MCP الخاص بـ Maps Groundling Lite
• مصادقة MCP