🤖 Graph RAG, ADK ve Memory Bank ile Çok Formatlı Yapay Zeka Temsilcisi Oluşturma

1. Giriş

cover

1. Hedef

Afet müdahale senaryolarında, farklı becerilere, kaynaklara ve ihtiyaçlara sahip afetzedelerin birden fazla konumda koordine edilmesi için akıllı veri yönetimi ve arama özellikleri gerekir. Bu atölyede, aşağıdakileri birleştiren bir üretim yapay zeka sistemi oluşturmayı öğreneceksiniz:

  1. 🗄️ Graph Database (Spanner): Hayatta kalanlar, beceriler ve kaynaklar arasındaki karmaşık ilişkileri depolama
  2. 🔍 Yapay zeka destekli arama: Yerleştirmeleri kullanan semantik ve anahtar kelime tabanlı karma arama
  3. 📸 Çok formatlı işleme: Resim, metin ve videolardan yapılandırılmış veriler ayıklama
  4. 🤖 Çoklu Temsilci Düzenleme: Karmaşık iş akışları için özel temsilcileri koordine edin.
  5. 🧠 Uzun süreli bellek: Vertex AI Memory Bank ile kişiselleştirme

sohbet

2. Ne oluşturacaksınız?

Şunları içeren bir Survivor Network Graph Database:

  • 🗺️ Hayatta kalanların ilişkilerinin 3D Etkileşimli Grafik Görselleştirmesi
  • 🔍 Akıllı Arama (anahtar kelime, semantik ve karma)
  • 📸 Çok formatlı yükleme ardışık düzeni (resimlerden/videolardan öğe ayıklama)
  • 🤖 Karmaşık görevleri yönetmek için çoklu temsilci sistemi
  • 🧠 Kişiselleştirilmiş etkileşimler için Memory Bank entegrasyonu

3. Temel Teknolojiler

Bileşen

Teknoloji

Amaç

Database

Cloud Spanner Graph

Düğümleri (hayatta kalanlar, beceriler) ve kenarları (ilişkiler) depolama

Yapay Zeka Destekli Arama

Gemini + Embeddings

Semantik anlayış + benzerlik araması

Agent Framework

ADK (Agent Development Kit)

Yapay zeka iş akışlarını yönetme

Bellek

Vertex AI Memory Bank

Uzun süreli kullanıcı tercihi depolama alanı

Ön uç

React + Three.js

Etkileşimli 3D grafik görselleştirme

2. 🛠️ Ortam Hazırlığı (Atölyedeyseniz atlayın)

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

Bu codelab'i çalıştırmak için kredisi olan bir faturalandırma hesabınız olmalıdır. Başlamak için bu codelab'in üst kısmındaki banner'da bulunan kredileri kullanın. Bir faturalandırma hesabına zaten 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 Authorize'ı (Yetkilendir) tıklayın. Cloud Shell'i yetkilendirmek için tıklayın
  3. 👉 Terminal, ekranın alt kısmında görünmüyorsa açın:
    • Görüntüle'yi tıklayın.
    • Terminal'i tıklayın.Cloud Shell Düzenleyici'de yeni terminal açma
  4. 👉💻 Terminalde, kimliğinizin doğrulandığını ve projenin, proje kimliğinize ayarlandığını doğrulamak için aşağıdaki komutu kullanın:
    gcloud auth list
    
  5. 👉💻 Bootstrap projesini GitHub'dan kopyalayın:
    git clone https://github.com/gca-americas/way-back-home.git
    

Üçüncü bölüm: Yeni bir proje oluşturma

👉💻 Terminalde, başlatma komut dosyasını yürütülebilir hale getirin ve çalıştırın:

cd ~/way-back-home/level_2
./init.sh

3. 🛠️ Ortam Kurulumu

1. Cloud Shell'i açın

Cloud Shell Düzenleyici terminalinde, terminal ekranın alt kısmında görünmüyorsa açın:

  • Görüntüle'yi tıklayın.
  • Terminal'i tıklayın.

Cloud Shell Düzenleyici'de yeni terminal açma

2. Projeyi yapılandırma

👉💻 Terminalde proje kimliğinizi ayarlayın:

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

👉💻 Gerekli API'leri etkinleştirin (bu işlem yaklaşık 2-3 dakika sürer):

gcloud services enable compute.googleapis.com \
                       aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       spanner.googleapis.com \
                       storage.googleapis.com

3. Kurulum komut dosyasını çalıştırma

👉💻 Kurulum komut dosyasını çalıştırın:

cd ~/way-back-home/level_2
./setup.sh

Bu işlem, sizin için .env oluşturur. Cloud Shell'inizde way_back_home projesini açın. level_2 klasöründe, sizin için oluşturulan .env dosyasını görebilirsiniz. Bulamıyorsanız View -> Toggle Hidden File simgesini tıklayarak görebilirsiniz. open_project

4. Örnek verileri yükleme

👉💻 Arka uca gidin ve bağımlılıkları yükleyin:

cd ~/way-back-home/level_2/backend
uv sync

👉💻 İlk hayatta kalan verilerini yükleme:

uv run python ~/way-back-home/level_2/backend/setup_data.py

Bu, şunları oluşturur:

  • Spanner örneği (survivor-network)
  • Veritabanı (graph-db)
  • Tüm düğüm ve kenar tabloları
  • Sorgulama için özellik grafikleri Beklenen çıkış:
============================================================
SUCCESS! Database setup complete.
============================================================

Instance:  survivor-network
Database:  graph-db
Graph:     SurvivorGraph

Access your database at:
https://console.cloud.google.com/spanner/instances/survivor-network/databases/graph-db?project=waybackhome

Çıktıda Access your database at ifadesinden sonraki bağlantıyı tıklarsanız Google Cloud Console Spanner'ı açabilirsiniz.

open_spanner

Google Cloud Console'da Spanner'ı göreceksiniz.

spanner

4. 🚀 Spanner Studio'da grafik verilerini görselleştirme

Bu kılavuz, Spanner Studio'yu kullanarak Survivor Network grafik verilerini doğrudan Google Cloud Console'da görselleştirmenize ve bu verilerle etkileşim kurmanıza yardımcı olur. Bu, yapay zeka temsilcinizi oluşturmadan önce verilerinizi doğrulamanın ve grafik yapısını anlamanın harika bir yoludur.

1. Spanner Studio'ya erişme

  1. Son adımda, bağlantıyı tıklayıp Spanner Studio'yu açtığınızdan emin olun.

spanner_studio

2. Grafik yapısını anlama ("Büyük resim")

Survivor Network veri kümesini bir mantık bulmacası veya oyun durumu olarak düşünün:

Varlık

Sistemdeki Rolü

Analoji

Survivors

Temsilciler/oyuncular

Oyuncular

Biyomlar

Nerede bulundukları

Harita Bölgeleri

Beceriler

Yapabilecekleri

Yetkileri

İhtiyaçlar

Eksiklikleri (Krizler)

Görevler

Kaynaklar

Dünyada bulunan öğeler

Ganimet

Hedef: Yapay zeka ajanının görevi, Biyomları (konum kısıtlamaları) dikkate alarak Becerileri (çözümler) İhtiyaçlar (sorunlar) ile eşleştirmektir.

🔗 Kenarlar (İlişkiler):

  • SurvivorInBiome: Konum izleme
  • SurvivorHasSkill: Yetenek envanteri
  • SurvivorHasNeed: Etkin sorunların listesi
  • SurvivorFoundResource: Öğelerin envanteri
  • SurvivorCanHelp: Tahmini ilişki (Yapay zeka bunu hesaplar.)

3. Grafiği sorgulama

Verilerdeki "hikayeyi" görmek için birkaç sorgu çalıştıralım.

Spanner Graph, GQL (Graph Query Language) kullanır. Sorgu çalıştırmak için GRAPH SurvivorNetwork ve ardından eşleşme kalıbınızı kullanın.

