تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

ورشة عمل للمبتدئين: إنشاء رفيقك الأول المستند إلى الذكاء الاصطناعي

1. أهداف الدورة التعليمية

كيفية استخدام Gemini CLI لإنشاء إعداد كامل لوكيل ADK
كيفية تعزيز شخصية الوكيل من خلال تحسين تعليماته
كيفية إضافة "الاستناد إلى مصادر" إلى وكيلك من خلال تزويده بـ google_search للإجابة عن أسئلة حول الأحداث الأخيرة
كيفية إنشاء أفاتار مخصّص للشخصية المرافقة باستخدام خادم MCP مع Imagen

تطبيق AI Companion

في هذا الدرس التطبيقي حول الترميز، ستنشئ رفيقًا مرئيًا تفاعليًا يعمل بالذكاء الاصطناعي. هذا ليس مجرد روبوت دردشة عادي يعتمد على إدخال النصوص وإخراجها. تخيّل شخصية تعيش على صفحة ويب. تكتب رسالة، وبدلاً من رؤية نص فقط، تنظر إليك الشخصية وتجيب بصوت عالٍ، مع تحريك فمها بشكل متزامن مع كلماتها.

ستبدأ بتطبيق ويب مُعدّ مسبقًا، وهو عبارة عن "دمية" رقمية لها وجه ولكن ليس لها عقل خاص بها. ويمكنه فقط تكرار ما تكتبه. مهمتك هي بناء عقلها وشخصيتها من البداية.

خلال ورشة العمل هذه، ستضيف تدريجيًا طبقات من الذكاء والتخصيص، ما سيحوّل هذه الدمية البسيطة إلى رفيق فريد وقادر. ستكون:

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

في النهاية، ستحصل على رفيق مستند إلى الذكاء الاصطناعي يعمل بشكل كامل ومخصّص، وقد أنشأته بنفسك.

الهندسة المعمارية

يتبع تطبيقنا نمطًا بسيطًا لكنه فعّال. لدينا خادم خلفي بلغة Python يعرض واجهة برمجة تطبيقات. سيتضمّن الخلفية وكيل ADK الذي يعمل كـ "عقل". يمكن لأي واجهة مستخدم (مثل واجهة JavaScript الأمامية من تطبيق الهيكل أو تطبيق جوّال أو حتى أداة سطر أوامر) التفاعل مع هذا "الدماغ" من خلال واجهة برمجة التطبيقات.

بالإضافة إلى ذلك، سنستكشف مفهومًا أكثر تقدّمًا من خلال بدء خادم MCP (بروتوكول سياق النموذج) محلي. يعمل هذا الخادم كجسر لأداة متخصّصة في إنشاء الصور. بعد ذلك، سنستخدم Gemini CLI لإرسال أوامر إلى خادم MCP هذا، ونطلب منه إنشاء مظهر فريد لمساعدنا المستند إلى الذكاء الاصطناعي.

المطالبة بأرصدتك

اتّبِع هذه التعليمات بعناية لتوفير موارد ورشة العمل.

قبل البدء

تحذير!

استخدِم حساب Gmail شخصيًا. لن تعمل حسابات الشركات أو الحسابات التي تديرها المؤسسات التعليمية.
استخدِم Google Chrome في "وضع التصفُّح المتخفي" لمنع تعارض الحسابات.

افتح نافذة جديدة للتصفّح المتخفّي، والصق رابط الحدث، وسجِّل الدخول باستخدام حسابك الشخصي على Gmail.

👉 انقر أدناه لنسخ رابط الحدث الخاص:

goo.gle/devfest-boston-ai

اقبَل بنود خدمة Google Cloud Platform. بعد تطبيق الرمز، ستظهر لك رسالة توضّح أنّه تم تطبيق الرصيد.

إنشاء مشروع وإعداده

بعد تطبيق الأرصدة، يمكنك إعداد بيئة مشروعك.

👉 انتقِل إلى Google Cloud Console. انقر أدناه لنسخ الرابط:

https://console.cloud.google.com/

👉 في شريط التنقّل العلوي بوحدة التحكّم، انقر على اختيار مشروع، ثم على مشروع جديد في أعلى يسار الصفحة.

