1. Giriş

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

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
- 👉 Doğrudan Cloud Shell Düzenleyici'ye gitmek için bu bağlantıyı tıklayın.
- 👉 Bugün herhangi bir noktada yetkilendirme yapmanız istenirse devam etmek için Authorize'ı (Yetkilendir) tıklayın.

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

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

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

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

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
- Son adımda, bağlantıyı tıklayıp Spanner Studio'yu açtığınızdan emin olun.

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 izlemeSurvivorHasSkill: Yetenek envanteriSurvivorHasNeed: Etkin sorunların listesiSurvivorFoundResource: Öğelerin envanteriSurvivorCanHelp: 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: 
👉 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: 
👉 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: 
🔎 [İ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: 
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:
- Benzer bir grafik sorgusu çalıştırma
- Döndürülen değer: "Dr. Frost has Medical Training and can help Captain Tanaka"
- 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

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

👉 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-004modelini 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.PREDICTkullanı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:

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:

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:

İş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ış:

6. Semantik aramayı test etme
Ş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_embeddinggeçici tablosunda depolar.
Beklenen sonuçlar (daha düşük mesafe = daha benzer):

7. Analiz için Gemini modeli oluşturma

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

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

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.

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.

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.
🧬 A. Graph RAG (Anlamsal Arama)
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.
🔀 B. Karma arama
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ış

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: 
👉 Terminalden Local: http://localhost:5173/ adresini tıklayın.

2. Semantik aramayı test etme
Sorgu:
Find skills similar to healing

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)
3. Karma aramayı test etme
Sorgu:
Find medical skills in the mountains
Bu durumda ne olur?
- Anahtar kelime bileşeni:
category='medical'filtresi - Anlamsal bileşen: "Tıbbi" kelimesini yerleştirin ve benzerliğe göre sıralayın.
- 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.

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:

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ü nesnesinigenerate_contentmodeline 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ı: |
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.

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 |
| Nasıl yapılır?: Yükleme, ayıklama, kaydetme |
Ajan |
| 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:
- Dosyayı yükleyene kadar verileri ayıklayamazsınız.
- Verileri ayıklayana kadar kaydedemezsiniz (Ayıklama).
- 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:

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.


👉💻 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
- Google Cloud Console Storage'ı açın.
- Cloud Storage'da "paket" seçin

- Paketinizi seçip
mediaseçeneğini tıklayın.

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

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:

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.

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:
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"
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.pykomutunu çalıştırır. - Yeni temsilci motoru kimliğini yakalar.
.envdosyanızıAGENT_ENGINE_IDile otomatik olarak günceller.USE_MEMORY_BANK=TRUEdeğerinin.envdosyanı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.
- Sol üstteki proje seçiciden projeyi seçtiğinizden emin olun:

- Önceki komuttan dağıttığınız temsilci motorunu doğrulayın
use_memory_bank.sh:
Oluşturduğunuz temsilci motorunu tıklayın. - Bu dağıtılan temsilcide
Memoriessekmesini tıklayın. Tüm hafızayı burada görüntüleyebilirsiniz.
👉💻 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. 
👉💻 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:
- Backend Build:
backend/Dockerfiledosyasından Docker görüntüsünü oluşturur. - Backend Deploy: Arka uç container'ını Cloud Run'a dağıtır.
- URL'yi yakala: Yeni arka uç URL'sini alır.
- Ön uç derlemesi:
- Bağımlılıkları yükler.
VITE_API_URL=ekleyerek React uygulamasını derler.
- Frontend Image:
frontend/Dockerfiledizininden Docker görüntüsünü oluşturur (statik öğeleri paketler). - 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:
- Cloud Run Console'a gidin.
survivor-frontendhizmetini bulun.- Uygulamayı açmak için URL'yi tıklayın.
- Ö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.txtpaylaşı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

3. En Önemli Noktalar
- Graph RAG: Akıllı arama için grafik veritabanı yapısını semantik yerleştirmelerle birleştirir.
- Çoklu Temsilci Modelleri: Karmaşık, çok adımlı iş akışları için sıralı ardışık düzenler
- Çok formatlı yapay zeka: Yapılandırılmamış medyadan (resimler/videolar) yapılandırılmış verileri ayıklama
- Durum bilgisi olan temsilciler: Memory Bank, oturumlar arasında kişiselleştirme sağlar.
4. Atölye İçeriği
- Level0: Kimliğinizi Tanımlama
- Level1: Nokta Konum
- Level2 This One: Graph RAG, ADK ve Memory Bank ile Çok Kalıplı Yapay Zeka Ajanı Oluşturma
- Level3: ADK çift yönlü akış temsilcisi oluşturma
- Level4: Canlı Çift Yönlü Çoklu Temsilci Sistemi
- Level5: Event-Driven Architecture with Google ADK, A2A, and Kafka