👉 Sorgu 1: Global liste (Kim nerede?) Bu sizin temelinizdir. Kurtarma operasyonları için konumu anlamak çok önemlidir.

GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[:SurvivorInBiome]->(b:Biomes)
RETURN TO_JSON(result) AS json_result

Aşağıdaki gibi bir sonuç görmeniz gerekir: query1

👉 Sorgu 2: Beceri Matrisi (Yetenekler) Artık herkesin nerede olduğunu bildiğinize göre neler yapabileceklerini öğrenin.

GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasSkill]->(k:Skills)
RETURN TO_JSON(result) AS json_result

Aşağıdaki gibi bir sonuç görmeniz gerekir: query2

👉 3. sorgu: Who is in Crisis? (Krizde olan kim?) ("Görev Panosu") Yardıma ihtiyacı olan hayatta kalanları ve ihtiyaçlarını görün.

GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasNeed]->(n:Needs)
RETURN TO_JSON(result) AS json_result

Aşağıdaki gibi bir sonuç görmeniz gerekir: query3

🔎 [İsteğe bağlı] Eşleştirme: Kim kime yardım edebilir?

Grafiğin gücü işte burada ortaya çıkıyor. Bu sorgu, diğer hayatta kalanların ihtiyaçlarını karşılayabilecek becerilere sahip hayatta kalanları bulur.

GRAPH SurvivorNetwork
MATCH result = (helper:Survivors)-[:SurvivorHasSkill]->(skill:Skills)-[:SkillTreatsNeed]->(need:Needs)<-[:SurvivorHasNeed]-(helpee:Survivors)
RETURN TO_JSON(result) AS json_result

Aşağıdaki gibi bir sonuç görmeniz gerekir: query4

aside positive Bu Sorgu Ne Yapar?

Bu sorgu, yalnızca "İlk yardım yanıkları tedavi eder" (şemadan anlaşılır) ifadesini göstermek yerine şunları bulur:

  • Dr. Elena Frost (Tıbbi Eğitimi var) → tedavi edebilir → Kaptan Tanaka (yanıkları var)
  • David Chen (ilk yardım bilgisi var) → tedavi edebilir → Teğmen Park (ayak bileği burkuldu)

Neden etkili?

Yapay zeka ajanınızın yapacakları:

Kullanıcı "Yanıkları kim tedavi edebilir?" diye sorduğunda temsilci:

  1. Benzer bir grafik sorgusu çalıştırma
  2. Döndürülen değer: "Dr. Frost has Medical Training and can help Captain Tanaka"
  3. Kullanıcının ara tablolar veya ilişkiler hakkında bilgi sahibi olması gerekmez.

5. 🚀 Spanner'da yapay zeka destekli yerleştirmeler

1. Neden yerleştirmeler? (İşlem yok, salt okunur)

Hayatta kalma senaryosunda zaman çok önemlidir. Afetzedeler I need someone who can treat burns veya Looking for a medic gibi acil durumları bildirirken veritabanındaki beceri adlarını tahmin etmeye çalışarak zaman kaybedemez.

Gerçek Senaryo: Survivor: Captain Tanaka has burns—we need medical help NOW!

"Sıhhiye" için geleneksel anahtar kelime araması → 0 sonuç ❌

Yerleştirmelerle semantik arama → "Tıp Eğitimi", "İlk Yardım"ı bulur ✅

Temsilcilerin tam olarak ihtiyacı olan şey budur: Yalnızca anahtar kelimeleri değil, amacı da anlayan akıllı, insan benzeri arama.

2. Yerleştirme modeli oluşturma

spanner_embedding

Şimdi Google'ın text-embedding-004 modelini kullanarak metni yerleştirmelere dönüştüren bir model oluşturalım.

👉 Spanner Studio'da şu SQL'i çalıştırın ($YOUR_PROJECT_ID ifadesini gerçek proje kimliğinizle değiştirin):

‼️ Cloud Shell düzenleyicisinde, projenin tamamını görmek için File -> Open Folder -> way-back-home/level_2 dosyasını açın.

project_id

👉 Aşağıdaki sorguyu kopyalayıp yapıştırarak Spanner Studio'da çalıştırın ve ardından Run (Çalıştır) düğmesini tıklayın:

CREATE OR REPLACE MODEL TextEmbeddings
INPUT(content STRING(MAX))
OUTPUT(embeddings STRUCT<values ARRAY<FLOAT32>>)
REMOTE OPTIONS (
    endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004'
);

Bu ne işe yarar?

  • Spanner'da sanal model oluşturur (model ağırlıkları yerel olarak depolanmaz).
  • Vertex AI'da Google'ın text-embedding-004 modelini kullanır.
  • Sözleşmeyi tanımlar: Giriş metindir, çıkış ise 768 boyutlu bir kayan nokta dizisidir.

Neden "UZAKTAN ÇALIŞMA SEÇENEKLERİ"?

  • Spanner, modeli kendisi çalıştırmaz.
  • ML.PREDICT kullanırken API aracılığıyla Vertex AI'ı çağırır.
  • Sıfır ETL: Verileri Python'a aktarmaya, işlemeye ve yeniden içe aktarmaya gerek yoktur.

Run düğmesini tıklayın. İşlem başarılı olduğunda sonucu aşağıdaki gibi görürsünüz:

spanner_result

3. Yerleştirme sütunu ekle

👉 Yerleştirmeleri depolamak için bir sütun ekleyin:

ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;

Run düğmesini tıklayın. İşlem başarılı olduğunda sonucu aşağıdaki gibi görebilirsiniz:

embedding_result

4. Yerleştirilmiş Öğeler Oluşturma

👉 Her beceri için vektör yerleştirmeleri oluşturmak üzere yapay zekayı kullanın:

UPDATE Skills
SET skill_embedding = (
    SELECT embeddings.values
    FROM ML.PREDICT(
        MODEL TextEmbeddings,
        (SELECT name AS content)
    )
)
WHERE skill_embedding IS NULL;

Run düğmesini tıklayın. İşlem başarılı olduğunda sonucu aşağıdaki gibi görürsünüz:

skills_result

İşlem: Her beceri adı (ör. "ilk yardım"), anlamsal anlamını temsil eden 768 boyutlu bir vektöre dönüştürülür.

5. Yerleştirmeleri Doğrulama

👉 Yerleştirmelerin oluşturulduğunu kontrol edin:

SELECT 
    skill_id,
    name,
    ARRAY_LENGTH(skill_embedding) AS embedding_dimensions
FROM Skills
LIMIT 5;

Beklenen çıkış:

spanner_result

Şimdi senaryomuzdaki kullanım alanını test edelim: "medic" terimini kullanarak tıbbi becerileri bulma.

👉 "Sıhhiye"ye benzer becerileri bulma:

WITH query_embedding AS (
    SELECT embeddings.values AS val
    FROM ML.PREDICT(MODEL TextEmbeddings, (SELECT "medic" AS content))
)
SELECT
    s.name AS skill_name,
    s.category,
    COSINE_DISTANCE(s.skill_embedding, (SELECT val FROM query_embedding)) AS distance
FROM Skills AS s
WHERE s.skill_embedding IS NOT NULL
ORDER BY distance ASC
LIMIT 10;
  • Kullanıcının "doktor" arama terimini yerleştirmeye dönüştürür.
  • query_embedding geçici tablosunda depolar.

Beklenen sonuçlar (daha düşük mesafe = daha benzer):

spanner_result

7. Analiz için Gemini modeli oluşturma

spanner_gemini

👉 Üretken yapay zeka modeli referansı oluşturun ($YOUR_PROJECT_ID ifadesini gerçek proje kimliğinizle değiştirin):

