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

1. Giriş

The Modern Agent Stack

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

Bu atölyede, üç 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 kullanılır.
2. Düzenleme (ADK): Aracının akıl yürütme 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.
Agent Development Kit (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 belleği yönetir. Anlık sohbet bağlamını (ör. "Kullanıcı az önce ne sordu?") korur ancak oturum sona erdiğinde temizlenir.
Vertex AI Memory Bank	Uzun süreli belleği yönetir. Kullanıcıya özel bilgileri ve tercihleri (ör. "Kullanıcı Python'ı tercih ediyor") süresiz olarak saklar. Böylece, ajan 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 yerel Python araçlarını bağımsız olarak düzenleyerek kişiselleştirilmiş kod ve resimler oluşturabilir.

Üç aşamada ilerlersiniz:

1. Araç Katmanı: Yerel Python işlevlerini yapay zekaya sunmak için bir MCP sunucusu oluşturun.
2. Aracı Katmanı: Çok adımlı iş akışlarını planlayan ve yürüten bir aracı oluşturmak için ADK'yı kullanın.
3. Bellek Katmanı: Aracının kullanıcı stili tercihlerini öğrenip hatırlaması için Memory Bank'ı 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

Bu codelab'i çalıştırmak için biraz kredisi olan bir faturalandırma hesabına ihtiyacınız var. Başlamak için bu codelab'in üst kısmındaki banner'da yer alan kredileri kullanın. Zaten bir faturalandırma hesabına bağlıysanız bu adımı atlayabilirsiniz.

2. 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ş varsayılan bir 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 bölümde 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 Bağlam Protokolü (MCP)'nü 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 bağlanır (Studio araçları).
2. Agent Development Kit (ADK)'yi kullanarak sohbet bağlamını güvenilir bir şekilde yönetir.
3. Vertex AI Memory Bank'i kullanarak farklı oturumlarda tercihlerinizi hatırlar (ör. "Python kodunu tercih ederim").

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

Sunucu Mantığını Oluşturma

Ortamı hazırladık ancak sunucu mantığı tamamlanmadı. Ajanımızın tatil kartımızı oluşturmak için kullanacağı dört 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
   

Ortak metin kodunun (MCP sunucusunu ayarlama, bağlantıları işleme ve Vertex AI istemcisini ilk kullanıma hazırlama) zaten tamamlandığını göreceksiniz. Ancak dört temel işlev şu anda boş yer tutucular.

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

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

#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 stilin 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 edebiliriz?

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 CLI'yı kullanabiliriz.

Gemini CLI nedir?

Gemini CLI, doğrudan terminalinizde bir Gemini modeliyle sohbet etmenize olanak tanıyan 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 sürecinde 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 KSA'ya sunucumuzu yönetmesini söyleyeceğiz.

Terminalinizde şu komutu ç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 verdik ("tatiller").
• uv run ...: Az önce değiştirdiğimiz Python sunucusunu başlatmak için açık komutu sağladık.

Haydi Yaratıcılığınızı Konuşturun!

Ş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'ın 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'yi 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ı 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 planlama yapabilen, kendi çalışmasını eleştirebilen ve tatil kartımızın 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 üretim hattında düzenleyen yapılandırılmış bir temsilci oluşturmak için Agent Development Kit'i (ADK) uygulayacağız.

5. ADK temsilcisini sezgisel olarak kodlama

Ç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 kullanacağını söylüyoruz.

Bu bölümde, yapay zeka ajanı oluşturacağız. Bu ajan, çok adımlı görevleri kendi kendine akıl yürüterek, planlayarak ve uygulayarak gerçekleştirebilen bir sistemdir. 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ı oluşturmayı 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 bir büyük istem kullanmak yaygın bir yöntemdir. Ancak karmaşık uygulamalar geliştirirken 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'ın Hafıza ö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şlatın:

gemini

2. Bağlamı ve Hafızayı Yönetme

Yapay zeka, vibe-coding yaparken kim olduğunu ve neleri 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 üretilmesini sağlar.

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

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

Aşağıdaki istemi Gemini CLI'ye 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.

Aşağıdaki istemi Gemini CLI'ye 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 öğenizi, araç tanımlarını ve bağlantı mantığını içerecek şekilde yeniden düzenleyecek.

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üme göre karşılaştırabilirsiniz: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution

6. Agent 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ü başlatır.

1. GeminiCLI'yı 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 Preview" (Web Önizlemesi) -> "Preview on port 8000" (8000 numaralı bağlantı noktasında önizle) seçeneğini tıklayın.

Ajanı test etme

Artık bir sohbet arayüzü görmeniz gerekir. 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. Köyü karlı yap."
  • (Temsilci, generate_holiday_scene numaralı telefonu aramalıdır. Sistem talimatlarında tanımlanan "sevimli/karikatür" stilini otomatik olarak nasıl uyguladığına dikkat edin.
• "Üzerinde küçük pizza dilimleri olan bir kazak deseni oluştur."
  • (Temsilci, generate_sweater_pattern numaralı telefonu aramalıdır.)

Üretilen görüntüyü buradan inceleyebilirsiniz:

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. 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'inizi 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

Artık bir Agent tanımımız olduğuna göre bunu uygulamamı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 öğesini açar.
2. # TODO: Create Session Service yerine aşağıdakini girin:

   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?") saklar.
   • İ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 devam edebilir.
3. # TODO: Initialize Runner yerine aşağıdakini girin:

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

Çalıştırıcı: Ajan "Beyin" ise Çalıştırıcı "Kalp"tir. Kan dolaşımını hızlandırır. Ç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. Bu ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(işlem yapmanız gerekmez) konumunda 158. satırı inceleyin: 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ü verilmiştir:

   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: Ajan, araçlarını ve hedeflerini göz önünde bulundurur.
3. İşlem: Uygunsa bir aracı (ör. list_files) çağırır.
4. Gözlemleme: 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ü: Memnun kalana kadar 2-5 arasındaki adımları tekrarlar.
7. Yanıtla: Kullanıcıya nihai yanıtı verir.

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

Bu ajanı 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 eşzamansız yapısı bu durumu mükemmel bir şekilde ele alır.
• Durumsuzluk: API uç noktamızın durum bilgisiz olduğunu unutmayın. 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 öğesini açar.
2. Sonucu aşağıdaki gibi görürsünüz:👉👉 http://localhost:5173/ ifadesini tıkladığınızdan veya yeni bir pencere açıp http://localhost:5173/ ifadesini 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 sitesini görürsünüz:
4. Bir resim yükleyerek testi yapın(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 resmi 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 düşünüyorsanız ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution'ya gidip ./start_app.sh'ı çalıştırabilir, ardından 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 ajan, 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 bilgileri 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 öğesini açar.
2. # TODO: Create Vertex AI Session Service & Memory Bank Service ifadesini bulun ve satırın tamamını aşağıdaki ifadeyle 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 öğesini açar.
4. # TODO: Set Up Configuration yerine aşağıdakini girin:

   # 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 etkin bir bilişsel hizmettir.

• Bellek Çıkarma: Sistem, sohbeti okumak ve tanımladığımız CustomMemoryTopic şemalara (ör. "Kazak Tercihleri") göre anlamlı bilgiler çıkarmak için bir LLM kullanır. Sohbeti yoksayar ve sinyali kaydeder.
• Bellek Birleştirme: Yeni bilgileri eskilerle otomatik olarak birleştirir. Bir kullanıcı "Kırmızıyı seviyorum" dedikten 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 oluşturulur. Ajanınız, Hafıza Bankası iletişimi "düşünürken" bekletilmez.

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ğıdakilerle 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]
                   }
               },
           }
       )
   

Ajan Motoru

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: Ajanın sorgu göndermesine izin vermek için. deploy_agent.py komutunu çalıştırdığınızda bu donanımı hazırlamış 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: Hafıza Bankası, temsilciniz için arama motoru görevi görür. Yalnızca ilgili bilgileri 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 öğesini 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 al" gibi belirsiz bir soru sorarsa ajan, yanıt vermeden önce "kahve tercihleri" için Bellek Bankası'nı sorgulamak üzere bu aracı kullanabilir.
• add_session_to_memory: Bu, arka planda geri çağırma işlemidir.
  • 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, aracı motoru kimliğinin environmental variable olarak kaydedilmesi için .env dosyasını sizin için günceller.

   ~/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ş aracınız 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 Hafıza Bankası'nda 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?

Ajan, Memory Bank'a sorgu gönderir, tercihinizi görür ve sorulmadan kazak deseni oluşturur.

Kişiselleştirme: Bu, faydalı temsilciler oluşturmak için çok önemlidir. 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ıklayın. 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 akıl yürütme 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 Memory Bank'ı 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.