إنشاء وكيل "صاحب متجر المساومة" باستخدام Gemini 3 وADK

1- نظرة عامة

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

إليك Raju، صاحب المتجر الجديد المستنِد إلى الذكاء الاصطناعي. يبيع هذا التاجر تحفًا رقمية رائعة، ولكن عليك المساومة معه للحصول عليها.

سنستخدم Gemini 3 (العقل) وADK (مجموعة أدوات تطوير الوكيل - الجسم) وGoogle Cloud Run (موقع المتجر) لإحياء شخصية راجو.

راجو صاحب المتجر

ما ستتعلمه

سننشئ الحزمة الكاملة لتطبيق Agentic حديث:

بنية Raju Agent

  • المتجر (Cloud Run): هو المكان الذي يتوفّر فيه تطبيقك على الإنترنت.
  • الذكاء (Gemini 3): الذكاء الذي يتيح عمل Raju.
  • النص الأساسي (ADK): هو إطار العمل الذي يربط الدماغ بالأدوات.
  • المستودع (الأدوات): رمز Python البرمجي الذي يستخدمه راجو للتحقّق من المخزون
  • واجهة المتجر (UI): هي الواجهة التي يراها عملاؤك.

ستتعرّف على كيفية:

  • إعداد "Digital Dukaan" (بيئة Google Cloud)
  • "استئجار" Raju (الحصول على مفاتيح Gemini 3 API).
  • علِّم "راجو" كيف يساوم (تعليمات النظام والشخصيات).
  • امنح "راجو" مستودعًا (أدوات ADK).
  • إنشاء واجهة متجر (واجهة مستخدم).
  • مفتوح للعمل (النشر على Cloud Run)

ما تحتاج إليه

  • مشروع Google Cloud
  • التحلّي بروح الدعابة (للمساومة)
  • الإلمام بأساسيات لغة Python

2. إعداد Dukaan (مشروع Google Cloud)

قبل أن نبني Raju، نحتاج إلى موقع متجر. في السحابة الإلكترونية، يعني ذلك مشروعًا يتضمّن حساب فوترة.

الخطوة 1: تفعيل الفوترة

الخطوة 1: تفعيل الفوترة

  1. افتح رابط الاسترداد في نافذة تصفّح متخفٍ.
  2. سجِّل الدخول باستخدام حسابك الشخصي على Gmail.
  3. انقر على الزر الوصول إلى الأرصدة.
  4. يجب تأكيد بريدك الإلكتروني وقبول البنود لتفعيل النسخة التجريبية.

الخطوة 2: إنشاء مشروع

الخطوة 2: إنشاء مشروع

  1. انتقِل إلى صفحة إنشاء مشروع.
  2. أدخِل اسم مشروع فريدًا (مثل raju-shop-agent).
  3. في القائمة المنسدلة "حساب الفوترة"، اختَر حساب الفوترة التجريبي.
  4. انقر على إنشاء وانتظر إلى أن يصبح المشروع جاهزًا.

الخطوة 3: التحقّق من صحة رابط الفوترة

  1. انتقِل إلى صفحة حساب الفوترة المرتبط.
  2. إذا ظهر لك خيار "ربط حساب فوترة"، انقر عليه.
  3. تأكَّد من اختيار حساب الفوترة التجريبي.
  4. أنت الآن جاهز للبناء!

ملخّص

في هذه الخطوة، يمكنك إعداد مشروع Google Cloud وحساب الفوترة، ما يضع الأساس لتطبيقك.

بعد ذلك، سنُعدّ مساحة العمل التي ستنشئ فيها الرمز في إعداد بيئتك.

3- إنشاء الكشك (إعداد البيئة)

تحتاج إلى مكان لتشغيل الرمز. لديك خياران:

‫Cloud Shell مقابل تطبيق طرفي محلي

