ورشة عمل حول الذكاء الاصطناعي التوليدي من البداية إلى النهاية

1. ما ستتعلمه

AI Agent Vibe Full Stack

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

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

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

• ترجمة فكرة عامة إلى بنية سحابية باستخدام الذكاء الاصطناعي
• تم إنشاء خلفية Python كاملة باستخدام طلبات محددة ومستهدفة.
• استخدام الذكاء الاصطناعي كمساعد برمجي لتصحيح الأخطاء في الرموز البرمجية وإصلاحها
• تفويض الذكاء الاصطناعي بإنشاء اختبارات الوحدة، بما في ذلك عمليات المحاكاة
• إنشاء بنية أساسية كرمز (IaC) جاهزة للإنتاج باستخدام Terraform
• أنشأنا مسار CI/CD كاملاً في GitHub Actions باستخدام طلب واحد.
• مراقبة تطبيقك المباشر وإدارته باستخدام أدوات تشغيلية مستندة إلى الذكاء الاصطناعي

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

2. المتطلّبات الأساسية والإعداد

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

إنشاء حساب جديد على Google Cloud Platform وربط الفوترة

لتشغيل وكلاء الذكاء الاصطناعي، نحتاج إلى عنصرَين: مشروع Google Cloud لتوفير الأساس، ومفتاح Gemini API للوصول إلى نماذج Google الفعّالة.

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

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

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

الخطوة 2: إنشاء مشروع جديد على Google Cloud Platform

• انتقِل إلى Google Cloud Console وأنشِئ مشروعًا جديدًا.

• افتح اللوحة اليمنى، وانقر على Billing، وتحقّق ممّا إذا كان حساب الفوترة مرتبطًا بحساب Google Cloud Platform هذا.

إذا ظهرت لك هذه الصفحة، تحقَّق من manage billing account، واختَر Google Cloud Trial One واربطه.

الخطوة 3: إنشاء مفتاح واجهة Gemini API

قبل أن تتمكّن من تأمين المفتاح، يجب أن يكون لديك مفتاح.

• انتقِل إلى Google AI Studio : https://aistudio.google.com/
• سجِّل الدخول باستخدام حسابك على Gmail.
• انقر على الزر "الحصول على مفتاح واجهة برمجة التطبيقات"، والذي يظهر عادةً في لوحة التنقّل على يمين الصفحة أو في أعلى يسارها.
• في مربّع الحوار "مفاتيح واجهة برمجة التطبيقات"، انقر على "إنشاء مفتاح واجهة برمجة التطبيقات في مشروع جديد".
• اختَر المشروع الجديد الذي أنشأته والذي تم إعداد حساب الفوترة فيه.
• سيتم إنشاء مفتاح واجهة برمجة تطبيقات جديد لك. انسخ هذا المفتاح على الفور وخزِّنه مؤقتًا في مكان آمن (مثل مدير كلمات المرور أو ملاحظة آمنة). هذه هي القيمة التي ستستخدِمها في الخطوات التالية.

مصادقة GitHub

احرص على استخدام حساب Gmail نفسه لحسابك على GitHub ومشروعك على Google Cloud.

افتح Cloud Shell من خلال الانتقال إلى Google Cloud Console والنقر على الزر "تفعيل Cloud Shell" في أعلى يسار الصفحة.

الخطوة 1: فتح Cloud Shell

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

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

👉بعد فتح المحرِّر، افتح نافذة الوحدة الطرفية في بيئة التطوير المتكاملة المستندة إلى السحابة الإلكترونية.

👉💻 في نافذة الوحدة الطرفية، تأكَّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:

gcloud auth list

الخطوة 2: المصادقة باستخدام GitHub وإنشاء نسخة طبق الأصل

المصادقة باستخدام GitHub:

👉💻 انسخ الأمر والصقه في نافذة سطر الأوامر على السحابة الإلكترونية:

gh auth login

• "أين تستخدم GitHub"، اختَر "GitHub.com"
• "ما هو البروتوكول المفضّل لديك لعمليات Git على هذا المضيف؟"، اختَر "HTTPS"
• "هل تريد مصادقة Git باستخدام بيانات اعتماد GitHub؟"، اختَر "نعم"
• "كيف تريد مصادقة GitHub CLI؟"، اختَر "تسجيل الدخول باستخدام متصفّح ويب"

مهم: لا تضغط على "Enter" بعد

يُرجى العِلم أنّه عليك نسخ الرابط ولصقه من الوحدة الطرفية لفتح صفحة المصادقة في GitHub.

انسخ الرمز من نافذة الأوامر إلى صفحة تأكيد تسجيل الدخول

بعد الانتهاء من إدخال الرمز، ارجع إلى وحدة Cloud Shell الطرفية، واضغط على "Enter" للمتابعة.

الخطوة 4: إنشاء نسخة من المستودع واستنساخها:

👉💻 انسخ الأمر والصقه في نافذة سطر الأوامر على السحابة الإلكترونية:

gh repo fork cuppibla/storygen-learning --clone=true

3- البنية: من الفكرة إلى المخطط باستخدام Cloud Assist

يبدأ كل مشروع ناجح برؤية واضحة. سنستخدم مساعدنا المستند إلى الذكاء الاصطناعي، Cloud Assist، لتصميم بنية تطبيقنا.

المهام

