1. مقدمة
في هذا الدرس التطبيقي حول الترميز، ستنشئ وكيلاً باستخدام "حزمة تطوير الوكلاء" (ADK) المستندة إلى Gemini 3.1 Pro. سيتم تزويد الوكيل بأدوات من خادمَين بعيدَين (تستضيفهما Google) لبروتوكول Model Context من أجل الوصول بشكل آمن إلى 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، في صفحة اختيار المشروع، اختَر مشروعًا على السحابة الإلكترونية أو أنشِئ مشروعًا على السحابة الإلكترونية.
- تأكَّد من تفعيل الفوترة لمشروعك على 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- تثبيت "حزمة تطوير التطبيقات" (ADK)
بعد أن أصبحت البنية الأساسية جاهزة، لننشئ بيئة 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" وعرض المستودع الذي تم استنساخه ضمن الدليل 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"، علينا ضبط إعدادات بروتوكول سياق النموذج (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 المميز، ويدرجه في عنوان Authorization.
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. يؤدي هذا الأمر إلى تشغيل خادم ويب خفيف الوزن لاستضافة تطبيق الدردشة:
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)
يتوفّر لك خياران للوصول إلى واجهة مستخدم حزمة تطوير التطبيقات:
الخيار 1: النقر على الرابط المحلي انقر على الرابط http://127.0.0.1:8000 الذي يظهر في نافذة Cloud Shell.
الخيار 2: استخدام ميزة "معاينة الويب"
- انقر على الزر معاينة الويب في أعلى يسار نافذة Cloud Shell.
- اختَر تغيير المنفذ.
- أدخِل 8000 كرقم المنفذ وانقر على تغيير ومعاينة.
التفاعل مع "الوكيل" من خلال طرح الأسئلة التالية في واجهة مستخدم الويب من المفترض أن تظهر لك الأدوات ذات الصلة التي يتم استدعاؤها.
- البحث عن الحي (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، أنشأت أداة فعّالة قادرة على إجراء عمليات استنتاج معقّدة بشأن الأنشطة التجارية، وكل ذلك من خلال بروتوكول سياق النموذج (MCP) وGemini.
الإنجازات:
- البنية الأساسية كرمز: لقد وفّرت مجموعة بيانات باستخدام أدوات Google Cloud CLI.
- التكامل مع MCP: ربطت وكيل الذكاء الاصطناعي بخادمَي MCP بعيدَين مختلفَين (BigQuery و"خرائط Google") بدون كتابة برامج تضمين معقّدة لواجهة برمجة التطبيقات.
- الاستدلال الموحّد: أنشأت وكيلاً واحدًا قادرًا على الجمع بشكل استراتيجي بين الإحصاءات من مجالَين مختلفَين لحلّ مشكلة تجارية.