ADK, MCP ve Memory Bank ile Kişiselleştirilmiş Aracı Oluşturma

1. Giriş

The Modern Agent Stack

Üretim düzeyinde bir yapay zeka aracısı oluşturmak için büyük bir dil modelinden (LLM) daha fazlası gerekir. LLM, muhakeme yetenekleri sağlarken güçlü bir aracının dış dünyayla etkileşime girmesi, görüşme durumunu yönetmesi ve kullanıcı tercihlerini zaman içinde hatırlaması gerekir.

Bu atölye çalışmasında, üç temel teknolojiyi kullanarak kapsamlı bir aracı sistemi tasarlamayı ve oluşturmayı öğreneceksiniz:

1. Bağlantı (MCP): Aracınıza yerel araçlara ve verilere erişim vermek için.
2. Düzenleme (ADK): Aracının muhakeme döngüsünü ve durumunu yönetmek için kullanılır.
3. Bellek (Bellek Bankası): Uzun vadeli ve kişiselleştirilmiş bağlam sağlamak için kullanılır.

Temel Kavramlar

Bileşen	İşlev
Model Context Protocol (MCP)	Yapay zeka modellerini özel entegrasyonlar olmadan harici sistemlere (veritabanları, dosya sistemleri, API'ler) bağlayan evrensel bir standarttır.
Aracı Geliştirme Kiti (ADK)	Etkinlik döngüsünü, durum geçişlerini ve araç yürütmeyi yöneterek aracılar için çalışma zamanı ortamı sağlayan bir çerçeve.
Oturum Hizmeti	Kısa süreli hafızayı yönetir. Anlık sohbet bağlamını korur (ör. "Kullanıcı az önce ne sordu?") ancak oturum sona erdiğinde temizlenir.
Vertex AI Memory Bank	Uzun süreli hafızayı yönetir. Kullanıcıya özgü bilgileri ve tercihleri (ör. "Kullanıcı Python'ı tercih ediyor") süresiz olarak saklanır. Böylece, aracı gelecekteki etkileşimleri kişiselleştirebilir.
Vertex AI Agent Engine	Aracı mantığınızı ve bellek bileşenlerinizi ölçekli olarak barındıran yönetilen altyapı hizmeti.

Ne Oluşturacaksınız?

Bu kavramları göstermek için Tatil Tasarımı Asistanı oluşturacaksınız. Bu aracı, üst düzey kullanıcı isteklerini alıp kişiselleştirilmiş kod ve resimler oluşturmak için yerel Python araçlarını bağımsız olarak düzenleyebilir.

Üç aşamada ilerlersiniz:

1. Araç Katmanı: Yerel Python işlevlerini yapay zekaya sunmak için bir MCP sunucusu oluşturun.
2. Temsilci Katmanı: Çok adımlı iş akışlarını planlayan ve yürüten bir temsilci oluşturmak için ADK'yı kullanın.
3. Bellek Katmanı: Aracının kullanıcı stili tercihlerini öğrenip hatırlamasını sağlamak için Bellek Bankası'nı entegre edin.

2. Kur

Yapay zeka aracılarımızı desteklemek için iki şeye ihtiyacımız var: temel işlevleri sağlayacak bir Google Cloud projesi.

Birinci Bölüm: Fatura Hesabını Etkinleştirme

• 5 ABD doları krediyle faturalandırma hesabınızı 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.

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.

İkinci Bölüm: Açık Ortam

1. 👉 Doğrudan Cloud Shell Düzenleyici'ye gitmek için bu bağlantıyı tıklayın.
2. 👉 Bugün herhangi bir noktada yetkilendirme yapmanız istenirse devam etmek için Yetkilendir'i tıklayın.
3. 👉 Terminal ekranın alt kısmında görünmüyorsa açın:
   • Görünüm'ü tıklayın.
   • Terminal'i tıklayın.
4. 👉💻 Terminalde, aşağıdaki komutu kullanarak kimliğinizin doğrulandığını ve projenin proje kimliğinize ayarlandığını doğrulayın:

   gcloud auth list
   

5. 👉💻 Bootstrap projesini GitHub'dan kopyalayın:

   git clone https://github.com/cuppibla/holiday_workshop
   

6. 👉💻 Kurulum komut dosyasını proje dizininden çalıştırın.

   cd ~/holiday_workshop
   ./init.sh
   

   ⚠️ Proje kimliğiyle ilgili not: Komut dosyası, rastgele oluşturulmuş bir varsayılan proje kimliği önerir. Bu varsayılanı kabul etmek için Enter tuşuna basabilirsiniz.

   Ancak belirli bir yeni proje oluşturmayı tercih ederseniz komut dosyasının istemi üzerine istediğiniz proje kimliğini yazabilirsiniz.

   Kurulum sürecinin geri kalanı, komut dosyası tarafından otomatik olarak gerçekleştirilir.
7. 👉💻 Gerekli proje kimliğini ayarlayın:

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

Üçüncü Bölüm: İzinleri ayarlama

1. 👉💻 Aşağıdaki komutu kullanarak gerekli API'leri etkinleştirin. Bu işlem birkaç dakika sürebilir.

   gcloud services enable \
       cloudresourcemanager.googleapis.com \
       servicenetworking.googleapis.com \
       run.googleapis.com \
       aiplatform.googleapis.com \
       compute.googleapis.com
   

2. 👉💻 Terminalde aşağıdaki komutları çalıştırarak gerekli izinleri verin:

   . ~/holiday_workshop/set_env.sh
   

Sizin için bir .env dosyasının oluşturulduğunu fark edin. Bu sayfada proje bilgileriniz gösterilir.

3. MCP ile Güçlenme

Yapay Zeka İçin "USB-C" Anı

Her yeni fare aldığınızda onu anakartınıza lehimlemeniz gerektiğini düşünün. Yapay zeka araçlarının durumu yakın zamana kadar böyleydi. Geliştiricilerin, LLM'leri veritabanlarına, dosya sistemlerine veya API'lere bağlamak için özel "yapıştırıcı kod" yazması gerekiyordu.

Model Context Protocol (MCP)'u girin. MCP'yi yapay zeka uygulamaları için USB-C bağlantı noktası olarak düşünebilirsiniz. Yapay zeka modellerini veri kaynaklarına ve araçlara bağlamak için standartlaştırılmış bir yöntem sunar.

Araçlarınız için bir kez MCP sunucusu oluşturursanız tek bir kod satırını bile değiştirmeden Gemini CLI'ye, bir IDE'ye veya MCP uyumlu başka bir istemciye bağlayabilirsiniz.

Ne Oluşturacaksınız?

Bu codelab'de, aşağıdakileri yapan bir Tatil Tasarımı Asistanı oluşturacaksınız:

1. MCP kullanarak yerel ortamınıza (Studio araçları) bağlanır.
2. Agent Development Kit (ADK)'yi kullanarak konuşma bağlamını güvenilir bir şekilde yönetir.
3. Tercihlerinizi hatırlar (ör. "Python kodunu tercih ederim") gibi tercihleri Vertex AI Memory Bank'i kullanarak farklı oturumlarda hatırlayabilir.

Uyarı Kod örneklerini çalıştırmadan önce Google Cloud CLI'nizi (gcloud auth login) doğruladığınızdan emin olun.

Sunucu Mantığını Oluşturma

Ortamı hazırladık ancak sunucu mantığı tamamlanmadı. Temsilcimizin sonunda tatil kartımızı oluşturmak için kullanacağı dört özel aracı uygulamamız gerekiyor.

Birinci Bölüm: Sunucu İskeletini Açma

01-MCP-Files-Testing/01-starter dizininde çalışacağız.

1. Cloud Shell terminalinizde doğru dizinde olduğunuzdan emin olun:

   cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
   

2. Aşağıdaki komutu çalıştırarak dosyayı Cloud Shell Düzenleyici'de açın:

   cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
   

Standart kodun (MCP sunucusunu ayarlama, bağlantıları işleme ve Vertex AI istemcisini başlatma) zaten tamamlandığını göreceksiniz. Ancak dört temel işlev şu anda boş yer tutuculardır.

İkinci Bölüm: Tatil Sahnesi Oluşturucu'yu uygulama

İlk olarak, kullanıcının ilgi alanını (ör. "kuşlar") ve bunu, görüntü oluşturma için optimize edilmiş zengin ve ayrıntılı bir isteme dönüştürür.

#REPLACE_GENERATE_HOLIDAY_SCENE işlevinin içindeki generate_holiday_scene yorumunu bulun.

Bu satırın tamamını aşağıdaki kodla değiştirin:

    prompt = (
        f"""
        Create a cozy, high-fidelity 3D render of a winter holiday scene.
        The scene should be warm and inviting with soft cinematic lighting.
        
        Seamlessly integrate the following specific theme/interest into the 
        holiday decor or landscape: {interest}.
        
        The style should be whimsical but detailed.
        Aspect Ratio: 16:9 Landscape.
        """
    )
    generate_image(prompt, "16:9", "static/generated_scene.png")
    return "Done! Saved at generated_scene.png"

Üçüncü Bölüm: Son Fotoğraf Sonucunu Uygulama

Son olarak, ışıklandırmanın ve tarzın fotogerçekçi ve şenlikli görünmesini istiyoruz.

Yorumu bulun #REPLACE_GENERATE_FINAL_PHOTO.

Son stil aktarımını ve oluşturma işlemini gerçekleştirmek için bu satırın tamamını aşağıdaki kodla değiştirin:

    prompt = (
        """
        Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
        
        Lighting: Warm, glowing ambient light from a fire below (out of frame).
        Background: Softly blurred (bokeh) pine garland and twinkling lights.
        
        Foreground Composition:
        1. A wooden picture frame containing the [attached selfie image]. 
           The face in the photo must be clearly visible.
        2. A folded holiday greeting card standing upright next to the frame. 
           The front of the card displays the [attached holiday scene image] as a print.
           
        Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
        """
    )
    generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
    return "Done! Saved at generated_final_photo.png"

Ortam Kurulumu

Kod yerleştirildiğine göre, bağımlılıklarımızın yüklendiğinden emin olmamız gerekiyor. Hızlı bir Python paketi ve proje yöneticisi olan uv'ı kullanacağız.

👉💻 Terminalinizde, FastMCP'yi projemizin bağımlılığı olarak eklemek için aşağıdaki komutu çalıştırın:

cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp

~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml dosyanıza yeni bir bağımlılık fastmcp>=2.13.3 eklendiğini görürsünüz.

4. MCP sunucusu için Gemini CLI ile test etme

Sunucu kodumuz tamamlandığına göre bunu nasıl test edeceğiz?

Genellikle bir arka uç sunucusunu test etmek için bir ön uç kullanıcı arayüzü oluşturmak veya karmaşık curl istekler yazmak gerekir. Ancak burada Gemini KSA'yı kullanabiliriz.

Gemini CLI nedir?

Gemini CLI, doğrudan terminalinizde bir Gemini modeliyle sohbet etmenizi sağlayan bir komut satırı aracıdır. Ancak bu araç, yerel MCP sunucunuzda çalışan araçları otomatik olarak keşfedip kullanabilen bir süper güce sahiptir.

Bu, mantığı izole ettiği için geliştirme açısından son derece yararlıdır. Web arayüzü veya aracı çerçevesi oluşturma konusunda endişelenmeden önce modelin araçlarınızı anladığını ve bunları doğru şekilde çağırdığını doğrulayabilirsiniz.

Bağlanma ve Çalıştırma

mcp add komutunu kullanarak Gemini CLI'ya sunucumuzu yönetmesini söyleyeceğiz.

Terminalinizde şunu çalıştırın:

gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py

• add holidays: Sunucumuza bir takma ad ("tatiller") verdik.
• uv run ...: Az önce değiştirdiğimiz Python sunucusunu başlatmak için açık komutu sağladık.

Muhteşem içeriklere devam!

Şimdi sohbet oturumunu başlatın:

gemini

Gemini'ın yeni araçlarınızı "görüp göremediğini" test etmek için aşağıdaki istemi deneyin. Gemini CLI'nin tatil aracımızı kullanmasına izin vermeniz gerekebilir.

• 👉 Kullanıcı:

  "I want to create a festive holiday photo. I like birds a lot."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_holiday_scene(interest='birds')*
  
  Done! Saved at generated_scene.png
  

• 👉 Kullanıcı:

  "Great! Now generate a knitting pattern for a sweater with reindeer on it."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_sweater_pattern(motif='reindeer')*
  
  Done! Saved at generated_pattern.png
  

  MCP kullandığınız için yapay zeka, isteğinizi karşılamak üzere hangi Python işlevinin çağrılacağını tam olarak anladı.

Resmi İnceleme

• Control+C tuşuna basarak Gemini CLI'yı sonlandırın.
• Klasörünüzdeki oluşturulan resmi kontrol edin: ~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.

Fotoğrafınızı buradan inceleyin:

Sonuç ve Sonraki Adımlar

Tebrikler! Çalışan bir MCP sunucusu oluşturmayı başarıyla tamamladınız. Artık desen oluşturabilen, görüntüleri birleştirebilen ve sahneleri iyileştirebilen işlevsel bir "yapay zeka araçları" setiniz var.

Ancak yukarıdaki testte bir şey fark ettiniz mi? Süreci sizin yönetmeniz gerekiyordu. Önce sahneyi, ardından deseni, sonra da bunları birleştirmeyi istemeniz gerekiyordu.

Gemini akıllı bir araç olsa da karmaşık bir üretim iş akışında (ör. bir deseni kazağa yerleştirmeden önce oluşturmamız ve görüntü oluşturma başarısız olursa hataları ele almamız gereken durumlarda) daha fazla kontrol istiyoruz. Her adımda elimizden tutmamıza gerek kalmadan tatil kartımızı planlayabilen, kendi çalışmasını eleştirebilen ve durumunu yönetebilen özel bir sistem istiyoruz.

Bir sonraki bölümde, bu yaratıcı karmaşaya düzen getireceğiz. Bu MCP araçlarını mükemmel bir prodüksiyon hattında düzenleyen yapılandırılmış bir Aracı oluşturmak için Aracı Geliştirme Kiti'ni (ADK) uygulayacağız.

5. ADK temsilcisini Vibe-Coding ile geliştirme

Çalışan bir araç setimiz (MCP sunucumuz) var ancak şu anda tüm ağır işleri biz yapıyoruz. Gemini'a tam olarak hangi aracı ne zaman kullanması gerektiğini söylüyoruz.

Bu bölümde, çok adımlı görevleri kendi kendine akıl yürüterek, planlayarak ve uygulayarak gerçekleştirebilen bir sistem olan yapay zeka temsilcisi oluşturacağız. Bunun için Agent Development Kit (ADK)'yi kullanacağız.

Aracı nedir?

MCP araçları "eller" (işi yapan) ise Agent "beyindir". Bir aracı, kullanıcının amacını ("Bana bir tatil kartı yap") anlamak için bir LLM kullanır, bunu adımlara ayırır ("Önce bir sahneye, sonra bir desene ihtiyacım var...") ve hedefe ulaşmak için hangi araçların kullanılacağına karar verir.

ADK nedir?

Agent Development Kit (ADK), Google'ın bu tür aracıların oluşturulmasını kolaylaştıran bir çerçevesidir. Sohbet geçmişini yönetme, araçlara bağlanma ve farklı modeller arasında geçiş yapma gibi karmaşık "altyapı" işlerini halleder. Böylece uygulamanızın kişiliğine ve mantığına odaklanabilirsiniz.

Bağlama Dayalı Sezgisel Kodlama

Kod oluşturmak için tek ve büyük bir istem kullanmak yaygın bir yöntemdir. Ancak karmaşık uygulamalar oluştururken yapay zekayı zaman içinde bağlamı koruyan bir ortak olarak ele almak genellikle daha iyidir.

Tek bir kod satırı yazmadan önce ortamı hazırlamak için Gemini CLI'nin Memory özelliklerini kullanacağız.

1. Ortamı hazırlama

Terminalinizi açın ve başlangıç dizinine gidin:

cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter

Gemini CLI'yı başlatma:

gemini

2. Bağlamı ve Belleği Yönetme

Yapay zeka, vibe-coding yaparken kim olduğunu ve ne bildiğini bilmelidir. Gemini CLI, bunu açıkça yönetmemize olanak tanır.

• /memory show: Yapay zekanın projeniz ve oturumunuz hakkında şu anda neler bildiğini görmek için bunu yazın.
• /memory add: Yapay zekanın sohbet boyunca hatırlaması gereken temel bilgileri eklemek için kullanılır.

Kodlama iş ortağımızın kişiliğini tanımlayarak başlayalım. Gemini CLI'da aşağıdaki komutu çalıştırın:

/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."

Gemini artık rolünü anlıyor. Bu bağlam, sonraki tüm yanıtları etkileyerek yüksek kaliteli ADK uyumlu kodlar oluşturulmasını sağlar.

3. 1. adım: Temel aracıyı Vibe-Coding ile kodlama

Tüm sistemi bir kerede oluşturmaya çalışmak yerine iskeletle başlayalım. Dosya yapısını ve temel temsilci kişiliğini oluşturmak istiyoruz.

Gemini CLI'ye aşağıdaki istemi girin:

Let's start by building the basic agent structure. 

Please create a file structure for a `root_agent`. 
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant". 
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.

Gemini, dosya yapısını ve ilk Python kodunu oluşturur. Doğru göründüğünden emin olmak için inceleyin, ardından değişiklikleri uygulayın/kabul edin.

4. 2. adım: MCP sunucusunu ekleme (araçlar)

Temel bir aracımız olduğuna göre, ona "eller" vermemiz gerekiyor. Aracı, önceki laboratuvarda oluşturduğumuz MCP sunucusuna bağlamamız gerekiyor.

Gemini CLI'ye aşağıdaki istemi girin:

Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.

Gemini artık mevcut agent.py'nizi yeniden düzenleyerek araç tanımlarını ve bağlantı mantığını ekleyecek.

Not: Çalışmanızı kontrol etmek istiyorsanız veya oluşturulan kod beklendiği gibi çalışmıyorsa dosyalarınızı şu konumdaki referans çözümüyle karşılaştırabilirsiniz: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution

6. Temsilci Web Arayüzünü Çalıştırma

ADK, adk web adlı yerleşik bir test arayüzüyle birlikte gelir. Bu işlem, temsilcimizle hemen konuşabilmemiz için basit bir sohbet kullanıcı arayüzü oluşturur.

1. GeminiCLI'ı hâlâ açık tutuyorsanız kapatmak için control+C tuşuna basın. Şimdi terminalinizde(bu, solution klasöründedir. starter klasörünüzde uv run adk web komutunu çalıştırarak kodunuzu test etmek için starter klasörüne gidebilirsiniz) şu komutu çalıştırın:

   cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution
   uv run adk web --port 8000
   

2. Cloud Shell, 8000 numaralı bağlantı noktasında bir hizmetin çalıştığı konusunda sizi uyarır. "Web Önizlemesi" -> "8000 numaralı bağlantı noktasında önizle" seçeneğini tıklayın.

Aracıyı test etme

Artık bir sohbet arayüzü görmelisiniz. Aracımızın yeni talimatlarına uyup uymadığına ve MCP araçlarına doğru şekilde erişip erişmediğine bakalım.

Şu istemleri deneyin:

• "Merhaba! Kimsiniz?"
  • (Şenlikli ve coşkulu bir yanıt bekleyin).
• "Yılbaşı kartım için arka plan istiyorum. Karla kaplı bir köy yap."
  • (Temsilci, generate_holiday_scene numaralı telefonu aramalıdır. Sistem talimatlarında tanımlanan "sevimli/karikatür" stilinin otomatik olarak uygulandığını fark edin).
• "Üzerinde küçük pizza dilimleri olan bir kazak deseni oluştur."
  • (Müşteri temsilcisi generate_sweater_pattern numaralı telefonu aramalıdır).

Oluşturulan görüntüyü buradan görüntüleyebilirsiniz:

Testi bitirdiyseniz çıkmak için Control+C düğmesine basın.

Sonuç ve Sonraki Adımlar

Artık bağlama duyarlı bir yaklaşımla Google ADK Aracısı'nı başarıyla "Vibe-Coded" ettiniz.

• Bağlam oluşturduk: Uzman kişiliği tanımlamak için /memory add kullandık.
• Iteratively'yi oluşturduk: Önce iskeleti oluşturup ardından araç bağlantılarını ekledik.

Yerleşik ADK web önizlemesi test için harika olsa da nihai ürünümüzde özel ve markalı bir deneyim istiyoruz. Bir sonraki bölümde bu Aracıyı özel bir web ön ucuna entegre edeceğiz.

Çalıştay sırasında herhangi bir noktada Unexpected response from metadata server: service account info is missing 'email' field ile karşılaşırsanız devam etmeden önce project id değerini ayarlamak için Cloud Shell'i yenilemeniz ve gcloud config set project $(cat ~/project_id.txt) --quiet komutunu yeniden çalıştırmanız gerekir.

7. ADK'yı kullanıcı arayüzüne bağlama

Temsilci tanımımız olduğuna göre bunu çalıştırmamız gerekiyor. Bu noktada Runner ve Oturum Hizmeti devreye girer.

Uygulama

1. 👉 Komutunuza aşağıdakileri yazın:

   cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py
   

   Bu işlem, düzenleyicinizde ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py simgesini açar.
2. # TODO: Create Session Service yerine aşağıdakini yazın:

   from google.adk.sessions import InMemorySessionService
   from google.adk.memory import InMemoryMemoryService
   session_service = InMemorySessionService()
   memory_service = InMemoryMemoryService()
   

   Oturum Hizmeti, temsilcinizin "Çalışma Belleği"dir.

   • Rol: Mevcut sohbetin karmaşık ve anlık geçmişini (ör. "Ne sormuştum?").
   • İki Aroma:
   • InMemorySessionService: Hızlı, kolay ancak unutkan. Sunucuyu yeniden başlatırsanız aracı her şeyi unutur. Test için idealdir.
   • VertexAiSessionService: Sağlam, veritabanı destekli. Durumu Google Cloud'a kaydettiği için sohbet haftalar sonra veya sunucu yeniden başlatıldıktan sonra da devam edebilir.
3. # TODO: Initialize Runner yerine aşağıdakini yazın:

   runner = Runner(
       app_name="agents",
       agent=christmas_agent,
       session_service=session_service,
       memory_service=memory_service,
   )
   

Çalıştırıcı Temsilci "Beyin" ise Çalıştırıcı "Kalp"tir. Kan dolaşımını sağlar. Çalıştırıcı şunlardan sorumludur:

• Aracıyı bir kullanıcıya ve oturuma bağlama.
• Olay Döngüsünü yürütme.
• Durum geçişlerini yönetme.

4. 158. satırı inceleyin ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(işlem yapmanız gerekmez): Uygulamanın nihai yanıtı nasıl aldığını merak ediyorsanız. Aşağıda, çalıştırıcı tarafından desteklenen etkinlik döngüsü gösterilmektedir:

   async for event in runner.run_async(
       user_id=user_id,
       session_id=session_id,
       new_message=content
   )
   

The Event Loop ADK aracıları yalnızca "yanıt vermez". Döngüsel düşünürler. runner.run_async() adlı kullanıcıyı aradığınızda:

1. Kullanıcı girişi döngüye girer.
2. Planlama: Aracı, araçlarını ve hedeflerini göz önünde bulundurur.
3. Eyleme geçme: Uygunsa bir aracı çağırır (ör. list_files).
4. Gözlemle: Araç çıkışını okur.
5. Yansıtma: Daha fazla bilgiye ihtiyacı olup olmadığına veya yanıt verip veremeyeceğine karar verir.
6. Döngü: Tatmin olana kadar 2-5 arasındaki adımları tekrar eder.
7. Yanıtla: Kullanıcıya nihai yanıtı verir.

Ayrıntılı İnceleme: Mimari ve Dağıtım

Bu aracıyı sunmak için FastAPI'yi kullanıyoruz.

• Neden FastAPI?: Aracılar genellikle G/Ç sınırlıdır (büyük dil modellerini bekler). FastAPI'nin asenkron yapısı bu durumu mükemmel bir şekilde ele alır.
• Durumsuzluk: API uç noktamızın durumsuz olduğunu fark edin. Değişkenleri genel kapsamda kaydetmiyoruz. Her isteğin durumunu yeniden oluşturmak için session_id ve SessionService hizmetlerinden yararlanırız. Bu, Cloud Run'a (sunucusuz) dağıtım yapabileceğiniz ve sıfıra kadar ölçeklendirebileceğiniz anlamına gelir.

8. Uygulamayı temsilci sihirbazıyla deneme

1. 👉💻 Komutunuza aşağıdakileri yazın:

   cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter
   ./start_app.sh
   

   Bu işlem, düzenleyicinizde ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py simgesini açar.
2. Sonucu aşağıdaki gibi görürsünüz:👉👉 http://localhost:5173/ seçeneğini tıkladığınızdan veya yeni bir pencere açıp http://localhost:5173/ yazdığınızdan emin olun.

   Bunun arka uç sunucusunun bağlantısı OLMADIĞINI unutmayın: Uvicorn running on http://0.0.0.0:8000

3. Ardından, sohbet arayüzü içeren web sitesi gösterilir:
4. Bir resim yükleyerek test edin(Kendinizin veya evcil hayvanınızın resmi olabilir)
5. 👉 Ardından sorunuzu sorun.

   Can you generate a picture my cat wearing snowflake pattern sweater?
   

   Üretilen görüntüyü burada görürsünüz:
6. 👉💻 Testi tamamladığınızda işlemi sonlandırmak için terminalde control+C tuşuna basın.

İşlerin beklendiği gibi yürümediğini fark ederseniz ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution bölümüne gidip ./start_app.sh komutunu çalıştırabilir ve yukarıdaki adımları uygulayabilirsiniz.

9. Vertex AI Memory Bank

Kısa süreli ve uzun süreli bellek

• Kısa Süreli Bağlam: "Ne dedim?" (Oturum geçmişi). Bu bilgi, sohbet penceresi kapatıldığında kaybolur.
• Uzun Süreli Bellek: "En sevdiğim programlama dili nedir?" (Kullanıcı tercihleri). Bu durum sonsuza kadar devam etmelidir.

Bu uzun süreli depolama alanı Vertex AI Memory Bank tarafından sağlanır. Bu sayede temsilci, kullanıcı hakkında kişiselleştirilmiş bilgileri depolayabilir ve alabilir.

Oturumlar ve Hafıza Bankası

• Oturumlar (VertexAiSessionService): Bu, Günlük'tür. Her mesajın, araç çağrısının ve etkinliğin (AppendEvent, ListEvents) ham ve kronolojik sırasını saklar. Ne olduğu konusunda gerçek bilgiyi sağlar.
• Bellek Bankası (VertexAiMemoryBankService): Bu, Bilgi'dir. Sentezlenmiş, uzun vadeli bilgileri (GenerateMemories, RetrieveMemories) depolar. Gizliliği ve izolasyonu sağlamak için belirli bir user_id ile sınırlandırılmıştır.

1. 👉💻 Komutunuza aşağıdakileri yazın:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py
   

   Bu işlem, düzenleyicinizde ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py simgesini açar.
2. # TODO: Create Vertex AI Session Service & Memory Bank Service ifadesini bulun ve satırın tamamını aşağıdakilerle değiştirin:

       session_service = VertexAiSessionService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
       memory_service = VertexAiMemoryBankService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
   
   

3. 👉💻 Komutunuza aşağıdakileri yazın:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py
   

   Bu işlem, düzenleyicinizde ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py simgesini açar.
4. # TODO: Set Up Configuration yerine aşağıdakini yazın:

   # Basic configuration types
   MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig
   SimilaritySearchConfig = (
       types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig
   )
   GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig
   
   # Advanced configuration types
   CustomizationConfig = types.MemoryBankCustomizationConfig
   MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic
   CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic
   GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample
   ConversationSource = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource
   )
   ConversationSourceEvent = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent
   )
   ExampleGeneratedMemory = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory
   )
   

