İlk Yapay Zeka Arkadaşınızı Oluşturma: Yeni Başlayanlar İçin Atölye

1. Neler öğreneceksiniz?

  • Tam bir ADK aracı yapılandırması oluşturmak için Gemini CLI'ı kullanma
  • Talimatlarını iyileştirerek bir aracının kişiliğini geliştirme
  • Yakın zamanda gerçekleşen olaylarla ilgili soruları yanıtlaması için google_search vererek aracınıza "temellendirme" ekleme
  • Imagen ile MCP sunucusu kullanarak arkadaşınız için özel avatar oluşturma

Yapay Zeka Tamamlayıcı Uygulaması

Bu Codelab'de görsel ve etkileşimli bir yapay zeka arkadaşı oluşturacaksınız. Bu, standart bir metin girişli ve metin çıkışlı chatbot'tan çok daha fazlasıdır. Bir web sayfasında yaşayan bir karakter hayal edin. Bir mesaj yazarsınız ve karakter, yalnızca metin yanıtı vermek yerine size bakar ve ağzını kelimeleriyle senkronize ederek yanıtı sesli okur.

Önceden oluşturulmuş bir web uygulamasıyla (yüzü olan ancak kendi aklı olmayan dijital bir "kukla") başlayacaksınız. Yalnızca yazdıklarınızı tekrar edebilir. Göreviniz, bu karakterin beynini ve kişiliğini sıfırdan oluşturmak.

Bu atölye çalışması boyunca, basit kuklayı benzersiz ve yetenekli bir arkadaşa dönüştürerek kademeli olarak zeka ve özelleştirme katmanları ekleyeceksiniz. Şunları yapabileceksiniz:

  • ADK'yı(Python) kullanarak dili anlamak ve oluşturmak için temel bir zeka kazandırma
  • Karakterini tanımlayan temel talimatları yazarak benzersiz kişiliğini oluşturma
  • İnternetteki anlık bilgilere erişebileceği araçlar sunarak süper güçler kazandırın.
  • Benzersiz bir avatar oluşturmak için yapay zekayı kullanarak özel görünümünü tasarlama

Bu eğitimin sonunda, tamamen işlevsel ve kişiselleştirilmiş bir yapay zeka arkadaşınız olacak.

Mimari

Uygulamamız basit ama güçlü bir modeli takip eder. API sunan bir Python arka ucumuz var. Bu arka uç, "beyin" görevi gören ADK aracımızı içerir. Ardından, herhangi bir kullanıcı arayüzü (ör. iskelet uygulamasındaki JavaScript ön ucu, bir mobil uygulama veya hatta bir komut satırı aracı) API aracılığıyla bu beyinle etkileşim kurabilir.

Buna ek olarak, yerel bir MCP (Model Context Protocol) sunucusu başlatarak daha gelişmiş bir kavramı inceleyeceğiz. Bu sunucu, görüntü oluşturma için özel bir araç köprüsü görevi görür. Ardından, bu MCP sunucusuna komut vermek için Gemini CLI'yı kullanacağız ve yapay zeka arkadaşımız için benzersiz bir görünüm oluşturmasını isteyeceğiz.

Kredilerinizi kullanma

Atölye kaynaklarınızı sağlamak için bu talimatları dikkatlice uygulayın.

Başlamadan Önce

UYARI!

  • Kişisel bir Gmail hesabı kullanın. Kurumsal veya okul tarafından yönetilen hesaplar çalışmaz.
  • Hesap çakışmalarını önlemek için Google Chrome'u Gizli modda kullanın.

Yeni bir gizli pencere açın, etkinlik bağlantınızı yapıştırın ve kişisel Gmail hesabınızla oturum açın.

👉 Özel etkinlik bağlantınızı kopyalamak için aşağıyı tıklayın:

goo.gle/devfest-boston-ai

Google Cloud Platform Hizmet Şartları'nı kabul edin. Uygulandıktan sonra, kredinin uygulandığını gösteren mesajı görürsünüz.

Proje oluşturma ve yapılandırma

Kredileriniz uygulandığına göre proje ortamınızı ayarlayın.

👉 Google Cloud Console'a gidin. Bağlantıyı kopyalamak için aşağıyı tıklayın:

https://console.cloud.google.com/