CREATE OR REPLACE MODEL GeminiPro
INPUT(prompt STRING(MAX))
OUTPUT(content STRING(MAX))
REMOTE OPTIONS (
    endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-pro',
    default_batch_size = 1
);

Yerleştirme modelinden farkı:

  • Yerleştirmeler: Metin → Vektör (benzerlik araması için)
  • Gemini: Metin → Oluşturulan Metin (akıl yürütme/analiz için)

spanner_result

8. Uyumluluk analizi için Gemini'ı kullanma

👉 Hayatta kalan çiftleri görev uyumluluğu açısından analiz edin:

WITH PairData AS (
    SELECT
        s1.name AS Name_A,
        s2.name AS Name_B,
        CONCAT(
            "Assess compatibility of these two survivors for a resource-gathering mission. ",
            "Survivor 1: ", s1.name, ". ",
            "Survivor 2: ", s2.name, ". ",
            "Give a score from 1-10 and a 1-sentence reason."
        ) AS prompt
    FROM Survivors s1
    JOIN Survivors s2 ON s1.survivor_id < s2.survivor_id
    LIMIT 1
)
SELECT
    Name_A,
    Name_B,
    content AS ai_assessment
FROM ML.PREDICT(
    MODEL GeminiPro,
    (SELECT Name_A, Name_B, prompt FROM PairData)
);

Beklenen çıkış:

Name_A          | Name_B            | ai_assessment
----------------|-------------------|----------------
"David Chen"    | "Dr. Elena Frost" | "**Score: 9/10** Their compatibility is extremely high as David's practical, hands-on scavenging skills are perfectly complemented by Dr. Frost's specialized knowledge to identify critical medical supplies and avoid biological hazards."

6. 🚀 Karma arama ile Graph RAG temsilcinizi oluşturma

1. Sistem Mimarisine Genel Bakış

Bu bölümde, temsilcinize farklı sorgu türlerini işleme esnekliği sağlayan çok yöntemli bir arama sistemi oluşturulur. Sistem üç katmandan oluşur: Temsilci Katmanı, Araç Katmanı, Hizmet Katmanı.

architecture_hybrid_search

Neden üç katman?

  • İşlevlerin ayrılması: Temsilci niyete, araçlar arayüze, hizmet ise uygulamaya odaklanır.
  • Esneklik: Temsilci, belirli yöntemleri zorunlu kılabilir veya yapay zekanın otomatik olarak yönlendirmesine izin verebilir.
  • Optimizasyon: Yöntem bilindiğinde pahalı yapay zeka analizini atlayabilir.

Bu bölümde, öncelikle semantik aramayı (RAG) uygulayacaksınız. Bu arama türünde, sonuçlar yalnızca anahtar kelimelere göre değil, anlama göre bulunur. Karma aramanın birden fazla yöntemi nasıl birleştirdiğini daha sonra açıklayacağız.

2. RAG hizmeti uygulaması

👉💻 Terminalde aşağıdaki komutu çalıştırarak dosyayı Cloud Shell Düzenleyici'de açın:

cloudshell edit ~/way-back-home/level_2/backend/services/hybrid_search_service.py

# TODO: REPLACE_SQL yorumunu bulma

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

        # This is your working query from the successful run!
        sql = """
            WITH query_embedding AS (
                SELECT embeddings.values AS val
                FROM ML.PREDICT(
                    MODEL TextEmbeddings,
                    (SELECT @query AS content)
                )
            )
            SELECT
                s.survivor_id,
                s.name AS survivor_name,
                s.biome,
                sk.skill_id,
                sk.name AS skill_name,
                sk.category,
                COSINE_DISTANCE(
                    sk.skill_embedding, 
                    (SELECT val FROM query_embedding)
                ) AS distance
            FROM Survivors s
            JOIN SurvivorHasSkill shs ON s.survivor_id = shs.survivor_id
            JOIN Skills sk ON shs.skill_id = sk.skill_id
            WHERE sk.skill_embedding IS NOT NULL
            ORDER BY distance ASC
            LIMIT @limit
        """

3. Semantik Arama Aracı Tanımı

👉💻 Terminalde aşağıdaki komutu çalıştırarak dosyayı Cloud Shell Düzenleyici'de açın:

cloudshell edit ~/way-back-home/level_2/backend/agent/tools/hybrid_search_tools.py

hybrid_search_tools.py içinde # TODO: REPLACE_SEMANTIC_SEARCH_TOOL yorumunu bulun.

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

async def semantic_search(query: str, limit: int = 10) -> str:
    """
    Force semantic (RAG) search using embeddings.
    
    Use this when you specifically want to find things by MEANING,
    not just matching keywords. Great for:
    - Finding conceptually similar items
    - Handling vague or abstract queries
    - When exact terms are unknown
    
    Example: "healing abilities" will find "first aid", "surgery", 
    "herbalism" even though no keywords match exactly.
    
    Args:
        query: What you're looking for (describe the concept)
        limit: Maximum results
        
    Returns:
        Semantically similar results ranked by relevance
    """
    try:
        service = _get_service()
        result = service.smart_search(
            query, 
            force_method=SearchMethod.RAG,
            limit=limit
        )
        
        return _format_results(
            result["results"],
            result["analysis"],
            show_analysis=True
        )
        
    except Exception as e:
        return f"Error in semantic search: {str(e)}"

Temsilci kullandığında:

  • Benzerlik soran sorgular ("X'e benzer olanları bul")
  • Kavramsal sorgular ("iyileştirme yetenekleri")
  • Anlamı anlamanın kritik olduğu durumlarda

4. Temsilci Karar Rehberi (Talimatlar)

Temsilci tanımında, anlamsal aramayla ilgili bölümü kopyalayıp talimata yapıştırın.

👉💻 Terminalde aşağıdaki komutu çalıştırarak dosyayı Cloud Shell Düzenleyici'de açın:

cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py

Temsilci, doğru aracı seçmek için bu talimatı kullanır:

👉agent.py dosyasında # TODO: REPLACE_SEARCH_LOGIC yorumunu bulun ve Replace this whole line ifadesini aşağıdaki kodla değiştirin:

- `semantic_search`: Force RAG/embedding search
  Use for: "Find similar to X", conceptual queries, unknown terminology
  Example: "Find skills related to healing"

👉# TODO: ADD_SEARCH_TOOLReplace this whole line yorumunu bulun ve aşağıdaki kodla değiştirin:

    semantic_search,         # Force RAG

5. Karma aramanın işleyiş şeklini anlama (Salt okunur, işlem gerekmez)

2-4. adımlarda, sonuçları anlama göre bulan temel arama yöntemi olan semantik aramayı (RAG) uyguladınız. Ancak sistemin "Karma Arama" olarak adlandırıldığını fark etmiş olabilirsiniz. Tüm bu unsurlar birbiriyle şu şekilde bağlantılıdır:

Karma Birleştirme'nin işleyiş şekli:

way-back-home/level_2/backend/services/hybrid_search_service.py dosyasında hybrid_search() çağrıldığında hizmet, HER İKİ aramayı da çalıştırır ve sonuçları birleştirir:

# Location: backend/services/hybrid_search_service.py

    rank_kw = keyword_ranks.get(surv_id, float('inf'))
    rank_rag = rag_ranks.get(surv_id, float('inf'))

    rrf_score = 0.0
    if rank_kw != float('inf'):
        rrf_score += 1.0 / (K + rank_kw)
    if rank_rag != float('inf'):
        rrf_score += 1.0 / (K + rank_rag)

    combined_score = rrf_score

Bu codelab'de, temel bileşen olan semantik arama bileşenini (RAG) uyguladınız. Anahtar kelime ve karma yöntemler hizmette zaten uygulanmıştır. Temsilciniz üç yöntemi de kullanabilir.

Tebrikler! Graph RAG Agent'ınızı karma arama ile başarıyla tamamladınız.

