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.
- Sol paneli açın,
Billingsimgesini 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 AI 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ındaki "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. 
👉Düzenleyiciyi açtıktan sonra bulut IDE'sinde terminali açın.
👉💻 Terminalde, aşağıdaki komutu kullanarak kimliğinizin 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:
👉💻 Komutu kopyalayıp bulut terminalinize yapıştırın:
gh auth login
- "GitHub'ı nerede kullanıyorsunuz?" bölümünde "GitHub.com"u seçin.
- "Bu ana makinede Git işlemleri için tercih ettiğiniz protokol nedir?" sorusuna "HTTPS" yanıtını verin.
- "Authenticate Git with your GitHub credentials?" (Git'in kimliğini GitHub kimlik bilgilerinizle doğrulayacak mısınız?) sorusuna "Yes" (Evet) yanıtını verin.
- "How would you like to authenticate GitHub CLI?" (GitHub CLI'nin kimliğini nasıl doğrulamak istersiniz?) sorusuna "Login with a web browser" (Web tarayıcısıyla giriş yap) yanıtını verin.
Önemli: Henüz "Enter" tuşuna basmayın.
Kodu terminalden kopyalayıp giriş doğrulama sayfasına yapıştırın.
Kodu girmeyi tamamladığınızda Cloud Shell terminalinize dönün ve devam etmek için "Enter" tuşuna basın.
4. adım: Depoyu çatallayın ve klonlayın:
👉💻 Komutu kopyalayıp bulut terminalinize yapıştırı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](Google Cloud Console)
- Sağ üst köşede "Cloud Assist Sohbeti'ni aç"ı tıklayın.
Cloud Assist'i etkinleştirme
Get Gemini Assistsimgesini, ardındanEnable Cloud Assist at no costsimgesini 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.
Bu kodla ilgili herhangi bir işlem yapmanız gerekmez. Daha fazla açıklama için aşağıyı okuyun.
Oluşturulan Terraform Kodunu Anlama Cloud Assist'ten yeni bir Terraform dosyaları grubu aldınız. Şu an için bu kodla ilgili herhangi bir işlem yapmanız gerekmez. Ancak bu kodun ne olduğunu ve neden bu kadar güçlü olduğunu kısaca açıklayalım.
Terraform nedir? Terraform, kod olarak altyapı (IaC) aracıdır. Bunu, bulut ortamınızın kodla yazılmış bir planı olarak düşünebilirsiniz. Hizmet, depolama ve izin oluşturmak için Google Cloud Console'da manuel olarak tıklamak yerine tüm bu kaynakları yapılandırma dosyalarında tanımlarsınız. Ardından Terraform, planınızı okur ve sizin için tam olarak bu ortamı otomatik olarak oluşturur.
Görsel plandan yürütülebilir koda. Cloud Assist'in sağladığı mimari şema, görsel planınızdır. Terraform kodu, aynı planın makine tarafından okunabilir sürümüdür. Tasarım konseptini tekrarlanabilir ve otomatik bir gerçeğe dönüştüren önemli bağlantıdır. Altyapınızı kodda tanımlayarak şunları yapabilirsiniz:
- Oluşturma İşlemini Otomatikleştirme: Aynı ortamı tekrar tekrar güvenilir bir şekilde oluşturun.
- Sürüm kontrolü kullanın: Altyapınızdaki değişiklikleri, uygulama kodunuzda olduğu gibi Git'te izleyin.
- Hataları Önleme: Web arayüzünde tıklama yaparken oluşabilecek manuel hatalardan kaçının.
Bu atölye çalışmasında, bu Terraform kodunu kendiniz çalıştırmanız gerekmez. Bunu, önümüzdeki adımlarda oluşturup dağıtacağınız altyapının profesyonel planı, yani "cevap anahtarı" olarak düşünebilirsiniz.
4. Geliştirme: Gemini CLI'ya Giriş
👉💻 Cloud Shell terminalinizde kişisel dizininize gidin.
cd ~/storygen-learning
👉💻 Gemini'ı ilk kez deneyin.
clear
gemini --model=gemini-2.5-flash
Do you want to connect Cloud Shell editor to Gemini CLI? sorulursa HAYIR'ı seçin.
👉✨ Her Gemini aracının açıklaması vardır. Hemen okuyun. Gemini istemine şunu yazın:
Gemini CLI'da
/help
👉✨ Gemini CLI'ın kendi yerleşik yetenekleri vardır. Bunları incelemek için:
Gemini CLI'da
/tools
ReadFile, WriteFile ve GoogleSearch'ın yer aldığı bir liste görürsünüz. Bunlar, harici bir cephanelikten yararlanmanıza gerek kalmadan kullanabileceğiniz varsayılan tekniklerdir.
👉✨ Gemini Blade, işlemlerini yönlendirmek için "taktiksel farkındalık" (bağlam) sağlayabilir.
Gemini CLI'da
/memory show
Şu anda boş bir başlangıç noktasıdır.
👉✨ Öncelikle, temsilcinin hafızasına bir karakter ekleyin. Bu, uzmanlık alanını tanımlar:
Gemini CLI'da
/memory add "I am master at python development"
Bıçağınızın bu bilgiyi aldığını onaylamak için /memory show komutunu tekrar çalıştırın.
👉✨ @ simgesiyle dosyalara nasıl referans verileceğini göstermek için önce bir "görev özeti" dosyası oluşturalım.
Yeni bir terminal açın ve görev dosyanızı oluşturmak için aşağıdaki komutu çalıştırın:
!echo "## Mission Objective: Create Imagen ADK Agent for Story Book" > mission.md
👉✨Şimdi Gemini CLI'nize brifingi analiz etmesini ve bulgularını bildirmesini söyleyin:
Gemini CLI'da
Explain the contents of the file @mission.md
Birincil silahınız artık amacının farkında.
👉💻 Gemini CLI'dan çıkmak için Ctrl+C tuşuna iki kez basın.
Öğrenme:
Gemini CLI'nin Süper Güçleri: gemini.md Devam etmeden önce Gemini CLI'nin belirli bir projeye nasıl uyarlanabileceğini anlamanız önemlidir. Genel amaçlı bir sohbet aracı olarak kullanabilirsiniz ancak gerçek gücü, özel bir yapılandırma dosyasından (gemini.md) gelir.
gemini komutunu çalıştırdığınızda, geçerli dizinde otomatik olarak bir gemini.md dosyası aranır. Bu dosya, yapay zeka için projeye özel bir talimat kılavuzu işlevi görür. Üç temel noktayı tanımlayabilir:
- Karakter: Yapay zekaya kim olması gerektiğini söyleyebilirsiniz. Örneğin, "Google Cloud konusunda uzmanlaşmış bir Python geliştiricisin." Bu, yanıtlarını ve stilini odaklar.
- Araçlar: Belirli dosyalara (@file.py) veya Google aramalarına (@google) erişim izni verebilirsiniz. Bu, yapay zekaya projenizin koduyla ilgili soruları yanıtlamak için ihtiyaç duyduğu bağlamı sağlar.
- Bellek: Yapay zekanın bu proje için her zaman hatırlaması gereken gerçekleri veya kuralları sağlayabilirsiniz. Bu, tutarlılığın korunmasına yardımcı olur.
gemini.md dosyası kullanarak genel Gemini modelini, projenizin hedefleri hakkında önceden bilgilendirilmiş ve doğru bilgilere erişimi olan uzman bir asistana dönüştürürsünüz.
5. 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 "Open Terminal" (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.
👉Google Cloud proje kimliğinizi bulun:
- Google Cloud Console'u açın: bağlantı
- 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.
👉GitHub kullanıcı adınızı bulma:
- GitHub hesabınıza gidip GitHub kullanıcı adınızı bulun.
.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
Gemini 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
Devam etmek için komut istemine ihtiyacınız var.
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.
6. 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 CLI'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.
Öğreniyor
İlk aracımız metin oluşturma konusunda harikaydı ancak artık görüntü oluşturmamız gerekiyor. Bu görev için daha doğrudan kontrole ihtiyacımız var. LLM'nin resim oluşturup oluşturmayacağına karar vermesini değil, doğrudan oluşturmasını istiyoruz. Bu, BaseAgent için mükemmel bir iş.
Bildirimsel LlmAgent'ın aksine, BaseAgent zorunludur. Bu, geliştirici olarak sizin _run_async_impl yöntemi içinde adım adım Python mantığını yazacağınız anlamına gelir. Yürütme akışı üzerinde tam kontrol sahibi olursunuz.
Aşağıdaki durumlarda BaseAgent'ı seçersiniz:
Belirleyici Mantık: Aracı, belirli ve değiştirilemez bir adım sırasını izlemelidir.
Doğrudan Araç Yürütme: Bir aracı LLM müdahalesi olmadan doğrudan çağırmak istiyorsunuz.
Karmaşık İş Akışları: Bu süreçte, özel veri manipülasyonu, API çağrıları ve bir LLM'nin yalnızca istemden güvenilir bir şekilde çıkarım yapamayacağı kadar karmaşık bir mantık yer alır.
Uygulamamızda, ilk aracıdan sahne açıklamalarını almak için bir BaseAgent kullanacağız ve her sahne için bir resim oluşturulmasını sağlamak üzere Imagen aracını doğrudan çağıracağız.
7. Test: Temsilci Değerlendirmesi
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 CLI'yı kullanma:
Gemini CLI'yı açma
gemini
Gemini 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çma
./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:
Öğreniyor
Bir aracı, hatasız çalıştığı için "çalışıyor" olabilir ancak doğru çıktıyı üretip üretmediğini nasıl bilebiliriz? Hikaye iyi mi? JSON biçimi doğru mu? Bu noktada ADK'nın değerlendirme çerçevesi devreye girer.
Aracı değerlendirmesi, aracınızın yanıtlarının kalitesini ve doğruluğunu ölçmek için tasarlanmış otomatik bir test sistemidir. Yalnızca kod hatalarını kontrol etmek yerine, aracının davranışının beklentilerinizi karşılayıp karşılamadığını kontrol eder. Çerçeve öncelikle birkaç temel dosyayı kullanır:
evalset.json: Bu, ana test paketinizi oluşturur. Bu dosyadaki her "değerlendirme durumu", örnek bir görüşme (ör. kullanıcı istemi) ve temsilcinin üretmesini beklediğiniz ideal, "altın" yanıtı içerir.
test_config.json: Bu dosya, başarı kurallarını tanımlar. Burada aşağıdaki gibi ölçütler belirleyebilirsiniz:
response_match_score: Temsilcinin yanıtı, "altın" yanıtla ne kadar yakından eşleşmelidir? (1,0 puanı, aynı olması gerektiği anlamına gelir.)
custom_evaluators: "Yanıt geçerli bir JSON olmalıdır" veya "Hikaye 100 kelimeden uzun olmalıdır" gibi kendi kurallarınızı oluşturabilirsiniz.
Bir değerlendirme çalıştırarak temsilcinizi düzinelerce senaryoya karşı otomatik olarak test edebilir, isteminizde veya araçlarınızda yapılan değişikliklerin temel işlevselliğini yanlışlıkla bozmadığından emin olabilirsiniz. Bu, üretime hazır yapay zeka temsilcileri oluşturmak için güçlü bir güvenlik ağıdır.
8. 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.
Docker nedir?
Docker, uygulamaları container'larda oluşturup çalıştırmak için kullanılan bir platformdur. Container'ı, yazılımlar için standartlaştırılmış bir kargo container'ı olarak düşünebilirsiniz. Uygulamanızın çalışması için gereken her şeyi tek ve izole bir pakette birleştirir:
- Uygulama kodunun kendisi
- Gerekli çalışma zamanı (ör. Python'ın belirli bir sürümü)
- Tüm sistem araçları ve kitaplıkları
Bu container mimarisine alınmış uygulama, Docker'ın yüklü olduğu herhangi bir makinede çalıştırılabilir. Böylece, klasik "makinemde çalışıyor" sorunu çözülür.
Bu bölümde, Gemini'dan Dockerfile oluşturmasını isteyeceğiz. Dockerfile, uygulamamızın container görüntüsünü oluşturmak için kullanılan tariftir.
İş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
9. Otomasyon (CI/CD): Dijital Montaj Hattı
Uygulamamızı manuel olarak dağıtmak, hareketli parçaları anlamak için harika bir yöntem olsa da yavaştır, manuel çaba gerektirir ve insan hatasına yol açabilir. Profesyonel yazılım geliştirmede bu sürecin tamamı, CI/CD adı verilen bir uygulama kullanılarak otomatikleştirilir.
CI/CD, Sürekli Entegrasyon ve Sürekli Dağıtım anlamına gelir. Her değişiklik yaptığınızda kodunuzu otomatik olarak derleme, test etme ve dağıtma yöntemidir.
- Sürekli Entegrasyon (CI): Bu, "derleme ve test" aşamasıdır. Bir geliştirici, paylaşılan bir depoya (ör. GitHub) kod değişikliği gönderir göndermez otomatik bir sistem devreye girer. Uygulamayı oluşturur ve yeni kodun doğru şekilde entegre olduğundan ve herhangi bir hata içermediğinden emin olmak için tüm testleri (oluşturduğumuz aracı değerlendirmeleri gibi) çalıştırır.
- Sürekli Dağıtım (CD): Bu, "yayınlama" aşamasıdır. CI aşaması başarıyla tamamlanırsa sistem, uygulamanın yeni ve test edilmiş sürümünü otomatik olarak üretime dağıtır ve kullanıcılar için yayınlar.
Bu otomatik ardışık düzen, geliştiricinin makinesindeki kodu hızlı, güvenli ve güvenilir bir şekilde üretime taşıyan bir "dijital montaj hattı" oluşturur. Bu bölümde, yapay zeka asistanımızdan GitHub Actions ve Google Cloud Build'i kullanarak bu montaj hattını bizim için oluşturmasını isteyeceğiz.
İş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.
10. İş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 aynı yapay zeka yardımcı pilotu, uygulamayı üretimde izlemek, sorunlarını gidermek ve optimize etmek için vazgeçilmez bir ortaktır.