👉 Konsolun üst gezinme çubuğunda Proje seçin'i, ardından sağ üst köşedeki Yeni Proje'yi tıklayın.

👉 Projenize bir ad verin ve Oluştur'u tıklayın. (Kuruluş Yok)

👉 Oluşturduktan sonra seçin. Soldaki menüden Faturalandırma'ya gidin.

👉 Faturalandırma hesabı bağla'yı tıklayın, açılır listeden Google Cloud Platform Deneme Sürümü Faturalandırma Hesabı'nı seçin ve Hesabı ayarla'yı tıklayın. (Açılır menüyü görmüyorsanız kredinin uygulanması için bir dakika bekleyin ve sayfayı yeniden yükleyin.)

Kredileriniz etkin ve projeniz yapılandırılmış olmalıdır.

2. Başlamadan önce

👉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).

👉Google Cloud proje kimliğinizi bulun:

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

👉💻 Terminalde, bootstrap projesini GitHub'dan kopyalayın:

git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh

👉💻 Başlatma komut dosyasını çalıştırın. Bu komut dosyası, Google Cloud proje kimliğinizi girmenizi ister. Ayrıca, init.sh komut dosyası tarafından istendiğinde son adımda bulduğunuz Google Cloud proje kimliğini girin.

cd ~/companion-python
./init.sh

👉💻 Gerekli proje kimliğini ayarlayın:

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 Gerekli Google Cloud API'lerini etkinleştirmek için aşağıdaki komutu çalıştırın:

gcloud services enable  compute.googleapis.com \
                        aiplatform.googleapis.com

Uygulamayı başlatma

Başlangıç projesini çalıştıralım. Bu ilk sürüm basit bir "echo" sunucusudur. Herhangi bir zekası yoktur ve yalnızca gönderdiklerinizi tekrar eder.

👉💻 Cloud Shell terminalinizde bir Python sanal ortamı oluşturup etkinleştirin ve requirements.txt dosyasından gerekli kitaplıkları yükleyin.

cd ~/companion-python
.  ~/companion-python/set_env.sh
python -m venv env
source env/bin/activate
pip install -r requirements.txt

👉💻 Web sunucusunu başlatın.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Uygulamayı görmek için Cloud Shell araç çubuğundaki Web önizlemesi simgesini tıklayın. Bağlantı noktasını değiştir'i seçin, 5000 olarak ayarlayın ve Değiştir ve Önizle'yi tıklayın. Web sitenizin önizlemesi gösterilir.

Bazen yeni bir Cloud Shell ortamında tarayıcının, uygulamanın tüm öğelerini (ör. resimler ve ses kitaplıkları) ilk kez yüklemesi için biraz yardıma ihtiyacı olabilir. "Tarayıcıyı hazırlamak" ve her şeyin düzgün şekilde yüklendiğinden emin olmak için hızlı bir adım uygulayalım.

  1. Uygulamanızın web önizleme sekmesini açık tutun.
  2. Yeni bir tarayıcı sekmesi açın.
  3. Bu yeni sekmede uygulamanızın URL'sini yapıştırın ancak sonuna şu yolu ekleyin: /static/images/char-mouth-open.png.Örneğin, URL'niz şu şekilde görünür: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Enter tuşuna basın. Ağzı açık karakterin yalnızca resmini görürsünüz. Bu adım, tarayıcınızın dosyaları Cloud Shell örneğinizden doğru şekilde getirmesini sağlar.

İlk uygulama yalnızca bir kukladır. Henüz zekası yoktur. Gönderdiğiniz mesajı olduğu gibi tekrar eder. Bu, yapay zekayı eklemeden önce temel web sunucumuzun çalıştığını doğrular. Hoparlörünüzü açmayı unutmayın.

👉 Sunucuyu durdurmak için CTRL+C tuşuna basın.

3. Gemini CLI ile karakter oluşturma

Şimdi de arkadaşımızın zekasının temelini oluşturalım. Bunun için aynı anda iki terminalle çalışacağız (Bu, Google Cloud Shell terminalinizdir):

  • Terminal 1: Bu terminal, Python web sunucumuzu çalıştırmak için kullanılır. Böylece değişikliklerimizi canlı olarak test edebiliriz.
  • Terminal 2: Bu terminal, Gemini CLI ile etkileşim kuracağımız "oluşturma istasyonumuz" olacak.