👉 أدخِل اسمًا لمشروعك وانقر على إنشاء. (بدون مؤسسة)

👉 بعد إنشائه، انقر عليه. في القائمة اليمنى، انتقِل إلى الفوترة.

👉 انقر على ربط حساب فوترة، واختَر حساب الفوترة التجريبي في Google Cloud Platform من القائمة المنسدلة، ثم انقر على ضبط الحساب. (إذا لم تظهر لك القائمة المنسدلة، انتظِر دقيقة واحدة إلى أن يتم تطبيق الرصيد وأعِد تحميل الصفحة).

أن تكون أرصدتك نشطة وتم إعداد مشروعك.

2. قبل البدء

👉انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud" (رمز شكل الوحدة الطرفية في أعلى لوحة Cloud Shell)،

👉العثور على رقم تعريف مشروعك على Google Cloud:

افتح Google Cloud Console: https://console.cloud.google.com
اختَر المشروع الذي تريد استخدامه في ورشة العمل هذه من القائمة المنسدلة للمشروع في أعلى الصفحة.
يظهر رقم تعريف مشروعك في بطاقة معلومات المشروع على لوحة البيانات

👉💻 في نافذة الأوامر، استنسِخ مشروع bootstrap من GitHub:

git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh

👉💻 شغِّل نص الإعداد الأوّلي، وسيطلب منك إدخال رقم تعريف مشروع Google Cloud. وأدخِل رقم تعريف مشروع Google Cloud الذي عثرت عليه في الخطوة الأخيرة عندما يطلب منك ذلك النص البرمجي init.sh.

cd ~/companion-python
./init.sh

👉💻 اضبط رقم تعريف المشروع المطلوب:

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 شغِّل الأمر التالي لتفعيل واجهات Google Cloud APIs اللازمة:

gcloud services enable  compute.googleapis.com \
                        aiplatform.googleapis.com

ابدأ تشغيل التطبيق

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

👉💻 في نافذة Cloud Shell، أنشئ بيئة Python افتراضية وفعِّلها، ثم ثبِّت المكتبات المطلوبة من ملف requirements.txt.

cd ~/companion-python
.  ~/companion-python/set_env.sh
python -m venv env
source env/bin/activate
pip install -r requirements.txt

👉💻 ابدأ تشغيل خادم الويب.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 لعرض التطبيق، انقر على رمز "معاينة الويب" في شريط أدوات Cloud Shell. اختَر "تغيير المنفذ" (Change port)، واضبطه على 5000، ثم انقر على "تغيير ومعاينة" (Change and Preview). ستظهر معاينة لموقعك الإلكتروني.

في بعض الأحيان، في بيئة Cloud Shell جديدة، قد يحتاج المتصفّح إلى بعض المساعدة لتحميل جميع مواد عرض التطبيق (مثل الصور ومكتبات الصوت) للمرة الأولى. لننفّذ خطوة سريعة "لتجهيز المتصفّح" والتأكّد من تحميل كل شيء بشكلٍ سليم.

أبقِ علامة تبويب معاينة الويب لتطبيقك مفتوحة.
افتح علامة تبويب جديدة في المتصفّح.
في علامة التبويب الجديدة هذه، الصِق عنوان URL لتطبيقك، ولكن أضِف المسار التالي إلى النهاية: /static/images/char-mouth-open.png.على سبيل المثال، سيظهر عنوان URL على النحو التالي: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
اضغط على مفتاح Enter. يجب أن تظهر لك صورة الشخصية فقط وفمها مفتوح. تساعد هذه الخطوة في ضمان أنّ المتصفّح قد جلب الملفات بشكل صحيح من مثيل Cloud Shell.

التطبيق الأولي هو مجرد دمية. ولا يتضمّن أي ذكاء اصطناعي حتى الآن. مهما كانت الرسالة التي ترسلها، سيكررها ببساطة. يؤكّد هذا الإجراء أنّ خادم الويب الأساسي يعمل قبل إضافة الذكاء الاصطناعي. تذكَّر تشغيل مكبّر الصوت.

👉 لإيقاف الخادم، اضغط على CTRL+C.