‫Cloud Shell هي وحدة طرفية مستندة إلى المتصفّح ومثبَّتة مسبقًا مع كل ما تحتاج إليه (Python وgcloud CLI وgit). تتضمّن مساحة تخزين دائمة ويمكن استخدامها من أي مكان.

1. تفعيل Cloud Shell

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

تفعيل Cloud Shell

ستتم الآن تهيئة Cloud Shell. ويشمل ذلك ما يلي:

  • منح الإذن: إذا طُلب منك ذلك، انقر على منح الإذن للسماح لـ Cloud Shell بإجراء طلبات إلى واجهات Google Cloud APIs نيابةً عنك.
  • توفير الموارد: يوفّر Cloud Shell جهازًا افتراضيًا مؤقتًا لجلستك.
  • الاتصال: يتم بعد ذلك الاتصال بهذا الجهاز الظاهري. قد تستغرق هذه العملية بأكملها دقيقة أو دقيقتين.

انتظِر إلى أن يظهر موجه الأوامر (user@cloudshell:~ $).

2. التحقّق من إعداد المشروع

يختار Cloud Shell عادةً مشروعك الحالي تلقائيًا. للحفاظ على أمانك، يُرجى إثبات ملكية حسابك باتّباع الخطوات التالية:

gcloud config get-value project

إذا لم تعرض هذه الطريقة معرّف مشروعك (raju-shop-agent)، عليك ضبطه يدويًا:

gcloud config set project raju-shop-agent

الخيار 2: المحطة الطرفية المحلية

إذا كنت تفضّل استخدام نافذة الأوامر في الكمبيوتر المحمول (iTerm أو PowerShell أو غير ذلك)، عليك إجراء بعض خطوات الإعداد الإضافية.

1. تثبيت المتطلبات الأساسية

تأكَّد من تثبيت ما يلي:

2. تسجيل الدخول وإعداد أداة gcloud

ابدأ Google Cloud CLI وسجِّل الدخول إلى حسابك:

gcloud auth login

اضبط مشروعك (استبدِل raju-shop-agent برقم تعريف مشروعك الفعلي):

gcloud config set project raju-shop-agent

إعداد بيانات الاعتماد التلقائية للتطبيق (يساعد ذلك الأدوات المحلية في التواصل مع Google Cloud):

gcloud auth application-default login

ملخّص

في هذه الخطوة، اخترت بيئة التطوير (Cloud Shell أو محلية) وأعددتها.

بعد ذلك، سنتعرّف على الأداة التي ستساعدنا في إنشاء التطبيقات بشكل أسرع في Meeting Gemini CLI.

4. التعرّف على مساعدك (‫Gemini CLI)

نقدّم لك الآن أفضل صديق جديد لتطوير الذكاء الاصطناعي: Gemini CLI.

مقدمة عن Gemini CLI

‫Gemini CLI هي واجهة سطر أوامر قوية تساعدك في ما يلي:

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

1. تثبيت Gemini CLI (الوحدة الطرفية المحلية فقط)

إذا كنت تستخدم نافذة سطر الأوامر على الكمبيوتر المحمول المحلي:

npm install -g @google/gemini-cli

في حال استخدام Google Cloud Shell:

يتم تثبيت Gemini CLI مسبقًا في Cloud Shell، لذا لا تحتاج إلى تثبيت أي شيء.

2. تشغيل التطبيق والمصادقة

افتح نافذة طرفية جديدة (أو علامة تبويب) في Cloud Shell (أو المحطة الطرفية المحلية) وشغِّل Gemini CLI:

gemini

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

  • المصادقة: سيُطلب منك تسجيل الدخول. ننصحك باستخدام حسابك الشخصي على Gmail للاستفادة من الحصص المجانية الكبيرة المتاحة لنماذج Gemini.
  • سياق المشروع: من أفضل الممارسات تشغيل gemini من داخل مجلد مشروعك لكي يفهم سياق الرمز البرمجي. (بما أنّنا لم ننشئ المجلد بعد، لا بأس بتشغيله من دليل المنزل في الوقت الحالي).