Temel Özellikler

Vertex AI Memory Bank yalnızca bir veritabanı değil, aynı zamanda aktif bir bilişsel hizmettir.

• Bellek Çıkarma: Sistem, konuşmayı okumak ve tanımladığımız CustomMemoryTopic şemalarına (ör. "Sweater Preferences" [Kazak Tercihleri]). Sohbeti yoksayar ve sinyali kaydeder.
• Bellek Birleştirme: Yeni bilgileri eskilerle otomatik olarak birleştirir. Bir kullanıcı "Kırmızıyı seviyorum" ve daha sonra "Aslında maviyi tercih ederim" derse Hafıza Bankası, çakışan kopyalar oluşturmak yerine hafıza kaydını geliştirir.
• Asenkron Üretim: Anılar arka planda üretilir. Temsilciniz, Hafıza Bankası iletişimi "düşünürken" beklemez.

5. 👉 Aynı dosyada: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. # TODO: Set up topic simgesini bulun ve satırın tamamını aşağıdakiyle değiştirin:

       custom_topics = [
           # Topic 1: Sweater Preference
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="sweater_preference",
                   description="""Extract the user's preferences for sweater styles, patterns, and designs. Include:
                   - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.)
                   - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted)
                   - Color preferences (red, green, navy, pastel, etc.)
                   - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft)
                   - Themes (retro, modern, ugly christmas sweater, elegant)
   
                   Example: "User wants a retro style sweater with a pixelated reindeer pattern."
                   Example: "User prefers dark blue colors and hates itchy wool."
                   """,
               )
           ),
           # Topic 2: Personal Context
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="personal_context",
                   description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include:
                   - Hobbies and activities (skiing, reading, gaming, cooking, etc.)
                   - Pets (type, breed, name, color)
                   - Job or profession if relevant to their style
                   - General interests (sci-fi, nature, vintage, tech)
                   - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach)
   
                   Example: "User has a golden retriever named Max."
                   Example: "User loves skiing and wants a snowy mountain background."
                   Example: "User is a software engineer who likes cyberpunk aesthetics."
                   """,
               )
           )
       ]
   

6. 👉 Aynı dosyada: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. # TODO: Create Agent Engine simgesini bulun ve satırın tamamını aşağıdakilerle değiştirin:

       agent_engine = client.agent_engines.create(
           config={
               "display_name": AGENT_DISPLAY_NAME,
               "context_spec": {
                   "memory_bank_config": {
                       "generation_config": {
                           "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
                       },
                       "customization_configs": [customization_config]
                   }
               },
           }
       )
   

Agent Engine

Agent Engine, buluttaki "Beyin Donanımı"dır. Şunları yönetir:

• Vektör Veritabanı: Anıları saklamak için kullanılır.
• Dizine ekleme: Anıları aranabilir hale getirmek için kullanılır.
• API: Temsilcinin sorgu göndermesine izin vermek için. deploy_agent.py komutunu çalıştırdığınızda bu donanımı sağlıyor olursunuz.

Neden sadece istemi kullanmıyoruz?

"Neden kullanıcının geçmişini isteme yapıştırmıyoruz?" diye sorabilirsiniz.

• Boyut sınırları: Bağlam pencereleri büyüktür ancak sınırsız değildir. 5 yıllık geçmişi sığdıramazsınız.
• Maliyet: Her "Merhaba" için 1 milyon jeton işlemek çok pahalıdır.
• Odaklanma: Memory Bank, aracınız için arama motoru görevi görür. Yalnızca alakalı gerçekleri alır.

7. 👉💻 Komutunuza aşağıdakileri yazın:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py
   

   Bu işlem, düzenleyicinizde ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py simgesini açar.
8. Dosyada: ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py# TODO: Add PreloadMemoryTool yerine aşağıdakileri girin:

   if USE_MEMORY_BANK:
       agent_tools.append(PreloadMemoryTool())
   

PreloadMemoryTool ve add_session_to_memory

agent.py bölümünde iki temel bileşen görürsünüz:

• PreloadMemoryTool: Bu araç, temsilcinin "kendisiyle ilgili Google araması" yapmasına olanak tanır. Kullanıcı "Her zamanki kahvemi getir" gibi net olmayan bir soru sorduğunda, yanıt vermeden önce "kahve tercihleri" için Bellek Bankası'nı sorgulamak üzere bu aracı kullanabilir.
• add_session_to_memory: Bu, arka planda yapılan bir geri aramadır.
  • Neden Eş Zamansız? Belleği kaydetmek zaman alır (sohbeti özetleme, bilgileri çıkarma). Kullanıcının bunu beklemesini istemiyoruz. after_agent_callback kullanarak arka planda (add_session_to_memory) çalıştırırız.

10. Memory Bank In Action

1. 👉💻 Komutunuza aşağıdakileri yazın:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./use_memory_bank.sh
   

   Sonucu aşağıdaki gibi görürsünüz:

   Bu use_memory_bank.sh komut dosyası, temsilcinizin Vertex AI Memory Bank'ı kullanabilmesi için önce 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py dosyasını kullanarak temsilci motorunu temsilcinize ekler. Ardından, .env dosyasını sizin için güncelleyerek agent engine ID'nin environmental variable olarak kaydedilmesini sağlar.

   ~/holiday_workshop/.env dosyanızı kontrol edin. (İşlem gerekmez) mesajını görürsünüz.

   USE_MEMORY_BANK=TRUE
   AGENT_ENGINE_ID={agent_engine_id}
   

2. 👉💻 Belleği uygulama kullanıcı arayüzüyle test edin. Komutunuza aşağıdakileri yazın:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./start_app.sh
   

   http://localhost:5173/ simgesini tıkladığınızdan veya yeni bir pencere açıp http://localhost:5173/ yazdığınızdan emin olun. Uvicorn running on http://0.0.0.0:8000 simgesinin yalnızca arka uç sunucusu olduğunu ve tıklamak istediğimiz gerçek bağlantı olmadığını unutmayın. Artık web sitesindeki sohbet arayüzü, kişiselleştirilmiş temsilciniz oldu.
3. 👉Belleği test edin. Kullanıcı arayüzünde yazarsanız:

   I want a sweater that matches my dog. He's a golden retriever.
   

   I'm a programmer, so I want something geeky. Maybe a matrix style?
   

   I like snowflake sweater pattern
   

Temsilci bunu tercih olarak tanımlar ve Memory Bank'te saklar.

Gelecek hafta(veya uygulamayı Control+C ve ./start_app.sh tuşlarına basarak yeniden başlattığınızda) şu soruyu sorarsanız:

what is my preference on sweater pattern?

Temsilci, Hafıza Bankası'na sorgu gönderir, tercihinizi görür ve istenmeden kazak deseni oluşturur.

Kişiselleştirme: Bu, faydalı temsilciler oluşturmanın anahtarıdır. Kullanıcı tercihlerini (ör. kazak deseni, kişisel bağlam) hatırlayan ajan, zaman içinde daha verimli ve faydalı hale gelir.

4. Google Cloud Console Agent Engine'e giderek Vertex AI Agent Engine'de doğrulayın.
   • Sol üstteki proje seçiciden projeyi seçtiğinizden emin olun:
   • Ayrıca, önceki komuttan yeni dağıttığınız temsilci motorunu doğrulayın. use_memory_bank.shYeni oluşturduğunuz temsilci motorunu tıklayın.
5. Bu dağıtılmış aracının Memories sekmesini tıkladığınızda tüm anıları burada görüntüleyebilirsiniz.

Tebrikler! Hafıza bankasını temsilcinize bağladınız.

11. Sonuç

Özet

Tam bir aracı sistemini başarıyla tasarlayıp oluşturdunuz.

• Bağlantı: Temsilcinizin yerel araçlara erişimini standartlaştırmak için MCP'yi kullandınız.
• Orkestrasyon: Çok adımlı görevler için gereken karmaşık muhakeme döngüsünü yönetmek üzere ADK'yı kullandınız.
• Kişiselleştirme: Kullanıcı bağlamını hatırlayan kalıcı ve öğrenme katmanı oluşturmak için Bellek Bankası'nı kullandınız.

Sonraki Adımlar

• Kendi MCP sunucunuzu oluşturma: Dahili API'niz veya veritabanınız için bir sunucu oluşturun.
• ADK Kalıplarını Keşfedin: ADK belgelerindeki "Akıl Yürütme Döngüleri" ve "Düzenleme" hakkında bilgi edinin.
• Dağıtma: Aracınızı yerel bir komut dosyasından Cloud Run'da üretim hizmetine taşıyın.

Geliştirmeye Devam Edin Bağlantı için MCP ve kişiselleştirme için Memory Bank'in birleşimi, yeni nesil akıllı uygulamaların temelini oluşturur.