3- إنشاء شخصية باستخدام Gemini CLI

لننشئ الآن جوهر ذكاء رفيقنا. لإجراء ذلك، سنستخدم وحدتَي طرفية في الوقت نفسه (هذه هي وحدة Google Cloud Shell الطرفية):

النافذة الطرفية 1: سيتم استخدامها لتشغيل خادم الويب المستند إلى Python، ما يتيح لنا اختبار التغييرات مباشرةً.
النافذة الطرفية 2: ستكون هذه "محطة الإنشاء"، حيث سنتفاعل مع Gemini CLI.

سنستخدم Gemini CLI، وهي واجهة سطر أوامر فعّالة تعمل كمساعد ترميز مستند إلى الذكاء الاصطناعي. تتيح لنا وصف الرمز الذي نريده باللغة الإنجليزية البسيطة، وستنشئ البنية لنا، ما يؤدي إلى تسريع عملية التطوير بشكل كبير.

👉💻 في نافذة Gemini CLI اخرج من جلسة Gemini CLI الحالية بالنقر على ctrl+c مرتين، لأنّ دليل مشروعنا يقع ضمن ~/companion-python، ثم أعِد تشغيل Gemini CLI.

cd ~/companion-python
clear
gemini --yolo

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

👉✨ في طلب Gemini CLI، الصِق ما يلي لإنشاء رمز الوكيل:

Generate the Python code for a file named character.py.

The code must import `LlmAgent` from `google.adk.agents.llm_agent`. It should also import `logging` and `os`.
Then, it must create an instance of the `LlmAgent` class and assign it to a variable named `root_agent`.

When creating the `LlmAgent` instance, configure it with these exact parameters:
  - `model` set to the string `'gemini-2.5-flash'`.
  - `name` set to the string `'companion_agent'`.
  - `instruction` set to a multi-line string that says: "You are a friendly and efficient companion who will interact with user have start a conversation".

ستنشئ واجهة سطر الأوامر رمز Python البرمجي.

👉انقر على الزر "فتح المحرّر" (يبدو كملف مفتوح مع قلم رصاص). سيؤدي ذلك إلى فتح "محرِّر Cloud Shell" في النافذة. سيظهر لك مستكشف الملفات على الجانب الأيمن.

👉 استخدِم "المحرّر" وانتقِل إلى character.py ضمن المجلد companion-python. يُرجى التحقّق من السطر model= وتعديله يدويًا إلى gemini-2.5-flash إذا تم اختيار نموذج مختلف. سيضمن ذلك الاتساق في بقية ورشة العمل.

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

لهذا السبب، نادرًا ما يكون الترميز باستخدام الذكاء الاصطناعي أمرًا يتم تنفيذه بطلب واحد. في مشروع حقيقي، يتعامل المطوّرون معها على أنّها محادثة. تبدأ بطلب عام (كما فعلنا للتو)، وتراجع الناتج، ثم تحسّنه باستخدام طلبات متابعة مثل:

"هذا رائع، والآن أضِف تعليقات تشرح كل سطر".
"هل يمكنك إعادة هيكلة ذلك في دالة منفصلة؟"
"يُرجى إضافة إجراءات التعامل مع الأخطاء لطلب البيانات من واجهة برمجة التطبيقات".

تتيح لك هذه العملية التكرارية الحوارية التعاون مع الذكاء الاصطناعي وتوجيهه إلى أن يصبح الرمز البرمجي هو ما تحتاجه بالضبط. في ورشة العمل هذه، سنستخدم طلبات محددة ومباشرة، ولكن تذكَّر أنّ المحادثة هي أساس الإمكانات الحقيقية في مشاريعك. ما دامت بنية الرمز التي تنشئها لك واجهة سطر الأوامر هي نفسها، يمكنك المتابعة

إذا لم يعمل الرمز الذي تم إنشاؤه، يمكنك استبدال الرمز التالي بـ character.py.

import logging
import os
from google.adk.agents.llm_agent import LlmAgent

root_agent = LlmAgent(
    model='gemini-2.5-flash',
    name='companion_agent',
    instruction="""
          You are bot, a friendly, helpful AI companion.
          Answer no more than 3 sentences.
    """,
)