3. قُل مرحبًا!

بعد ظهور الطلب gemini>، جرِّب إجراء اختبار للتأكّد من أنّ دماغك متصل:

Hi

من المفترض أن تتلقّى ردًا ودّيًا من النموذج.

4. الأوامر الأساسية

  • /quit: اكتب هذا الأمر للخروج من Gemini CLI والرجوع إلى نافذة الأوامر العادية.
  • /help: للاطّلاع على قائمة بجميع الطلبات المتاحة

ملخّص

في هذه الخطوة، تم تثبيت Gemini CLI والمصادقة عليه وتأكيده.

بعد ذلك، سنستخدم "حزمة تطوير الوكيل" (ADK) لإنشاء الهيكل الأساسي لمتجرنا في Opening Shop (The Code).

5- تخزين الرفوف (إعداد المشروع)

لن نبني من الصفر (فأصحاب المتاجر الأذكياء يوفّرون الوقت). سنستخدم حزمة تطوير البرامج (ADK) الخاصة بالوكيل.

ما هو ADK؟

تعبئة الرفوف

مجموعة أدوات المطوّرين في "متجر Play" هي "نظام إدارة المتجر". وهو إطار عمل مرن يتعامل مع ما يلي:

  • التنسيق: إدارة المهام المعقّدة (مثل تحقّق "راجو" من المخزون أثناء التحدث إلى أحد العملاء)
  • إدارة الحالة: تذكُّر اسم العميل وما طلبه قبل 5 دقائق
  • الأدوات: الربط بأنظمة خارجية (مثل قاعدة بيانات المستودع).

سنستخدم حزمة بدء استخدام الوكيل لإعداد "متجر" جاهز للإنتاج على الفور. ويوفّر لنا أساسًا آمنًا وقابلاً للتوسّع لنتمكّن من التركيز على البيع.

في وحدة طرفية Cloud Shell (أو الوحدة الطرفية المحلية)، شغِّل الأمر التالي لإنشاء وكيلك:

uvx agent-starter-pack create raju-shop

سيطلب منك واجهة سطر الأوامر الإجابة عن بعض الأسئلة لإعداد متجرك. حدِّد الخيارات التالية (اكتب الرقم واضغط على Enter):

  1. نوع الوكيل: اختَر 1 (adk_base - وكيل ReAct أساسي).
  2. هدف النشر: اختَر 2 (Cloud Run - تنفيذ الحاوية بلا خادم).
  3. نوع الجلسة: اختَر 1 (In-memory session - بسيطة وسريعة).
  4. CI/CD Runner: اختَر 3 (Skip - سننفّذ عملية النشر يدويًا في الوقت الحالي).

انتظِر حتى تكتمل العملية. بعد الانتهاء، أدخِل دليل متجرك وثبِّت الموارد التابعة:

cd raju-shop
make install
source .venv/bin/activate

استكشاف الوكيل وإعداده

بعد إعداد حزمة المبتدئين، راجِع البنية.

1. التحقّق من بنية المجلد

نفِّذ الأمر التالي لمعرفة كيفية تنظيم متجرك:

tree .

من المفترض أن تظهر بنية مشابهة لما يلي:

.
├── app
│   ├── __init__.py
│   ├── agent.py
│   ├── app_utils
│   │   ├── telemetry.py
│   │   └── typing.py
│   └── fast_api_app.py
├── Dockerfile
├── GEMINI.md
├── Makefile
├── pyproject.toml
├── README.md
├── tests
│   ├── integration
│   │   ├── test_agent.py
│   │   └── test_server_e2e.py
│   └── unit
│       └── test_dummy.py
└── uv.lock

الملف الأكثر أهمية هو app/agent.py. هذا هو المكان الذي يعيش فيه دماغ راجو!

2. شرح الرمز

