סדנה בנושא סוכן AI מקצה לקצה

1. מה תלמדו

AI Agent Vibe Full Stack

שלום! אתם עומדים ללמוד את המיומנות הקריטית הבאה בפיתוח תוכנה: איך להנחות ביעילות בינה מלאכותית (AI) ליצור, לבדוק ולפרוס תוכנה ברמת ייצור. ‫AI גנרטיבי הוא לא 'טייס אוטומטי', אלא טייס משנה רב-עוצמה שזקוק לבמאי מיומן.

בסדנה הזו נציג מתודולוגיה מובנית וניתנת לשחזור לשילוב AI בכל שלב במחזור החיים של פיתוח תוכנה (SDLC). תעברו מלהיות כותבי קוד שורה אחר שורה למנהלים טכניים – אדריכלים עם חזון וקבלנים כלליים שמשתמשים ב-AI כדי להגשים את החזון הזה בדיוק רב. 🚀

בסוף המדריך הזה, יהיו לכם:

• תרגום רעיון כללי לארכיטקטורת ענן באמצעות AI.
• יצרתי קצה עורפי מלא של Python באמצעות הנחיות ספציפיות וממוקדות.
• השתמשתי ב-AI כמתכנת שותף כדי לנפות באגים ולתקן קוד.
• העברנו ל-AI את האחריות ליצירת בדיקות יחידה, כולל מוקאפים.
• יצירת תשתית כקוד (IaC) שמוכנה לייצור באמצעות Terraform.
• יצירת צינור עיבוד נתונים מלא של CI/CD ב-GitHub Actions באמצעות הנחיה אחת.
• ניטור וניהול של האפליקציה הפעילה באמצעות כלים תפעוליים מבוססי-AI.

תצאו מהסדנה לא רק עם אפליקציה עובדת, אלא גם עם תוכנית לפיתוח בעזרת AI. בואו נתחיל!

2. דרישות מוקדמות והגדרה

לפני שמתחילים, צריך להכין את הסביבה. זהו שלב חשוב כדי להבטיח חוויה חלקה בסדנה.

יצירת חשבון GCP חדש וקישור החיוב

כדי להפעיל את סוכני ה-AI שלנו, אנחנו צריכים שני דברים: פרויקט ב-Google Cloud שיספק את הבסיס ומפתח Gemini API כדי לגשת למודלים המתקדמים של Google.

שלב 1: הפעלת חשבון לחיוב

• כדי לממש את הזיכוי בסך 5 דולר בחשבון לחיוב, תצטרכו אותו לפריסה. חשוב לוודא שאתם מחוברים לחשבון Gmail.

אין צורך בכרטיס אשראי או באמצעי תשלום – תקבלו 5 $בקרדיט בחינם. התהליך יימשך פחות מ-2 דקות. רק צריך להזין את השם ולאשר את הזיכויים.

שלב 2: יצירת פרויקט חדש ב-GCP

• נכנסים אל Google Cloud Console ויוצרים פרויקט חדש.

• פותחים את החלונית הימנית, לוחצים על Billing ובודקים אם החשבון לחיוב מקושר לחשבון GCP הזה.

אם הדף הזה מופיע, מסמנים את התיבה manage billing account, בוחרים באפשרות 'תקופת ניסיון של Google Cloud One' ומקשרים אליה.

שלב 3: יצירת מפתח Gemini API

כדי לאבטח את המפתח, צריך קודם שיהיה לכם מפתח.

• עוברים אל Google AI Studio : https://aistudio.google.com/
• נכנסים באמצעות חשבון Gmail.
• לוחצים על הלחצן Get API key (קבלת מפתח API), שנמצא בדרך כלל בחלונית הניווט בצד ימין או בפינה השמאלית העליונה.
• בתיבת הדו-שיח API keys (מפתחות API), לוחצים על Create API key in new project (יצירת מפתח API בפרויקט חדש).
• בוחרים את הפרויקט החדש שיצרתם והגדרתם בו חשבון לחיוב.
• המערכת תיצור בשבילכם מפתח API חדש. מעתיקים את המפתח הזה באופן מיידי ושומרים אותו במקום בטוח באופן זמני (למשל, במנהל סיסמאות או בהערה מאובטחת). זה הערך שתשתמשו בו בשלבים הבאים.

אימות ב-GitHub

חשוב להשתמש באותו חשבון Gmail גם ב-GitHub וגם בפרויקט ב-Google Cloud.

פותחים את Cloud Shell דרך Google Cloud Console, לוחצים על הלחצן 'הפעלת Cloud Shell' בפינה הימנית העליונה.

שלב 1: פותחים את Cloud Shell

‫👈 לוחצים על 'הפעלת Cloud Shell' בחלק העליון של מסוף Google Cloud (זהו הסמל בצורת טרמינל בחלק העליון של חלונית Cloud Shell),