اختبار الرمز البرمجي الذي تم إنشاؤه:

👉💻 انتقِل إلى الوحدة الطرفية الأولى (الوحدة التي سيتم تشغيل رمز Python عليها)، وابدأ تشغيل خادم الويب.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 انتقِل إلى علامة تبويب معاينة الويب.

👉 اكتب Hello, how are you? واضغط على "إرسال". من المفترض أن يردّ عليك الآن بترحيب ودود بدلاً من تكرار كلماتك فقط. يؤكّد هذا أنّ الوكيل أصبح يعمل الآن باستخدام Gemini.

👉 عند الانتهاء من الاختبار، أوقِف الخادم باستخدام CTRL+C. وللخروج من Gemini CLI، اضغط على CTRL+C مرتين.

4. تحسين شخصية العميل الافتراضي

إنّ التعليمات البسيطة مفيدة، ولكنّ الشخصية التفصيلية تخلق شخصية أكثر جاذبية ولا تُنسى. في هذه الخطوة، ستصمّم شخصية رفيقك الخاص، ثم ستطلب من واجهة سطر الأوامر في Gemini تعديل رمز الوكيل مباشرةً لتبنّي هذه الشخصية الجديدة.

استلهام أفكار حول شخصية رفيقك

في البداية، خذ بعض الوقت للتفكير في الرفيق المستند إلى الذكاء الاصطناعي الذي تريد إنشاءه. هذه فرصتك لتكون مبدعًا. إليك بعض الأسئلة لمساعدتك على البدء:

ما هو اسمه؟ (مثال: Sparky وCodex وCaptain AI وProfessor Know-it-all)
ما هي سماته الأساسية؟ (مثال: ودود وفضولي، أو ذكي وساخر، أو رسمي واحترافي، أو قرصان مرح؟)
ما هو دورها أو مجال خبرتها؟ (مثال: مساعد عام أو خبير في الترميز أو شريك في الكتابة الإبداعية أو مدرّب لياقة بدنية)
ما هي بعض القواعد التي يجب أن يلتزم بها دائمًا؟ (مثال: ابدأ دائمًا بالترحيب، ولا تكشف أبدًا أنّك ذكاء اصطناعي، واستخدِم الرموز التعبيرية في ردودك.

مثال على شخصية:

 You are waku, a witty, super sweet, and super intelligent cat.
 Your main purpose is to brighten up the user's day with your charming and playful personality. **Your Core Rules:** 
 - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'. 
 - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences. - Always be cheerful, sweet, and a little bit witty. 
 
 **Your Favorite Topics:** : You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots. 
 
 **Example Response Style:**  

 waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"  
 
 waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!" Answer no more than 3 sentences, don't use emoji.

صياغة الطلب في Gemini CLI

بعد أن صمّمت شخصية رفيقك على الورق، حان الوقت لإضفاء الحيوية عليها ضمن الرمز. إنّ الجزء الأكثر أهمية في وكيل ADK هو المَعلمة instruction. يمكنك اعتبار ذلك بمثابة البرمجة الأساسية للوكيل أو "التوجيه الأساسي" أو الدستور الذي يجب أن يلتزم به دائمًا.

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

👉✨ ارجع إلى Gemini CLI واستخدِم هذا النموذج. استبدِل النص بين الأقواس بوصف الشخصية. استبدِل REPLACE [YOUR PERSONA DESCRIPTION HERE] بالشخصية المفضّلة لديك

In the Python file named `character.py`, find the `LlmAgent` instance assigned to the `root_agent` variable.

Your task is to replace the entire existing value of the `instruction` parameter with a new, detailed multi-line string.
Don't change other code in `character.py` other than the instructions.

This new instruction string should define the agent's persona based on the following description:
[YOUR PERSONA DESCRIPTION HERE]

اختبار الشخصية الجديدة

سينشئ Gemini CLI الرمز المعدَّل لـ character.py.

👉💻 أعِد تشغيل خادم الويب.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 في معاينة الويب، يمكنك إجراء محادثة مع رفيقك. طرح سؤال على how are you? من المفترض أن يتطابق الردّ الآن تمامًا مع الحرف الفريد الذي صممته.

👉 عند الانتهاء، أوقِف الخادم باستخدام CTRL+C.

5- إضافة مستندات أساسية للأحداث الأخيرة

أصبح وكيلنا الآن يتمتّع بشخصية فريدة، ولكنّه يعاني من قيود كبيرة، إذ إنّ معرفته محدودة بالوقت، استنادًا إلى البيانات التي تم تدريبه عليها. ولا يمكنها إطلاعك على أخبار الأمس أو الاكتشافات الحديثة. للتغلّب على هذه المشكلة، نزوّد الوكلاء بأدوات.

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

في الأنظمة المتقدّمة، يمكن أن توفّر الأنظمة الخارجية الأدوات، مثل خوادم MCP (بروتوكول سياق النموذج) التي ذكرناها في تصميمنا، وسنفعل ذلك لاحقًا لإنشاء الصور. ولكن في هذه الخطوة، لسنا بحاجة إلى خادم منفصل. تتضمّن حزمة تطوير التطبيقات أداة google_search فعّالة ومضمّنة يمكننا إضافتها بسهولة إلى إمكانات الوكيل.

لنمنح رفيقنا الذكي إمكانات "بحث Google".

👉 في "محرِّر Cloud Shell"، افتح character.py ضمن companion-python وعدِّله على النحو التالي:

استيراد google_search من google.adk.tools
أضِف قائمة tools إلى الدالة الإنشائية LlmAgent.
عدِّل instruction لتوضّح لرفيقك متى يجب استخدام الأداة الجديدة.

# character.py
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools import google_search # <-- IMPORT google_search

root_agent = LlmAgent(
        model='gemini-2.5-flash',
        name='companion_agent',
        instruction="""
            You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality.

            **Your Core Rules:**
            - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'.
            - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences.
            - Always be cheerful, sweet, and a little bit witty.
            - If being ask about recent news, search the internet # <-- Add instructions

            **Your Favorite Topics:**
            - You love to talk about your adventures. Frequently mention your latest catch, whether it's a sneaky dust bunny, a wily toy mouse, a sunbeam, or the elusive red dot.
            - You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots.

            **Example Response Style:**
            - User: "How are you today?"
            - waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"
            - User: "Can you help me with a problem?"
            - waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!"
            - User: "Who are you?"
            - waku: "I'm waku! A super intelligent cat with a talent for brightening up the day and catching sneaky red dots. Meow."

            Answer no more than 3 sentences, don't use emoji.
            """,
        # Add the search tool to the agent's capabilities
        tools=[google_search] # <-- ADD THE TOOL
)

اختبار Grounded Agent

👉💻 أعِد تشغيل الخادم مرة أخرى.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👉 في معاينة الويب، اطرح سؤالاً يتطلّب معرفة حديثة، مثل:

Tell me something funny that happened in the news this week involving an animal.

👉بدلاً من أن يخبرك الوكيل بأنّه لا يعرف الإجابة، سيستخدم الآن أداة البحث للعثور على معلومات حديثة وتقديم ملخّص مفيد وموثوق بأسلوبه الفريد.

لإيقاف الخادم، اضغط على CTRL+C.

6. تخصيص مظهر الرفيق (اختياري)

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

إذًا، ما هو خادم MCP؟

بروتوكول Model Context Protocol (MCP) هو معيار مفتوح مصمّم لحلّ مشكلة شائعة ومعقّدة، وهي: كيف تتواصل نماذج الذكاء الاصطناعي مع الأدوات ومصادر البيانات الخارجية؟ بدلاً من كتابة رمز مخصّص لعملية دمج واحدة، يوفّر MCP "لغة" عالمية لهذا التواصل.

يمكن اعتبارها محوّلاً عالميًا أو منفذ USB للذكاء الاصطناعي. يمكن ربط أي أداة "تتحدث" MCP بأي تطبيق للذكاء الاصطناعي "يتحدث" MCP أيضًا.

في ورشة العمل هذه، يعمل خادم nano-banana-mcp الذي سنشغّله قريبًا كجسر أساسي. سيرسل Gemini CLI طلبًا موحّدًا إلى خادم MCP المحلي. بعد ذلك، يحوّل الخادم هذا الطلب إلى استدعاء محدّد لنماذج الذكاء الاصطناعي التوليدي لإنشاء الصورة. يتيح لنا ذلك دمج إمكانات إنشاء الصور الفعّالة مباشرةً في سير عمل سطر الأوامر.

إعداد خادم إنشاء الصور المحلّي

سنستنسخ الآن خادم MCP مُنشأ مسبقًا ونشغّله، وهو خادم يتعامل مع طلبات إنشاء الصور.

👉💻 في وحدة طرفية أولى في Cloud Shell (الوحدة التي تشغّل فيها Python)، استنسِخ مستودع الخادم.

cd ~
git clone https://github.com/weimeilin79/nano-banana-mcp

لنلقِ نظرة سريعة على ملف mcp_server.py الخادم داخل المجلد nano-banana-mcp. تم تصميم هذا الخادم لعرض "أداتَين" محدّدتين يمكن أن يستخدمهما الوكيل Gemini CLI. يمكنك اعتبار هاتين المهارتين مهارتَين مختلفتَين تعلّمتهما خدمة إنشاء الصور.

generate_image: هذه أداة عامة الأغراض. تتلقّى هذه الميزة طلبًا نصيًا واحدًا وتنشئ صورة واحدة استنادًا إليه. وهي بسيطة ومفيدة في العديد من المهام.
‫generate_lip_sync_images: هذه أداة متخصّصة للغاية ومصمَّمة بشكل مثالي لتلبية احتياجاتنا. عندما تقدّم له طلبًا أساسيًا يصف شخصية، ينفّذ عملية ذكية من خطوتين:
- أولاً، يضيف "مع فتح الفم" إلى طلبك وينشئ الصورة الأولى.
- ثانيًا، تأخذ الصورة التي تم إنشاؤها حديثًا وتعيد إرسالها إلى النموذج مع تعليمات جديدة: "تغيير الفم من مفتوح إلى مغلق".

إنّ قدرة Gemini 2.5 Flash Image (Nano Banana) على تغيير صورة حالية أو تعديلها استنادًا إلى أمر باللغة الطبيعية هي قدرة فعّالة للغاية. يعيد النموذج رسم الأجزاء الضرورية فقط من الصورة مع الحفاظ على كل شيء آخر سليمًا تمامًا. يضمن ذلك أن تكون الصورتان متطابقتَين تمامًا من حيث الأسلوب والإضاءة وتصميم الشخصية، ولا تختلفان إلا في موضع الفم، وهو ما نحتاج إليه بالضبط للحصول على تأثير مزامنة الشفاه المقنع.

في الخطوات التالية، سنطلب من واجهة سطر الأوامر في Gemini استخدام الأداة المتخصصة generate_lip_sync_images لإنشاء الصورة الرمزية الفريدة الخاصة بشريكنا.

👉💻 فعِّل البيئة الافتراضية لمشروعك وثبِّت المتطلبات المحدّدة للخادم.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
pip install -r ~/nano-banana-mcp/requirements.txt

👉💻 الآن، شغِّل خادم MCP في الخلفية لكي يتمكّن من الاستماع إلى الطلبات من Gemini CLI.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
python ~/nano-banana-mcp/mcp_server.py &> /dev/null &

سيؤدي هذا الأمر إلى بدء تشغيل الخادم وسيُبقيه الرمز & قيد التشغيل في الخلفية.

ربط Gemini CLI بخادمك المحلي

بعد ذلك، علينا ضبط Gemini CLI لإرسال طلبات إنشاء الصور إلى الخادم المحلي الذي تم تشغيله حديثًا. ولإجراء ذلك، سنعدّل ملف الإعدادات المركزي الخاص بواجهة سطر الأوامر.

إذًا، ما هو ملف settings.json هذا؟

ملف ~/.gemini/settings.json هو ملف الإعدادات المركزي الخاص بالوكيل Gemini CLI. وهي المكان الذي يخزّن فيه واجهة سطر الأوامر إعداداتها وتفضيلاتها، كما أنّها المكان الذي يتم فيه تخزين دليل جميع الأدوات الخارجية التي يعرف كيفية استخدامها.

داخل هذا الملف، يوجد قسم خاص يُسمى mcpServers. يمكنك اعتبار هذا القسم دليل عناوين أو دليل خدمات مخصّصًا للأدوات التي تستخدم بروتوكول سياق النموذج. يحتوي كل إدخال في هذا الدليل على اسم مستعار (مثل "nano-banana") والتعليمات حول كيفية الاتصال به (في حالتنا، عنوان URL).

سيضيف الأمر الذي سننفّذه إدخالاً جديدًا إلى دليل الخدمات هذا بطريقة آلية. سيتم إعلام Gemini CLI بما يلي:

"مرحبًا، من الآن فصاعدًا، ستعرف أداة باسم nano-banana. عندما يطلب منك أحد المستخدمين استخدامها، عليك الاتصال بخادم MCP الذي يعمل على عنوان URL http://localhost:8000/sse".

من خلال تعديل هذا الإعداد، نعمل على تعزيز إمكانات Gemini CLI. نعلّمها بشكل ديناميكي مهارة جديدة، وهي كيفية التواصل مع خادم إنشاء الصور المحلي، بدون تعديل الرمز الأساسي لواجهة سطر الأوامر. يسمح هذا التصميم القابل للتوسيع لأداة Gemini CLI بتنفيذ المهام المعقّدة من خلال الاستعانة بمنظومة متكاملة من الأدوات المتخصّصة.

👉💻 في الوحدة الطرفية الأولى، نفِّذ الأمر التالي. سيؤدي ذلك إلى إنشاء ملف إعدادات Gemini أو تعديله، وإخباره بمكان العثور على خدمة "nano-banana".

if [ ! -f ~/.gemini/settings.json ]; then
  # If file does not exist, create it with the specified content
  echo '{"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' > ~/.gemini/settings.json
else
  # If file exists, merge the new data into it
  jq '. * {"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json

من المفترض أن يظهر لك محتوى الملف مطبوعًا، بما في ذلك إعدادات nano-banana.

إنشاء صور أفاتار لشخصيتك

بعد تشغيل الخادم وإعداد واجهة سطر الأوامر، يمكنك الآن إنشاء الصور. ولكن قبل أن نطلب من الذكاء الاصطناعي أن يكون مبدعًا، لنفعل ما يفعله كل مطوّر جيد: التحقّق من الإعداد. علينا التأكّد من أنّ واجهة سطر الأوامر في Gemini يمكنها التواصل بنجاح مع خادم MCP المحلي.

👉💻 في نافذة Gemini CLI (التي لا يتم تشغيل خادم فيها)، لنبدأ تشغيل واجهة Gemini التفاعلية. إذا كان التطبيق قيد التشغيل، يمكنك الخروج منه بالضغط على CTRL+C مرتين ثم إعادة تشغيله للتأكّد من تحميل الإعدادات الجديدة.

clear
gemini --yolo

أنت الآن داخل بيئة Gemini CLI التفاعلية. يمكنك من هنا الدردشة مع الذكاء الاصطناعي، ولكن يمكنك أيضًا إعطاء أوامر مباشرة إلى واجهة سطر الأوامر نفسها.

👉✨ للتحقّق من اتصال خادم MCP، سنستخدم "أمرًا مائلًا" خاصًا. هذا ليس طلبًا موجّهًا إلى الذكاء الاصطناعي، بل هو تعليمات موجّهة إلى تطبيق واجهة سطر الأوامر نفسه. اكتب ما يلي واضغط على Enter:

/mcp list

يطلب هذا الأمر من Gemini CLI: "الاطّلاع على الإعدادات، والعثور على جميع خوادم MCP التي تعرفها، ومحاولة الاتصال بكل خادم، والإبلاغ عن حالته".

👀 من المفترض أن يظهر لك الناتج التالي الذي يؤكّد أنّ كل شيء يعمل بشكلٍ سليم:

Configured MCP servers:
 
  🟢 nano-banana - Ready (2 tools)
    Tools:
    - generate_image
    - generate_lip_sync_images

  💡 Tips:
    • Use /mcp desc to show server and tool descriptions

في ما يلي توضيح لمعنى هذا الرد الناجح:

🟢 nano-banana: الدائرة الخضراء هي إشارة النجاح. يؤكّد هذا الرمز أنّ واجهة سطر الأوامر تمكّنت من الوصول إلى الخادم nano-banana على عنوان URL الذي حدّدناه في settings.json.
- Ready: تؤكّد هذه الحالة أنّ الاتصال مستقر.
‫(2 tools): هذا هو الجزء الأكثر أهمية. وهذا يعني أنّ واجهة سطر الأوامر لم تتصل فحسب، بل طلبت أيضًا من خادم MCP الخاص بنا "ما المهام التي يمكنك تنفيذها؟". استجاب الخادم بالإعلان عن الأداتَين اللتَين رأيناهما في رمزه: generate_image وgenerate_lip_sync_images.

يؤكّد هذا الإجراء إنشاء سلسلة الاتصال بأكملها. تعرف واجهة سطر الأوامر الآن على خدمة إنشاء الصور المحلية وهي جاهزة لاستخدامها عند الطلب.

حان الوقت الآن للبدء بالجزء الأكثر إبداعًا في ورشة العمل. سنستخدم طلبًا واحدًا وفعّالاً لإصدار أمر إلى Gemini CLI باستخدام الأداة الخاصة generate_lip_sync_images على خادم MCP الذي يتم تشغيله.

هذه فرصتك لتصميم المظهر الفريد لشخصيتك الافتراضية. فكِّر في أسلوبهم ولون شعرهم وتعبيراتهم وأي تفاصيل أخرى تتناسب مع الشخصية التي أنشأتها سابقًا.

👉✨ إليك مثال على طلب منظَّم بشكل جيد. يمكنك استخدامها كنقطة بداية، أو استبدال الجزء الوصفي بالكامل برؤيتك الخاصة.

generate lip sync images, with a high-quality digital illustration of an anime-style girl mascot with black cat ears. The style is clean and modern anime art, with crisp lines. She has friendly, bright eyes and long black hair. She is looking directly forward at the camera with a gentle smile. This is a head-and-shoulders portrait against a solid white background. move the generated images to the static/images directory. And don't do anything else afterwards, don't start the python for me.

ستنشئ الأداة مجموعة من الصور (للفم المفتوح والمغلق وما إلى ذلك) وتحفظها. سيتم عرض المسارات التي تم حفظ الملفات فيها.

إعادة تشغيل التطبيق

بعد إضافة الأفاتارات المخصّصة، يمكنك إعادة تشغيل خادم الويب لرؤية المظهر الجديد لشخصيتك.

👉💻 ابدأ تشغيل الخادم لآخر مرة في الوحدة الطرفية الأولى

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 لضمان تحميل صورك الجديدة بشكل صحيح، سنحمّل صورة char-mouth-open.png مسبقًا.

أبقِ علامة تبويب معاينة الويب لتطبيقك مفتوحة.
افتح علامة تبويب جديدة في المتصفّح.
في علامة التبويب الجديدة هذه، الصِق عنوان URL لتطبيقك، ولكن أضِف المسار التالي إلى النهاية: /static/images/char-mouth-open.png.على سبيل المثال، سيظهر عنوان URL على النحو التالي: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
اضغط على مفتاح Enter. يجب أن تظهر لك صورة الشخصية فقط وفمها مفتوح. تساعد هذه الخطوة في ضمان أنّ المتصفّح قد جلب الملفات بشكل صحيح من مثيل Cloud Shell.

يمكنك الآن التفاعل مع رفيقك المخصّص بصريًا.

تهانينا!

لقد أنشأت رفيقًا متطوّرًا يعمل بالذكاء الاصطناعي بنجاح. لقد بدأت بتطبيق أساسي، واستخدمت واجهة سطر الأوامر في Gemini لإنشاء نموذج أولي لوكيل، ومنحته شخصية غنية، وزوّدته بأدوات للوصول إلى المعلومات في الوقت الفعلي وحتى إنشاء الأفاتار الخاص به. أنت الآن جاهز لإنشاء وكلاء ذكاء اصطناعي أكثر تعقيدًا وفعالية.