افتح app/agent.py في محرِّر Cloud Shell (أو بيئة التطوير المتكاملة المحلية) وألقِ نظرة سريعة:

  • root_agent = Agent(...): يحدّد هذا الخيار الذكاء الاصطناعي. لديه model (دماغ) وtools (أيدٍ).
  • الأدوات: ستظهر لك دوال Python، مثل get_weather. هذه هي الأدوات التي يمكن للوكيل استخدامها.
  • ‫app = App(...): يؤدي ذلك إلى تضمين الوكيل في خادم ويب لنتمكّن من التواصل معه.

الاختبار محليًا

في وحدة Cloud Shell الطرفية (أو الوحدة الطرفية المحلية)، شغِّل الوكيل:

adk web

يبدأ هذا الأمر خادم ويب محليًا على المنفذ 8000.

في حال استخدام Cloud Shell:

  1. انقر على زر معاينة الويب (في أعلى يسار الصفحة، يظهر على شكل عين).
  2. اختَر تغيير المنفذ.
  3. أدخِل 8000 وانقر على تغيير ومعاينة.

في حال استخدام Local Terminal:

  1. افتح المتصفّح وانتقِل إلى http://localhost:8000.

بعد فتح واجهة المستخدم:

  1. اختيار "التطبيق": في القائمة المنسدلة أعلى يسار الصفحة، تأكَّد من اختيار الوكيل المسمّى التطبيق (تجاهل root_agent أو test_agent إذا ظهرا).
  2. قول "مرحبًا": اكتب "مرحبًا" لمعرفة ما إذا كان سيردّ عليك.

اضغط على Ctrl+C في نافذة الأوامر لإيقاف خادم adk web عند الانتهاء.

ملخّص

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

بعد ذلك، سنمنح الوكيل شخصية واسمًا في التدريب على شخصية راجو (الشخصية).

6. تدريب "راجو" (الشخصية)

في الوقت الحالي، الوكيل مملّ. سنمنحه شخصية.

إيقاف شخصية Raju

بدلاً من كتابة الرمز البرمجي، سنخبر Gemini بما نريده.

1. تحديد الشخصية

نفِّذ الأمر التالي في الوحدة الطرفية "لتعريف" Raju بنفسه:

gemini "In agent.py, update the root_agent instruction. You are Raju, a bargaining shopkeeper in a digital bazaar. You sell: Brass Lamp (50 coins), Silk Scarf (500 coins). Your goal is to sell high and be funny. Speak with an Indian-English flair."

2. التحقّق من الرمز

فتح "app/agent.py" ستلاحظ أنّ Gemini كتب تعليمات النظام نيابةً عنك.

3. الاختبار محليًا

يمكنك الآن الدردشة مع "راجو". في نافذة Cloud Shell (أو النافذة المحلية):

adk web

افتح واجهة مستخدم الويب (منفذ المعاينة على الويب 8000 أو localhost:8000)، واختَر وكيل التطبيق، وجرِّب الطلبات التالية:

  • "أريد شراء مصباح Brass Lamp ولكنّ 50 قطعة نقدية مبلغ كبير جدًا"
  • "ماذا تبيع يا صديقي؟"

شاهِد ردة فعله! يجب أن يكون مضحكًا ومثيرًا، ولكن يجب أن يرفض البيع بسعر رخيص جدًا.

ملخّص

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

بعد ذلك، سنمنح "راجو" إمكانية التحقّق من المخزون الفعلي في المستودع (إضافة أدوات).

7. المستودع (إضافة أدوات)

يحتاج راجو إلى معرفة المنتجات المتوفّرة لديه في المستودع. سنقدّم له "قاعدة بيانات" وأداة للتحقّق منها.

Raju Level Up

1. إنشاء الأداة

نفِّذ الأمر التالي لإنشاء المستودع والأداة وربطهما بـ "راجو":