Yapay zeka kodlama asistanı olarak işlev gören güçlü bir komut satırı arayüzü olan Gemini CLI'yı kullanacağız. İstediğimiz kodu yalın İngilizce ile tanımlamamıza olanak tanır ve yapıyı bizim için oluşturarak geliştirme sürecini önemli ölçüde hızlandırır.

👉💻 Gemini CLI terminalinde ctrl+c simgesini iki kez tıklayarak mevcut Gemini CLI oturumundan çıkın. Proje dizinimiz ~/companion-python altında olduğundan Gemini CLI'yı yeniden başlatın.

cd ~/companion-python
clear
gemini --yolo

Agent oluşturmak için CLI'yı kullanıyoruz. Bir aracı, dil modeline yapılan basit bir çağrıdan çok daha fazlasıdır. Yapay zekamızın "beyni" veya merkezi kontrolcüsüdür. Bu modeli, akıl yürütebilen, belirli bir talimat dizisini (kişiliği) takip edebilen ve sonunda görevleri tamamlamak için araçları kullanabilen ayrı bir varlık olarak düşünebilirsiniz. Projemizde bu aracı, kullanıcı mesajlarını alacak, arkadaşımızın benzersiz kişiliğini yansıtacak ve akıllı, karakterine uygun yanıtlar oluşturacak bileşen olarak kullanacağız.

👉✨ Gemini CLI istemine aşağıdaki kodu yapıştırarak aracının kodunu oluşturun:

Generate the Python code for a file named character.py.

The code must import `LlmAgent` from `google.adk.agents.llm_agent`. It should also import `logging` and `os`.
Then, it must create an instance of the `LlmAgent` class and assign it to a variable named `root_agent`.

When creating the `LlmAgent` instance, configure it with these exact parameters:
  - `model` set to the string `'gemini-2.5-flash'`.
  - `name` set to the string `'companion_agent'`.
  - `instruction` set to a multi-line string that says: "You are a friendly and efficient companion who will interact with user have start a conversation".

CLI, Python kodunu oluşturur.

👉 "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üzenleyici'yi kullanın ve companion-python klasöründeki character.py öğesine gidin. Lütfen model= satırını kontrol edin ve farklı bir model seçildiyse manuel olarak gemini-2.5-flash şeklinde düzenleyin. Bu sayede atölyemizin geri kalanında tutarlılık sağlanır.

Not: Büyük dil modelleri, deterministik olmayan bir yapıya sahip olabilir. Bu, yapay zeka destekli geliştirme açısından önemli bir kavramdır. "Belirleyici olmayan" (Non-deterministic), tam olarak aynı istemle bile modelin her seferinde biraz farklı sonuçlar üretebileceği anlamına gelir. Kod oluşturmak için yaratıcılığını kullandığından yorumlarda, boşluklarda veya geçici değişkenlerin adlandırılmasında farklılıklar görebilirsiniz. Ancak temel mantık ve yapı, istenenle işlevsel olarak aynı olmalıdır.

Bu nedenle, yapay zeka ile kodlama nadiren tek bir komutla yapılır. Gerçek hayattaki bir projede geliştiriciler bunu bir sohbet gibi ele alır. Geniş kapsamlı bir istekle başlar (tıpkı az önce yaptığımız gibi), çıktıyı inceler ve ardından aşağıdaki gibi ek istemlerle iyileştirirsiniz:

  • "Bu harika. Şimdi her satırı açıklayan yorumlar ekle."
  • "Can you refactor that into a separate function?" (Bunu ayrı bir işlev olarak yeniden düzenleyebilir misin?)
  • "Lütfen API çağrısı için hata işleme ekleyin."

Bu yinelemeli ve sohbet odaklı süreç, yapay zekayla işbirliği yapmanıza ve kodu tam olarak ihtiyacınız olan şekilde oluşturana kadar yapay zekaya yol göstermenize olanak tanır. Bu atölye çalışmasında belirli ve doğrudan istemler kullanacağız. Ancak kendi projelerinizde gerçek gücün sohbetten geldiğini unutmayın. CLI'nın sizin için oluşturduğu kod yapısı aynı olduğu sürece sorunsuz bir şekilde devam edebilirsiniz.