7. 🚀 ADK Web ile Temsilcinizi Test Etme

Temsilcinizi test etmenin en kolay yolu, temsilcinizi yerleşik bir sohbet arayüzüyle başlatan adk web komutunu kullanmaktır.

1. Temsilciyi çalıştırma

👉💻 Arka uç dizinine (ajanınızın tanımlandığı yer) gidin ve web arayüzünü başlatın:

cd ~/way-back-home/level_2/backend
uv run adk web

Bu komut, içinde tanımlanan aracıyı başlatır.

agent/agent.py

ve test için bir web arayüzü açar.

👉 URL'yi açın:

Komut, yerel bir URL (genellikle http://127.0.0.1:8000 veya benzeri) döndürür. Bu bağlantıyı tarayıcınızda açın.

adk web

URL'yi tıkladığınızda ADK web kullanıcı arayüzünü görürsünüz. Sol üst köşeden "agent"ı seçtiğinizden emin olun.

adk_ui

2. Arama özelliklerini test etme

Temsilci, sorgularınızı akıllıca yönlendirecek şekilde tasarlanmıştır. Farklı arama yöntemlerini görmek için sohbet penceresinde aşağıdaki girişleri deneyin.

Anahtar kelimeler eşleşmese bile öğeleri anlam ve kavrama göre bulur.

Test Sorguları: (Aşağıdakilerden birini seçin)

Who can help with injuries?
What abilities are related to survival?

Dikkat edilecek noktalar:

  • Gerekçede semantik veya RAG aramadan bahsedilmelidir.
  • Kavramsal olarak alakalı sonuçlar görmeniz gerekir (ör. "İlk Yardım" için arama yaparken "Ameliyat").
  • Sonuçlarda 🧬 simgesi gösterilir.

Karmaşık sorgular için anahtar kelime filtrelerini semantik anlamla birleştirir.

Test Sorguları: (Aşağıdakilerden birini seçin)

Find someone who can fly a plane in the volcanic area
Who has healing abilities in the FOSSILIZED?
Who has healing abilities in the mountains?

Dikkat edilecek noktalar:

  • Gerekçede karma aramadan bahsedilmelidir.
  • Sonuçlar her iki ölçütle de (kavram + konum/kategori) eşleşmelidir.
  • Her iki yöntemle de bulunan sonuçlarda 🔀 simgesi bulunur ve bu sonuçlar en üstte sıralanır.

👉💻 Testi tamamladığınızda komut satırınızda Ctrl+C tuşuna basarak işlemi sonlandırın.

8. 🚀 Uygulamanın tamamını çalıştırma

Full Stack Mimarisine Genel Bakış

architecture_fullstack

SessionService ve Runner ekleme

👉💻 Terminalde, aşağıdaki komutu çalıştırarak chat.py dosyasını Cloud Shell Düzenleyici'de açın (Devam etmeden önce önceki işlemi sonlandırmak için "Ctrl+C" tuşlarına bastığınızdan emin olun):

cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py

👉chat.py dosyasında # TODO: REPLACE_INMEMORY_SERVICES yorumunu bulun ve bu satırın tamamını aşağıdaki kodla değiştirin:

    session_service = InMemorySessionService()
    memory_service = InMemoryMemoryService()

👉chat.py dosyasında # TODO: REPLACE_RUNNER yorumunu bulun ve bu satırın tamamını aşağıdaki kodla değiştirin:

runner = Runner(
    agent=root_agent, 
    session_service=session_service,
    memory_service=memory_service,
    app_name="survivor-network"
)

1. Başvuruyu başlatın

Önceki terminal hâlâ çalışıyorsa Ctrl+C tuşuna basarak sonlandırın.

👉💻 Uygulamayı başlatma:

cd ~/way-back-home/level_2/
./start_app.sh

Arka uç başarıyla başlatıldığında aşağıdaki gibi Local: http://localhost:5173/" ifadesini görürsünüz: fronted

👉 Terminalden Local: http://localhost:5173/ adresini tıklayın.

sohbet

Sorgu:

Find skills similar to healing

sohbet

Bu durumda ne olur?

  • Temsilci, benzerlik isteğini tanır
  • "İyileşme" için yerleştirme oluşturur.
  • Anlamsal olarak benzer becerileri bulmak için kosinüs uzaklığını kullanır.
  • Döndürülen sonuç: ilk yardım (adlar "iyileşme" ile eşleşmese bile)

Sorgu:

Find medical skills in the mountains

Bu durumda ne olur?

  1. Anahtar kelime bileşeni: category='medical' filtresi
  2. Anlamsal bileşen: "Tıbbi" kelimesini yerleştirin ve benzerliğe göre sıralayın.
  3. Birleştirme: Sonuçları birleştirerek her iki yöntemle de bulunan sonuçlara öncelik verir. 🔀

Sorgu (isteğe bağlı):

Who is good at survival and in the forest?

Bu durumda ne olur?

  • Anahtar kelime bulguları: biome='forest'
  • Semantik bulgular: "hayatta kalma" ile benzer beceriler
  • Karma, en iyi sonuçlar için her ikisini de birleştirir.

👉💻 Testi tamamladığınızda terminalde Ctrl+C tuşlarına basarak testi sonlandırın.

4. (!ONLY FOR WORKSHOP ATTENDEE) Konumunuzu güncelleme

👉💻 Tamamlama komut dosyasını çalıştırın:

cd ~/way-back-home/level_2
./set_level_2.sh

Şimdi waybackhome.dev uygulamasını açın. Konumunuzun güncellendiğini göreceksiniz. 2. seviyeyi tamamladığınız için tebrikler.

oyun sonucu

9. ☕️ [İsteğe bağlı] Çok Kalıplı Ardışık Düzen (Salt Okunur) — Araç Katmanı

Neden Çok Kalıplı Bir Pipeline'a İhtiyacımız Var?

Hayatta kalma ağı yalnızca metinden ibaret değildir. Sahadaki hayatta kalanlar, yapılandırılmamış verileri doğrudan sohbet üzerinden gönderir:

  • 📸 Görseller: Kaynakların, tehlikelerin veya ekipmanların fotoğrafları
  • 🎥 Videolar: Durum raporları veya acil durum yayınları
  • 📄 Metin: Saha notları veya günlükler

Hangi Dosyaları İşliyoruz?

Mevcut verileri aradığımız önceki adımın aksine, burada Kullanıcı Tarafından Yüklenen Dosyalar'ı işleriz. chat.py arayüzü, dosya eklerini dinamik olarak işler:

Kaynak

İçerik

Hedef

Kullanıcı Bağlılığı

Resim/Video/Metin

Grafiğe eklenecek bilgiler

Sohbet Bağlamı

"İşte malzemelerin fotoğrafı"

Amaç ve ek ayrıntılar

Planlı yaklaşım: Sıralı temsilci ardışık düzeni

Uzmanlaşmış temsilcileri birbirine bağlayan bir sıralı temsilci (multimedia_agent.py) kullanıyoruz:

architecture_uploading

Bu, backend/agent/multimedia_agent.py içinde SequentialAgent olarak tanımlanır.

Araç katmanı, temsilcilerin çağırabileceği özellikleri sağlar. Araçlar, "nasıl" sorusunu yanıtlar. Dosya yükleme, varlıkları ayıklama ve veritabanına kaydetme gibi işlemleri gerçekleştirir.

1. Araçlar dosyasını açma

👉💻 level_2/backend/agent/tools/extraction_tools.py dosyasını açın veya terminale aşağıdaki komutu yazın. Yeni bir terminal açın. Terminalde, dosyayı Cloud Shell Düzenleyici'de açın:

cloudshell edit ~/way-back-home/level_2/backend/agent/tools/extraction_tools.py

2. upload_media aracını uygulama

Bu araç, yerel bir dosyayı Google Cloud Storage'a yükler.

👉 def upload_media(file_path: str, survivor_id: Optional[str] = None) -> Dict[str, Any]: dosyasında, dosyaları GCS'ye yükleme ve türlerini algılama ile ilgili aşağıdaki kod bulunur:

    """
    Upload media file to GCS and detect its type.
    
    Args:
        file_path: Path to the local file
        survivor_id: Optional survivor ID to associate with upload
        
    Returns:
        Dict with gcs_uri, media_type, and status
    """
    try:
        if not file_path:
            return {"status": "error", "error": "No file path provided"}
        
        # Strip quotes if present
        file_path = file_path.strip().strip("'").strip('"')
        
        if not os.path.exists(file_path):
            return {"status": "error", "error": f"File not found: {file_path}"}
        
        gcs_uri, media_type, signed_url = gcs_service.upload_file(file_path, survivor_id)
        
        return {
            "status": "success",
            "gcs_uri": gcs_uri,
            "signed_url": signed_url,
            "media_type": media_type.value,
            "file_name": os.path.basename(file_path),
            "survivor_id": survivor_id
        }
    except Exception as e:
        logger.error(f"Upload failed: {e}")
        return {"status": "error", "error": str(e)}

3. extract_from_media aracını uygulama

Bu araç bir yönlendiricidir. media_type değerini kontrol eder ve doğru ayıklayıcıya (metin, resim veya video) gönderir.

👉 async def extract_from_media(gcs_uri: str, media_type: str, signed_url: Optional[str] = None) -> Dict[str, Any]: dilinde, aşağıdaki kod yüklenen medyalardan varlıkların ve ilişkilerin nasıl çıkarılacağıyla ilgilidir.

    """
    Extract entities and relationships from uploaded media.
    
    Args:
        gcs_uri: GCS URI of the uploaded file
        media_type: Type of media (text/image/video)
        signed_url: Optional signed URL for public/temporary access
        
    Returns:
        Dict with extraction results
    """
    try:
        if not gcs_uri:
             return {"status": "error", "error": "No GCS URI provided"}

        # Select appropriate extractor
        if media_type == MediaType.TEXT.value or media_type == "text":
            result = await text_extractor.extract(gcs_uri)
        elif media_type == MediaType.IMAGE.value or media_type == "image":
            result = await image_extractor.extract(gcs_uri)
        elif media_type == MediaType.VIDEO.value or media_type == "video":
            result = await video_extractor.extract(gcs_uri)
        else:
            return {"status": "error", "error": f"Unsupported media type: {media_type}"}
            
        # Inject signed URL into broadcast info if present
        if signed_url:
            if not result.broadcast_info:
                result.broadcast_info = {}
            result.broadcast_info['thumbnail_url'] = signed_url
        
        return {
            "status": "success",
            "extraction_result": result.to_dict(), # Return valid JSON dict instead of object
            "summary": result.summary,
            "entities_count": len(result.entities),
            "relationships_count": len(result.relationships),
            "entities": [e.to_dict() for e in result.entities],
            "relationships": [r.to_dict() for r in result.relationships]
        }
    except Exception as e:
        logger.error(f"Extraction failed: {e}")
        return {"status": "error", "error": str(e)}

Uygulamayla İlgili Önemli Ayrıntılar:

  • Çok formatlı giriş: Hem yazılı istemi (_get_extraction_prompt()) hem de görüntü nesnesini generate_content modeline iletiyoruz.
  • Yapılandırılmış çıkış: response_mime_type="application/json", LLM'nin geçerli JSON döndürmesini sağlar. Bu, ardışık düzen için çok önemlidir.
  • Görsel Varlık Bağlama: Gemini'ın belirli karakterleri tanıyabilmesi için istemde bilinen varlıklar yer alır.

4. save_to_spanner aracını uygulama

Bu araç, ayıklanan varlıkları ve ilişkileri Spanner Graph DB'ye kaydeder.

👉 def save_to_spanner(extraction_result: Any, survivor_id: Optional[str] = None) -> Dict[str, Any]: dosyasında, ayıklanan varlıkların ve ilişkilerin Spanner Graph DB'ye nasıl kaydedileceğiyle ilgili aşağıdaki kod yer alır.

    """
    Save extracted entities and relationships to Spanner Graph DB.
    
    Args:
        extraction_result: ExtractionResult object (or dict from previous step if passed as dict)
        survivor_id: Optional survivor ID to associate with the broadcast
        
    Returns:
        Dict with save statistics
    """
    try:
        # Handle if extraction_result is passed as the wrapper dict from extract_from_media
        result_obj = extraction_result
        if isinstance(extraction_result, dict) and 'extraction_result' in extraction_result:
             result_obj = extraction_result['extraction_result']
        
        # If result_obj is a dict (from to_dict()), reconstruct it
        if isinstance(result_obj, dict):
            from extractors.base_extractor import ExtractionResult
            result_obj = ExtractionResult.from_dict(result_obj)
        
        if not result_obj:
            return {"status": "error", "error": "No extraction result provided"}
            
        stats = spanner_service.save_extraction_result(result_obj, survivor_id)
        
        return {
            "status": "success",
            "entities_created": stats['entities_created'],
            "entities_existing": stats['entities_found_existing'],
            "relationships_created": stats['relationships_created'],
            "broadcast_id": stats['broadcast_id'],
            "errors": stats['errors'] if stats['errors'] else None
        }
    except Exception as e:
        logger.error(f"Spanner save failed: {e}")
        return {"status": "error", "error": str(e)}

Temsilcilere üst düzey araçlar sunarak temsilcinin akıl yürütme yeteneklerinden yararlanırken veri bütünlüğünü de sağlıyoruz.

5. GCS hizmetini güncelleme

GCSService, Google Cloud Storage'a gerçek dosya yükleme işlemini gerçekleştirir.

👉💻 level_2/backend/services/gcs_service.py dosyasını açın veya dosyayı Cloud Shell Düzenleyici'de açmak için terminale şunu yazın:

cloudshell edit ~/way-back-home/level_2/backend/services/gcs_service.py

👉 def upload_file(self, file_path: str, survivor_id: Optional[str] = None) -> Tuple[str, MediaType, str]: dosyasında, ayıklanan varlıkların ve ilişkilerin Spanner Graph DB'ye nasıl kaydedileceğiyle ilgili aşağıdaki kod yer alır.

        blob = self.bucket.blob(blob_name)
        blob.upload_from_filename(file_path)

Bu işlemi bir hizmete soyutlayarak temsilcinin GCS paketleri, blob adları veya imzalı URL oluşturma hakkında bilgi sahibi olması gerekmez. Yalnızca "yükle" seçeneği sunuluyor.

6. Neden temsilci tabanlı iş akışı geleneksel yaklaşımlardan daha iyi?

Temsilci tabanlı çözümlerin avantajı:

Özellik

Batch Ardışık Düzen

Etkinliğe Dayalı

Temsilci Tabanlı İş Akışı

Karmaşıklık

Düşük (1 komut dosyası)

Yüksek (5'ten fazla hizmet)

Düşük (1 Python dosyası: multimedia_agent.py)

Durum yönetimi

Genel değişkenler

Sert (ayrılmış)

Birleşik (Temsilci durumu)

Hata İşleme

Kilitlenme sayısı

Sessiz günlükler

Etkileşimli ("Bu dosyayı okuyamadım")

Kullanıcı Geri Bildirimi

Konsol yazdırma işlemleri

Anket gerekiyor

Anında (Sohbetin bir parçası)

Uyarlanabilirlik

Sabit mantık

Katı işlevler

Akıllı (LLM sonraki adıma karar verir)

Bağlam Farkındalığı

Yok

Yok

Tam (Kullanıcı niyetini bilir)

Neden önemli? multimedia_agent.py (4 alt ajana sahip bir SequentialAgent: Yükleme → Ayıklama → Kaydetme → Özet) kullanarak karmaşık altyapıyı VE kırılgan komut dosyalarını akıllı, etkileşimli uygulama mantığıyla değiştiriyoruz.

10. ☕️ [İsteğe bağlı] Çok formatlı ardışık düzen (salt okunur) - Temsilci katmanı

Ajan katmanı, zekayı tanımlar. Bu katmanda, görevleri gerçekleştirmek için araçları kullanan ajanlar yer alır. Her temsilcinin belirli bir rolü vardır ve bağlamı bir sonrakine aktarır. Aşağıda çoklu temsilci sisteminin mimari diyagramı verilmiştir.

agent_diagram

1. Temsilci dosyasını açma

👉💻 level_2/backend/agent/multimedia_agent.py dosyasını açın veya terminale aşağıdaki komutu yazın. Yeni bir terminal açın. Terminalde, dosyayı Cloud Shell Düzenleyici'de açın:

cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py

2. Yükleme aracısını tanımlama

Bu temsilci, kullanıcının mesajından bir dosya yolu çıkarır ve bunu GCS'ye yükler.

👉multimedia_agent.py dosyasında, aşağıdaki kodla GCS'ye yüklenen upload_agent oluşturulur:

upload_agent = LlmAgent(
    name="UploadAgent",
    model="gemini-2.5-flash",
    instruction="""Extract the file path from the user's message and upload it.

Use `upload_media(file_path, survivor_id)` to upload the file.
The survivor_id is optional - include it if the user mentions a specific survivor (e.g., "survivor Sarah" -> "Sarah").
If the user provides a path like "/path/to/file", use that.

Return the upload result with gcs_uri and media_type.""",
    tools=[upload_media],
    output_key="upload_result"
)

3. Ayıklama Temsilcisi'ni tanımlama

Bu temsilci, yüklenen medyayı "görür" ve Gemini Vision'ı kullanarak yapılandırılmış verileri ayıklar.

👉multimedia_agent.py dosyasında, aşağıdaki kodla, yüklenen medyadan bilgi çıkaran extraction_agent oluşturulur:

extraction_agent = LlmAgent(
    name="ExtractionAgent", 
    model="gemini-2.5-flash",
    instruction="""Extract information from the uploaded media.

Previous step result: {upload_result}

Use `extract_from_media(gcs_uri, media_type, signed_url)` with the values from the upload result.
The gcs_uri is in upload_result['gcs_uri'], media_type in upload_result['media_type'], and signed_url in upload_result['signed_url'].

Return the extraction results including entities and relationships found.""",
    tools=[extract_from_media],
    output_key="extraction_result"
)

instruction öğesinin {upload_result} öğesine nasıl referans verdiğine dikkat edin. ADK'da temsilciler arasında durum bu şekilde aktarılır.

4. Spanner Agent'ı tanımlama

Bu temsilci, ayıklanan varlıkları ve ilişkileri grafik veritabanına kaydeder.

👉multimedia_agent.py dosyasında, aşağıdaki kodla, ayıklanan bilgileri veritabanına kaydeden spanner_agent oluşturulur:

spanner_agent = LlmAgent(
    name="SpannerAgent",
    model="gemini-2.5-flash", 
    instruction="""Save the extracted information to the database.

Upload result: {upload_result}
Extraction result: {extraction_result}

Use `save_to_spanner(extraction_result, survivor_id)` to save to Spanner.
Pass the WHOLE `extraction_result` object/dict from the previous step.
Include survivor_id if it was provided in the upload step.

Return the save statistics.""",
    tools=[save_to_spanner],
    output_key="spanner_result"
)

Bu temsilci, önceki iki adımdan da (upload_result ve extraction_result) bağlam bilgisi alır.

5. Özet Temsilcisi'ni tanımlama

Bu temsilci, önceki tüm adımlardan elde edilen sonuçları kullanıcı dostu bir yanıtta birleştirir.

👉multimedia_agent.py dosyasında, aşağıdaki kodla sonucu özetleyen summary_agent istemi tanımlanır:

USE_MEMORY_BANK = os.getenv("USE_MEMORY_BANK", "false").lower() == "true"
save_msg = "6. Mention that the data is also being synced to the memory bank." if USE_MEMORY_BANK else ""

summary_instruction = f"""Provide a user-friendly summary of the media processing.

Upload: {{upload_result}}
Extraction: {{extraction_result}}
Database: {{spanner_result}}

Summarize:
1. What file was processed (name and type)
2. Key information extracted (survivors, skills, needs, resources found) - list names and counts
3. Relationships identified
4. What was saved to the database (broadcast ID, number of entities)
5. Any issues encountered
{save_msg}

Be concise but informative."""

Bu temsilcinin araçlara ihtiyacı yoktur. Yalnızca paylaşılan bağlamı okur ve kullanıcı için net bir özet oluşturur.

🧠 Mimari Özeti

Katman

Dosya

Sorumluluk

Araçlar

extraction_tools.py + gcs_service.py

Nasıl yapılır?: Yükleme, ayıklama, kaydetme

Ajan

multimedia_agent.py

Ne?: Ardışık düzeni yönetme

11. 🚀 Çok formatlı Data Pipelines: Düzenleme

Yeni sistemimizin temelini, backend/agent/multimedia_agent.py içinde tanımlanan MultimediaExtractionPipeline oluşturur. ADK'deki (Agent Development Kit) Sequential Agent kalıbını kullanır.

1. Neden sıralı?

Yükleme işlemi, doğrusal bir bağımlılık zinciridir:

  1. Dosyayı yükleyene kadar verileri ayıklayamazsınız.
  2. Verileri ayıklayana kadar kaydedemezsiniz (Ayıklama).
  3. Sonuçları alana kadar özetleme yapamazsınız (Kaydet).

SequentialAgent bunun için idealdir. Bir temsilcinin çıkışını bir sonraki temsilciye bağlam/giriş olarak iletir.

2. Temsilci Tanımı

Şimdi multimedia_agent.py dosyasının alt kısmında ardışık düzenin nasıl oluşturulduğuna bakalım: 👉💻 Terminalde aşağıdaki komutu çalıştırarak dosyayı Cloud Shell Düzenleyici'de açın:

cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py

Önceki iki adımdan da giriş alır. # TODO: REPLACE_ORCHESTRATION yorumunu bulun. Bu satırın tamamını aşağıdaki kodla değiştirin:

    sub_agents=[upload_agent, extraction_agent, spanner_agent, summary_agent]

3. Root Agent ile bağlantı kurun

👉💻 Terminalde aşağıdaki komutu çalıştırarak dosyayı Cloud Shell Düzenleyici'de açın:

cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py

# TODO: REPLACE_ADD_SUBAGENT yorumunu bulun. Bu satırın tamamını aşağıdaki kodla değiştirin:

    sub_agents=[multimedia_agent],

Bu tek nesne, dört "uzmanı" tek bir çağrılabilir varlıkta birleştirir.

4. Temsilciler Arasında Veri Akışı

Her temsilci, çıkışını sonraki temsilcilerin erişebileceği paylaşılan bir bağlamda depolar:

architecture_uploading

5. Uygulamayı açın (uygulama hâlâ çalışıyorsa bu adımı atlayın).

👉💻 Uygulamayı başlatma:

cd ~/way-back-home/level_2/
./start_app.sh

👉 Terminalden Local: http://localhost:5173/ adresini tıklayın.

6. Test Resmi Yükleme

👉 Sohbet arayüzünde, buradaki fotoğraflardan birini seçip kullanıcı arayüzüne yükleyin:

Sohbet arayüzünde, temsilciye bağlamınızla ilgili bilgi verin:

Here is the survivor note

Ardından resmi buraya ekleyin.

upload_input

upload_result

👉💻 Testi tamamladığınızda terminalde "Ctrl+C" tuşlarına basarak işlemi sonlandırın.

6. GCS paketine çok formatlı yüklemeyi doğrulama

gcs

  • Paketinizi seçip media seçeneğini tıklayın.

medya

  • Yüklediğiniz resmi buradan görüntüleyebilirsiniz. uploaded_img

7. Spanner'da çok formatlı yüklemeyi doğrulama (isteğe bağlı)

Aşağıda, test_photo1 için kullanıcı arayüzündeki örnek çıkış gösterilmektedir.

  • Google Cloud Console Spanner'ı açın.
  • Örneğinizi seçin: Survivor Network
  • Veritabanınızı seçin: graph-db
  • Sol kenar çubuğunda Spanner Studio'yu tıklayın.

👉 Spanner Studio'da yeni verileri sorgulayın:

SELECT 
  s.name AS Survivor,
  s.role AS Role,
  b.name AS Biome,
  r.name AS FoundResource,
  s.created_at
FROM Survivors s
LEFT JOIN SurvivorInBiome sib ON s.survivor_id = sib.survivor_id
LEFT JOIN Biomes b ON sib.biome_id = b.biome_id
LEFT JOIN SurvivorFoundResource sfr ON s.survivor_id = sfr.survivor_id
LEFT JOIN Resources r ON sfr.resource_id = r.resource_id
ORDER BY s.created_at DESC;

Aşağıdaki sonucu görerek bunu doğrulayabiliriz:

spanner_verify

12. ☕️ [İsteğe bağlı] Agent Engine ile Memory Bank

1. Hafıza nasıl çalışır?

Sistem, hem anlık bağlamı hem de uzun süreli öğrenmeyi yönetmek için ikili bellek yaklaşımı kullanır.

memory_bank

2. Anı Konuları Nedir?

Hafıza Konuları, temsilcinin sohbetler boyunca hatırlaması gereken bilgi kategorilerini tanımlar. Bunları, farklı kullanıcı tercihi türleri için dosya dolapları olarak düşünebilirsiniz.

2 Konumuz:

  1. search_preferences: Kullanıcının tercih ettiği arama yöntemi
    • Anahtar kelime araması mı yoksa semantik arama mı tercih ediyorlar?
    • Sık sık hangi becerileri/biyomları arıyorlar?
    • Örnek hafıza: "Kullanıcı, tıbbi beceriler için semantik aramayı tercih ediyor"
  2. urgent_needs_context: Takip ettikleri krizler
    • Hangi kaynakları izliyorlar?
    • Hangi mağdurlar hakkında endişeleniyorlar?
    • Örnek hafıza: "Kullanıcı, Kuzey Kampı'ndaki ilaç sıkıntısını takip ediyor"

3. Anı Konularını Ayarlama

Özel hafıza konuları, temsilcinin neyi hatırlaması gerektiğini tanımlar. Bunlar, Agent Engine dağıtılırken yapılandırılır.

👉💻 Terminalde aşağıdaki komutu çalıştırarak dosyayı Cloud Shell Düzenleyici'de açın:

cloudshell edit ~/way-back-home/level_2/backend/deploy_agent.py

Bu işlem, düzenleyicinizde ~/way-back-home/level_2/backend/deploy_agent.py dosyasını açar.

LLM'ye hangi bilgileri çıkarıp kaydedeceği konusunda yol göstermek için yapı MemoryTopic nesneleri tanımlarız.

👉deploy_agent.py dosyasında # TODO: SET_UP_TOPIC ifadesini şununla değiştirin:

# backend/deploy_agent.py

    custom_topics = [
        # Topic 1: Survivor Search Preferences
        MemoryTopic(
            custom_memory_topic=CustomMemoryTopic(
                label="search_preferences",
                description="""Extract the user's preferences for how they search for survivors. Include:
                - Preferred search methods (keyword, semantic, direct lookup)
                - Common filters used (biome, role, status)
                - Specific skills they value or frequently look for
                - Geographic areas of interest (e.g., "forest biome", "mountain outpost")
                
                Example: "User prefers semantic search for finding similar skills."
                Example: "User frequently checks for survivors in the Swamp Biome."
                """,
            )
        ),
        # Topic 2: Urgent Needs Context
        MemoryTopic(
            custom_memory_topic=CustomMemoryTopic(
                label="urgent_needs_context",
                description="""Track the user's focus on urgent needs and resource shortages. Include:
                - Specific resources they are monitoring (food, medicine, ammo)
                - Critical situations they are tracking
                - Survivors they are particularly concerned about
                
                Example: "User is monitoring the medicine shortage in the Northern Camp."
                Example: "User is looking for a doctor for the injured survivors."
                """,
            )
        )
    ]

4. Ajan Entegrasyonu

Temsilci kodu, bilgileri kaydetmek ve almak için Hafıza Bankası'nı bilmelidir.

👉💻 Terminalde aşağıdaki komutu çalıştırarak dosyayı Cloud Shell Düzenleyici'de açın:

cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py

Bu işlem, düzenleyicinizde ~/way-back-home/level_2/backend/agent/agent.py dosyasını açar.

Temsilci Oluşturma

Temsilciyi oluştururken, etkileşimlerden sonra oturumların belleğe kaydedilmesini sağlamak için after_agent_callback parametresini iletiyoruz. add_session_to_memory işlevi, sohbet yanıtını yavaşlatmamak için eşzamansız olarak çalışır.

👉agent.py dosyasında # TODO: REPLACE_ADD_SESSION_MEMORY yorumunu bulun ve bu satırın tamamını aşağıdaki kodla değiştirin:

async def add_session_to_memory(
        callback_context: CallbackContext
) -> Optional[types.Content]:
    """Automatically save completed sessions to memory bank in the background"""
    if hasattr(callback_context, "_invocation_context"):
        invocation_context = callback_context._invocation_context
        if invocation_context.memory_service:
            # Use create_task to run this in the background without blocking the response
            asyncio.create_task(
                invocation_context.memory_service.add_session_to_memory(
                    invocation_context.session
                )
            )
            logger.info("Scheduled session save to memory bank in background")

Arka Planda Kaydetme

👉agent.py dosyasında # TODO: REPLACE_ADD_MEMORY_BANK_TOOL yorumunu bulun ve bu satırın tamamını aşağıdaki kodla değiştirin:

if USE_MEMORY_BANK:
    agent_tools.append(PreloadMemoryTool())

👉agent.py dosyasında # TODO: REPLACE_ADD_CALLBACK yorumunu bulun ve bu satırın tamamını aşağıdaki kodla değiştirin:

    after_agent_callback=add_session_to_memory if USE_MEMORY_BANK else None

Vertex AI Session Service'i ayarlama

👉💻 Terminalde aşağıdaki komutu çalıştırarak Cloud Shell Düzenleyici'de chat.py dosyasını açın:

cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py

👉chat.py dosyasında # TODO: REPLACE_VERTEXAI_SERVICES yorumunu bulun ve bu satırın tamamını aşağıdaki kodla 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
    )

13. ☕️ [İsteğe bağlı] Temsilciyi Agent Engine'e ekleme

1. Kurulum ve Dağıtım

Hafıza özelliklerini test etmeden önce temsilciyi yeni hafıza konularıyla dağıtmanız ve ortamınızın doğru şekilde yapılandırıldığından emin olmanız gerekir.

Bu işlemi gerçekleştirmek için kullanabileceğiniz bir komut dosyası hazırladık.

Dağıtım komut dosyasını çalıştırma

👉💻 Terminalde dağıtım komut dosyasını çalıştırın:

cd ~/way-back-home/level_2
./deploy_and_update_env.sh

Bu komut dosyası aşağıdaki işlemleri gerçekleştirir:

  • Temsilciyi ve bellek konularını Vertex AI'a kaydetmek için backend/deploy_agent.py komutunu çalıştırır.
  • Yeni temsilci motoru kimliğini yakalar.
  • .env dosyanızı AGENT_ENGINE_ID ile otomatik olarak günceller.
  • USE_MEMORY_BANK=TRUE değerinin .env dosyanızda ayarlandığından emin olun.

[!IMPORTANT] deploy_agent.py içinde custom_topics üzerinde değişiklik yaparsanız Agent Engine'i güncellemek için bu komut dosyasını yeniden çalıştırmanız gerekir.

Hafıza Bankası'nı doğrulama

Şimdi, temsilciye bir tercih öğreterek ve bu tercihin oturumlar arasında kalıcı olup olmadığını kontrol ederek bellek bankasının çalıştığını doğrulayabilirsiniz.

Birinci adım. Uygulamayı açın.

Aşağıdaki talimatları uygulayarak uygulamayı tekrar açın: Önceki terminal hâlâ çalışıyorsa Ctrls+C tuşuna basarak sonlandırın.

👉💻 Uygulamayı başlatma:

cd ~/way-back-home/level_2/
./start_app.sh

👉 Terminalden Local: http://localhost:5173/ adresini tıklayın.

İkinci adım. Bellek Bankası'nı metinle test etme

Sohbet arayüzünde, temsilciye bağlamınızla ilgili bilgi verin:

"I'm planning a medical rescue mission in the mountains. I need survivors with first aid and climbing skills."

👉 Belleğin arka planda işlenmesi için yaklaşık 30 saniye bekleyin.

Üçüncü adım. Yeni oturum başlatma

Mevcut sohbet geçmişini (kısa süreli bellek) temizlemek için sayfayı yenileyin.

Daha önce sağladığınız bağlama dayalı bir soru sorun:

"What kind of missions am I interested in?"

Beklenen yanıt:

"Önceki sohbetlerinize göre şunlarla ilgileniyorsunuz:

  • Tıbbi kurtarma görevleri
  • Dağda/yüksek rakımda yapılan operasyonlar
  • Gerekli beceriler: ilk yardım, tırmanma

Bu ölçütlere uyan hayatta kalanları bulmamı ister misiniz?"

Dördüncü adım. Resim yükleyerek test etme

Bir resim yükleyip şunu sorun:

remember this

Buradaki fotoğraflardan birini veya kendi fotoğrafınızı seçip kullanıcı arayüzüne yükleyebilirsiniz:

Beşinci adım. Vertex AI Agent Engine'de doğrulama

Google Cloud Console Agent Engine'e gidin.

  1. Sol üstteki proje seçiciden projeyi seçtiğinizden emin olun:proje seçici
  2. Önceki komuttan dağıttığınız temsilci motorunu doğrulayın use_memory_bank.sh:temsilci motoruOluşturduğunuz temsilci motorunu tıklayın.
  3. Bu dağıtılan temsilcide Memories sekmesini tıklayın. Tüm hafızayı burada görüntüleyebilirsiniz.anı görüntüleme

👉💻 Testi tamamladığınızda terminalinizde "Ctrl + C" tuşlarına basarak işlemi sonlandırın.

🎉 Tebrikler! Bellek bankasını temsilcinize eklediniz.

14. ☕️ [İsteğe bağlı] Cloud Run'a dağıtma

1. Dağıtım komut dosyasını çalıştırma

👉💻 Dağıtım komut dosyasını çalıştırın:

cd ~/way-back-home/level_2
./deploy_cloud_run.sh

Başarıyla dağıtıldıktan sonra URL'yi alırsınız. Bu, sizin için dağıtılan URL'dir. Dağıtıldı

👉💻 URL'yi almadan önce şu komutu çalıştırarak izin verin:

source .env && gcloud run services add-iam-policy-binding survivor-frontend --region $REGION --member=allUsers --role=roles/run.invoker && gcloud run services add-iam-policy-binding survivor-backend --region $REGION --member=allUsers --role=roles/run.invoker

Dağıtılan URL'ye gidin. Uygulamanızın orada yayınlandığını göreceksiniz.

2. Derleme ardışık düzenini anlama

cloudbuild.yaml dosyası aşağıdaki sıralı adımları tanımlar:

  1. Backend Build: backend/Dockerfile dosyasından Docker görüntüsünü oluşturur.
  2. Backend Deploy: Arka uç container'ını Cloud Run'a dağıtır.
  3. URL'yi yakala: Yeni arka uç URL'sini alır.
  4. Ön uç derlemesi:
    • Bağımlılıkları yükler.
    • VITE_API_URL= ekleyerek React uygulamasını derler.
  5. Frontend Image: frontend/Dockerfile dizininden Docker görüntüsünü oluşturur (statik öğeleri paketler).
  6. Frontend Deploy: Ön uç container'ını dağıtır.

3. Dağıtımı doğrulama

Derleme tamamlandıktan sonra (komut dosyasının sağladığı günlük bağlantısını kontrol edin) şunları doğrulayabilirsiniz:

  1. Cloud Run Console'a gidin.
  2. survivor-frontend hizmetini bulun.
  3. Uygulamayı açmak için URL'yi tıklayın.
  4. Ön ucun arka uçla iletişim kurabildiğinden emin olmak için bir arama sorgusu yapın.

(İSTEĞE BAĞLI) 4. Manuel Dağıtım

Komutları manuel olarak çalıştırmayı tercih ediyorsanız veya süreci daha iyi anlamak istiyorsanız cloudbuild.yaml aracını doğrudan nasıl kullanacağınızı aşağıda bulabilirsiniz.

cloudbuild.yaml adlı dosya yazılıyor

cloudbuild.yaml dosyası, Google Cloud Build'e hangi adımları uygulayacağını bildirir.

  • steps: Sıralı işlemlerin listesi. Her adım bir kapsayıcıda (ör. docker, gcloud, node, bash) çalışır.
  • substitutions: Derleme sırasında iletilebilecek değişkenler (ör. $_REGION).
  • workspace: Adımların dosya paylaşabileceği ortak bir dizindir (backend_url.txt paylaşımına benzer).

Dağıtımı Çalıştırma

Komut dosyası olmadan manuel olarak dağıtmak için gcloud builds submit komutunu kullanın. Gerekli ikame değişkenlerini iletmeniz ZORUNLUDUR.

# Load your env vars first or replace these values manually
export PROJECT_ID=your-project-id
export REGION=us-central1

gcloud builds submit --config cloudbuild.yaml \
    --project "$PROJECT_ID" \
    --substitutions _REGION="us-central1",_GOOGLE_API_KEY="",_AGENT_ENGINE_ID="your-agent-id",_USE_MEMORY_BANK="TRUE",_GOOGLE_GENAI_USE_VERTEXAI="TRUE"

15. Sonuç

1. Oluşturduklarınız

✅ Graph Database: Spanner with nodes (survivors, skills) and edges (relationships)
✅ AI Search: Keyword, semantic, and hybrid search with embeddings
✅ Multimodal Pipeline: Extract entities from images/video with Gemini
✅ Multi-Agent System: Coordinated workflow with ADK
✅ Memory Bank: Long-term personalization with Vertex AI
✅ Production Deployment: Cloud Run + Agent Engine

2. Mimari Özeti

architecture_fullstack

3. En Önemli Noktalar

  1. Graph RAG: Akıllı arama için grafik veritabanı yapısını semantik yerleştirmelerle birleştirir.
  2. Çoklu Temsilci Modelleri: Karmaşık, çok adımlı iş akışları için sıralı ardışık düzenler
  3. Çok formatlı yapay zeka: Yapılandırılmamış medyadan (resimler/videolar) yapılandırılmış verileri ayıklama
  4. Durum bilgisi olan temsilciler: Memory Bank, oturumlar arasında kişiselleştirme sağlar.

4. Atölye İçeriği

5. Kaynaklar