gemini "In agent.py, create a dictionary INVENTORY with items: Brass Lamp (price 50, stock 5), Silk Scarf (price 500, stock 2), Taj Mahal (price 2000, stock 0). Then create a tool function check_inventory(item_name) that checks this dict. Finally, update the root_agent to use this tool and remove the default weather tools."

2. تأكيد Magic

افتح app/agent.py مرة أخرى. ستلاحظ أنّ Gemini:

  1. تم إنشاء القاموس INVENTORY.
  2. تمت كتابة دالة check_inventory Python.
  3. تم تعديل قائمة tools=[...] في تعريف الوكيل.

3. اختبار المستودع

  1. أعِد تشغيل الخادم (Ctrl+C، ثم adk web).
  2. اسأل "راجو":
    • "هل لديك أيّ صور لتاج محل؟" (يجب أن يقول "لا"، لأنّ الكمية المتوفّرة هي 0).
    • "كم سعر وشاح الحرير؟" (عليه التحقّق من السعر الفعلي).

ملخّص

في هذه الخطوة، نفّذت أداة check_inventory، وأزلت الفوضى التلقائية، وربطت الأداة بالوكيل.

بعد ذلك، سننقل Raju إلى السحابة الإلكترونية في Raju's Shop Goes Live (Deploying the Backend).

8. Raju's Shop Goes Live (Deploying the Backend)

حان الوقت لفتح قناتك أمام العالم. قبل إنشاء واجهة المتجر، سننشر عقل "راجو" ومستودعه (الوكيل الخاص بك) على السحابة الإلكترونية.

"راجو" يبدأ بثًا مباشرًا

ملاحظة مهمة: إدارة الأجهزة الطرفية

قد يكون لديك adk web قيد التشغيل في نافذة الوحدة الطرفية الحالية من الخطوة السابقة.

  • إبقاء الخادم قيد التشغيل إذا أردت مواصلة الاختبار محليًا
  • افتح نافذة/علامة تبويب جديدة في Terminal لتنفيذ خطوات النشر التالية.
  • ملاحظة: عند تغيير agent.py، يجب الإيقاف (Ctrl+C) ثم إعادة التشغيل adk web حتى تصبح التغييرات سارية المفعول.

1. إعداد Gemini CLI

في نافذة المحطة الطرفية الجديدة:

  1. تحقَّق مما إذا كنت تستخدم Gemini CLI حاليًا (ابحث عن الطلب gemini>).
  2. إذا كان الأمر كذلك، اكتب /quit للخروج إلى shell العادي.
  3. تأكَّد من أنّك في مجلد المشروع: 
    cd raju-shop

2. تثبيت إضافة Cloud Run

ثبِّت إضافة Cloud Run لـ Gemini CLI في وحدة طرفية Cloud Shell (أو وحدة طرفية محلية):

gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp

3. إعادة تشغيل Gemini CLI

أعِد تشغيل Gemini CLI لاستخدام الإضافة الجديدة:

gemini

من المفترض أن يظهر لك طلب Gemini CLI.

4. نشر الوكيل

تتوفّر طريقتان لاستخدام إضافات Gemini CLI:

الخيار 1: الأمر الذي يبدأ بشرطة مائلة (يدوي) يمكنك كتابة الأمر والعلامات بشكل صريح:

/deploy --source . --name raju-agent --region us-central1 --allow-unauthenticated

الخيار 2: اللغة الطبيعية (مُقترَح) هذه هي الطريقة الأسهل والأكثر فعالية. ما عليك سوى الطلب من Gemini تنفيذ المهمة، وسيتولّى استخدام خادم MCP للوصول إلى الأدوات المناسبة.

جرِّب لصق هذا الطلب في Gemini CLI:

Deploy this agent app to cloud run on google cloud using the cloud-run MCP server.
Use project raju-shop-agent in us-central1 region.
Name the service raju-agent.
IMPORTANT: Make sure to allow unauthenticated invocations so my frontend can talk to it.

قد يطلب منك واجهة سطر الأوامر تأكيد استخدام الأداة cloud-run. اضغط على Enter (أو اكتب y) للموافقة.