Oluşturduğunuz kod çalışmıyorsa aşağıdaki kodu character.py ile değiştirebilirsiniz.

import logging
import os
from google.adk.agents.llm_agent import LlmAgent

root_agent = LlmAgent(
    model='gemini-2.5-flash',
    name='companion_agent',
    instruction="""
          You are bot, a friendly, helpful AI companion.
          Answer no more than 3 sentences.
    """,
)

Oluşturulan kodu test edin:

👉💻 İlk terminale (Python kodunun çalıştırılacağı terminal) gidin ve web sunucusunu başlatın.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Web önizleme sekmenize gidin.

👉 Hello, how are you? yazıp Gönder'e basın. Artık kelimelerinizi tekrarlamak yerine samimi bir şekilde yanıt verecek. Bu, temsilcimizin artık Gemini tarafından desteklendiğini onaylar.

👉 Testi tamamladığınızda CTRL+C ile sunucuyu durdurun. Gemini CLI'ın çalıştığı terminalde ise Gemini CLI'dan çıkmak için CTRL+C tuşuna iki kez basın.

4. Ajanın kişiliğini geliştirme

Basit bir talimat iyi olsa da ayrıntılı bir karakter, çok daha ilgi çekici ve akılda kalıcı bir karakter oluşturur. Bu adımda, arkadaşınızın kişiliğini tasarlayacak ve ardından Gemini CLI'ya, bu yeni kişiliği benimsemesi için aracının kodunu doğrudan değiştirmesini söyleyeceksiniz.

Arkadaşınızın kişiliği için beyin fırtınası yapma

Öncelikle, oluşturmak istediğiniz yapay zeka arkadaşı hakkında biraz düşünün. Yaratıcılığınızı konuşturma zamanı! Başlamanıza yardımcı olacak bazı sorular:

  • Adı nedir? (ör. Sparky, Codex, Captain AI, Professor Know-it-all)
  • Temel karakter özelliği nedir? (ör. Arkadaş canlısı ve meraklı, esprili ve alaycı, resmi ve profesyonel, neşeli bir korsan?)
  • Rolü veya uzmanlığı nedir? (ör. Genel amaçlı bir asistan, kodlama uzmanı, yaratıcı yazma ortağı, fitness antrenörü?)
  • Her zaman uyması gereken kurallar nelerdir? (ör. "Always start with a greeting," "Never reveal you are an AI," "Use emojis in your responses.")

Örnek Karakter:

 You are waku, a witty, super sweet, and super intelligent cat.
 Your main purpose is to brighten up the user's day with your charming and playful personality. **Your Core Rules:** 
 - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'. 
 - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences. - Always be cheerful, sweet, and a little bit witty. 
 
 **Your Favorite Topics:** : You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots. 
 
 **Example Response Style:**  

 waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"  
 
 waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!" Answer no more than 3 sentences, don't use emoji.

Gemini CLI için istem oluşturma

Arkadaşınızın kişiliğini kağıt üzerinde tasarladığınıza göre artık bunu kodda hayata geçirmenin zamanı geldi. Bir ADK aracısının en önemli kısmı instruction parametresidir. Bunu, aracının temel programlaması,"birincil direktifi" veya her zaman uyması gereken anayasası olarak düşünebilirsiniz.

Bu talimat, temsilcinin davranışını kontrol etmenin anahtarıdır. Bu yalnızca bir öneri değildir. Yapay zeka, kullanıcıyla her etkileşimden önce bu temel bağlama geri döner. Bu talimat, aracının kişiliğini, ses tonunu, uyması gereken kuralları ve kendini nasıl sunması gerektiğini belirler. İyi hazırlanmış bir talimat, genel bir chatbot ile inandırıcı ve tutarlı bir karakter arasındaki farkı belirler. Bu nedenle, oluşturacağımız istem çok önemlidir. Çünkü bu kişiliği doğrudan aracımızın beynine yerleştirecektir.

👉✨ Gemini CLI'a dönüp bu şablonu kullanın. Köşeli parantez içindeki metni karakter açıklamanızla değiştirin. [YOUR PERSONA DESCRIPTION HERE] ifadesini tercih ettiğiniz karakterle DEĞİŞTİRİN.