• افتح Google Cloud Console: [https://console.cloud.google.com](Google Cloud Console)
• في أعلى يسار الصفحة، انقر على "فتح نافذة Cloud Assist Chat"

تفعيل ميزة "المساعدة من السحابة الإلكترونية"

• انقر على Get Gemini Assist، ثم على Enable Cloud Assist at no cost.
• وابدأ المحادثة.

قدِّم الطلب التفصيلي التالي إلى Cloud Assist:

إدخال فكرتك

Generate a Python web application that uses AI to generate children's stories and illustrations. It has Python backend and React frontend host separately on Cloudrun. They communicate through Websocket. It needs to use a generative model for text and another for images. The generated images must be used by Imagen from Vertex AI and stored in a Google Cloud Storage bucket so that frontend can fetch from the bucket to render images. I do not want any load balancer or a database for the story text. We need a solution to store the API key.

الحصول على مخطط تطبيقك

• انقر على "تعديل تصميم التطبيق"، وسيظهر لك الرسم البياني. انقر على اللوحة العلوية اليسرى "<> الحصول على الرمز" لتنزيل رمز Terraform.
• ستنشئ أداة Cloud Assist مخططًا للبنية. هذه هي خطتنا المرئية.

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

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

ما هي أداة Terraform؟ ‫Terraform هي أداة "البنية الأساسية كرمز" (IaC). يمكنك اعتبارها مخططًا لبيئة السحابة الإلكترونية مكتوبًا بلغة البرمجة. بدلاً من النقر يدويًا في Google Cloud Console لإنشاء الخدمات والمساحة التخزينية والأذونات، يمكنك تحديد جميع هذه الموارد في ملفات الإعداد هذه. بعد ذلك، يقرأ Terraform مخططك وينشئ لك هذه البيئة بالضبط تلقائيًا.

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

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

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

4. تطوير: مقدّمة عن Gemini CLI

👉💻 في وحدة Cloud Shell الطرفية، انتقِل إلى الدليل الشخصي.

cd ~/storygen-learning

👉💻 جرِّب Gemini للمرة الأولى.

clear
gemini --model=gemini-2.5-flash

إذا طُلب منك ذلك Do you want to connect Cloud Shell editor to Gemini CLI?، اختَر لا.

👉✨ تتضمّن كل أداة من أدوات Gemini وصفًا. يمكنك الاطّلاع عليها الآن. في طلب Gemini، اكتب ما يلي:

في Gemini CLI

/help

👉✨ يمتلك Gemini CLI مجموعة من القدرات المضمّنة. لفحصها، اتّبِع الخطوات التالية:

في Gemini CLI

/tools

ستظهر لك قائمة تتضمّن ReadFile وWriteFile وGoogleSearch. هذه هي التقنيات التلقائية التي يمكنك الاستعانة بها بدون الحاجة إلى استخدام مجموعة أدوات خارجية.

👉✨ يمكن أن يحمل Gemini Blade "وعيًا تكتيكيًا" (سياقًا) لتوجيه إجراءاته.

في Gemini CLI

/memory show

وهي فارغة حاليًا.

👉✨ أولاً، أضِف شخصية إلى ذاكرة الوكيل. سيحدّد هذا الإجراء مجال خبرة الحساب:

في Gemini CLI

/memory add "I am master at python development"

نفِّذ /memory show مرة أخرى للتأكّد من أنّ السكين قد استوعب هذه المعلومات.

👉✨ لتوضيح كيفية الإشارة إلى الملفات باستخدام الرمز @، لننشئ أولاً ملف "موجز المهمة".

افتح وحدة طرفية جديدة ونفِّذ الأمر التالي لإنشاء ملف المهمة:

!echo "## Mission Objective: Create Imagen ADK Agent for Story Book" > mission.md

👉✨الآن، اطلب من Gemini CLI تحليل الموجز وإعداد تقرير بالنتائج التي توصل إليها:

في Gemini CLI

Explain the contents of the file @mission.md

أصبح سلاحك الأساسي على دراية بهدفه.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI

قيد التعلّم:

كيفية حصول Gemini CLI على قدراته الفائقة: gemini.md قبل المتابعة، من المهم فهم كيفية تخصيص Gemini CLI لمشروع معيّن. على الرغم من إمكانية استخدامه كأداة دردشة للأغراض العامة، تكمن قوته الحقيقية في ملف إعداد خاص: gemini.md.

عند تشغيل الأمر gemini، يبحث تلقائيًا عن ملف gemini.md في الدليل الحالي. يعمل هذا الملف كدليل تعليمات خاص بالمشروع للذكاء الاصطناعي. يمكن أن تحدّد ثلاثة أشياء رئيسية:

• الشخصية: يمكنك تحديد الشخصية التي يجب أن يتّبعها الذكاء الاصطناعي. على سبيل المثال، "أنت مطوّر خبير في لغة Python ومتخصّص في Google Cloud". ويساعد ذلك في تركيز ردوده وأسلوبه.
• الأدوات: يمكنك منحها إذن الوصول إلى ملفات معيّنة (@file.py) أو حتى عمليات بحث على Google (@google). يوفّر ذلك للذكاء الاصطناعي السياق المطلوب للإجابة عن الأسئلة المتعلقة بالرمز البرمجي لمشروعك.
• الذاكرة: يمكنك تقديم حقائق أو قواعد يجب أن يتذكرها الذكاء الاصطناعي دائمًا لهذا المشروع، ما يساعد في الحفاظ على الاتساق.

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

5- التطوير: إنشاء ADK باستخدام Gemini CLI

عملية الإعداد الأوّلية

تأكَّد من استخدام Gemini CLI لإنشاء نسخة من المستودع وإعداد مساحة العمل:

إعدادات البيئة

انتقِل إلى Cloud Shell، وانقر على الزر "فتح نافذة Terminal".

1. انسخ نموذج البيئة:

   cd ~/storygen-learning
   cp ~/storygen-learning/env.template ~/storygen-learning/.env
   

عرض الملف المخفي في المحرّر إذا لم تعثر على ملف ‎ .env

• انقر على عرض في شريط القائمة العلوي.
• انقر على تبديل الملفات المخفية.

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

• افتح Google Cloud Console: link
• اختَر المشروع الذي تريد استخدامه في ورشة العمل هذه من القائمة المنسدلة للمشروع في أعلى الصفحة.
• يظهر رقم تعريف مشروعك في بطاقة "معلومات المشروع" على "لوحة البيانات".

👉العثور على اسم المستخدم على GitHub:

• انتقِل إلى حسابك على GitHub وابحث عن اسم المستخدم على GitHub

تعديل ملف ‎ .env 2. استبدِل القيم التالية في .env:

GOOGLE_API_KEY=[REPLACE YOUR API KEY HERE]
GOOGLE_CLOUD_PROJECT_ID=[REPLACE YOUR PROJECT ID]
GITHUB_USERNAME=[REPLACE YOUR USERNAME]
GENMEDIA_BUCKET=[REPLACE YOUR PROJECT ID]-bucket

على سبيل المثال، إذا كان رقم تعريف مشروعك هو: testproject، عليك وضع GOOGLE_CLOUD_PROJECT_ID=testproject وGENMEDIA_BUCKET=testproject-bucket

نصوص الإعداد

الانتقال إلى 00_Starting_Here فتح نافذة طرفية جديدة (ليست في Gemini CLI)

cd ~/storygen-learning/00_Starting_Here

إجراء عملية الإعداد الكاملة:

./setup-complete.sh

من المفترض أن تظهر لك نتائج الإعداد في نافذة الوحدة الطرفية

إنشاء الوكيل الأول

انتقِل إلى 01a_First_Agent_Ready لنستخدم Gemini CLI لإنشاء وكيل ADK:**

cd ~/storygen-learning/01a_First_Agent_Ready

فتح Gemini CLI

gemini

داخل نافذة Gamini CLI، جرِّب الطلب التالي:

I need you to help me create a Google ADK (Agent Development Kit) agent for story generation. I'm working on a children's storybook app that generates creative stories with visual scenes.

Please create a complete `agent.py` file that implements an LlmAgent using Google's ADK framework. The agent should:

**Requirements:**
1. Use the `google.adk.agents.LlmAgent` class
2. Use the "gemini-2.5-flash" model (supports streaming)
3. Be named "story_agent"
4. Generate structured stories with exactly 4 scenes each
5. Output valid JSON with story text, main characters, and scene data
6. No tools needed (images are handled separately)

**Agent Specifications:**
- **Model:** gemini-2.5-flash
- **Name:** story_agent  
- **Description:** "Generates creative short stories and accompanying visual keyframes based on user-provided keywords and themes."
**Story Structure Required:**
- Exactly 4 scenes: Setup → Inciting Incident → Climax → Resolution
- 100-200 words total
- Simple, charming language for all audiences
- Natural keyword integration
**JSON Output Format:**

{
  "story": "Complete story text...",
  "main_characters": [
    {
      "name": "Character Name",
      "description": "VERY detailed visual description with specific colors, features, size, etc."
    }
  ],
  "scenes": [
    {
      "index": 1,
      "title": "The Setup",
      "description": "Scene action and setting WITHOUT character descriptions",
      "text": "Story text for this scene"
    }
    // ... 3 more scenes
  ]
}


**Key Instructions for the Agent:**
- Extract 1-2 main characters maximum
- Character descriptions should be extremely detailed and visual
- Scene descriptions focus on ACTION and SETTING only
- Do NOT repeat character appearance in scene descriptions
- Always respond with valid JSON

Please include a complete example in the instructions showing the exact format using keywords like "tiny robot", "lost kitten", "rainy city".

The file should start with necessary imports, define an empty tools list, include a print statement for initialization, and then create the LlmAgent with all the detailed instructions.

Can you create this agent in backend/story_agent/agent.py

بعد الانتهاء، أوقِف نافذة Gemini CLI باستخدام Control+C

—————————————— اختياري، يمكنك الانتقال إلى قسم الحل——————————————–

تأكيد التغيير في ADK Web

cd ~/storygen-learning/01a_First_Agent_Ready/backend

source ../../.venv/bin/activate

adk web --port 8080

للمتابعة، ستحتاج إلى موجه أوامر.

يمكنك فتح نافذة وحدة طرفية جديدة أو إيقاف خادم الويب الحالي لحزمة تطوير التطبيقات (ADK) بالضغط على Ctrl+C.

Spin Up The Website

cd ~/storygen-learning/01a_First_Agent_Ready

./start.sh

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

——————————————– الحل يبدأ هنا ——————————————–

Solution

أنهِ العملية السابقة باستخدام Control+C أو يمكنك فتح نافذة طرفية أخرى:

cd ~/storygen-learning/01b_First_Agent_Done

إنشاء الموقع الإلكتروني:

./start.sh

سيظهر لك الموقع الإلكتروني:

جرِّب واجهة مستخدم ADK: افتح نافذة وحدة طرفية أخرى:

cd ~/storygen-learning/01b_First_Agent_Done/backend

source ../../.venv/bin/activate

adk web --port 8080

ستظهر لك واجهة مستخدم "حزمة تطوير التطبيقات" حيث يمكنك طرح أسئلة على الوكيل

قبل الانتقال إلى القسم التالي، اضغط على Ctrl+C لإنهاء العملية.

6. التطوير: إنشاء وكيلك المخصّص باستخدام Imagen

إنشاء أداة Imagen (الوكيل الثاني)

cd ~/storygen-learning/02a_Image_Agent_Ready

استخدام Gemini CLI لإنشاء وكيل إنشاء الصور:

gemini generate "I need you to help me create a custom Google ADK (Agent Development Kit) agent for image generation. This is different from the story agent - this one handles image generation directly using the BaseAgent pattern for full control over tool execution.

Please create a complete `agent.py` file that implements a custom image generation agent. The agent should:

**Requirements:**
1. Use the `google.adk.agents.BaseAgent` class (NOT LlmAgent)
2. Be named "custom_image_agent" 
3. Directly execute the ImagenTool without LLM intermediation
4. Handle JSON input with scene descriptions and character descriptions
5. Store results in session state for retrieval by main.py
6. Use async generators and yield Events

**Key Specifications:**
- **Class Name:** CustomImageAgent (inherits from BaseAgent)
- **Agent Name:** "custom_image_agent"
- **Tool:** Uses ImagenTool for direct image generation
- **Purpose:** Bypass LLM agent limitations and directly call ImagenTool

**Input Format:**
The agent should handle JSON input like:
{
  "scene_description": "Scene action and setting",
  "character_descriptions": {
    "CharacterName": "detailed visual description"
  }
}


**Core Method:** `async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:`
   - Extract user message from `ctx.user_content.parts`
   - Parse JSON input or fallback to plain text
   - Extract scene_description and character_descriptions
   - Build image prompt with style prefix: "Children's book cartoon illustration with bright vibrant colors, simple shapes, friendly characters."
   - Include character descriptions for consistency
   - Call `await self.imagen_tool.run()` directly
   - Store results in `ctx.session.state["image_result"]`
   - Yield Event with results


 **Session State:**
   - Store JSON results in `ctx.session.state["image_result"]`
   - Include success/error status
   - Store actual image URLs or error messages

Expected Output Structure:
- Successful results stored as JSON with image URLs
- Error results stored as JSON with error messages
- Results accessible via session state in main.py

Can you create this agent in backend/story_image_agent/agent.py

"

—————————————— اختياري، يمكنك الانتقال إلى قسم الحل——————————————–

تأكيد التغيير في ADK Web

cd ~/storygen-learning/02a_Image_Agent_Ready/backend

source ../../.venv/bin/activate

adk web --port 8080

Spin Up The Website

cd ~/storygen-learning/02a_Second_Agent_Ready

./start.sh

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

—————————————- الحل يبدأ من هنا ——————————————–

Solution

أنهِ العملية السابقة باستخدام Control+C أو يمكنك فتح نافذة طرفية أخرى:

# Open new terminal
cd ~/storygen-learning/02b_Image_Agent_Done

إنشاء الموقع الإلكتروني:

./start.sh

سيظهر لك الموقع الإلكتروني:

جرِّب واجهة مستخدم ADK: افتح نافذة وحدة طرفية أخرى:

# Open new terminal
cd ~/storygen-learning/02b_Image_Agent_Done/backend

source ../../.venv/bin/activate

adk web --port 8080

ستظهر لك واجهة مستخدم ADK حيث يمكنك طرح أسئلة على الوكيل:

قبل الانتقال إلى القسم التالي، اضغط على Ctrl+C لإنهاء العملية.

قيد التعلم

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

على عكس LlmAgent الإجرائي، يكون BaseAgent إلزاميًا. هذا يعني أنّك بصفتك المطوّر تكتب منطق Python الدقيق خطوة بخطوة داخل طريقة _run_async_impl. يمكنك التحكّم الكامل في مسار التنفيذ.

يمكنك اختيار BaseAgent عندما تحتاج إلى:

المنطق الحتمي: يجب أن يتّبع الوكيل تسلسلاً محدّدًا وغير قابل للتغيير من الخطوات.

التنفيذ المباشر للأداة: تريد استدعاء أداة مباشرةً بدون تدخّل نموذج اللغة الكبير.

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

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

7. الاختبار: تقييم الوكيل

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

المهام

cd ~/storygen-learning/03a_Agent_Evaluation_Ready/backend

استخدام Gemini CLI لكتابة اختبارات شاملة:

فتح Gemini CLI

gemini

داخل نافذة Gamini CLI، جرِّب الطلب التالي:

I need you to create comprehensive test files for my backend/story_agent in Google ADK. I need three specific JSON files that match the testing structure used in ADK evaluation.

**Context:** 
- The story agent generates structured JSON stories with exactly 4 scenes
- It uses LlmAgent with no tools, just direct LLM responses
- Input: Keywords
- Output: JSON with story, main_characters, and scenes arrays

**Files to Create:**

### 1. `story_agent_eval.evalset.json` (Comprehensive Integration Tests)
Create a comprehensive evaluation set with:
- **eval_set_id**: "story_agent_comprehensive_evalset"
- **name**: "Story Agent Comprehensive Evaluation Set" 
- **description**: "Comprehensive evaluation scenarios for story_agent covering various keyword combinations, edge cases, and story quality metrics"


Each eval_case should include:
- Full conversation arrays with invocation_id, user_content, final_response
- Complete expected JSON responses with detailed stories, characters, and 4 scenes
- session_input with app_name "story_agent"
- All fields: story (narrative text), main_characters (with detailed visual descriptions), scenes (with index, title, description, text)

### 2. `story_generation.test.json` (Unit Tests)
Create basic generation tests with:
- **eval_set_id**: "story_agent_basic_generation_tests"
- **name**: "Story Agent Basic Generation Tests"
- **description**: "Unit tests for story_agent focusing on JSON structure compliance, scene generation, and keyword integration"

### 3. `test_config.json` (Evaluation Configuration)
Create test configuration with:
- **criteria**: response_match_score: 0.7, tool_trajectory_avg_score: 1.0
- **custom_evaluators**: 
  - json_structure_validator (validates required fields, scene count, character fields)
  - story_quality_metrics (word count 80-250, keyword integration threshold 0.8)
- **evaluation_notes**: Story agent specifics and trajectory expectations

**Important Requirements:**
1. All responses must be valid, parseable JSON
2. Stories must have exactly 4 scenes with indices 1-4
3. Each scene must have: index, title, description, text
4. Main characters must have detailed visual descriptions
5. No tool_uses expected (empty arrays) since story agent uses direct LLM
6. Word count should be 100-200 words total
7. Keywords must be naturally integrated into the narrative

Please generate all three files with realistic example stories and comprehensive test coverage matching the ADK evaluation format.

—————————————— اختياري، يمكنك الانتقال إلى قسم الحل——————————————–

للاطّلاع على التقييم:

./run_adk_web_persistent.sh

انتقِل إلى علامة التبويب eval في واجهة مستخدم "حزمة تطوير التطبيقات".

من المفترض أن تظهر لك واجهة مستخدم ADK على الويب مع إمكانات اختبار مستمرة

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

——————————————– الحل يبدأ هنا ——————————————–

Solution

• انتقِل إلى مجلد الحل:

cd ~/storygen-learning/03b_Agent_Evaluation_Done/backend

• فتح واجهة مستخدم ADK على الويب

./run_adk_web_persistent.sh

يمكنك الاطّلاع على حالات الاختبار من علامة التبويب Eval:

يمكنك تعديل المقاييس هنا:

يمكنك الاطّلاع على نتيجة عملية التقييم هنا:

قيد التعلم

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

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

evalset.json: هذه هي مجموعة الاختبار الرئيسية. يحتوي كل "حالة تقييم" داخل هذا الملف على محادثة نموذجية (مثل طلب مستخدم) والاستجابة المثالية التي تتوقّع أن يقدّمها الوكيل.

test_config.json: يحدّد هذا الملف قواعد النجاح. يمكنك ضبط معايير هنا، مثل:

response_match_score: ما مدى تطابق ردّ الوكيل مع الردّ "المثالي"؟ (تعني النتيجة 1.0 أنّه يجب أن يكون المحتوى مطابقًا تمامًا).

custom_evaluators: يمكنك إنشاء قواعدك الخاصة، مثل "يجب أن تكون الاستجابة ملف JSON صالحًا" أو "يجب أن تتضمّن القصة أكثر من 100 كلمة".

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

8. البنية الأساسية كرمز (IaC): بناء منزل في السحابة الإلكترونية

تم اختبار الرمز البرمجي، ولكنّه يحتاج إلى بيئة إنتاج جاهزة. سنستخدم "البنية الأساسية كرمز" لتحديد بيئتنا.

ما هو Docker؟

‫Docker هي منصة لإنشاء التطبيقات وتشغيلها في حاويات. يمكن اعتبار الحاوية بمثابة حاوية شحن موحّدة للبرامج. تجمع كل ما يحتاجه تطبيقك لتشغيله في حزمة واحدة معزولة:

• رمز التطبيق نفسه
• وقت التشغيل المطلوب (مثل الإصدار المحدّد من Python)
• جميع أدوات النظام ومكتباته

ويمكن بعد ذلك تشغيل هذا التطبيق الذي يعمل في حاوية على أي جهاز مثبَّت عليه Docker، ما يحلّ مشكلة "يعمل على جهازي" الكلاسيكية.

في هذا القسم، سنطلب من Gemini إنشاء Dockerfile، وهو ببساطة الوصفة أو المخطط لإنشاء صورة حاوية التطبيق.

المهام

cd ~/storygen-learning/04a_Manual_Deployment_Ready

استخدام Gemini CLI لإنشاء Dockerfile للخادم الخلفي: افتح Gemini CLI

Gemini

داخل Gemini CLI، جرِّب الطلب التالي:

Create a manual deployment plan for my StoryGen app with Google Cloud Platform. I have a Next.js frontend, Python backend, and Terraform infrastructure.

Generate these deployment files:
1. **01-setup.sh** - Environment setup and authentication
2. **02-build-images.sh** - Build and push Docker images to Google Container Registry
3. **03-deploy-infrastructure.sh** - Deploy with Terraform and configure services
4. **load-env.sh** - Load environment variables for deployment

**Requirements:**
- Use Google Cloud Run for both frontend and backend
- Configure Imagen API and storage buckets
- Set up proper IAM permissions
- Use environment variables from .env file
- Include error handling and status checks

Keep scripts simple, well-commented, and production-ready for manual execution.

الحلّ:

cd ~/storygen-learning/04b_Manual_Deployment_Done

التشغيل:

source ../.venv/bin/activate
./01-setup.sh

./02-build-images.sh

./03-deploy-infrastructure.sh

من المفترض أن تظهر لك نتائج النشر وعملية إنشاء البنية الأساسية

9- التشغيل الآلي (التكامل المستمر/التسليم المستمر): خط التجميع الرقمي

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

يشير مصطلح CI/CD إلى التكامل المستمر والنشر المستمر. وهي طريقة لإنشاء الرمز البرمجي واختباره ونشره تلقائيًا في كل مرة تجري فيها تغييرًا.

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

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

المهام

cd ~/storygen-learning/05a_CICD_Pipeline_Ready

استخدام Gemini CLI لإنشاء مسار CI/CD باستخدام GitHub:

فتح Gemini CLI

Gemini

داخل Gemini CLI، جرِّب الطلب التالي:

Create a CI/CD pipeline for my StoryGen app using Google Cloud Build and GitHub integration.

Generate these automation files:
1. **cloudbuild.yaml** (for backend) - Automated build, test, and deploy pipeline
2. **GitHub Actions workflow** - Trigger builds on push/PR
3. **Deployment automation scripts** - Streamlined deployment process

**Requirements:**
- Auto-trigger on GitHub push to main branch
- Build and push Docker images
- Run automated tests if available
- Deploy to Google Cloud Run
- Environment-specific deployments (staging/prod)
- Notification on success/failure

Focus on fully automated deployment with minimal manual intervention. Include proper secret management and rollback capabilities.

——————————————– الحل يبدأ هنا ——————————————–

الحلّ:

cd ~/storygen-learning/06_Final_Solution/
# Copy the GitHub workflow to parent folder
cp -r 06_Final_Solution/.GitHub ../../../.GitHub

ارجع إلى المجلد 06_Final_Solution ونفِّذ النص البرمجي:

cd ~/storygen-learning/06_Final_Solution/

./setup-cicd-complete.sh

يجب أن يظهر لك اكتمال عملية إعداد مسار CI/CD

تشغيل سير العمل: نفِّذ التغييرات وادفع الرمز إلى الفرع الرئيسي. يُرجى العِلم أنّه عليك إعداد عنوان بريدك الإلكتروني واسمك على GitHub للسماح بالإذن.

git add .
git commit -m "feat: Add backend, IaC, and CI/CD workflow"
git push origin main

انتقِل إلى علامة التبويب "الإجراءات" في مستودع GitHub لمشاهدة عملية النشر المبرمَجة.

10. العمليات: برج مراقبة الذكاء الاصطناعي

بدأ البث المباشر. لكنّ الرحلة لم تنتهِ بعد. هذا هو "اليوم الثاني"، أي العمليات. لنرجع إلى Cloud Assist لإدارة تطبيقنا قيد التشغيل.

المهام

1. انتقِل إلى خدمة Cloud Run في وحدة تحكّم Google Cloud. تفاعَل مع تطبيقك المباشر لإنشاء بعض الزيارات والسجلات.
2. افتح لوحة Cloud Assist واستخدِمها كطيار مساعد تشغيلي من خلال طلبات مثل ما يلي:

تحليل السجلات:

Summarize the errors in my Cloud Run logs for the service 'genai-backend' from the last 15 minutes.

تحسين الأداء:

My Cloud Run service 'genai-backend' has high startup latency. What are common causes for a Python app and how can I investigate with Cloud Trace?

تحسين التكلفة:

Analyze the costs for my 'genai-backend' service and its GCS bucket. Are there any opportunities to save money?

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