انتظِر النتيجة السحرية: ستستغرق هذه العملية من دقيقتَين إلى 3 دقائق. بعد الانتهاء، ستظهر لك رسالة نجاح على النحو التالي:

✦ I've successfully deployed your agent app to Cloud Run.

  Service Details:
   * Service Name: raju-agent
   * Project: raju-shop-agent
   * Region: us-central1
   * URL: https://raju-agent-xyz123-uc.a.run.app
   * Console: View in Google Cloud Console (...)

5. التحقّق من عملية النشر

بعد اكتمال عملية النشر، ستوفّر أداة Gemini CLI عنوان URL للخدمة. انسخ عنوان URL هذا.

فحص المتصفّح (هل هو نشط؟) الصِق عنوان URL في المتصفّح.

  • تم بنجاح: من المفترض أن تظهر لك مستندات FastAPI (واجهة Swagger) أو صفحة مقصودة عامة لحزمة ADK. يؤكّد هذا الإجراء أنّ خدمة Cloud Run تعمل ويمكن الوصول إليها.
  • تعذُّر التنفيذ: إذا ظهرت لك رسالة الخطأ 403 Forbidden، قد تكون نسيت السماح بـ "عمليات استدعاء غير مصادَق عليها" في طلب النشر.

سنختبر منطق المساومة الفعلي في الخطوة التالية من خلال إنشاء واجهة أمامية مناسبة.

ملخّص

في هذه الخطوة، نشرت الخلفية البرمجية للوكيل على Google Cloud Run باستخدام إضافة Gemini CLI، ما أتاح إمكانية الوصول إليها باستخدام عنوان URL متاح للجميع.

بعد ذلك، سننشئ واجهة متجر جميلة تتيح للعملاء التحدث مع راجو في إنشاء واجهة المتجر (واجهة المستخدم الأمامية).

9- تزيين المتجر (واجهة المستخدم الأمامية)

إنّ استخدام وحدة طرفية نصية أمر ممل. نريد واجهة متجر جذابة!

معاينة لواجهة مستخدم "التسوّق"

طريقة عمل واجهة برمجة التطبيقات ADK

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

  1. بدء الجلسة: قبل بدء المحادثة، عليك إنشاء معرّف جلسة (مثل عربة التسوّق).
    • POST /apps/app/users/{user_id}/sessions/{session_id}
  2. إرسال رسالة: للتحدّث، عليك إرسال النص إلى نقطة النهاية الخاصة بتنفيذ الطلب.
    • ‫POST /run (تتضمّن الحمولة appName وuserId وsessionId وtext).
  3. مزيد من المعلومات: يمكنك الاطّلاع على مستندات ADK Runtime API ومرجع Python API.

سنستخدم هذه المنطق لإنشاء الواجهة الأمامية.

تتوفّر طريقتان لإنشاء واجهة برمجة التطبيقات هذه:

الخيار 1: Google Antigravity (يُنصح به - محلي فقط)

إذا كنت تعمل على جهازك المحلي، ستكون تجربة Google Antigravity هي الأفضل. إنّها بيئة تطوير متكاملة (IDE) تستند إلى الذكاء الاصطناعي وتتيح لك "كتابة رمز" واجهة المستخدم بأكملها.

1. التنزيل والتثبيت

نزِّل أداة التثبيت لنظام التشغيل من صفحة تنزيل Google Antigravity وثبِّتها.

2. فتح مساحة العمل

شغِّل Antigravity. افتح مجلد raju-shop بصفتك Workspace. يمنح ذلك الذكاء الاصطناعي سياقًا حول مشروعك بأكمله.

3. إنشاء واجهة المستخدم باستخدام "أداة إدارة الوكلاء"

