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.
שלב 2: יצירת פרויקט חדש ב-GCP
- נכנסים אל Google Cloud Console ויוצרים פרויקט חדש.
- נכנסים אל Google Cloud Console ויוצרים פרויקט חדש.
- פותחים את החלונית הימנית, לוחצים על
Billing
ובודקים אם החשבון לחיוב מקושר לחשבון GCP הזה.
אם הדף הזה מופיע, מסמנים את התיבה manage billing account
, בוחרים באפשרות Google Cloud Trial 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
פותחים את Cloud Shell. לשם כך, עוברים אל Google Cloud Console ולוחצים על הלחצן 'הפעלת Cloud Shell' בפינה הימנית העליונה.
שלב 1: פותחים את Cloud Shell
👈 לוחצים על 'הפעלת Cloud Shell' בחלק העליון של מסוף Google Cloud (הסמל בצורת טרמינל בחלק העליון של חלונית Cloud Shell),
👈 לוחצים על הלחצן 'פתיחת הכלי לעריכה' (הוא נראה כמו תיקייה פתוחה עם עיפרון). חלון Cloud Shell Code Editor ייפתח. בצד ימין יופיע סייר הקבצים.
👈כך מוצאים את מזהה הפרויקט ב-Google Cloud:
- פותחים את מסוף Google Cloud: https://console.cloud.google.com
- בוחרים את הפרויקט שבו רוצים להשתמש בסדנה הזו מהתפריט הנפתח של הפרויקט בחלק העליון של הדף.
- מזהה הפרויקט מוצג בכרטיס Project info בלוח הבקרה
👈פותחים את הטרמינל בסביבת הפיתוח המשולבת (IDE) בענן,
👈💻 בטרמינל, מוודאים שכבר עברתם אימות ושהפרויקט מוגדר למזהה הפרויקט שלכם באמצעות הפקודה הבאה:
gcloud auth list
שלב 2: אימות באמצעות GitHub ויצירת עותק (Fork)
אימות באמצעות GitHub:
👉💻
gh auth login
מעתיקים את הקוד לדף האימות של הכניסה
מבצעים Fork ושיבוט של המאגר: 👉💻
gh repo fork cuppibla/storygen-learning --clone=true
3. ארכיטקטורה: מרעיון לתוכנית פעולה באמצעות Cloud Assist
כל פרויקט מוצלח מתחיל בחזון ברור. נשתמש ב-Cloud Assist, העוזר הדיגיטלי שלנו שמבוסס על AI, כדי לתכנן את ארכיטקטורת האפליקציה.
פעולות
- פותחים את מסוף Google Cloud: https://console.cloud.google.com
- בפינה השמאלית העליונה, לוחצים על 'פתיחת צ'אט עם 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 ייצור תרשים ארכיטקטורה. זו התוכנית הוויזואלית שלנו.
רגע חשוב ללמידה: AI מצטיין בתכנון מערכות ברמה גבוהה. הוא יכול לתרגם באופן מיידי דרישות בשפה פשוטה לארכיטקטורה מקצועית וחזותית.
4. פיתוח: בניית ADK באמצעות Gemini CLI
הגדרה ראשונית
מוודאים שמשתמשים ב-Gemini CLI כדי ליצור עותק של המאגר ולהכין את סביבת העבודה:
הגדרת הסביבה
עוברים אל Cloud Shell ולוחצים על הלחצן Open Terminal (פתיחת טרמינל).
- מעתיקים את תבנית הסביבה:
cd ~/storygen-learning cp ~/storygen-learning/env.template ~/storygen-learning/.env
הצגת קובץ מוסתר בעורך אם לא מוצאים את הקובץ .env
- לוחצים על תצוגה בסרגל התפריטים העליון.
- לוחצים על החלפת קבצים נסתרים.
עריכת קובץ .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
הפעלת האתר
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 כדי לסיים את התהליך.
5. פיתוח: יצירת סוכן בהתאמה אישית באמצעות 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 כדי לסיים את התהליך.
6. בדיקה: הערכת נציג
האפליקציה שלנו פועלת, אבל אנחנו צריכים רשת ביטחון אוטומטית של בדיקות. זו משימה מושלמת להעביר לטייס המשנה שלנו מבוסס-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
:
כאן אפשר לשנות את המדדים:
כאן אפשר לראות את תוצאת הרצת ההערכה:
7. תשתית כקוד (IaC): בניית בית בענן
הקוד שלנו נבדק, אבל הוא צריך מקום מוכן להפקה. נשתמש ב'תשתית כקוד' כדי להגדיר את הסביבה שלנו.
פעולות
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
אמורות להופיע תוצאות הפריסה ויצירת התשתית
8. אוטומציה (CI/CD): פס הייצור הדיגיטלי
פריסה ידנית של האפליקציה שלנו היא איטית ומסוכנת. נבקש מה-AI שלנו לכתוב צינור CI/CD מלא באמצעות GitHub Actions.
פעולות
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 כדי לצפות בהרצת הפריסה האוטומטית.
רגע חשוב ללמידה: אפשר ליצור באמצעות AI את כל צינור ה-CI/CD – חלק מורכב וקריטי ב-DevOps.
9. פעולות: מגדל הפיקוח של ה-AI
אנחנו בשידור חי! אבל המסע לא הסתיים. זהו "יום 2" – פעולות. נחזור ל-Cloud Assist כדי לנהל את האפליקציה הפועלת.
פעולות
- נכנסים לשירות Cloud Run במסוף Google Cloud. כדי ליצור תנועה ויומנים, מנהלים אינטראקציה עם האפליקציה הפעילה.
- פותחים את החלונית של 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 שעזר לבנות את האפליקציה הוא שותף חיוני למעקב, לפתרון בעיות ולאופטימיזציה שלה בסביבת הייצור.