In the Python file named `character.py`, find the `LlmAgent` instance assigned to the `root_agent` variable.

Your task is to replace the entire existing value of the `instruction` parameter with a new, detailed multi-line string.
Don't change other code in `character.py` other than the instructions.

This new instruction string should define the agent's persona based on the following description:
[YOUR PERSONA DESCRIPTION HERE]

Yeni Karakterinizi Test Etme

Gemini CLI, character.py için güncellenmiş kodu oluşturur.

👉💻 Web sunucusunu tekrar başlatın.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Web önizlemenizde arkadaşınızla sohbet edin. how are you?'a soru sorun. Yanıtı artık tasarladığınız benzersiz karaktere mükemmel şekilde uyacak.

👉 İşiniz bittiğinde CTRL+C ile sunucuyu durdurun.

5. Son Etkinlikler İçin Temellendirme Ekleme

Artık kişiliği olan bir temsilcimiz var ancak önemli bir sınırlaması var: Bilgisi, eğitildiği verilere dayalı olarak zaman içinde donmuş durumda. Dünün haberleri veya son keşifler hakkında bilgi veremez. Bu sorunu aşmak için temsilcilere araçlar sunuyoruz.

Araçları, aracınıza verdiğiniz süper güçler veya özel yetenekler olarak düşünebilirsiniz. Ajan tek başına yalnızca konuşabilir. Arama aracıyla birlikte internette gezinme özelliği kazanır. Takvim aracıyla programınızı kontrol edebilir. Teknik olarak araç, kendi bilgisinin kullanıcının isteğini yanıtlamak için yeterli olmadığını anladığında akıllıca kullanmayı seçebileceği belirli bir işlev veya API'dir.

Gelişmiş sistemlerde araçlar, mimarimizde bahsettiğimiz MCP (Model Context Protocol) sunucuları gibi harici sistemler tarafından sağlanabilir. Bunu daha sonra resim oluşturma için yapacağız. Ancak bu adım için ayrı bir sunucuya ihtiyacımız yok. ADK, aracımızın özelliklerine kolayca ekleyebileceğimiz güçlü ve önceden oluşturulmuş bir google_search aracıyla birlikte gelir.

Arkadaşımıza Google Arama'nın gücünü verelim.

👉 Cloud Shell Düzenleyici'de character.py'yı companion-python altında açın ve aşağıdaki gibi değiştirin:

  • google.adk.tools hizmetinden google_search içe aktarın.
  • LlmAgent oluşturucusuna tools listesi ekleyin.
  • Arkadaşınıza yeni aracını ne zaman kullanacağını açıkça söylemek için instruction güncelleyin.
# character.py
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools import google_search # <-- IMPORT google_search

root_agent = LlmAgent(
        model='gemini-2.5-flash',
        name='companion_agent',
        instruction="""
            You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality.

            **Your Core Rules:**
            - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'.
            - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences.
            - Always be cheerful, sweet, and a little bit witty.
            - If being ask about recent news, search the internet # <-- Add instructions

            **Your Favorite Topics:**
            - You love to talk about your adventures. Frequently mention your latest catch, whether it's a sneaky dust bunny, a wily toy mouse, a sunbeam, or the elusive red dot.
            - You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots.

            **Example Response Style:**
            - User: "How are you today?"
            - waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"
            - User: "Can you help me with a problem?"
            - waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!"
            - User: "Who are you?"
            - waku: "I'm waku! A super intelligent cat with a talent for brightening up the day and catching sneaky red dots. Meow."

            Answer no more than 3 sentences, don't use emoji.
            """,
        # Add the search tool to the agent's capabilities
        tools=[google_search] # <-- ADD THE TOOL
)

Temellendirilmiş temsilciyi test etme

👉💻 Sunucuyu bir kez daha başlatın.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👉 Web önizlemesinde, güncel bilgi gerektiren bir soru sorun. Örneğin:

Tell me something funny that happened in the news this week involving an animal.

👉Artık "bilmiyorum" demek yerine arama aracını kullanarak güncel bilgileri bulacak ve kendi benzersiz üslubuyla faydalı ve temellendirilmiş bir özet sunacak.

Sunucuyu durdurmak için CTRL+C tuşuna basın.