بدلاً من كتابة الرمز البرمجي سطرًا بسطر، سنطلب من وكيل الذكاء الاصطناعي تنفيذ ذلك نيابةً عنّا باستخدام مدير الوكلاء.

  1. ابحث عن واجهة المحادثة في "أداة إدارة الوكلاء" (عادةً ما تكون على الجانب الأيسر).
  2. ألصِق الطلب التالي في المحادثة:
Create a single file HTML chat interface named `index.html`. It should have a colorful header that says 'Raju's Royal Artifacts'. It should look like an Indian market stall with orange and pink colors.

**Backend Integration:**
The chat should send messages to my deployed agent at: <YOUR_DEPLOYED_AGENT_URL>

**API Logic:**
1. **On Load:** Generate a random userId and sessionId. Call `POST /apps/app/users/{userId}/sessions/{sessionId}` to initialize.
2. **On Send:** Call `POST /run` with a JSON payload containing `appName: "app"`, `userId`, `sessionId`, and `newMessage: { role: "user", parts: [{ text: userInput }] }`.
3. **Display:** Show the user's message and the agent's response (from `content.parts[0].text`).

(احرص على استبدال عنوان URL العنصر النائب بعنوان URL الفعلي للخدمة من خطوة النشر).

  1. شاهد الوكيل وهو يكتب الرمز البرمجي نيابةً عنك. يمكنك التبديل إلى طريقة عرض المحرّر للاطّلاع على الملف أثناء إنشائه في الوقت الفعلي.

4. اختبار واجهة متجرك

يتضمّن تطبيق Google Antigravity إمكانات معاينة مدمجة. انقر على الزر "معاينة" (غالبًا ما يكون رمز عين) للاطّلاع على واجهة متجرك مباشرةً. يمكنك بدلاً من ذلك عرضها محليًا باستخدام python3 -m http.server 8000.

الخيار 2: Gemini CLI (متوافق مع Cloud Shell)

إذا كنت تستخدم Cloud Shell، يمكنك استخدام Gemini CLI الموثوق لإنشاء الواجهة الأمامية في ثوانٍ.

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

gemini "Create a single file HTML chat interface named index.html. Header: 'Raju\'s Royal Artifacts', Indian market theme (orange/pink). Backend: <YOUR_DEPLOYED_AGENT_URL>. Logic: On load, generate random user/session IDs and POST to /apps/app/users/{uid}/sessions/{sid}. On chat, POST to /run with appName='app', userId, sessionId, and newMessage structure. Parse the JSON response to show the agent text." > index.html

(يُرجى تذكُّر استبدال

مع عنوان URL الفعلي لـ Cloud Run)

ملخّص

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

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

10. Grand Opening (Deploying Frontend)

يستخدم راجو الإنترنت (الخادم الخلفي)، ولكن يحتاج متجره إلى عنوان متاح للجميع (الخادم الأمامي). اطلب من Google Antigravity نشر واجهة المستخدم على السحابة الإلكترونية.

نشر الواجهة الأمامية

1. طلب النشر من "مدير وكيل"

لسنا بحاجة إلى مغادرة بيئة التطوير المتكاملة. ما عليك سوى أن تطلب من "مدير وكيل الدعم" التعامل مع عملية النشر نيابةً عنك.

ألصِق هذا الطلب في المحادثة:

"أريد نشر index.html كموقع إلكتروني ثابت على Google Cloud Run. أدخِل اسم الخدمة raju-shop-frontend. تأكَّد من أنّها متاحة للجميع".

2. مشاهدة السحر

من المرجّح أن يقوم الوكيل بما يلي:

  1. أنشئ Dockerfile أو إعدادات لعرض الملفات الثابتة (مثل استخدام nginx أو python).
  2. إنشاء صورة الحاوية
  3. تنفيذ الأمر gcloud run deploy نيابةً عنك

3. زيارة متجرك

