1. Öğrenecekleriniz
AI Agent Vibe Full Stack
Hoş geldiniz! Yazılım geliştirmede bir sonraki önemli beceriyi, yani yapay zekayı üretim düzeyinde yazılımlar oluşturma, test etme ve dağıtma konusunda etkili bir şekilde yönlendirmeyi öğrenmek üzeresiniz. Üretken yapay zeka bir "otomatik pilot" değildir. Yetenekli bir yönetmene ihtiyaç duyan güçlü bir yardımcı pilottur.
Bu atölye çalışması, profesyonel yazılım geliştirme yaşam döngüsünün (SDLC) her aşamasında yapay zekayla ortak çalışma için yapılandırılmış ve tekrarlanabilir bir metodoloji sunar. Satır satır kod yazan birinden teknik yönetmene, yani vizyon sahibi bir mimara ve bu vizyonu yapay zekayı kullanarak hassasiyetle hayata geçiren bir genel müteahhide dönüşeceksiniz. 🚀
Bu eğiticiyi tamamladığınızda:
- Yapay zekayı kullanarak üst düzey bir fikri bulut mimarisine dönüştürme
- Hedeflenen ve belirli istemlerle eksiksiz bir Python arka ucu oluşturdu.
- Hata ayıklama ve kodu düzeltme için yapay zekayı yardımcı programcı olarak kullanma
- Mock'lar da dahil olmak üzere birim testlerinin oluşturulması için yapay zekayı yetkilendirme.
Terraform ile üretime hazır kod olarak altyapı (IaC) oluşturun.
Tek bir istemle GitHub Actions'ta tam bir CI/CD ardışık düzeni oluşturdu.
Yapay zeka destekli operasyonel araçları kullanarak canlı uygulamanızı izleyip yönetin.
Çalışan bir uygulamanın yanı sıra yapay zeka destekli geliştirme için bir planla da ayrılacaksınız. Başlayalım!
2. Ön koşullar ve kurulum
Başlamadan önce ortamınızı hazırlayalım. Sorunsuz bir atölye deneyimi için bu adım çok önemlidir.
Yeni bir GCP hesabı oluşturma ve faturalandırmanızı bağlama
Yapay zeka aracılarımızı desteklemek için iki şeye ihtiyacımız var: temel işlevleri sağlamak üzere bir Google Cloud projesi ve Google'ın güçlü modellerine erişmek için bir Gemini API anahtarı.
1. adım: Faturalandırma hesabını etkinleştirin
- Faturalandırma hesabınızı 5 ABD doları krediyle talep edin. Bu hesabı dağıtımınız için kullanmanız gerekir. Gmail hesabınızda oturum açtığınızdan emin olun.
2. adım: Yeni bir GCP projesi oluşturun
- Google Cloud Console'a gidip yeni bir proje oluşturun.
- Google Cloud Console'a gidip yeni bir proje oluşturun.
- Sol paneli açın,
Billing
simgesini tıklayın ve faturalandırma hesabının bu GCP hesabına bağlı olup olmadığını kontrol edin.
Bu sayfayı görüyorsanız manage billing account
işaretini kontrol edin, Google Cloud deneme sürümünü seçin ve bu sürüme bağlanın.
3. adım: Gemini API anahtarınızı oluşturun
Anahtarı güvence altına alabilmek için önce anahtarınızın olması gerekir.
- Google Yapay Zeka Studio'ya gidin : https://aistudio.google.com/
- Gmail hesabınızla oturum açın.
- Genellikle soldaki gezinme bölmesinde veya sağ üst köşede bulunan "API anahtarı al" düğmesini tıklayın.
- "API anahtarları" iletişim kutusunda "Yeni projede API anahtarı oluştur"u tıklayın.
- Faturalandırma hesabı ayarlanmış olan yeni projenizi seçin.
- Sizin için yeni bir API anahtarı oluşturulur. Bu anahtarı hemen kopyalayın ve geçici olarak güvenli bir yerde (ör. şifre yöneticisi veya güvenli not) saklayın. Bu, sonraki adımlarda kullanacağınız değerdir.
GitHub ile kimlik doğrulama
Google Cloud Console'a gidip sağ üstteki "Cloud Shell'i Etkinleştir" düğmesini tıklayarak Cloud Shell'i açın.
1. adım: Cloud Shell'i açın
👉Google Cloud Console'un üst kısmında Cloud Shell'i etkinleştir'i tıklayın (Cloud Shell bölmesinin üst kısmındaki terminal şeklindeki simge).
👉 "Open Editor" (Düzenleyiciyi aç) düğmesini tıklayın (kalemli açık bir klasöre benzer). Bu işlemle pencerede Cloud Shell kod düzenleyici açılır. Sol tarafta bir dosya gezgini görürsünüz.
👉Google Cloud proje kimliğinizi bulma:
- Google Cloud Console'u açın: https://console.cloud.google.com
- Sayfanın üst kısmındaki proje açılır listesinden bu atölye çalışması için kullanmak istediğiniz projeyi seçin.
- Proje kimliğiniz, kontrol panelindeki Proje bilgileri kartında gösterilir.
👉Bulut IDE'sinde terminali açın.
👉💻 Terminalde, aşağıdaki komutu kullanarak kimliğinizin zaten doğrulandığını ve projenin proje kimliğinize ayarlandığını doğrulayın:
gcloud auth list
2. adım: GitHub ile kimlik doğrulama ve Fork
GitHub ile kimlik doğrulama:
👉💻
gh auth login
Kodu kopyalayıp giriş doğrulama sayfasına yapıştırın.
Depoyu çatallayın ve klonlayın: 👉💻
gh repo fork cuppibla/storygen-learning --clone=true
3. Mimari: Cloud Assist ile Fikirden Plan Oluşturmaya
Her büyük proje net bir vizyonla başlar. Uygulama mimarimizi tasarlamak için yapay zeka yardımcı pilotumuz Cloud Assist'i kullanacağız.
İşlemler
- Google Cloud Console'u açın: https://console.cloud.google.com
- Sağ üst köşede "Cloud Assist Sohbeti'ni aç"ı tıklayın.
Cloud Assist'i etkinleştirme
Get Gemini Assist
simgesini, ardındanEnable Cloud Assist at no cost
simgesini tıklayın.- Ve sohbet etmeye başlayın.
Cloud Destek Ekibi'ne aşağıdaki ayrıntılı istemi gönderin:
Fikrinizi Girin
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.
Uygulama Blueprint'inizi edinme
- "Uygulama tasarımını düzenle"yi tıkladığınızda şemayı görürsünüz. Terraform kodunu indirmek için sağ üstteki "<> Get Code" (Kodu Al) panelini tıklayın.
- Cloud Assist bir mimari şeması oluşturur. Bu, görsel planımız.
Önemli Öğrenme Anı: Yapay zeka, üst düzey sistem tasarımında mükemmeldir. Bu araç, yalın dildeki gereksinimleri anında profesyonel ve görsel bir mimariye çevirebilir.
4. Geliştirme: Gemini CLI ile ADK oluşturma
İlk Kurulum
Depoyu çatallamak ve çalışma alanını hazırlamak için Gemini CLI'yı kullandığımızdan emin olun:
Ortam Yapılandırması
Cloud Shell'inize gidin ve "Terminali aç" düğmesini tıklayın.
- Ortam şablonunu kopyalayın:
cd ~/storygen-learning cp ~/storygen-learning/env.template ~/storygen-learning/.env
.env Dosyasını Bulamıyorsanız Düzenleyici'de Gizli Dosyayı Görüntüleme
- Üst menü çubuğunda Görünüm'ü tıklayın.
- Gizli Dosyaları Aç/Kapat'ı seçin.
.env dosyasını düzenleme 2. .env
içinde aşağıdaki değerleri değiştirin:
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
Örneğin, proje kimliğiniz testproject
ise GOOGLE_CLOUD_PROJECT_ID=testproject
ve GENMEDIA_BUCKET=testproject-bucket
değerlerini girmelisiniz.
Kurulum komut dosyaları
00_Starting_Here'a gidin. Yeni bir terminal açın (Gemini CLI'da değil).
cd ~/storygen-learning/00_Starting_Here
Kurulumu tamamlayın:
./setup-complete.sh
Kurulum sonuçlarını terminalde görmeniz gerekir
İlk Aracınızı Oluşturma
01a_First_Agent_Ready'ye gidin. ADK aracısını oluşturmak için Gemini CLI'yı kullanalım:**
cd ~/storygen-learning/01a_First_Agent_Ready
Gemini CLI'yı açma
gemini
Gamini CLI penceresinde şu istemi deneyin:
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
İşiniz bittiğinde Control+C
ile Gemini CLI terminalini kapatın.
—————————————— İsteğe bağlı, Çözüm bölümüne geçebilirsiniz.——————————————–
ADK Web'de Değişikliğinizi Doğrulama
cd ~/storygen-learning/01a_First_Agent_Ready/backend
source ../../.venv/bin/activate
adk web --port 8080
Web Sitesini Oluşturma
cd ~/storygen-learning/01a_First_Agent_Ready
./start.sh
Değişikliğiniz çalışmazsa ADK web kullanıcı arayüzünde ve web sitesinde hatalar görmeyi beklersiniz.
——————————————– Çözüm Buradan Başlıyor ——————————————–
Çözüm
Önceki işlemi Control+C
ile sonlandırın veya başka bir terminal açabilirsiniz:
cd ~/storygen-learning/01b_First_Agent_Done
Web sitesini başlatma:
./start.sh
Web sitesini görürsünüz:
ADK kullanıcı arayüzünü deneyin: Başka bir terminal açın:
cd ~/storygen-learning/01b_First_Agent_Done/backend
source ../../.venv/bin/activate
adk web --port 8080
Temsilciye soru sorabileceğiniz ADK kullanıcı arayüzünü görürsünüz.
Bir sonraki bölüme geçmeden önce işlemi sonlandırmak için Ctrl+C tuşlarına basın.
5. Geliştirme: Imagen ile Özel Aracınızı Oluşturma
Imagen aracını oluşturma (ikinci temsilci)
cd ~/storygen-learning/02a_Image_Agent_Ready
Görüntü oluşturma aracını oluşturmak için Gemini KSA'yı kullanın:
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
"
—————————————— İsteğe bağlı, Çözüm bölümüne geçebilirsiniz.——————————————–
ADK Web'de Değişikliğinizi Doğrulama
cd ~/storygen-learning/02a_Image_Agent_Ready/backend
source ../../.venv/bin/activate
adk web --port 8080
Web Sitesini Oluşturma
cd ~/storygen-learning/02a_Second_Agent_Ready
./start.sh
Değişikliğiniz çalışmazsa ADK web kullanıcı arayüzünde ve web sitesinde hatalar görmeyi beklersiniz.
——————————————- Çözüm Buradan Başlıyor ——————————————–
Çözüm
Önceki işlemi Control+C
ile sonlandırın veya başka bir terminal açabilirsiniz:
# Open new terminal
cd ~/storygen-learning/02b_Image_Agent_Done
Web sitesini başlatma:
./start.sh
Web sitesini görürsünüz:
ADK kullanıcı arayüzünü deneyin: Başka bir terminal açın:
# Open new terminal
cd ~/storygen-learning/02b_Image_Agent_Done/backend
source ../../.venv/bin/activate
adk web --port 8080
Temsilciye soru sorabileceğiniz ADK kullanıcı arayüzünü görürsünüz:
Bir sonraki bölüme geçmeden önce işlemi sonlandırmak için Ctrl+C tuşlarına basın.
6. Testing: Agent Evaluation
Uygulamamız çalışıyor ancak otomatik bir test güvenlik ağına ihtiyacımız var. Bu görev, yapay zeka yardımcı pilotumuza devretmek için idealdir.
İşlemler
cd ~/storygen-learning/03a_Agent_Evaluation_Ready/backend
Kapsamlı testler yazmak için Gemini KSA'yı kullanma:
Gemini KSA'yı açma
gemini
Gamini CLI penceresinde şu istemi deneyin:
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.
—————————————— İsteğe bağlı, Çözüm bölümüne geçebilirsiniz.——————————————–
Değerlendirmeyi görmek için:
./run_adk_web_persistent.sh
ADK kullanıcı arayüzünde eval
sekmesine gidin.
ADK Web kullanıcı arayüzünü kalıcı test özellikleriyle görmelisiniz
Önemli Öğrenme Anı: Yapay zeka, kalite kontrolünü otomatikleştirmede güçlü bir ortaktır. Test yazma sürecindeki standart metinleri yöneterek özellik geliştirmeye odaklanmanızı sağlar.
——————————————– Çözüm Buradan Başlıyor ——————————————–
Çözüm
- Çözüm klasörüne gidin:
cd ~/storygen-learning/03b_Agent_Evaluation_Done/backend
- ADK web kullanıcı arayüzünü açın
./run_adk_web_persistent.sh
Test senaryolarını Eval
sekmesinde görebilirsiniz:
Metrikleri buradan ayarlayın:
Değerlendirme çalıştırma sonucunu buradan görüntüleyin:
7. Kod Olarak Altyapı (IaC): Bulutta Ev İnşa Etme
Kodumuz test edildi ancak üretime hazır bir ortamda kullanılması gerekiyor. Ortamımızı tanımlamak için "Kod Olarak Altyapı"yı kullanacağız.
İşlemler
cd ~/storygen-learning/04a_Manual_Deployment_Ready
Arka uç için Dockerfile oluşturmak üzere Gemini CLI'yı kullanma: Gemini CLI'yı açın.
Gemini
Gemini CLI'da şu istemi deneyin:
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.
Çözüm:
cd ~/storygen-learning/04b_Manual_Deployment_Done
Çalıştır:
source ../.venv/bin/activate
./01-setup.sh
./02-build-images.sh
./03-deploy-infrastructure.sh
Dağıtım sonuçlarını ve altyapı oluşturma işlemini görmeniz gerekir
8. Otomasyon (CI/CD): Dijital Montaj Hattı
Uygulamamızı manuel olarak dağıtmak yavaş ve riskli. Yapay zekamızdan GitHub Actions kullanarak eksiksiz bir CI/CD ardışık düzeni yazmasını isteyelim.
İşlemler
cd ~/storygen-learning/05a_CICD_Pipeline_Ready
GitHub ile CI/CD ardışık düzeninizi oluşturmak için Gemini CLI'yı kullanma:
Gemini CLI'yı açma
Gemini
Gemini CLI'da şu istemi deneyin:
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.
——————————————– Çözüm Buradan Başlıyor ——————————————–
Çözüm:
cd ~/storygen-learning/06_Final_Solution/
# Copy the GitHub workflow to parent folder
cp -r 06_Final_Solution/.github ../../../.github
06_Final_Solution klasörüne geri dönün ve komut dosyasını çalıştırın:
cd ~/storygen-learning/06_Final_Solution/
./setup-cicd-complete.sh
CI/CD ardışık düzeni kurulumunun tamamlandığını görmelisiniz
İş Akışını Tetikleme: Kodunuzu ana dala gönderin. İzne izin vermek için GitHub e-posta adresinizi ve adınızı ayarlamanız gerektiğini unutmayın.
git add .
git commit -m "feat: Add backend, IaC, and CI/CD workflow"
git push origin main
Otomatik dağıtımınızın çalışmasını izlemek için GitHub kod deponuzdaki "Actions" (İşlemler) sekmesine gidin.
Önemli Öğrenme Anı: DevOps'un karmaşık ve kritik bir parçası olan CI/CD ardışık düzeninin tamamı yapay zeka tarafından oluşturulabilir.
9. İşlemler: Yapay Zeka Kontrol Kulesi
Canlı yayındayız! Ancak yolculuk henüz bitmedi. Bu, "2. Gün" yani operasyonlar. Çalışan uygulamamızı yönetmek için Cloud Assist'e dönelim.
İşlemler
- Google Cloud Console'da Cloud Run hizmetinize gidin. Biraz trafik ve günlük oluşturmak için canlı uygulamanızla etkileşimde bulunun.
- Cloud Assist bölmesini açın ve aşağıdaki gibi istemlerle operasyonel yardımcı pilot olarak kullanın:
Günlük Analizi:
Summarize the errors in my Cloud Run logs for the service 'genai-backend' from the last 15 minutes.
Performans Ayarı:
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?
Maliyet optimizasyonu:
Analyze the costs for my 'genai-backend' service and its GCS bucket. Are there any opportunities to save money?
Önemli Öğrenme Anı: Yapay zeka SDLC'si sürekli bir döngüdür. Uygulamanın oluşturulmasına yardımcı olan yapay zeka yardımcı pilotu, üretimde izleme, sorun giderme ve optimizasyon için vazgeçilmez bir iş ortağıdır.