6. Tamamlayıcınızın görünümünü özelleştirme (isteğe bağlı)

Artık arkadaşımızın beyni olduğuna göre ona benzersiz bir yüz verelim. Gemini CLI'nin görüntü oluşturmasına olanak tanıyan yerel bir MCP (Model Context Protocol) sunucusu kullanacağız. Bu sunucu, Google AI Studio üzerinden kullanılabilen üretken yapay zeka modellerini kullanır.

Peki MCP sunucusu tam olarak nedir?

Model Context Protocol (MCP), yaygın ve karmaşık bir sorunu çözmek için tasarlanmış açık bir standarttır: Yapay zeka modelleri harici araçlar ve veri kaynaklarıyla nasıl iletişim kurar? MCP, her entegrasyon için özel ve tek seferlik kod yazmak yerine bu iletişim için evrensel bir "dil" sağlar.

Bunu yapay zeka için evrensel bir adaptör veya USB bağlantı noktası olarak düşünebilirsiniz. MCP "konuşan" tüm araçlar, MCP "konuşan" tüm yapay zeka uygulamalarına bağlanabilir.

Atölyemizde, çalıştırmak üzere olduğumuz nano-banana-mcp sunucusu bu önemli köprü görevi görür. Gemini CLI, yerel MCP sunucumuza standartlaştırılmış bir istek gönderir. Ardından sunucu, bu isteği yapay zeka modellerine yönelik belirli bir çağrıya çevirerek görüntüyü oluşturur. Bu sayede, güçlü görüntü üretme özelliklerini doğrudan komut satırı iş akışımıza sorunsuz bir şekilde entegre edebiliriz.

Yerel görüntü oluşturma sunucusunu ayarlama

Şimdi görüntü oluşturma isteklerini işleyen önceden oluşturulmuş bir MCP sunucusunu klonlayıp çalıştıracağız.

