نمط ADK Agentic مع الذاكرة وMCP

1. ما ستتعلمه

مرحبًا بك في "الدرس المتقدّم حول ADK" - رحلتك إلى الأنظمة المتعددة الوكلاء

أنت على وشك الدخول إلى عالم وكلاء الذكاء الاصطناعي المثير. لا داعي لروبوتات الدردشة البسيطة التي تجيب عن الأسئلة فقط. نحن نركّز جهودنا على Agent Development Kit (ADK) لإنشاء أنظمة متطورة ذاتية التشغيل يمكنها التفكير والتخطيط واستخدام الأدوات لإنجاز مهام معقّدة.

سيكون هذا الدرس التطبيقي رحلة عملية بالكامل، وهو مستودع GitHub واحد يحتوي على جميع الرموز والأمثلة لجلساتنا. مستودع GitHub

في نهاية هذا البرنامج التعليمي، ستتمكّن من:

• إنشاء أول وكيل مستند إلى الذكاء الاصطناعي: يمكنك الانتقال من مستوى المبتدئين إلى إنشاء وكيل يعمل بكامل طاقته ويمكنه فهم احتياجات المستخدم واستخدام أدوات مثل "بحث Google" وإنشاء ردود مفصّلة ومفيدة.
• إنشاء أنظمة تستند إلى عدّة وكلاء: تعرَّف على نمط "الوكيل كأداة"، وهو مفهوم ثوري يفوّض فيه الوكلاء المهام إلى وكلاء متخصصين آخرين، ما يؤدي إلى إنشاء فريق من خبراء الذكاء الاصطناعي الذين يعملون معًا.
• تنظيم سير العمل المعقّد: يمكنك الاستفادة من الأنماط المتقدّمة، مثل أدوات التوجيه والسلاسل التسلسلية والحلقات والتنفيذ المتوازي، لإنشاء تطبيقات قوية وفعّالة وذكية يمكنها التعامل مع أي طلبات تقريبًا.
• تزويد الوكلاء بالذاكرة: تعرَّف على الدور المهم الذي تؤدّيه الذاكرة الحوارية، ما يتيح لوكلائك التعامل مع أسئلة المتابعة والاستفادة من الملاحظات وإدارة المهام المتعددة الخطوات بسلاسة.
• الربط بمنصة MCP: اربط بمنصة MCP Toolbox.

لِنبدأ. 🚀

2. الإعداد: الحصول على مفتاح واجهة برمجة التطبيقات

إعداد مفتاح Google AI Studio API

يعمل هذا الدرس التطبيقي حول الترميز بالكامل باستخدام مفتاح واجهة برمجة تطبيقات مجاني من Google AI Studio. لا يلزم توفّر مشروع أو حساب فوترة أو أرصدة على Google Cloud، بل يتم تشغيل كل جلسة محليًا باستخدام مفتاحك، بما في ذلك "الذاكرة" (الجلسة 6) و"التحكّم المتعدّد الأطراف" (الجلسة 7). يستخدم كل طالب مفتاحه الخاص، لذا تكون حصة واجهة برمجة التطبيقات لكل شخص، وليس مشتركة.

المتطلبات:

• الإصدار 3.9 أو الإصدارات الأحدث من Python (python3 --version للتحقّق)
• حساب Google (لإنشاء مفتاح AI Studio)
• وحدة طرفية، سواء جهازك المحلي أو Cloud Shell
• ‫10 دقائق تقريبًا

لتشغيل وكلاء الذكاء الاصطناعي، نحتاج إلى مفتاح Gemini API من Google AI Studio. هذه هي أسرع طريقة للبدء.

الخطوة 1: الحصول على مفتاح Gemini API من AI Studio (دقيقة واحدة)

1. افتح https://aistudio.google.com/app/apikey في علامة تبويب جديدة في المتصفّح.
2. سجِّل الدخول باستخدام حسابك على Google.
3. انقر على "إنشاء مفتاح واجهة برمجة التطبيقات" (في أعلى يسار الصفحة).
4. سيظهر مربّع حوار يتضمّن قائمة منسدلة للمشاريع:

• إذا كان لديك مشروع Google تم إنشاؤه من قبل: اختَر المشروع وانقر على "إنشاء مفتاح واجهة برمجة التطبيقات في مشروع حالي"
• إذا لم يكن المشروع في القائمة: انقر على "إنشاء مشروع".

5. انسخ مفتاح واجهة برمجة التطبيقات الذي يظهر. يبدأ بالرمز AIza... ويتألف من 40 حرفًا تقريبًا.

✏️ ألصِقها في مكان آمن، ستحتاج إليها في الخطوة 4 أدناه.

التعامل مع مفتاح واجهة برمجة التطبيقات كما لو كان كلمة مرور لا تلصقها في المحادثات العامة أو لقطات الشاشة أو ترسلها إلى مستودع GitHub عام.

الخطوة 2: إنشاء نسخة طبق الأصل من المستودع (دقيقة واحدة)

👉💻 افتح الوحدة الطرفية (أو Cloud Shell) واستنسِخ مستودع الدليل التعليمي:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