‫👈 לוחצים על הלחצן 'פתיחת הכלי לעריכה' (הוא נראה כמו תיקייה פתוחה עם עיפרון). חלון Cloud Shell Code Editor ייפתח. בצד ימין יופיע סייר הקבצים.

👈אחרי שפותחים את העורך, פותחים את הטרמינל בסביבת הפיתוח המשולבת בענן.

‫👈💻 בטרמינל, מוודאים שכבר עברתם אימות ושהפרויקט מוגדר למזהה הפרויקט שלכם באמצעות הפקודה הבאה:

gcloud auth list

שלב 2: אימות באמצעות GitHub ויצירת עותק (Fork)

אימות באמצעות GitHub:

‫👈💻 מעתיקים את הפקודה ומדביקים אותה במסוף הענן:

gh auth login

• בשאלה 'איפה אתה משתמש ב-GitHub', בוחרים באפשרות 'GitHub.com'.
• 'מה הפרוטוקול המועדף עליך לפעולות Git במארח הזה?', בוחרים באפשרות 'HTTPS'
• בשאלה 'האם לאמת את Git באמצעות פרטי הכניסה שלך ל-GitHub?', בוחרים באפשרות 'כן'.
• בשאלה 'איך תרצה לאמת את GitHub CLI?', בוחרים באפשרות 'כניסה באמצעות דפדפן אינטרנט'.

חשוב!! אל תקישו על Enter עדיין

שימו לב: צריך להעתיק את הקישור מהטרמינל ולהדביק אותו כדי לפתוח את דף האימות של GitHub.

מעתיקים את הקוד מהטרמינל לדף האימות של הכניסה.

אחרי שמזינים את הקוד, חוזרים אל הטרמינל של Cloud Shell ומקישים על Enter כדי להמשיך.

שלב 4: יוצרים Fork ומשכפלים את המאגר:

‫👈💻 מעתיקים את הפקודה ומדביקים אותה במסוף הענן:

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

3. ארכיטקטורה: מרעיון לתוכנית פעולה באמצעות Cloud Assist

כל פרויקט מוצלח מתחיל בחזון ברור. נשתמש ב-Cloud Assist, העוזר הדיגיטלי שלנו שמבוסס על AI, כדי לתכנן את ארכיטקטורת האפליקציה.

פעולות