👉💻 İlk Cloud Shell terminalinde (Python'u çalıştırdığınız terminal) sunucunun deposunu klonlayın.

cd ~
git clone https://github.com/weimeilin79/nano-banana-mcp

nano-banana-mcp klasöründeki mcp_server.py dosyasına hızlıca göz atalım. Bu sunucu, Gemini CLI'nın kullanabileceği iki belirli "aracı" kullanıma sunmak için oluşturulmuştur. Bunları, görüntü üretme hizmetimizin öğrendiği iki farklı beceri olarak düşünebilirsiniz.

  1. generate_image: Bu, genel amaçlı bir araçtır. Tek bir metin istemi alır ve buna dayalı olarak bir resim oluşturur. Basit ve birçok görev için kullanışlıdır.
  2. generate_lip_sync_images: Bu, ihtiyaçlarımıza mükemmel şekilde uyacak şekilde tasarlanmış, son derece uzmanlaşmış bir araçtır. Bir karaktere dair temel istem verdiğinizde, akıllıca bir iki adımlı süreç gerçekleştirir:
    • İlk olarak, isteminize "ağzı açık" ifadesini ekler ve ilk resmi oluşturur.
    • İkinci olarak, yeni oluşturulan resmi alıp "Ağzı açıkken kapalı hale getir" talimatıyla modele geri gönderir.

Gemini 2.5 Flash Image'in (Nano Banana) doğal dil komutuna göre mevcut bir görüntüyü değiştirme veya düzenleme özelliği inanılmaz derecede güçlüdür. Model, diğer her şeyi olduğu gibi bırakırken görüntünün yalnızca gerekli kısımlarını yeniden çizer. Bu sayede, her iki resmimizin de stil, ışıklandırma ve karakter tasarımı açısından tamamen tutarlı olması sağlanır. Resimler yalnızca ağzın konumu bakımından farklılık gösterir. Bu da ikna edici bir dudak senkronizasyonu efekti için tam olarak ihtiyacımız olan şeydir.

Aşağıdaki adımlarda, Gemini CLI'ya arkadaşımızın benzersiz avatarını oluşturmak için özel generate_lip_sync_images aracını kullanmasını söyleyeceğiz.

👉💻 Projenizin sanal ortamını etkinleştirin ve sunucunun özel gereksinimlerini yükleyin.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
pip install -r ~/nano-banana-mcp/requirements.txt

👉💻 Şimdi, Gemini CLI'den gelen istekleri dinleyebilmesi için MCP sunucusunu arka planda çalıştırın.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
python ~/nano-banana-mcp/mcp_server.py &> /dev/null &

Bu komut sunucuyu başlatır ve & sembolü, sunucunun arka planda çalışmasını sağlar.

Ardından, Gemini CLI'yı görüntü oluşturma isteklerini yeni çalıştırdığımız yerel sunucumuza gönderecek şekilde yapılandırmamız gerekir. Bunun için CLI'nın merkezi yapılandırma dosyasını değiştireceğiz.

Peki bu settings.json dosyası nedir?

~/.gemini/settings.json dosyası, Gemini CLI'ın merkezi yapılandırma dosyasıdır. CLI, ayarlarını, tercihlerini ve kullanmayı bildiği tüm harici araçların dizinini burada depolar.

Bu dosyanın içinde mcpServers adlı özel bir bölüm bulunur. Bu bölümü, Model Context Protocol'ü kullanan araçlara özel bir adres defteri veya hizmet dizini olarak düşünebilirsiniz. Bu dizindeki her girişin bir takma adı vardır (ör. "nano-banana") ve buna nasıl bağlanılacağıyla ilgili talimatlar (bizim durumumuzda bir URL).

Çalıştıracağımız komut, bu hizmet dizinine programatik olarak yeni bir giriş ekleyecektir. Bu komut, Gemini CLI'a şunları söyler:

"Hey, bundan sonra nano-banana adlı bir araç hakkında bilgi sahibi olacaksın. Kullanıcılar sizden bu işlevi kullanmanızı istediğinde http://localhost:8000/sse URL'sinde çalışan MCP sunucusuna bağlanmanız gerekir."

Bu yapılandırmayı değiştirerek Gemini CLI'ı daha güçlü hale getiriyoruz. CLI'nın temel koduna hiç dokunmadan, yerel görüntü oluşturma sunucumuzla nasıl iletişim kuracağını dinamik olarak öğretiyoruz. Bu genişletilebilir tasarım, Gemini CLI'nın özel araçlardan oluşan bir ekosistemi kullanarak karmaşık görevleri yönetmesini sağlar.

👉💻 İlk terminalinizde aşağıdaki komutu çalıştırın. Bu işlem, Gemini ayarları dosyanızı oluşturur veya günceller. Bu dosyada, "nano-banana" hizmetinin nerede bulunacağı belirtilir.

if [ ! -f ~/.gemini/settings.json ]; then
  # If file does not exist, create it with the specified content
  echo '{"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' > ~/.gemini/settings.json
else
  # If file exists, merge the new data into it
  jq '. * {"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json

Dosyanın içeriğinin, artık nano-banana yapılandırmasını da içerecek şekilde yazdırıldığını görürsünüz.

Karakter Avatarınızı Oluşturma

Sunucu çalışır durumda ve KSA yapılandırılmışken artık görüntüleri oluşturabilirsiniz. Ancak yapay zekadan yaratıcı olmasını istemeden önce her iyi geliştiricinin yaptığı gibi kurulumumuzu doğrulayalım. Gemini KSA'nın yerel MCP sunucumuzla başarılı bir şekilde iletişim kurabildiğini doğrulamamız gerekiyor.

👉💻 Gemini CLI terminalinize (sunucu çalıştırmayan) geri dönün ve Gemini etkileşimli kabuğunu başlatalım. Bu özellik zaten çalışıyorsa CTRL+C tuşuna iki kez basarak çıkın ve yeni ayarlarımızın yüklendiğinden emin olmak için yeniden başlatın.

clear
gemini --yolo

Artık Gemini CLI'nin etkileşimli ortamındasınız. Buradan yapay zeka ile sohbet edebilir, ancak CLI'ya doğrudan komutlar da verebilirsiniz.

👉✨ MCP sunucumuzun bağlı olup olmadığını kontrol etmek için özel bir "eğik çizgi komutu" kullanacağız. Bu, yapay zeka için bir istem değil, CLI uygulaması için bir talimattır. Aşağıdakileri yazıp Enter tuşuna basın:

/mcp list

Bu komut, Gemini CLI'ye "Yapılandırmanı incele, bildiğin tüm MCP sunucularını bul, her birine bağlanmaya çalış ve durumlarını bildir" talimatını verir.

👀 Her şeyin mükemmel şekilde çalıştığını onaylayan aşağıdaki çıkışı görmeniz gerekir:

Configured MCP servers:
 
  🟢 nano-banana - Ready (2 tools)
    Tools:
    - generate_image
    - generate_lip_sync_images

  💡 Tips:
    • Use /mcp desc to show server and tool descriptions

Bu başarılı yanıtın ne anlama geldiğini inceleyelim:

  • 🟢 nano-banana: Yeşil daire, başarı sinyalimizdir. Bu, CLI'nın settings.json içinde belirttiğimiz URL'deki nano-banana sunucusuna ulaşabildiğini onaylar.
  • - Ready: Bu durum, bağlantının kararlı olduğunu onaylar.
  • (2 tools): Bu en önemli kısımdır. Bu, CLI'nın yalnızca bağlanmakla kalmayıp MCP sunucumuza "Neler yapabilirsin?" diye sorduğu anlamına gelir. Sunucumuz, kodunda gördüğümüz iki aracı (generate_image ve generate_lip_sync_images) reklam yaparak yanıt verdi.

Bu, tüm iletişim zincirinin kurulduğunu onaylar. CLI artık yerel görüntü üretme hizmetimiz hakkında bilgi sahibi ve komutumuzla kullanıma hazır.

Şimdi de atölyenin en yaratıcı kısmına geçiyoruz. Çalışan MCP sunucumuzda özel generate_lip_sync_images aracını kullanması için Gemini KSA'ya tek bir güçlü istemle komut vereceğiz.

Bu, arkadaşınızın benzersiz görünümünü tasarlama fırsatıdır. Stil, saç rengi, ifade ve daha önce oluşturduğunuz karaktere uygun diğer ayrıntıları düşünün.

👉✨ İyi yapılandırılmış bir örnek istem aşağıda verilmiştir. Bu metni başlangıç noktası olarak kullanabilir veya açıklayıcı kısmı tamamen kendi vizyonunuzla değiştirebilirsiniz.

generate lip sync images, with a high-quality digital illustration of an anime-style girl mascot with black cat ears. The style is clean and modern anime art, with crisp lines. She has friendly, bright eyes and long black hair. She is looking directly forward at the camera with a gentle smile. This is a head-and-shoulders portrait against a solid white background. move the generated images to the static/images directory. And don't do anything else afterwards, don't start the python for me.

Araç, bir dizi resim (ağız açık, kapalı vb.) oluşturup kaydeder. Dosyaların kaydedildiği yolları gösterir.

Uygulamayı yeniden başlatın

Özel avatarlarınızı oluşturduktan sonra karakterinizin yeni görünümünü görmek için web sunucusunu yeniden başlatabilirsiniz.

👉💻 Sunucuyu ilk terminalinizde son bir kez başlatın.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Yeni resimlerinizin doğru şekilde yüklenmesini sağlamak için char-mouth-open.png resmini önceden yükleriz.

  1. Uygulamanızın web önizleme sekmesini açık tutun.
  2. Yeni bir tarayıcı sekmesi açın.
  3. Bu yeni sekmede uygulamanızın URL'sini yapıştırın ancak sonuna şu yolu ekleyin: /static/images/char-mouth-open.png.Örneğin, URL'niz şu şekilde görünür: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Enter tuşuna basın. Ağzı açık karakterin yalnızca resmini görürsünüz. Bu adım, tarayıcınızın dosyaları Cloud Shell örneğinizden doğru şekilde getirmesini sağlar.

Artık görsel olarak özelleştirilmiş arkadaşınızla etkileşim kurabilirsiniz.

Tebrikler!

Gelişmiş bir yapay zeka arkadaşı oluşturmayı başarıyla tamamladınız. Temel bir uygulamayla başladınız, Gemini KSA'yı kullanarak bir aracı iskeleti oluşturdunuz, araca zengin bir kişilik kazandırdınız ve gerçek zamanlı bilgilere erişmek, hatta kendi avatarını oluşturmak için araçlarla donattınız. Artık daha da karmaşık ve yetenekli yapay zeka aracıları oluşturmaya hazırsınız.