1- مقدمة
The Modern Agent Stack
يتطلّب إنشاء وكيل ذكاء اصطناعي جاهز للاستخدام أكثر من مجرد نموذج لغوي كبير. في حين يوفّر النموذج اللغوي الكبير إمكانات الاستدلال، يحتاج الوكيل الفعّال إلى التفاعل مع العالم الخارجي، وإدارة حالة المحادثة، وتذكُّر الإعدادات المفضّلة للمستخدم بمرور الوقت.
في ورشة العمل هذه، ستتعرّف على كيفية تصميم وبناء نظام شامل قائم على الوكلاء باستخدام ثلاث تقنيات أساسية:
- الاتصال (MCP): لمنح الوكيل إذن الوصول إلى الأدوات والبيانات المحلية.
- التنسيق (ADK): لإدارة حلقة الاستدلال وحالة الوكيل
- الذاكرة (مستودع الذاكرة): لتوفير سياق مخصّص طويل الأمد
المفاهيم الأساسية
المكوّن | الوظيفة |
بروتوكول سياق النموذج (MCP) | معيار عالمي يربط نماذج الذكاء الاصطناعي بالأنظمة الخارجية (قواعد البيانات وأنظمة الملفات وواجهات برمجة التطبيقات) بدون عمليات دمج مخصّصة |
مجموعة أدوات تطوير الوكيل (ADK) | إطار عمل يوفّر بيئة وقت التشغيل للوكلاء، ويدير حلقة الأحداث وعمليات نقل الحالة وتنفيذ الأدوات. |
خدمة الجلسات | التعامل مع الذاكرة القصيرة المدى ويحافظ على سياق المحادثة المباشرة (مثلاً، "ما هو السؤال الذي طرحه المستخدم للتو؟")، ولكن يتم محوه عند انتهاء الجلسة. |
Vertex AI Memory Bank | تتعامل مع الذاكرة الطويلة الأمد يحتفظ هذا الملف بالحقائق والإعدادات المفضّلة الخاصة بالمستخدم (مثل "يفضّل المستخدم لغة Python") إلى أجل غير مسمى، ما يسمح للوكيل بتخصيص التفاعلات المستقبلية. |
محرك وكلاء Vertex AI | خدمة البنية الأساسية المُدارة التي تستضيف منطق الوكيل ومكوّنات الذاكرة على نطاق واسع. |
ما ستنشئه
لتوضيح هذه المفاهيم، ستنشئ مساعد تصميم خاصًا بالأعياد. سيكون هذا الوكيل قادرًا على تلقّي طلبات المستخدمين العالية المستوى وتنسيق أدوات Python المحلية بشكل مستقل لإنشاء رموز وصور مخصّصة.
ستنتقل خلال ثلاث مراحل:
- طبقة الأدوات: أنشئ خادم MCP لعرض دوال Python المحلية على الذكاء الاصطناعي.
- طبقة الوكيل: استخدِم ADK لإنشاء وكيل يخطّط وينفّذ سير عمل متعدّد الخطوات.
- طبقة الذاكرة: يمكنك دمج "بنك الذاكرة" لتمكين الوكيل من التعرّف على تفضيلات المستخدمين المتعلقة بالأسلوب وتذكُّرها.
2. إعداد
لتشغيل وكلاء الذكاء الاصطناعي، نحتاج إلى عنصرَين: مشروع على Google Cloud لتوفير الأساس.
الجزء الأول: تفعيل حساب الفوترة
- للمطالبة بحساب الفوترة الذي يتضمّن رصيدًا بقيمة 5 دولار أمريكي، ستحتاج إليه عند نشر تطبيقك. تأكَّد من تسجيل الدخول إلى حسابك على Gmail.
الجزء الثاني: البيئة المفتوحة
- 👉 انقر على هذا الرابط للانتقال مباشرةً إلى محرّر Cloud Shell
- 👉 إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على منح الإذن للمتابعة.
- 👉 إذا لم تظهر نافذة Terminal في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
- انقر على عرض.
- انقر على Terminal
.
- 👉💻 في نافذة الوحدة الطرفية، تأكَّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:
gcloud auth list - 👉💻 استنسِخ مشروع bootstrap من GitHub:
git clone https://github.com/cuppibla/holiday_workshop - 👉💻 شغِّل نص الإعداد البرمجي من دليل المشروع.
cd ~/holiday_workshop ./init.sh - 👉💻 اضبط رقم تعريف المشروع المطلوب:
gcloud config set project $(cat ~/project_id.txt) --quiet
الجزء الثالث: إعداد الأذونات
- 👉💻 فعِّل واجهات برمجة التطبيقات المطلوبة باستخدام الأمر التالي. قد يستغرق هذا بضع دقائق.
gcloud services enable \ cloudresourcemanager.googleapis.com \ servicenetworking.googleapis.com \ run.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com - 👉💻 امنح الأذونات اللازمة من خلال تنفيذ الأوامر التالية في الوحدة الطرفية:
. ~/holiday_workshop/set_env.sh
لاحظ أنّه تم إنشاء ملف .env لك. تعرض هذه الصفحة معلومات مشروعك.
3- تعزيز الأداء باستخدام "برنامج شركاء المحتوى"
لحظة "USB-C" في مجال الذكاء الاصطناعي
تخيَّل أنّه في كل مرة تشتري فيها فأرة جديدة، عليك لحامها باللوحة الأم. كانت هذه هي حالة أدوات الذكاء الاصطناعي حتى وقت قريب. كان على المطوّرين كتابة "رمز ربط" مخصّص لربط النماذج اللغوية الكبيرة بقواعد البيانات أو أنظمة الملفات أو واجهات برمجة التطبيقات.
أدخِل بروتوكول سياق النموذج (MCP). يمكن اعتبار MCP منفذ USB-C لتطبيقات الذكاء الاصطناعي. توفّر هذه المنصة طريقة موحَّدة لربط نماذج الذكاء الاصطناعي بمصادر البيانات والأدوات.
إذا أنشأت خادم MCP لأدواتك مرة واحدة، يمكنك توصيله بواجهة سطر الأوامر في Gemini أو بيئة تطوير متكاملة أو أي عميل آخر متوافق مع MCP بدون تغيير أي سطر من الرمز البرمجي.
ما ستنشئه
في هذا الدرس التطبيقي حول الترميز، ستنشئ مساعد تصميم عطلات يعمل على:
- الاتصال ببيئتك المحلية (أدوات الاستوديو) باستخدام MCP
- إدارة سياق المحادثة بشكل موثوق باستخدام حزمة تطوير الوكلاء (ADK)
- تذكُّر إعداداتك المفضّلة (مثل "أفضّل رموز Python البرمجية") في جلسات مختلفة باستخدام Vertex AI Memory Bank.
إنشاء منطق الخادم
لقد أعددنا البيئة، ولكن منطق الخادم غير مكتمل. علينا تنفيذ الأدوات الأربع المحدّدة التي سيستخدمها "الوكيل" في النهاية لإنشاء بطاقة العطلة.
الجزء الأول: فتح هيكل الخادم
سنعمل في الدليل 01-MCP-Files-Testing/01-starter.
- في نافذة Cloud Shell، تأكَّد من أنّك في الدليل الصحيح:
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/ - افتح الملف في "محرِّر Cloud Shell" من خلال تنفيذ ما يلي:
cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
ستلاحظ أنّه تمّت كتابة الرمز النموذجي (إعداد خادم MCP، والتعامل مع عمليات الربط، وإعداد برنامج Vertex AI) مسبقًا. ومع ذلك، فإنّ الوظائف الأساسية الأربع هي حاليًا عناصر نائبة فارغة.
الجزء الثاني: تنفيذ "أداة إنشاء المشاهد الاحتفالية"
أولاً، نحتاج إلى أداة تأخذ اهتمامات المستخدم (مثل "طيور") ويحوّله إلى طلب غني بالتفاصيل ومحسّن لإنشاء الصور.
ابحث عن التعليق #REPLACE_GENERATE_HOLIDAY_SCENE داخل الدالة generate_holiday_scene.
استبدِل هذا السطر بأكمله بالرمز التالي:
prompt = (
f"""
Create a cozy, high-fidelity 3D render of a winter holiday scene.
The scene should be warm and inviting with soft cinematic lighting.
Seamlessly integrate the following specific theme/interest into the
holiday decor or landscape: {interest}.
The style should be whimsical but detailed.
Aspect Ratio: 16:9 Landscape.
"""
)
generate_image(prompt, "16:9", "static/generated_scene.png")
return "Done! Saved at generated_scene.png"
الجزء الثالث: تنفيذ نتيجة الصورة النهائية
أخيرًا، نريد التأكّد من أنّ الإضاءة والأسلوب يبدوان واقعيين واحتفاليين.
ابحث عن التعليق #REPLACE_GENERATE_FINAL_PHOTO.
استبدِل هذا السطر بالكامل بالرمز التالي لتنفيذ عملية نقل الأسلوب النهائية وعرض الصورة:
prompt = (
"""
Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
Lighting: Warm, glowing ambient light from a fire below (out of frame).
Background: Softly blurred (bokeh) pine garland and twinkling lights.
Foreground Composition:
1. A wooden picture frame containing the [attached selfie image].
The face in the photo must be clearly visible.
2. A folded holiday greeting card standing upright next to the frame.
The front of the card displays the [attached holiday scene image] as a print.
Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
"""
)
generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
return "Done! Saved at generated_final_photo.png"
إعداد البيئة
بعد وضع الرمز، علينا التأكّد من تثبيت التبعيات. سنستخدم uv، وهي أداة سريعة لإدارة حِزم ومشاريع Python.
👉💻 في الوحدة الطرفية، شغِّل ما يلي لإضافة FastMCP كعنصر تابع لمشروعنا:
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp
ستلاحظ إضافة تبعية جديدة fastmcp>=2.13.3 إلى ملف ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml.
4. الاختبار باستخدام Gemini CLI لخادم MCP
بعد اكتمال رمز الخادم، كيف يمكننا اختباره؟
عادةً ما يتطلّب اختبار خادم الخلفية إنشاء واجهة مستخدم أمامية أو كتابة طلبات curl معقّدة. ومع ذلك، يمكننا هنا استخدام Gemini CLI.
وهذا مفيد للغاية في عملية التطوير لأنّه يعزل المنطق. يمكنك التأكّد من أنّ النموذج يفهم أدواتك ويستدعيها بشكل صحيح قبل أن تقلق بشأن إنشاء واجهة ويب أو إطار عمل وكيل.
الربط والتنفيذ
سنطلب من Gemini CLI إدارة الخادم باستخدام الأمر mcp add.
في الوحدة الطرفية، شغِّل الأمر التالي:
gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
add holidays: أطلقنا لقبًا على الخادم ("عطلات").uv run ...: قدّمنا الأمر الصريح لبدء خادم Python الذي عدّلناه للتو.
لنبدأ الابتكار
الآن، ابدأ جلسة المحادثة:
gemini
جرِّب الطلب التالي لمعرفة ما إذا كان بإمكان Gemini "رؤية" أدواتك الجديدة. يُرجى العِلم أنّه قد تحتاج إلى منح Gemini CLI الإذن باستخدام أداة العطلات.
- 👉 المستخدم:
"I want to create a festive holiday photo. I like birds a lot." - Gemini:
*Thinking...* *Calling tool: generate_holiday_scene(interest='birds')* Done! Saved at generated_scene.png - 👉 المستخدم:
"Great! Now generate a knitting pattern for a sweater with reindeer on it." - Gemini:
*Thinking...* *Calling tool: generate_sweater_pattern(motif='reindeer')* Done! Saved at generated_pattern.png
مراجعة الصورة
- يمكنك إنهاء Gemini CLI بالضغط على
Control+C. - تحقَّق من الصورة التي تم إنشاؤها في مجلدك:
~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.
مراجعة صورتك هنا: 
الخاتمة والخطوات التالية
تهانينا! لقد أنشأت خادم MCP يعمل بنجاح. أصبح لديك الآن مجموعة عملية من "أدوات الذكاء الاصطناعي" التي يمكنها إنشاء أنماط وتركيب صور وتحسين المشاهد.
ومع ذلك، هل لاحظت شيئًا في الاختبار أعلاه؟ كان عليك قيادة العملية. كان عليك طلب المشهد، ثم طلب النمط، ثم طلب دمجهما.
على الرغم من أنّ Gemini ذكي، إلا أنّنا نريد المزيد من التحكّم في سير عمل الإنتاج المعقّد، حيث نحتاج إلى إنشاء نمط قبل أن نتمكّن من وضعه على سترة، والتعامل مع الأخطاء في حال تعذّر إنشاء الصورة. نريد نظامًا مخصّصًا يمكنه التخطيط والتعقيب على عمله وإدارة حالة بطاقة الأعياد بدون أن نساعده في كل خطوة.
في القسم التالي، سننظّم هذه الفوضى الإبداعية. سنستخدم حزمة تطوير الوكيل (ADK) لإنشاء وكيل منظَّم ينسّق أدوات MCP هذه في مسار إنتاج مثالي.
5- البرمجة الوصفية لوكيل ADK
لدينا مجموعة أدوات تعمل بشكل جيد (خادم MCP)، ولكنّنا حاليًا من يقوم بكل العمل الشاق، أي تحديد الأداة التي يجب استخدامها ومتى.
في هذا القسم، سننشئ وكيل ذكاء اصطناعي، وهو نظام يمكنه التفكير والتخطيط وتنفيذ المهام المتعددة الخطوات بشكل مستقل. لإجراء ذلك، سنستخدم حزمة تطوير الوكيل (ADK).
ما هو "الوكيل"؟
إذا كانت أدوات MCP هي "الأيدي" (التي تقوم بالعمل)، فإنّ الوكيل هو "العقل". يستخدم الوكيل نموذج لغة كبيرًا لفهم نية المستخدم ("أريد بطاقة تهنئة بمناسبة العطلة")، ويقسّمها إلى خطوات ("أحتاج أولاً إلى مشهد، ثم إلى نمط...")، ويقرّر الأدوات التي يجب استخدامها لتحقيق الهدف.
ما هي "حزمة تطوير التطبيقات" (ADK)؟
حزمة تطوير الوكيل (ADK) هي إطار عمل من Google يسهّل إنشاء هؤلاء الوكلاء. وهي تتولّى المهام المعقّدة، مثل إدارة سجلّ المحادثات والربط بالأدوات والتبديل بين النماذج المختلفة، ما يتيح لك التركيز على شخصية تطبيقك ومنطقه.
البرمجة الوصفية المستندة إلى السياق
من الأنماط الشائعة استخدام طلب واحد كبير لإنشاء الرمز. ومع ذلك، عند إنشاء تطبيقات معقّدة، من الأفضل غالبًا التعامل مع الذكاء الاصطناعي كشريك يحافظ على السياق بمرور الوقت.
سنستخدم ميزات الذاكرة في Gemini CLI لتمهيد الطريق قبل كتابة أي سطر من التعليمات البرمجية.
1- إعداد البيئة
افتح نافذة الأوامر الطرفية وانتقِل إلى دليل التطبيق الأوّلي:
cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter
ابدأ Gemini CLI باتّباع الخطوات التالية:
gemini
2. إدارة السياق والذاكرة
عند استخدام الترميز المستند إلى المشاعر، يحتاج الذكاء الاصطناعي إلى معرفة هويته ومعلوماته. يتيح لنا Gemini CLI إدارة ذلك بشكل صريح.
/memory show: اكتب هذا الأمر لمعرفة المعلومات التي يعرفها الذكاء الاصطناعي حاليًا عن مشروعك وجلسة التعديل./memory add: استخدِم هذه السمة لإدخال معلومات أساسية يجب أن يتذكّرها الذكاء الاصطناعي طوال المحادثة.
لنبدأ بتحديد شخصية شريكنا في الترميز. نفِّذ الأمر التالي داخل Gemini CLI:
/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."
Gemini يفهم دوره الآن سيؤثّر هذا السياق في كل استجابة لاحقة، ما يضمن الحصول على رمز عالي الجودة ومتوافق مع "حزمة تطوير التطبيقات".
3- الخطوة 1: ترميز "الوكيل الأساسي"
بدلاً من محاولة إنشاء النظام بأكمله في وقت واحد، لنبدأ بالهيكل الأساسي. نريد تحديد بنية الملف والشخصية الأساسية للوكيل.
أدخِل الطلب التالي إلى Gemini CLI:
Let's start by building the basic agent structure.
Please create a file structure for a `root_agent`.
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant".
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.
سينشئ Gemini بنية الملف والرمز البرمجي الأولي في Python. راجِعها للتأكّد من أنّها تبدو صحيحة، ثم طبِّق التغييرات أو اقبلها.
4. الخطوة 2: إضافة خادم MCP (الأدوات)
بعد أن أصبح لدينا وكيل أساسي، علينا أن نزوّده بـ "أدوات". علينا ربط البرنامج بخادم MCP الذي أنشأناه في التمرين المعملي السابق.
أدخِل الطلب التالي إلى Gemini CLI:
Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.
سيعيد Gemini الآن تصميم agent.py الحالي ليشمل تعريفات الأدوات ومنطق الربط.
ملاحظة: إذا أردت التحقّق من عملك أو إذا كان الرمز الذي تم إنشاؤه لا يعمل على النحو المتوقّع، يمكنك مقارنة ملفاتك بالحل المرجعي الموجود في: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution
6. تشغيل واجهة الويب الخاصة بالوكيل
تتضمّن حزمة تطوير التطبيقات (ADK) واجهة اختبار مدمَجة تُسمى adk web. يؤدي ذلك إلى إنشاء واجهة مستخدم بسيطة للدردشة حتى نتمكّن من التحدث مع الوكيل على الفور.
- إذا كان GeminiCLI لا يزال مفتوحًا، اضغط على
control+Cلإغلاقه. الآن، في نافذة الأوامر(هذا في المجلدsolution، يمكنك الانتقال إلىstarterلاختبار الرمز عن طريق تشغيلuv run adk webفي المجلدstarter)، شغِّل ما يلي:cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution uv run adk web --port 8000 - ستنبّهك Cloud Shell إلى أنّ إحدى الخدمات تعمل على المنفذ 8000. انقر على "معاينة الويب" -> "المعاينة على المنفذ 8000".
اختبار الوكيل
من المفترض أن تظهر الآن واجهة محادثة. لنتأكّد مما إذا كان "الوكيل" يتبع التعليمات الجديدة ويصل إلى أدوات MCP بشكل صحيح.
جرِّب هذه الطلبات:
- "مرحبًا! من أنت؟"
- (توقَّع ردًا احتفاليًا وحماسيًا).
- "أحتاج إلى خلفية لبطاقة التهنئة بمناسبة الأعياد. أريد أن تكون قرية ثلجية".
- (على موظّف الدعم الاتصال بالرقم
generate_holiday_scene. لاحظ كيف يتم تلقائيًا تطبيق نمط "لطيف/رسوم متحركة" المحدّد في تعليمات النظام).
- (على موظّف الدعم الاتصال بالرقم
- "أريد إنشاء تصميم لكنزة يتضمّن شرائح بيتزا صغيرة".
- (على موظّف الدعم الاتصال بالرقم
generate_sweater_pattern).
- (على موظّف الدعم الاتصال بالرقم
يمكنك الاطّلاع على الصورة التي تم إنشاؤها هنا:
اضغط على Control+C للخروج إذا انتهيت من الاختبار.
الخاتمة والخطوات التالية
لقد نجحت الآن في "ترميز" وكيل Google ADK باستخدام أسلوب مراعاة السياق.
- تحديد السياق: استخدمنا
/memory addلتحديد شخصية خبير. - أنشأنا المنتج بشكل متكرّر: أنشأنا الهيكل أولاً، ثم أضفنا عمليات ربط الأدوات.
تُعدّ المعاينة المضمّنة على الويب في ADK رائعة للاختبار، ولكن بالنسبة إلى منتجنا النهائي، نريد تجربة مخصّصة تحمل علامتنا التجارية. في القسم التالي، سنربط هذا "الوكيل" بواجهة أمامية مخصّصة على الويب.
7. ربط "حزمة تطوير التطبيقات" بواجهة المستخدم
بعد أن أصبح لدينا تعريف للوكيل، علينا تنفيذه. وهنا يأتي دور Runner وخدمة الجلسات.
التنفيذ
- 👉 اكتب ما يلي في الأمر:
cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.pyفي المحرّر. - استبدِل
# TODO: Create Session Serviceبما يلي:from google.adk.sessions import InMemorySessionService from google.adk.memory import InMemoryMemoryService session_service = InMemorySessionService() memory_service = InMemoryMemoryService() - استبدِل
# TODO: Initialize Runnerبما يلي:runner = Runner( app_name="agents", agent=christmas_agent, session_service=session_service, memory_service=memory_service, )
- راجِع السطر 158 في هذا
~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(ليس عليك اتّخاذ أي إجراء): إذا كنت تتساءل عن كيفية حصول التطبيق على الردّ النهائي. في ما يلي حلقة الأحداث التي يتم تشغيلها بواسطة برنامج التشغيل:async for event in runner.run_async( user_id=user_id, session_id=session_id, new_message=content )
نظرة متعمّقة: البنية وعملية النشر
نستخدم FastAPI لتقديم هذا الوكيل.
- لماذا FastAPI؟: غالبًا ما تكون البرامج الوكيلة مرتبطة بالإدخال/الإخراج (في انتظار نماذج اللغات الكبيرة). تتعامل ميزة عدم التزامن في FastAPI مع هذه الحالة بشكل مثالي.
- عدم الاحتفاظ بالحالة: لاحظ أنّ نقطة نهاية واجهة برمجة التطبيقات لا تحتفظ بالحالة. لا نحفظ المتغيرات في النطاق العام. نعتمد على
session_idوSessionServiceلإعادة إنشاء الحالة لكل طلب. وهذا يعني أنّه يمكنك نشر هذا التطبيق على Cloud Run (بدون خادم) وتوسيع نطاقه إلى صفر.
8. تجربة التطبيق باستخدام ميزة "السحر"
- 👉💻 اكتب ما يلي في الأمر:
cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter ./start_app.sh~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.pyفي المحرّر. - ستظهر لك النتيجة كما هو موضّح أدناه:
👉👉 احرص على النقر على http://localhost:5173/أو فتح نافذة جديدة وكتابةhttp://localhost:5173/. - سيظهر لك الموقع الإلكتروني مع واجهة المحادثة:
- اختبِر الميزة من خلال تحميل صورة واحدة(يمكن أن تكون لك أو لحيوانك الأليف)
- 👉 ثم اطرح السؤال
Can you generate a picture my cat wearing snowflake pattern sweater?
- 👉💻 بعد الانتهاء من الاختبار، اضغط على
control+Cفي نافذة الجهاز لإنهاء العملية.
إذا لم تنجح الخطوات السابقة، يمكنك الانتقال إلى ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution وتشغيل ./start_app.sh، ثم اتّباع الخطوات نفسها الموضّحة أعلاه.
9- Vertex AI Memory Bank
الذاكرة القصيرة المدى مقابل الذاكرة الطويلة المدى
- السياق القصير الأمد: "ماذا قلتُ للتو؟" (سجلّ الجلسة). ويتم فقدانها عند إغلاق نافذة المحادثة.
- الذاكرة الطويلة الأمد: "ما هي لغة البرمجة المفضّلة لديّ؟" (الإعدادات المفضّلة للمستخدم). يجب أن يستمر هذا الإعداد إلى الأبد.
توفّر Vertex AI Memory Bank مساحة التخزين الطويل الأمد هذه. تسمح هذه الميزة للوكيل بتخزين المعلومات المخصّصة عن المستخدم واسترجاعها.
الجلسات مقابل "بنك الذاكرة"
- الجلسات (
VertexAiSessionService): هذا هو سجلّ الجلسات. يخزِّن هذا السجلّ التسلسل الزمني الأولي لكل رسالة واستدعاء أداة وحدث (AppendEventوListEvents)، ويقدّم الحقيقة الأساسية لما حدث. - بنك الذاكرة (
VertexAiMemoryBankService): يمثّل هذا القسم المعرفة. يخزّن هذا المكوّن الحقائق المركّبة والطويلة الأمد (GenerateMemories،RetrieveMemories)، ويقتصر نطاقه علىuser_idمعيّن، ما يضمن الخصوصية والعزل.
- 👉💻 اكتب ما يلي في الأمر:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.pyفي المحرّر. - ابحث عن
# TODO: Create Vertex AI Session Service & Memory Bank Service، واستبدِل السطر بأكمله بما يلي:session_service = VertexAiSessionService( project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID ) memory_service = VertexAiMemoryBankService( project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID )
- 👉💻 اكتب ما يلي في الأمر:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.pyفي المحرّر. - استبدِل
# TODO: Set Up Configurationبما يلي:# Basic configuration types MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig SimilaritySearchConfig = ( types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig ) GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig # Advanced configuration types CustomizationConfig = types.MemoryBankCustomizationConfig MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample ConversationSource = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource ) ConversationSourceEvent = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent ) ExampleGeneratedMemory = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory )
- 👉 في الملف نفسه:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.pyابحث عن# TODO: Set up topic، واستبدِل السطر بأكمله بما يلي:custom_topics = [ # Topic 1: Sweater Preference MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="sweater_preference", description="""Extract the user's preferences for sweater styles, patterns, and designs. Include: - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.) - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted) - Color preferences (red, green, navy, pastel, etc.) - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft) - Themes (retro, modern, ugly christmas sweater, elegant) Example: "User wants a retro style sweater with a pixelated reindeer pattern." Example: "User prefers dark blue colors and hates itchy wool." """, ) ), # Topic 2: Personal Context MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="personal_context", description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include: - Hobbies and activities (skiing, reading, gaming, cooking, etc.) - Pets (type, breed, name, color) - Job or profession if relevant to their style - General interests (sci-fi, nature, vintage, tech) - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach) Example: "User has a golden retriever named Max." Example: "User loves skiing and wants a snowy mountain background." Example: "User is a software engineer who likes cyberpunk aesthetics." """, ) ) ] - 👉 في الملف نفسه:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.pyابحث عن# TODO: Create Agent Engine، واستبدِل السطر بأكمله بما يلي:agent_engine = client.agent_engines.create( config={ "display_name": AGENT_DISPLAY_NAME, "context_spec": { "memory_bank_config": { "generation_config": { "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash" }, "customization_configs": [customization_config] } }, } )
لماذا لا نستخدم الطلب فقط؟
قد تسأل: "لماذا لا نلصق سجلّ المستخدم في الطلب؟"
- حدود الحجم: قدرات الاستيعاب كبيرة، ولكن ليست لا نهائية. لا يمكنك عرض سجلّ لمدة 5 سنوات.
- التكلفة: إنّ معالجة مليون رمز مميز لكل "مرحبًا" مكلفة للغاية.
- التركيز: يعمل "مستودع الذاكرة" كمحرّك بحث للوكيل. يستردّ الحقائق ذات الصلة فقط.
- 👉💻 اكتب ما يلي في الأمر:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pyفي المحرّر. - في الملف:
~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pyاستبدِل# TODO: Add PreloadMemoryToolبما يلي:if USE_MEMORY_BANK: agent_tools.append(PreloadMemoryTool())
PreloadMemoryTool وadd_session_to_memory
في agent.py، ستظهر لك مكوّنان رئيسيان:
PreloadMemoryTool: هذه أداة تتيح للوكيل "البحث عن نفسه على Google". إذا طلب المستخدم شيئًا غامضًا مثل "أريد قهوتي المعتادة"، يمكن للوكيل استخدام هذه الأداة للاستعلام من "بنك الذاكرة" عن "تفضيلات القهوة" قبل الإجابة.-
add_session_to_memory: هذا هو ردّ الاتصال في الخلفية.- لماذا يجب استخدام Async؟ يستغرق حفظ الذاكرة وقتًا (تلخيص المحادثة واستخراج الحقائق). ولا نريد أن ينتظر المستخدم هذه العملية. ننفّذها في الخلفية (
add_session_to_memory) باستخدامafter_agent_callback.
- لماذا يجب استخدام Async؟ يستغرق حفظ الذاكرة وقتًا (تلخيص المحادثة واستخراج الحقائق). ولا نريد أن ينتظر المستخدم هذه العملية. ننفّذها في الخلفية (
10. Memory Bank In Action
- 👉💻 اكتب ما يلي في الأمر:
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./use_memory_bank.sh
تحقَّق من ملف ~/holiday_workshop/.env، وسيظهر لك (ليس عليك اتّخاذ أي إجراء)USE_MEMORY_BANK=TRUE AGENT_ENGINE_ID={agent_engine_id} - 👉💻 اختبِر الذاكرة باستخدام واجهة مستخدم التطبيق. اكتب ما يلي في الأمر:
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./start_app.shhttp://localhost:5173/أو فتح نافذة جديدة وكتابةhttp://localhost:5173/. يُرجى العِلم أنّUvicorn running on http://0.0.0.0:8000هو مجرد خادم خلفي، وليس الرابط الفعلي الذي نريد النقر عليه. أصبح الآن بإمكانك استخدام واجهة المحادثة في الموقع الإلكتروني كوكيل شخصي. - 👉اختبِر الذاكرة. إذا كتبت في واجهة المستخدم:
I want a sweater that matches my dog. He's a golden retriever.I'm a programmer, so I want something geeky. Maybe a matrix style?I like snowflake sweater pattern
سيتعرّف الوكيل على هذا الإجراء كتفضيل ويخزّنه في "بنك الذاكرة".
في الأسبوع التالي(أو في أي وقت تعيد فيه تشغيل التطبيق من خلال Control+C و./start_app.sh)، إذا طرحت السؤال التالي:
what is my preference on sweater pattern?
سيطلب الوكيل من بنك الذاكرة الحصول على معلومات حول تفضيلاتك، وسينشئ تصميمًا لسترة من دون أن يُطلب منه ذلك. 
- يمكنك إثبات الملكية في "محرك وكلاء Vertex AI" من خلال الانتقال إلى محرك وكلاء Google Cloud Console
- تأكَّد من اختيار المشروع من أداة اختيار المشاريع في أعلى يمين الصفحة:
- وتأكَّد من محرّك الوكيل الذي نشرته للتو من الأمر السابق
use_memory_bank.sh
انقر على محرّك الوكيل الذي أنشأته للتو.
- تأكَّد من اختيار المشروع من أداة اختيار المشاريع في أعلى يمين الصفحة:
- انقر على علامة التبويب
Memoriesفي هذا الوكيل الذي تم نشره، ويمكنك الاطّلاع على كل الذكريات هنا.
تهانينا! لقد أضفت للتوّ "بنك الذاكرة" إلى وكيلك.
11. الخاتمة
ملخّص
لقد تمكّنت من تصميم وبناء نظام كامل يعتمد على الوكلاء بنجاح.
- الاتصال: استخدمت MCP لتوحيد طريقة وصول وكيلك إلى الأدوات المحلية.
- التنسيق: استخدمت مجموعة أدوات المطوّرين لإدارة حلقة الاستدلال المعقّدة المطلوبة للمهام المتعددة الخطوات.
- التخصيص: لقد استخدمت بنك الذاكرة لإنشاء طبقة تعلّم مستمرة تتذكّر سياق المستخدم.
الخطوات التالية
- إنشاء خادم MCP: يمكنك إنشاء خادم لقاعدة البيانات أو واجهة برمجة التطبيقات الداخلية.
- استكشاف أنماط ADK: يمكنك الاطّلاع على "حلقات الاستدلال" و "التنسيق" في مستندات ADK.
- النشر: يمكنك نقل برنامجك من نص برمجي محلي إلى خدمة إنتاج على Cloud Run.