Uçtan Uca Yapay Zeka Temsilcisi - Çalıştay

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 yazmaktan teknik yönetmenliğe, yani vizyon sahibi bir mimar ve bu vizyonu yapay zeka kullanarak hassasiyetle hayata geçiren bir genel müteahhit olmaya geçiş yapacaksınız. 🚀

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ı eşli programcı olarak kullanma
• Mock'lar da dahil olmak üzere birim testlerinin oluşturulması için yapay zekaya yetki verildi.
• 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 uygulamayla birlikte, 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 krediyi dağıtımınız için kullanmanız gerekir. Gmail hesabınızda oturum açtığınızdan emin olun.

Kredi kartı veya ödeme gerekmez. 5 ABD doları tutarında ücretsiz kredi alırsınız. Bu işlem 2 dakikadan kısa sürer. Adınızı girip kredileri kabul etmeniz yeterlidir.

2. adım: Yeni bir GCP projesi 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 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

GitHub ve Google Cloud projeniz için aynı Gmail hesabını kullandığınızdan emin olun.

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şlem, pencerede Cloud Shell kod düzenleyiciyi açar. 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

Kimliği GitHub ile doğrulama:

👉💻 Komutu kopyalayıp bulut terminalinize yapıştırın:

gh auth login

• "Where do you use GitHub" (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.

GitHub kimlik doğrulama sayfasını açmak için bağlantıyı terminalden kopyalayıp yapıştırmanız gerektiğini unutmayı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 harika 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 Assist simgesini, ardından Enable Cloud Assist at no cost simgesini tıklayın.
• Ve sohbet etmeye başlayın.

Cloud Destek'e aşağıdaki ayrıntılı istemi girin:

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 diyagramı 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ızdır.

Bu kodla ilgili herhangi bir işlem yapmanız gerekmez. Daha fazla açıklama için aşağıdaki bölümü 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 kritik 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 kodunuz gibi Git'te izleyin.
• Hataları Önleme: Bir 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, profesyonel bir plan olarak, önümüzdeki adımlarda oluşturup dağıtacağınız altyapının "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'nin 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) sahibi olabilir.

Gemini CLI'da

/memory show

Şu anda boş bir durumdadı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 başvurulacağını 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 anlamak önemlidir. Bu aracı genel amaçlı bir sohbet aracı olarak kullanabilirsiniz ancak gerçek gücü gemini.md adlı özel yapılandırma dosyasından 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 uzman bir Python geliştiricisin." Bu sayede yanıtları ve tarzı daha odaklı olur.
• 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

Ortam Yapılandırması

Cloud Shell'inize gidin ve "Terminali aç" düğmesini tıklayın.

1. 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 bulma:

• 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.

Yeni bir terminal penceresi açabilir veya Ctrl+C tuşlarına basarak mevcut ADK web sunucusunu durdurabilirsiniz.

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

ADK kullanıcı arayüzünde, ajana soru sorabilirsiniz.

Bir sonraki bölüme geçmeden önce işlemi sonlandırmak için Ctrl+C tuşlarına basın.

6. Geliştirme: Gemini CLI ile ADK oluşturma - (Bağlam Mühendisliği Yöntemi)

İlk Kurulum

01a_First_Agent_Ready/backend/story_agent/agent.py dosyasında daha önce oluşturduğumuz aracı dosyasını sildiğimizden emin olun:

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/backend

Gemini CLI'yı açma

gemini

Gemini CLI penceresinde şu istemi deneyin:

Summarize the design doc @design.md for me, do not attempt to create file just yet. 

👉💻 Ctrl+C tuşuna iki kez basarak Gemini'dan kısa süreliğine çıkabilirsiniz.

👉💻 Kurallar dosyasını yazmak için terminalinizde aşağıdaki komutu çalıştırın.

cat << 'EOF' > GEMINI.md
  ### **Coding Guidelines**
  **1. Python Best Practices:**

  *   **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
  *   **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or 
  Google Style.
  *   **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
  *   **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
  *   **Naming Conventions:**
      *   `snake_case` for variables, functions, and methods.
      *   `PascalCase` for classes.
      *   `UPPER_SNAKE_CASE` for constants.
  *   **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.

  **2. Web APIs (FastAPI):**

  *   **Data Validation:** Use `pydantic` models for request and response data validation.
  *   **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
  *   **Error Handling:** Implement centralized error handling using middleware or exception handlers.
  *   **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md

Yazılı yasalarla birlikte yapay zeka iş ortağımızı yeniden çağıralım ve yapay eserin büyüsüne tanık olalım.

👉💻 Gemini CLI'yı shadowblade dizininden yeniden başlatın:

cd ~/storygen-learning/01a_First_Agent_Ready/backend
clear
gemini

👉✨ Artık Gemini'a ne düşündüğünü göstermesini isteyebilirsiniz. Rünler okundu.

/memory show 

👉✨ Bu, ajanınızı oluşturacak tek ve güçlü komuttur. Hemen yayınlayın:

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.

Analyze the design document at `@design.md` and generate the corresponding Python code for `agent.py`.

I need you to generate a Python script based on the provided design document and reference examples. Follow these requirements:

Read the design document carefully - it contains the complete technical specification for the code you need to write
Follow the structure and patterns shown in the reference context files
Adhere to all Python best practices specified in the coding standards document
Implement every requirement mentioned in the design document exactly as specified
Use the exact variable names, function names, and string values mentioned in the specifications

The design document describes the complete architecture, dependencies, configuration, and logic flow. Your generated code must match these specifications precisely while following professional Python coding standards.
Generate clean, production-ready Python code that can be used immediately without modifications.

İş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.

Yeni bir terminal penceresi açabilir veya Ctrl+C tuşlarına basarak mevcut ADK web sunucusunu durdurabilirsiniz.

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

ADK kullanıcı arayüzünde, ajana soru sorabilirsiniz.

Bir sonraki bölüme geçmeden önce işlemi sonlandırmak için Ctrl+C tuşlarına basın.

7. Geliştirme: Imagen ile Özel Temsilcinizi Oluşturma

Imagen aracını oluşturma (ikinci temsilci)

cd ~/storygen-learning/02a_Image_Agent_Ready

Görüntü üretme 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

ADK kullanıcı arayüzünde, ajana soru sorabileceğiniz bir bölüm 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ştir.

Bildirimsel LlmAgent'ın aksine, BaseAgent zorunludur. Bu, geliştirici olarak _run_async_impl yönteminin içine adım adım Python mantığını tam olarak yazdığı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.

8. 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'ı 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 tekrarlayan görevleri hallederek ö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.

Ajan değerlendirmesi, ajanı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 öncelikli olarak 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: Ajanın 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 JSON biçiminde 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şlevini yanlışlıkla bozmadığından emin olabilirsiniz. Üretime hazır yapay zeka temsilcileri oluşturmak için güçlü bir güvenlik ağıdır.

9. 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 "Benim 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'ı kullanma: Gemini CLI'ı 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

10. 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'ı 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.

11. İş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

1. Google Cloud Console'da Cloud Run hizmetinize gidin. Biraz trafik ve günlük oluşturmak için canlı uygulamanızla etkileşimde bulunun.
2. 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.