• פותחים את מסוף Google Cloud:‏ [https://console.cloud.google.com](Google Cloud Console)
• בפינה השמאלית העליונה, לוחצים על 'פתיחת צ'אט עם Cloud Assist'.

הפעלת Cloud Assist

• לוחצים על 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.

קבלת תוכנית האפליקציה

• לוחצים על 'עריכת עיצוב האפליקציה' ורואים את הדיאגרמה. לוחצים על החלונית הימנית העליונה "<> Get Code" (קבלת קוד) כדי להוריד את קוד Terraform.
• ‫Cloud Assist ייצור תרשים ארכיטקטורה. זו התוכנית הוויזואלית שלנו.

לא צריך לעשות שום דבר עם הקוד הזה. הסבר נוסף מופיע בהמשך

הסבר על קוד Terraform שנוצר קיבלתם עכשיו קבוצה מלאה של קובצי Terraform מ-Cloud Assist. בשלב הזה לא נדרשת פעולה כלשהי עם הקוד הזה, אבל נסביר בקצרה מה הוא ולמה הוא כל כך יעיל.

מה זה Terraform? ‫Terraform הוא כלי של תשתית כקוד (IaC). אפשר לחשוב על זה כעל תוכנית לסביבת הענן שלכם, שנכתבת בקוד. במקום ללחוץ באופן ידני במסוף Google Cloud כדי ליצור שירותים, אחסון והרשאות, אתם מגדירים את כל המשאבים האלה בקובצי ההגדרה האלה. לאחר מכן, 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

הנשק הראשי שלכם מודע עכשיו למטרה שלו.

‫👈💻 כדי לצאת מ-Gemini CLI, לוחצים פעמיים על Ctrl+C

למידה:

איך Gemini CLI מקבל את היכולות המתקדמות שלו: gemini.md לפני שנמשיך, חשוב להבין איך אפשר להתאים את Gemini CLI לפרויקט ספציפי. אפשר להשתמש בו ככלי צ'אט למטרות כלליות, אבל העוצמה האמיתית שלו נובעת מקובץ הגדרות מיוחד: gemini.md.

כשמריצים את הפקודה gemini, המערכת מחפשת אוטומטית קובץ gemini.md בספרייה הנוכחית. הקובץ הזה משמש כהוראות הפעלה ספציפיות לפרויקט עבור ה-AI. אפשר להגדיר בו שלושה דברים עיקריים:

• פרסונה: אתם יכולים להגדיר ל-AI מי הוא צריך להיות. לדוגמה, "אתה מפתח Python מומחה שמתמחה ב-Google Cloud". כך התשובות והסגנון שלו יהיו ממוקדים יותר.
• כלים: אתם יכולים לתת לו גישה לקבצים ספציפיים (@file.py) או אפילו לחיפושים ב-Google ‏ (@google). כך ה-AI מקבל את ההקשר שהוא צריך כדי לענות על שאלות לגבי הקוד של הפרויקט.
• זיכרון: אתם יכולים לספק עובדות או כללים שה-AI צריך לזכור תמיד לגבי הפרויקט הזה, כדי לשמור על עקביות.

באמצעות קובץ gemini.md, אתם הופכים את מודל Gemini הגנרי לעוזר מומחה שכבר קיבל תדרוך לגבי המטרות של הפרויקט שלכם ויש לו גישה למידע הנכון.

5. פיתוח: בניית ADK באמצעות Gemini CLI

הגדרה ראשונית

מוודאים שאנחנו משתמשים ב-Gemini CLI כדי ליצור עותק של המאגר ולהכין את סביבת העבודה:

הגדרת הסביבה

עוברים אל Cloud Shell ולוחצים על הלחצן Open Terminal (פתיחת טרמינל).

1. מעתיקים את תבנית הסביבה:

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

הצגת קובץ מוסתר בעורך אם לא מוצאים את הקובץ ‎ .env

• לוחצים על תצוגה בסרגל התפריטים העליון.
• לוחצים על החלפת קבצים נסתרים.

‫👈איך מוצאים את מזהה הפרויקט ב-Google Cloud:

• פותחים את Google Cloud Console: קישור
• בוחרים את הפרויקט שבו רוצים להשתמש בסדנה הזו מהתפריט הנפתח של הפרויקטים בחלק העליון של הדף.
• מזהה הפרויקט מוצג בכרטיס Project info בלוח הבקרה

👈איך מוצאים את שם המשתמש ב-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

בחלון של Gemini 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.

הפעלת האתר

cd ~/storygen-learning/01a_First_Agent_Ready

./start.sh

אם השינוי לא פועל, צפויות להופיע שגיאות בממשק המשתמש של ADK Web ובאתר.

—————————————— Solution Starting Here ———————————————

המוצר

מפסיקים את התהליך הקודם באמצעות 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

יוצג ממשק המשתמש של ADK שבו אפשר לשאול שאלות את הסוכן.

לפני שעוברים לקטע הבא, מקישים על 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

הפעלת האתר

cd ~/storygen-learning/02a_Second_Agent_Ready

./start.sh

אם השינוי לא פועל, צפויות להופיע שגיאות בממשק המשתמש של ADK Web ובאתר.

—————————————- הפתרון מתחיל כאן ——————————————–

המוצר

מפסיקים את התהליך הקודם באמצעות 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 כדי לסיים את התהליך.

למידה

הסוכן הראשון שלנו היה מצוין ביצירת טקסט, אבל עכשיו אנחנו צריכים ליצור תמונות. למשימה הזו אנחנו צריכים שליטה ישירה יותר. אנחנו לא רוצים שה-LLM יחליט אם ליצור תמונה, אלא רוצים לתת לו פקודה ישירה לעשות זאת. זו עבודה מושלמת ל-BaseAgent.

בניגוד ל-LlmAgent הדקלרטיבי, BaseAgent הוא אימפרטיבי. כלומר, אתם, המפתחים, כותבים את הלוגיקה המדויקת של Python שלב אחר שלב בתוך השיטה _run_async_impl. יש לכם שליטה מלאה על זרימת הביצוע.

תבחרו BaseAgent כשאתם צריכים:

לוגיקה דטרמיניסטית: הסוכן צריך לפעול לפי רצף ספציפי של שלבים שלא ניתן לשנות.

הפעלה ישירה של כלי: אתם רוצים להפעיל כלי ישירות בלי התערבות של LLM.

זרימות עבודה מורכבות: התהליך כולל מניפולציה של נתונים בהתאמה אישית, קריאות ל-API ולוגיקה שמורכבת מדי בשביל ש-LLM יסיק אותה באופן מהימן רק מההנחיה.

באפליקציה שלנו, נשתמש ב-BaseAgent כדי לקבל את תיאורי הסצנות מהסוכן הראשון, ונקרא ישירות לכלי Imagen כדי להבטיח שתיצור תמונה לכל סצנה.

7. בדיקה: הערכת נציג

האפליקציה שלנו פועלת, אבל אנחנו צריכים רשת ביטחון אוטומטית של בדיקות. זו משימה מושלמת להעביר לטייס המשנה שלנו מבוסס ה-AI.

פעולות

cd ~/storygen-learning/03a_Agent_Evaluation_Ready/backend

שימוש ב-Gemini CLI כדי לכתוב בדיקות מקיפות:

פתיחת Gemini CLI

gemini

בחלון של Gemini 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.

ממשק המשתמש של ADK Web עם יכולות בדיקה קבועות אמור להופיע

רגע חשוב ללמידה: AI הוא שותף רב עוצמה באוטומציה של בקרת איכות. הוא יכול לטפל בקוד הסטנדרטי של כתיבת בדיקות, וכך אתם יכולים להתמקד בפיתוח תכונות.

—————————————— Solution Starting Here ———————————————

המוצר

• עוברים לתיקיית הפתרון:

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 מילים'.

כשמריצים הערכה, אפשר לבדוק באופן אוטומטי את הנציג מול עשרות תרחישים, כדי לוודא ששינויים בהנחיה או בכלים לא פוגעים בטעות בפונקציונליות המרכזית שלו. זוהי רשת ביטחון חזקה לפיתוח סוכני AI שמוכנים לייצור.

8. תשתית כקוד (IaC): בניית בית בענן

הקוד שלנו נבדק, אבל הוא צריך מקום מוכן להפקה. נשתמש ב'תשתית כקוד' כדי להגדיר את הסביבה שלנו.

מה זה Docker?

‫Docker היא פלטפורמה ליצירה ולהרצה של אפליקציות בקונטיינרים. אפשר לחשוב על קונטיינר כמו על קונטיינר משלוחים סטנדרטי לתוכנה. הוא כולל בחבילה אחת מבודדת את כל מה שהאפליקציה צריכה כדי לפעול:

• קוד האפליקציה עצמו
• סביבת זמן הריצה הנדרשת (לדוגמה, גרסה ספציפית של Python)
• כל הכלים והספריות של המערכת

אחרי זה אפשר להריץ את האפליקציה הזו בכל מכונה שמותקן בה Docker, וכך לפתור את הבעיה הקלאסית של 'זה עובד במחשב שלי'.

בקטע הזה, נבקש מ-Gemini ליצור Dockerfile, שהוא פשוט המתכון או התוכנית ליצירת תמונת הקונטיינר של האפליקציה שלנו

פעולות

cd ~/storygen-learning/04a_Manual_Deployment_Ready

שימוש ב-Gemini CLI ליצירת Dockerfile עבור ה-Backend: פותחים את 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/CD.

‫CI/CD מייצג אינטגרציה רציפה ופריסה רציפה. זו שיטה לבנייה, לבדיקה ולפריסה אוטומטית של הקוד בכל פעם שמבצעים בו שינוי.

• אינטגרציה רציפה (CI): זהו השלב של 'בנייה ובדיקה'. ברגע שמפתח מעלה שינוי בקוד למאגר משותף (כמו GitHub), מערכת אוטומטית מתחילה לפעול. הוא יוצר את האפליקציה ומריץ את כל הבדיקות (כמו הערכות הסוכן שיצרנו) כדי לוודא שהקוד החדש משתלב בצורה נכונה ולא גורם לבאגים.
• פריסה רציפה (CD): זהו שלב ה'השחרור'. אם שלב ה-CI עובר בהצלחה, המערכת פורסת באופן אוטומטי את הגרסה החדשה שנבדקה של האפליקציה בסביבת הייצור, והיא הופכת לזמינה למשתמשים.

הצינור האוטומטי הזה יוצר 'פס ייצור דיגיטלי' שמעביר קוד ממחשב של מפתח לייצור במהירות, בצורה בטוחה ואמינה. בקטע הזה נבקש מהעוזר הדיגיטלי מבוסס ה-AI שלנו ליצור עבורנו את פס הייצור הזה באמצעות 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.

—————————————— Solution Starting Here ———————————————

הפתרון:

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

הפעלת תהליך העבודה: מבצעים Commit ו-Push של הקוד אל main. חשוב לדעת שצריך להגדיר את האימייל והשם ב-GitHub כדי לאשר את ההרשאה.

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

עוברים לכרטיסייה Actions (פעולות) במאגר GitHub כדי לצפות בהרצת הפריסה האוטומטית.

10. פעולות: מרכז הבקרה של ה-AI

אנחנו בשידור חי! אבל המסע לא הסתיים. זהו "יום 2" – פעולות. נחזור ל-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?

רגע חשוב ללמידה: מחזור החיים של פיתוח תוכנה מבוססת-AI הוא לולאה מתמשכת. אותו טייס משנה מבוסס-AI שעזר לבנות את האפליקציה הוא שותף חיוני למעקב, לפתרון בעיות ולאופטימיזציה שלה בסביבת הייצור.