الخطوة 3: إنشاء البيئة الافتراضية وتثبيت التبعيات

👉💻 أنشئ بيئة افتراضية باسم .adk_env وفعّلها، ثم ثبِّت التبعيات:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

من المفترض أن يظهر الرمز (.adk_env) في بداية طلبك في نافذة Terminal.

الخطوة 4 — 🔥 مهم: إضافة مفتاح واجهة برمجة التطبيقات

⚠️ لا تتخطَّ هذه الخطوة! أنشئ ملف .env في المجلد الجذر للمجلد adk_tutorial. يتم استخدام هذا الملف الواحد في كل جلسة في هذا الدرس التطبيقي حول الترميز، إذ تقرأه تلقائيًا جلسات ADK Web (من 1 إلى 5) وجلسات Memory وMCP (من 6 إلى 7) في سطر الأوامر.

👉💻 أنشئ ملف .env باستخدام مفتاحك (استبدِل your_actual_api_key_here بالمفتاح من الخطوة 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

يجب أن يتضمّن ~/adk_tutorial/.env ما يلي:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 مهم: استبدِل your_actual_api_key_here بمفتاح واجهة برمجة التطبيقات الفعلي من الخطوة 1 (يبدأ بـ AIza...).

⚠️ تأكَّد من ضبط GOOGLE_GENAI_USE_VERTEXAI على FALSE. يطلب ذلك من حزمة تطوير التطبيقات إجراء المصادقة باستخدام مفتاح واجهة برمجة التطبيقات في Google AI Studio بدلاً من Vertex AI.

✅ نقطة التحقّق: لديك ملف .env في ~/adk_tutorial/.env يحتوي على مفتاح AIza...، ويظهر في موجه الأوامر (.adk_env). أنت الآن جاهز لإنشاء وكلاء.

3- الجلسة 1: الوكيل الأول في ADK Web

افتح ADK Web من خلال تنفيذ ما يلي:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

بعد تنفيذ الأوامر، من المفترض أن تظهر لك نتيجة في نافذة الأوامر تشير إلى أنّ خادم ADK Web Server قد بدأ، على النحو التالي:

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

👉 بعد ذلك، افتح المتصفّح على http://localhost:8000 للوصول إلى واجهة مستخدم ADK Dev.

هل يتم تشغيلها في Cloud Shell بدلاً من تشغيلها محليًا؟ انقر على رمز معاينة الويب في شريط أدوات Cloud Shell (عادةً في أعلى يسار الصفحة)، واختَر تغيير المنفذ، واضبط المنفذ على 8000، ثم انقر على "التغيير والمعاينة". سيفتح Cloud Shell واجهة مستخدم ADK Dev في علامة تبويب جديدة في المتصفّح.

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

اختيار الوكيل الأول في القائمة المنسدلة أعلى واجهة المستخدم، اختَر a_single_agent.

يمكنك النقر على a_single_agent هنا:

يمكنك الاطّلاع على التتبُّع هنا:

👉 طلب الاختبار:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. الجلسة 2: وكيل سير العمل: الوكيل التسلسلي، والوكيل المتوازي، ووكيل التكرار

افتح واجهة مستخدم الويب الخاصة بـ ADK باتّباع خطوات الجلسة 1.

Parallel Agent

اختيار عامل سير العمل المتوازي في القائمة المنسدلة في أعلى واجهة المستخدم، اختَر b2_parallel_agent.

👉 طلب الاختبار:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

يمكنك النقر على b2_parallel_agent هنا:

يمكنك الاطّلاع على التتبُّع هنا:

الوكيل التسلسلي

اختَر وكيل سير العمل التسلسلي في القائمة المنسدلة في أعلى واجهة المستخدم، اختَر b1_sequential_agent.

👉 طلب الاختبار:

Find a good sushi near Standford and tell me how to get there.

يمكنك النقر على b1_sequential_agent هنا:

يمكنك الاطّلاع على التتبُّع هنا:

وكيل التكرار

اختيار عامل سير عمل الحلقة في القائمة المنسدلة في أعلى واجهة المستخدم، اختَر b3_loop_agent.

👉 طلب الاختبار:

Plan a trip from Sunnyvale to San Francisco today.

يمكنك النقر على b3_loop_agent هنا:

يمكنك الاطّلاع على التتبُّع هنا:

5- الجلسة 3: وكيل مخصّص

افتح واجهة مستخدم الويب الخاصة بـ ADK باتّباع خطوات الجلسة 1.

بعد فتح واجهة مستخدم ADK Web، اختَر c_custom_agent من القائمة المنسدلة.

👉 طلب الاختبار:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

يمكنك النقر على c_custom_agent هنا:

يمكنك الاطّلاع على التتبُّع هنا:

6. الجلسة 4: نمط المنسّق - وكيل التوجيه

افتح واجهة مستخدم الويب الخاصة بـ ADK باتّباع خطوات الجلسة 1.

بعد فتح واجهة مستخدم ADK Web، اختَر d_routing_agent من القائمة المنسدلة.

👉 طلب الاختبار:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

يمكنك النقر على d_routing_agent هنا:

يمكنك الاطّلاع على التتبُّع هنا:

7. الجلسة 5: الوكيل كأداة

افتح واجهة مستخدم الويب الخاصة بـ ADK باتّباع خطوات الجلسة 1.

بعد فتح واجهة مستخدم ADK Web، اختَر e_agent_as_tool من القائمة المنسدلة.

👉 طلب الاختبار:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

يمكنك النقر على e_agent_as_tool هنا:

يمكنك الاطّلاع على التتبُّع هنا:

8. الجلسة 6: وكيل مزوّد بذاكرة طويلة الأمد

يتم تشغيلها بالكامل على الجهاز. تخزِّن هذه الجلسة سجلّ المحادثات في قاعدة بيانات SQLite محلية (ضمن ~/.adk/)، لذا تظل إعداداتك المفضّلة محفوظة عند إعادة التشغيل بدون الحاجة إلى Google Cloud أو الفوترة أو الرصيد. يقرأ الوكيل مفتاح AI Studio من ~/adk_tutorial/.env الذي أنشأته في "الإعداد".

👉💻 اختبِر ذاكرتك الطويلة الأمد من خلال الانتقال إلى المجلد واستخدام أداة التشغيل لتنشيط الوكيل:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 طلب الاختبار:

I like Art and Italian food.

بعد ذلك، أنهِ الجلسة بالضغط على Ctrl+C. أعِد تشغيل الجلسة:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 طلب الاختبار:

Plan a trip to San Francisco based on my preference.

✅ يجب أن يتذكّر الوكيل "الفن والطعام الإيطالي" من عملية التشغيل السابقة، وهذا يعني أنّ الذاكرة الطويلة الأمد تعمل على مستوى الجلسات.

9. الجلسة 7: تعزيز أداء وكيلك باستخدام MCP

يتم تشغيلها بالكامل على الجهاز. تبدأ هذه الجلسة خادم محليًا لـ MCP Toolbox يقرأ قاعدة بيانات SQLite محلية (destinations.db)، بدون الحاجة إلى Google Cloud أو الفوترة أو الأرصدة. التنزيل الخارجي الوحيد هو ثنائي MCP Toolbox مفتوح المصدر.

الخطوة 1: إعداد قاعدة البيانات المحلية

👉💻 من جذر المستودع، أنشئ قاعدة البيانات النموذجية:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

يؤدي ذلك إلى إنشاء destinations.db في ~/adk_tutorial/.

⚠️ لا تحتوي قاعدة البيانات النموذجية إلا على أربع مدن: باريس وروما ونيويورك وطوكيو (أنواع الأماكن الجاذبة للسياح: مَعلم ومتحف ومتنزه). ستعرض الطلبات التي تشير إلى مدن أخرى (مثل سان فرانسيسكو أو ساني فيل) عدم توفّر نتائج بشكلٍ صحيح، لأنّ هذه الصفوف غير متوفّرة. استخدِم المدن الأربع المذكورة أعلاه عند اختبار هذه الجلسة.

الخطوة 2: تثبيت خادم MCP Toolbox وتشغيله

👉💻 نزِّل ملف MCP Toolbox الثنائي لنظام التشغيل:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

بعد الانتهاء من التنزيل، شغِّل

chmod +x toolbox

إذا لم تكن متأكدًا من طراز جهاز Mac الذي تستخدمه، تشغيل uname -m — arm64 = Apple Silicon، x86_64 = Intel على Windows، نزِّل .../windows/amd64/toolbox.exe وشغِّله من PowerShell.

الخطوة 3

في إحدى الوحدات الطرفية، شغِّل الأمر التالي (اتركه قيد التشغيل، وسيتصل به الوكيل في http://127.0.0.1:7001):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

في وحدة طرفية أخرى، نفِّذ الأمر التالي

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 طلبات تجريبية (استخدِم المدن المتوفّرة في قاعدة البيانات النموذجية، أي القاهرة أو شرم الشيخ أو الرياض أو أبوظبي أو طنجة أو بيروت):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

تحديد المشاكل وحلّها في الجلسة 7

• "تم رفض الاتصال" / لم يعثر الوكيل على أي أدوات: لم يتم تشغيل خادم Toolbox في الوحدة الطرفية الأولى، لذا أعِد تشغيله وتأكَّد من أنّه يستمع إلى المنفذ 7001.
• كل طلب بحث يعرض نتائج فارغة: تأكَّد من أنّك نفّذت الخطوة 1 لضمان توفّر ~/adk_tutorial/destinations.db، ومن أنّ طلبك يستخدم إحدى المدن الأربع (باريس أو روما أو نيويورك أو طوكيو).
• toolbox: cannot execute binary file على نظام التشغيل macOS: إذا نزّلت إصدار Linux، أعِد تنفيذ الخطوة 2 باستخدام OS=darwin/arm64 (معالج Apple Silicon) أو OS=darwin/amd64 (معالج Intel).