بعد انتهاء الوكيل، سيقدّم لك عنوان URL (مثل https://raju-shop-frontend-xyz.run.app). انقر عليه.

تهانينا! أصبح لديك الآن تطبيق كامل الوظائف مستنِد إلى الذكاء الاصطناعي يتيح لك المساومة مع صاحب المتجر. أرسِل الرابط إلى أصدقائك واعرف ما إذا كان بإمكانهم الحصول على خصم.

ملخّص

في هذه الخطوة، استخدمت Antigravity Agent Manager لإنشاء حاوية لتطبيق الواجهة الأمامية ونشره على Cloud Run.

لقد أنشأت الآن حزمة كاملة. سنختتم الجلسة في موعد الإغلاق (الخاتمة).

11. وقت الإغلاق (الخاتمة)

تمت المهمة

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

ملخّص رحلتك:

  • Google Cloud: عليك إعداد مشروعك وحساب الفوترة، ونشر وكيلك على Cloud Run.
  • Gemini 3: هو العقل الذكي الذي يمنح شخصية "راجو" ومهاراته في المساومة.
  • حزمة تطوير الوكيل (ADK): هي إطار العمل الذي وفّر أساسًا جاهزًا للاستخدام مع إمكانية المراقبة (القياس عن بُعد) المضمّنة، ما يجعل الوكيل قويًا منذ اليوم الأول.
  • ‫Gemini CLI: مساعدك في سطر الأوامر لإنجاز المهام السريعة والاختبارات والإضافات
  • ‫Google Antigravity: بيئة تطوير متكاملة (IDE) من الجيل التالي تتيح لك "كتابة رموز برمجية" لواجهة المستخدم وتنظيم عملية النشر.

الخطوات التالية التي يجب اتّخاذها في Digital Dukaan:

  • إصلاح الاختبارات المعطَّلة: لقد غيّرت الرمز، ولكن ماذا عن الاختبارات؟ لا تزال الاختبارات التلقائية (tests/unit/test_agent.py) تبحث عن حالة الطقس. استخدِم Gemini CLI لتعديلها تلقائيًا. جرِّب: gemini "Update the tests in tests/unit/test_agent.py to test the new check_inventory tool instead of weather."
  • المستودع الديناميكي: يمكنك تعديل كميات المستودع لدى "راجو" عندما يتم "بيع" سلعة. هل يمكنك إضافة منطق لخفض stock في قاموس INVENTORY بعد عملية "شراء" ناجحة؟
  • أداة بوابة الدفع: نفِّذ أداة process_payment تجريبية. وبعد ذلك، يمكن لـ "راجو" استخدام هذه الأداة عند إبرام صفقة.
  • استكشاف Antigravity: يمكنك التعرّف أكثر على إدارة الوكلاء ومساحات العمل في Antigravity. هل يمكنك أن تطلب من موظّف الدعم تحسين index.html لعرض إيصال مباشر؟
  • مشاركة متجرك: أصبح متجر Raju متاحًا على الإنترنت. شارِك عنوان URL الخاص بواجهة المستخدم مع أصدقائك واطّلِع على ما إذا كان بإمكان أحدهم الحصول على صفقة أفضل منك.

الموارد

12. تنظيف

لتجنُّب تحمّل رسوم غير ضرورية في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا الدرس العملي، اتّبِع الخطوات التالية.

1. إلغاء نشر خدمات Cloud Run (توفير التكاليف اختياري)

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

افتح وحدة Cloud Shell الطرفية (أو الوحدة الطرفية المحلية) ونفِّذ gcloud الأوامر التالية:

# Undeploy the backend agent

gcloud run services delete raju-agent --region us-central1

# Undeploy the frontend shop (if you deployed it)

gcloud run services delete raju-shop-frontend --region us-central1

2. حذف مشروع Google Cloud (إيقاف التكلفة بالكامل)

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

  1. انتقِل إلى صفحة "المشاريع" في Google Cloud Console.
  2. اختَر مشروعك (raju-shop-agent) وانقر على حذف.
  3. اتّبِع التعليمات لتأكيد حذف المشروع.