1. Einführung

1. Die Herausforderung
In Katastrophenszenarien erfordert die Koordination von Überlebenden mit unterschiedlichen Fähigkeiten, Ressourcen und Bedürfnissen an mehreren Standorten intelligentes Datenmanagement und Suchfunktionen. In diesem Workshop lernen Sie, wie Sie ein KI-System für die Produktion erstellen, das Folgendes kombiniert:
- 🗄️ Graphdatenbank (Spanner): Speichern komplexer Beziehungen zwischen Überlebenden, Fähigkeiten und Ressourcen
- 🔍 KI-basierte Suche: Hybride Suche mit Semantik und Keywords unter Verwendung von Einbettungen
- 📸 Multimodale Verarbeitung: Strukturierte Daten aus Bildern, Text und Videos extrahieren
- 🤖 Orchestrierung mehrerer KI-Agenten: Koordinieren Sie spezialisierte KI-Agenten für komplexe Workflows.
- 🧠 Langzeitgedächtnis: Personalisierung mit Vertex AI Memory Bank

2. Umfang
Eine Survivor Network Graph Database mit:
- 🗺️ Interaktive 3D-Grafikvisualisierung der Beziehungen zwischen den Überlebenden
- 🔍 Intelligente Suche (Keyword-, semantische und hybride Suche)
- 📸 Multimodale Upload-Pipeline (Entitäten aus Bildern/Videos extrahieren)
- 🤖 Multi-Agenten-System für die Orchestrierung komplexer Aufgaben
- 🧠 Memory Bank-Integration für personalisierte Interaktionen
3. Kerntechnologien
Komponente | Technologie | Zweck |
Datenbank | Cloud Spanner-Graph | Knoten (Überlebende, Fähigkeiten) und Kanten (Beziehungen) speichern |
KI-Suche | Gemini und Einbettungen | Semantisches Verständnis + Ähnlichkeitssuche |
Agent Framework | ADK (Agent Development Kit) | KI-Workflows orchestrieren |
Arbeitsspeicher | Vertex AI Memory Bank | Langfristige Speicherung von Nutzereinstellungen |
Frontend | React + Three.js | Interaktive 3D-Diagrammvisualisierung |
2. 🛠️ Umgebung vorbereiten (überspringen, wenn Sie an einem Workshop teilnehmen)
Teil 1: Rechnungskonto aktivieren
Für dieses Codelab benötigen Sie ein Rechnungskonto mit Guthaben. Verwenden Sie das Guthaben aus dem Banner oben in diesem Codelab, um loszulegen. Wenn Sie bereits mit einem Rechnungskonto verbunden sind, können Sie diesen Schritt überspringen.
Teil 2: Umgebung öffnen
- 👉 Klicken Sie auf diesen Link, um direkt zum Cloud Shell-Editor zu gelangen.
- 👉 Wenn Sie heute zu irgendeinem Zeitpunkt zur Autorisierung aufgefordert werden, klicken Sie auf Autorisieren, um fortzufahren.

- 👉 Wenn das Terminal nicht unten auf dem Bildschirm angezeigt wird, öffnen Sie es:
- Klicken Sie auf Ansehen.
- Klicken Sie auf Terminal.

- 👉💻 Prüfen Sie im Terminal mit dem folgenden Befehl, ob Sie bereits authentifiziert sind und ob das Projekt auf Ihre Projekt-ID festgelegt ist:
gcloud auth list - 👉💻 Klonen Sie das Bootstrap-Projekt von GitHub:
git clone https://github.com/gca-americas/way-back-home.git
Teil 3: Neues Projekt erstellen
👉💻 Machen Sie im Terminal das Initialisierungsskript ausführbar und führen Sie es aus:
cd ~/way-back-home/level_2
./init.sh
3. 🛠️ Umgebung einrichten
1. Cloud Shell öffnen
Wenn das Terminal im Cloud Shell-Editor nicht unten auf dem Bildschirm angezeigt wird, öffnen Sie es:
- Klicken Sie auf Ansehen.
- Klicken Sie auf Terminal.

2. Projekt konfigurieren
👉💻 Legen Sie im Terminal Ihre Projekt-ID fest:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 Erforderliche APIs aktivieren (dauert etwa 2–3 Minuten):
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. Setupscript ausführen
👉💻 Führen Sie das Setupscript aus:
cd ~/way-back-home/level_2
./setup.sh
Dadurch wird .env für Sie erstellt. Öffnen Sie in Cloud Shell das Projekt way_back_home. Im Ordner level_2 wurde die Datei .env für Sie erstellt. Wenn Sie sie nicht finden, können Sie auf View -> Toggle Hidden File klicken, um sie aufzurufen. 
4. Beispieldaten laden
👉💻 Wechseln Sie zum Backend und installieren Sie die Abhängigkeiten:
cd ~/way-back-home/level_2/backend
uv sync
👉💻 Erste Überlebendendaten laden:
uv run python ~/way-back-home/level_2/backend/setup_data.py
Dadurch wird Folgendes erstellt:
- Spanner-Instanz (
survivor-network) - Datenbank (
graph-db) - Alle Knoten- und Kantentabellen
- Attributgrafiken für Abfragen Erwartete Ausgabe:
============================================================
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
Wenn Sie in der Ausgabe auf den Link nach Access your database at klicken, können Sie die Google Cloud Console für Spanner öffnen.

Spanner wird in der Google Cloud Console angezeigt.

4. 🚀 Grafikdaten in Spanner Studio visualisieren
In diesem Leitfaden erfahren Sie, wie Sie die Survivor Network-Diagrammdaten mithilfe von Spanner Studio direkt in der Google Cloud Console visualisieren und mit ihnen interagieren können. So können Sie Ihre Daten überprüfen und die Graphstruktur nachvollziehen, bevor Sie Ihren KI-Agenten erstellen.
1. Auf Spanner Studio zugreifen
- Klicken Sie im letzten Schritt auf den Link, um Spanner Studio zu öffnen.

2. Die Graphstruktur verstehen (das „Gesamtbild“)
Stellen Sie sich das Survivor Network-Dataset als Logikrätsel oder Spielstatus vor:
Entität | Rolle im System | Analogie |
Survivors | Die Agenten/Spieler | Spieler |
Biome | Wo sie sich befinden | Kartenzonen |
Skills | Was sie tun können | Funktionen |
Anforderungen | Was ihnen fehlt (Krisen) | Quests/Missionen |
Ressourcen | In der Welt gefundene Gegenstände | Loot |
Das Ziel: Der KI-Agent muss Fähigkeiten (Lösungen) mit Anforderungen (Problemen) verbinden und dabei Biome (Standorteinschränkungen) berücksichtigen.
🔗 Kanten (Beziehungen):
SurvivorInBiome: StandortbestimmungSurvivorHasSkill: Inventar der FähigkeitenSurvivorHasNeed: Liste der aktiven ProblemeSurvivorFoundResource: Inventar der ArtikelSurvivorCanHelp: Abgeleitete Beziehung (wird von der KI berechnet)
3. Grafik abfragen
Führen wir ein paar Abfragen aus, um die „Story“ in den Daten zu sehen.
Spanner Graph verwendet GQL (Graph Query Language). Wenn Sie eine Abfrage ausführen möchten, verwenden Sie GRAPH SurvivorNetwork gefolgt von Ihrem Übereinstimmungsmuster.
👉 Abfrage 1: Die globale Teilnehmerliste (Wer ist wo?) Das ist die Grundlage – die Kenntnis des Standorts ist für Rettungseinsätze entscheidend.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[:SurvivorInBiome]->(b:Biomes)
RETURN TO_JSON(result) AS json_result
Das Ergebnis sollte so aussehen: 
👉 Abfrage 2: Die Skill-Matrix (Fähigkeiten): Nachdem Sie nun wissen, wo sich alle befinden, finden Sie heraus, was sie können.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasSkill]->(k:Skills)
RETURN TO_JSON(result) AS json_result
Das Ergebnis sollte so aussehen: 
👉 Abfrage 3: Wer ist in einer Krise? („Mission Board“) – Hier siehst du, welche Überlebenden Hilfe benötigen und was sie brauchen.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasNeed]->(n:Needs)
RETURN TO_JSON(result) AS json_result
Das Ergebnis sollte so aussehen: 
🔎 [Optional] Matchmaking – Wer kann wem helfen?
Hier wird das Diagramm so richtig nützlich. Mit dieser Abfrage werden Überlebende gefunden, die über Fähigkeiten verfügen, mit denen sie die Bedürfnisse anderer Überlebender erfüllen können.
GRAPH SurvivorNetwork
MATCH result = (helper:Survivors)-[:SurvivorHasSkill]->(skill:Skills)-[:SkillTreatsNeed]->(need:Needs)<-[:SurvivorHasNeed]-(helpee:Survivors)
RETURN TO_JSON(result) AS json_result
Das Ergebnis sollte so aussehen: 
aside positive Was diese Abfrage bewirkt:
Anstatt nur „Erste Hilfe behandelt Verbrennungen“ anzuzeigen (was aus dem Schema ersichtlich ist), findet diese Abfrage Folgendes:
- Dr. Elena Frost (mit medizinischer Ausbildung) → kann behandeln → Captain Tanaka (mit Verbrennungen)
- David Chen (der Erste Hilfe leisten kann) → kann → Lt. Park (der einen verstauchten Knöchel hat) behandeln
Warum das so wichtig ist:
Was Ihr KI-Agent tun wird:
Wenn ein Nutzer fragt: „Wer kann Verbrennungen behandeln?“, führt der KI-Agent Folgendes aus:
- Ähnliche Diagrammabfrage ausführen
- Rückgabe: „Dr. Frost hat eine medizinische Ausbildung und kann Captain Tanaka helfen.“
- Der Nutzer muss nichts über Zwischentabellen oder Beziehungen wissen.
5. 🚀 KI-gestützte Einbettungen in Spanner
1. Warum Einbettungen? (Keine Aktion, nur Lesezugriff)
In einem Überlebensszenario ist Zeit ein entscheidender Faktor. Wenn ein Überlebender einen Notfall wie I need someone who can treat burns oder Looking for a medic meldet, kann er keine Zeit damit verschwenden, die genauen Namen der Fähigkeiten in der Datenbank zu erraten.
Reales Szenario: Überlebender: Captain Tanaka has burns—we need medical help NOW!
Traditionelle Stichwortsuche nach „medic“ → 0 Ergebnisse ❌
Semantische Suche mit Einbettungen → Findet „Medizinisches Training“, „Erste Hilfe“ ✅
Genau das brauchen KI-Agenten: eine intelligente, menschenähnliche Suche, die nicht nur Keywords, sondern auch die Absicht versteht.
2. Einbettungsmodell erstellen

Jetzt erstellen wir ein Modell, das Text mithilfe von text-embedding-004 von Google in Einbettungen umwandelt.
👉 Führen Sie in Spanner Studio die folgende SQL-Abfrage aus (ersetzen Sie $YOUR_PROJECT_ID durch Ihre tatsächliche Projekt-ID):
‼️ Öffnen Sie im Cloud Shell-Editor File -> Open Folder -> way-back-home/level_2, um das gesamte Projekt zu sehen.

👉 Führen Sie diese Abfrage in Spanner Studio aus, indem Sie die folgende Abfrage kopieren und einfügen und dann auf „Ausführen“ klicken:
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'
);
Damit wird Folgendes bewirkt:
- Erstellt ein virtuelles Modell in Spanner (keine lokal gespeicherten Modellgewichtungen)
- Verweist auf das
text-embedding-004von Google in Vertex AI - Definiert den Vertrag: Die Eingabe ist Text, die Ausgabe ein Float-Array mit 768 Dimensionen.
Warum „REMOTE-OPTIONEN“?
- Spanner führt das Modell nicht selbst aus.
- Vertex AI wird über die API aufgerufen, wenn Sie
ML.PREDICTverwenden. - Zero-ETL: Daten müssen nicht nach Python exportiert, verarbeitet und wieder importiert werden.
Klicken Sie auf den Button Run. Wenn der Vorgang erfolgreich war, wird das folgende Ergebnis angezeigt:

3. Einbettungsspalte hinzufügen
👉 Fügen Sie eine Spalte zum Speichern von Einbettungen hinzu:
ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;
Klicken Sie auf den Button Run. Wenn der Vorgang erfolgreich war, wird das folgende Ergebnis angezeigt:

4. Einbettungen generieren
👉 Verwenden Sie KI, um Vektoreinbettungen für jede Fähigkeit zu erstellen:
UPDATE Skills
SET skill_embedding = (
SELECT embeddings.values
FROM ML.PREDICT(
MODEL TextEmbeddings,
(SELECT name AS content)
)
)
WHERE skill_embedding IS NULL;
Klicken Sie auf den Button Run. Wenn der Vorgang erfolgreich war, wird das folgende Ergebnis angezeigt:

Ablauf: Jeder Skillname (z.B. „Erste Hilfe“) wird in einen 768-dimensionalen Vektor umgewandelt, der seine semantische Bedeutung darstellt.
5. Einbettungen prüfen
👉 Prüfen Sie, ob Einbettungen erstellt wurden:
SELECT
skill_id,
name,
ARRAY_LENGTH(skill_embedding) AS embedding_dimensions
FROM Skills
LIMIT 5;
Erwartete Ausgabe:

6. Semantische Suche testen
Jetzt testen wir den genauen Anwendungsfall aus unserem Szenario: die Suche nach medizinischen Fähigkeiten mit dem Begriff „medic“.
👉 Fähigkeiten finden, die „medic“ ähneln:
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;
- Konvertiert den Suchbegriff „medic“ des Nutzers in eine Einbettung
- Speichert sie in der temporären Tabelle
query_embedding.
Erwartete Ergebnisse (geringere Distanz = größere Ähnlichkeit):

7. Gemini-Modell für die Analyse erstellen

👉 Erstellen Sie eine Referenz für ein generatives KI-Modell (ersetzen Sie $YOUR_PROJECT_ID durch Ihre tatsächliche Projekt-ID):
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
);
Unterschied zum Einbettungsmodell:
- Einbettungen: Text → Vektor (für die Ähnlichkeitssuche)
- Gemini: Text → Generierter Text (für logisches Denken/Analyse)

8. Gemini für die Kompatibilitätsanalyse verwenden
👉 Analysiere Überlebendenpaare auf ihre Kompatibilität für die Mission:
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)
);
Erwartete Ausgabe:
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. 🚀 GraphRAG-Agenten mit Hybridsuche erstellen
1. Systemarchitektur – Übersicht
In diesem Abschnitt wird ein Suchsystem mit mehreren Methoden erstellt, mit dem Ihr Agent verschiedene Arten von Abfragen flexibel verarbeiten kann. Das System besteht aus drei Ebenen: Agentenebene, Toolebene und Dienstebene.

Warum drei Schichten?
- Trennung der Zuständigkeiten: Der Agent konzentriert sich auf die Absicht, die Tools auf die Schnittstelle und der Dienst auf die Implementierung.
- Flexibilität: Der KI-Agent kann bestimmte Methoden erzwingen oder die KI automatisch weiterleiten lassen.
- Optimierung: Teure KI-Analyse kann übersprungen werden, wenn die Methode bekannt ist.
In diesem Abschnitt implementieren Sie hauptsächlich die semantische Suche (RAG), bei der Ergebnisse nach ihrer Bedeutung und nicht nur nach Suchbegriffen gefunden werden. Später erklären wir, wie die hybride Suche mehrere Methoden kombiniert.
2. RAG-Dienstimplementierung
👉💻 Öffnen Sie die Datei im Terminal im Cloud Shell-Editor, indem Sie Folgendes ausführen:
cloudshell edit ~/way-back-home/level_2/backend/services/hybrid_search_service.py
Suchen Sie den Kommentar # TODO: REPLACE_SQL.
Ersetzen Sie diese gesamte Zeile durch den folgenden Code:
# 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. Definition des Tools für die semantische Suche
👉💻 Öffnen Sie die Datei im Terminal im Cloud Shell-Editor, indem Sie Folgendes ausführen:
cloudshell edit ~/way-back-home/level_2/backend/agent/tools/hybrid_search_tools.py
Suchen Sie in hybrid_search_tools.py nach dem Kommentar # TODO: REPLACE_SEMANTIC_SEARCH_TOOL.
👉 Ersetzen Sie diese gesamte Zeile durch den folgenden Code:
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)}"
Wenn der Agent Folgendes verwendet:
- Anfragen, die nach Ähnlichkeit fragen („Finde etwas Ähnliches wie X“)
- Konzeptionelle Suchanfragen („Heilfähigkeiten“)
- Wenn es wichtig ist, die Bedeutung zu verstehen
4. Leitfaden für Entscheidungen des KI-Agenten (Anweisungen)
Kopieren Sie in der Agentendefinition den Teil, der sich auf die semantische Suche bezieht, und fügen Sie ihn in die Anweisung ein.
👉💻 Öffnen Sie die Datei im Terminal im Cloud Shell-Editor, indem Sie Folgendes ausführen:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
Der Agent verwendet diese Anweisung, um das richtige Tool auszuwählen:
👉 Suchen Sie in der Datei agent.py nach dem Kommentar # TODO: REPLACE_SEARCH_LOGIC und ersetzen Sie die gesamte Zeile durch den folgenden Code:
- `semantic_search`: Force RAG/embedding search
Use for: "Find similar to X", conceptual queries, unknown terminology
Example: "Find skills related to healing"
👉 Suchen Sie den Kommentar # TODO: ADD_SEARCH_TOOLReplace this whole line und ersetzen Sie ihn durch den folgenden Code:
semantic_search, # Force RAG
5. Funktionsweise der hybriden Suche (Lesezugriff, keine Aktion erforderlich)
In den Schritten 2 bis 4 haben Sie die semantische Suche (RAG) implementiert, die wichtigste Suchmethode, bei der Ergebnisse nach Bedeutung gefunden werden. Vielleicht ist Ihnen aufgefallen, dass das System „Hybrid Search“ heißt. So funktioniert das Ganze:
So funktioniert die Hybridzusammenführung:
Wenn in der Datei way-back-home/level_2/backend/services/hybrid_search_service.py die Funktion hybrid_search() aufgerufen wird, führt der Dienst BEIDE Suchen aus und führt die zusammengeführten Ergebnisse zusammen:
# 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
In diesem Codelab haben Sie die Komponente Semantische Suche (RAG) implementiert, die die Grundlage bildet. Die Keyword- und die Hybridmethode sind bereits im Dienst implementiert – Ihr Agent kann alle drei verwenden.
Glückwunsch! Sie haben Ihren Graph RAG-Agenten mit Hybridsuche erfolgreich fertiggestellt.
7. 🚀 KI-Agenten mit ADK Web testen
Am einfachsten lässt sich Ihr KI-Agent mit dem Befehl adk web testen. Dadurch wird Ihr KI-Agent mit einer integrierten Chat-Oberfläche gestartet.
1. Agent ausführen
👉💻 Wechseln Sie zum Backend-Verzeichnis (in dem Ihr Agent definiert ist) und starten Sie die Weboberfläche:
cd ~/way-back-home/level_2/backend
uv run adk web
Mit diesem Befehl wird der in definierte Agent gestartet.
agent/agent.py
und öffnet eine Weboberfläche zum Testen.
👉 Öffnen Sie die URL:
Der Befehl gibt eine lokale URL aus (normalerweise http://127.0.0.1:8000 oder ähnlich). Öffnen Sie diesen Link in Ihrem Browser.

Wenn Sie auf die URL klicken, wird die ADK-Weboberfläche angezeigt. Achten Sie darauf, dass Sie oben links den „Agent“ auswählen.

2. Suchfunktionen testen
Der KI-Agent ist so konzipiert, dass er Ihre Anfragen intelligent weiterleitet. Probieren Sie die folgenden Eingaben im Chatfenster aus, um verschiedene Suchmethoden in Aktion zu sehen.
🧬 A. GraphRAG (semantische Suche)
Findet Elemente anhand von Bedeutung und Konzept, auch wenn die Suchbegriffe nicht übereinstimmen.
Testanfragen: (Wähle eine der folgenden Optionen aus)
Who can help with injuries?
What abilities are related to survival?
Darauf sollten Sie achten:
- In der Begründung sollte die semantische Suche oder die RAG-Suche erwähnt werden.
- Sie sollten Ergebnisse sehen, die konzeptionell verwandt sind (z.B. „Chirurgie“, wenn Sie nach „Erste Hilfe“ fragen).
- Die Ergebnisse sind mit dem Symbol 🧬 gekennzeichnet.
🔀 B. Hybridsuche
Kombiniert Keyword-Filter mit semantischem Verständnis für komplexe Abfragen.
Testanfragen: (Wählen Sie eine der folgenden Optionen aus)
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?
Darauf sollten Sie achten:
- In der Begründung sollte die hybride Suche erwähnt werden.
- Die Ergebnisse sollten BEIDEN Kriterien entsprechen (Konzept + Ort/Kategorie).
- Ergebnisse, die mit beiden Methoden gefunden wurden, sind mit dem Symbol 🔀 gekennzeichnet und werden am höchsten eingestuft.
👉💻 Wenn Sie mit dem Testen fertig sind, beenden Sie den Vorgang, indem Sie in der Befehlszeile Ctrl+C drücken.
8. 🚀 Vollständige Anwendung ausführen
Full-Stack-Architektur – Übersicht

SessionService und Runner hinzufügen
👉💻 Öffnen Sie im Terminal die Datei chat.py im Cloud Shell-Editor, indem Sie den folgenden Befehl ausführen. Beenden Sie vorher den vorherigen Prozess mit „Strg + C“.
cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py
👉 Suchen Sie in der Datei chat.py nach dem Kommentar # TODO: REPLACE_INMEMORY_SERVICES und ersetzen Sie die gesamte Zeile durch den folgenden Code:
session_service = InMemorySessionService()
memory_service = InMemoryMemoryService()
👉 Suchen Sie in der Datei chat.py nach dem Kommentar # TODO: REPLACE_RUNNER und ersetzen Sie die gesamte Zeile durch den folgenden Code:
runner = Runner(
agent=root_agent,
session_service=session_service,
memory_service=memory_service,
app_name="survivor-network"
)
1. Antrag stellen
Wenn das vorherige Terminal noch ausgeführt wird, beenden Sie es, indem Sie Ctrl+C drücken.
👉💻 App starten:
cd ~/way-back-home/level_2/
./start_app.sh
Wenn das Backend erfolgreich gestartet wurde, wird Local: http://localhost:5173/" angezeigt: 
👉 Klicken Sie im Terminal auf Local: http://localhost:5173/.

2. Semantische Suche testen
Abfrage:
Find skills similar to healing

Was passiert?:
- Der Agent erkennt die Ähnlichkeitsanfrage.
- Generiert eine Einbettung für „healing“
- Verwendet die Kosinus-Distanz, um semantisch ähnliche Fähigkeiten zu finden.
- Gibt zurück: Erste Hilfe (obwohl die Namen nicht mit „Heilung“ übereinstimmen)
3. Hybridsuche testen
Abfrage:
Find medical skills in the mountains
Was passiert?:
- Keyword-Komponente: Nach
category='medical'filtern - Semantische Komponente: „medizinisch“ einbetten und nach Ähnlichkeit sortieren
- Zusammenführen: Ergebnisse kombinieren, wobei die von beiden Methoden gefundenen Ergebnisse priorisiert werden 🔀
Abfrage (optional):
Who is good at survival and in the forest?
Was passiert?:
- Keyword-Funde:
biome='forest' - Semantische Ergebnisse: Skills, die „Überleben“ ähneln
- Hybrid kombiniert beide für optimale Ergebnisse
👉💻 Wenn Sie mit dem Testen fertig sind, beenden Sie den Vorgang im Terminal, indem Sie Ctrl+C drücken.
4. (!ONLY FOR WORKSHOP ATTENDEE) Update your location
👉💻 Führen Sie das Skript zum Abschließen aus:
cd ~/way-back-home/level_2
./set_level_2.sh
Öffne jetzt waybackhome.dev. Du wirst sehen, dass dein Standort aktualisiert wurde. Herzlichen Glückwunsch zum Abschluss von Level 2!

9. ☕️ [Optional] Multimodale Pipeline (Lesezugriff) – Tooling-Ebene
Warum brauchen wir eine multimodale Pipeline?
Das Survival-Netzwerk besteht nicht nur aus Text. Überlebende vor Ort senden unstrukturierte Daten direkt über den Chat:
- 📸 Bilder: Fotos von Ressourcen, Gefahren oder Ausrüstung
- 🎥 Videos: Statusberichte oder SOS-Meldungen
- 📄 Text: Feldnotizen oder Protokolle
Welche Dateien werden verarbeitet?
Im Gegensatz zum vorherigen Schritt, bei dem wir vorhandene Daten durchsucht haben, verarbeiten wir hier von Nutzern hochgeladene Dateien. Die chat.py-Schnittstelle verarbeitet Dateianhänge dynamisch:
Quelle | Inhalt | Ziel |
Nutzerbindung | Bild/Video/Text | Informationen, die dem Diagramm hinzugefügt werden sollen |
Chatkontext | „Hier ist ein Foto der Vorräte“ | Absicht und zusätzliche Details |
Der geplante Ansatz: Sequenzielle Agenten-Pipeline
Wir verwenden einen sequenziellen Agenten (multimedia_agent.py), der spezialisierte Agenten miteinander verknüpft:

Dies wird in backend/agent/multimedia_agent.py als SequentialAgent definiert.
Die Tool-Ebene stellt die Funktionen bereit, die Agenten aufrufen können. Tools kümmern sich um das „Wie“ – Dateien hochladen, Entitäten extrahieren und in der Datenbank speichern.
1. Datei „Tools“ öffnen
👉💻 Öffnen Sie die Datei level_2/backend/agent/tools/extraction_tools.py oder geben Sie den folgenden Befehl im Terminal ein. Öffnen Sie ein neues Terminal. Öffnen Sie die Datei im Terminal im Cloud Shell-Editor:
cloudshell edit ~/way-back-home/level_2/backend/agent/tools/extraction_tools.py
2. Tool „upload_media“ implementieren
Mit diesem Tool wird eine lokale Datei in Google Cloud Storage hochgeladen.
👉 In def upload_media(file_path: str, survivor_id: Optional[str] = None) -> Dict[str, Any]: wird im folgenden Code gezeigt, wie Dateien in GCS hochgeladen und ihr Typ erkannt wird:
"""
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. Tool „extract_from_media“ implementieren
Dieses Tool ist ein Router. Es prüft die media_type und leitet sie an den richtigen Extractor (Text, Bild oder Video) weiter.
👉 In async def extract_from_media(gcs_uri: str, media_type: str, signed_url: Optional[str] = None) -> Dict[str, Any]: wird im folgenden Code gezeigt, wie Entitäten und Beziehungen aus hochgeladenen Medien extrahiert werden.
"""
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)}
Wichtige Implementierungsdetails:
- Multimodale Eingabe: Wir übergeben sowohl den Text-Prompt (
_get_extraction_prompt()) als auch das Bildobjekt angenerate_content. - Strukturierte Ausgabe:
response_mime_type="application/json"sorgt dafür, dass das LLM gültiges JSON zurückgibt, was für die Pipeline entscheidend ist. - Visual Entity Linking: Der Prompt enthält bekannte Entitäten, damit Gemini bestimmte Zeichen erkennen kann.
4. Tool „save_to_spanner“ implementieren
Dieses Tool speichert die extrahierten Entitäten und Beziehungen in der Spanner Graph-Datenbank.
👉 In def save_to_spanner(extraction_result: Any, survivor_id: Optional[str] = None) -> Dict[str, Any]: wird im folgenden Code gezeigt, wie extrahierte Entitäten und Beziehungen in der Spanner Graph-Datenbank gespeichert werden.
"""
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)}
Durch die Bereitstellung von High-Level-Tools für KI-Agenten wird die Datenintegrität gewahrt, während gleichzeitig die Reasoning-Funktionen des KI-Agenten genutzt werden.
5. GCS-Dienst aktualisieren
Die GCSService übernimmt das eigentliche Hochladen der Datei in Google Cloud Storage.
👉💻 Öffnen Sie die Datei level_2/backend/services/gcs_service.py oder geben Sie im Terminal Folgendes ein, um die Datei im Cloud Shell-Editor zu öffnen:
cloudshell edit ~/way-back-home/level_2/backend/services/gcs_service.py
👉 In def upload_file(self, file_path: str, survivor_id: Optional[str] = None) -> Tuple[str, MediaType, str]: wird im folgenden Code gezeigt, wie extrahierte Entitäten und Beziehungen in der Spanner Graph-Datenbank gespeichert werden.
blob = self.bucket.blob(blob_name)
blob.upload_from_filename(file_path)
Durch die Abstraktion in einen Dienst muss der Agent nichts über GCS-Buckets, Blob-Namen oder die Generierung signierter URLs wissen. Es wird nur nach „Hochladen“ gefragt.
6. Warum sind Agentic Workflows besser als herkömmliche Ansätze?
Der Vorteil von Agenten:
Funktion | Batchpipeline | Ereignisgesteuert | Agentic Workflow |
Komplexität | Niedrig (1 Skript) | Hoch (mindestens 5 Dienste) | Niedrig (1 Python-Datei: |
Zustandsverwaltung | Globale Variablen | Hart (entkoppelt) | Einheitlich (Agentenstatus) |
Fehlerbehandlung | Abstürze | Stille Logs | Interaktiv („Ich konnte diese Datei nicht lesen“) |
Nutzerfeedback | Konsolenausgaben | Abfrage erforderlich | Sofort (Teil des Chats) |
Anpassungsfähigkeit | Feste Logik | Starre Funktionen | Intelligent (LLM entscheidet über den nächsten Schritt) |
Kontextsensitivität | Keine | Keine | Vollständig (Nutzerabsicht bekannt) |
Warum ist das wichtig? Durch die Verwendung von multimedia_agent.py (ein SequentialAgent mit 4 Unter-Agenten: Upload → Extract → Save → Summary) ersetzen wir komplexe Infrastruktur UND fehleranfällige Skripts durch intelligente, konversationelle Anwendungslogik.
10. ☕️ [Optional] Multimodale Pipeline (Lesezugriff) – Agent-Ebene
Die Agentenebene definiert die Intelligenz – Agenten, die Tools verwenden, um Aufgaben zu erledigen. Jeder Agent hat eine bestimmte Rolle und gibt den Kontext an den nächsten weiter. Unten sehen Sie ein Architekturdiagramm für ein Multi-Agenten-System.

1. Agentendatei öffnen
👉💻 Öffnen Sie die Datei level_2/backend/agent/multimedia_agent.py oder geben Sie den folgenden Befehl im Terminal ein. Öffnen Sie ein neues Terminal. Öffnen Sie die Datei im Terminal im Cloud Shell-Editor:
cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py
2. Upload-Agent definieren
Dieser Agent extrahiert einen Dateipfad aus der Nachricht des Nutzers und lädt die Datei in GCS hoch.
👉 In der Datei multimedia_agent.py wird mit dem folgenden Code upload_agent erstellt, das in GCS hochgeladen wird:
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. Extraktions-Agent definieren
Dieser Agent „sieht“ die hochgeladenen Medien und extrahiert mit Gemini Vision strukturierte Daten.
👉 In der Datei multimedia_agent.py wird mit dem folgenden Code extraction_agent erstellt, um Informationen aus den hochgeladenen Medien zu extrahieren:
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"
)
Beachten Sie, dass instruction auf {upload_result} verweist. So wird der Zustand zwischen Agenten im ADK übergeben.
4. Cloud Spanner-Agent definieren
Dieser KI-Agent speichert die extrahierten Entitäten und Beziehungen in der Graphdatenbank.
👉 In der Datei multimedia_agent.py wird mit dem folgenden Code spanner_agent erstellt, um die extrahierten Informationen in der Datenbank zu speichern:
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"
)
Dieser KI-Agent erhält Kontext aus beiden vorherigen Schritten (upload_result und extraction_result).
5. Zusammenfassungs-Agent definieren
Dieser Agent fasst die Ergebnisse aus allen vorherigen Schritten in einer nutzerfreundlichen Antwort zusammen.
👉 In der Datei multimedia_agent.py wird mit dem folgenden Code der Prompt für summary_agent definiert, der das Ergebnis zusammenfasst:
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."""
Dieser Agent benötigt keine Tools – er liest einfach den freigegebenen Kontext und generiert eine übersichtliche Zusammenfassung für den Nutzer.
🧠 Zusammenfassung der Architektur
Ebene | Datei | Zuständigkeit |
Tools |
| Wie – Hochladen, extrahieren, speichern |
Agentenmodus |
| Was: Pipeline orchestrieren |
11. 🚀 Multimodale Datenpipeline – Orchestrierung
Das Herzstück unseres neuen Systems ist die MultimediaExtractionPipeline, die in backend/agent/multimedia_agent.py definiert ist. Es verwendet das Muster Sequenzieller Agent aus dem ADK (Agent Development Kit).
1. Warum sequenziell?
Die Verarbeitung eines Uploads ist eine lineare Abhängigkeitskette:
- Sie können erst dann Daten extrahieren, wenn Sie die Datei haben (Upload).
- Sie können Daten erst speichern, wenn Sie sie extrahiert haben (Extraktion).
- Sie können erst dann eine Zusammenfassung erstellen, wenn Sie die Ergebnisse haben (Speichern).
Ein SequentialAgent ist dafür perfekt geeignet. Die Ausgabe eines Agenten wird als Kontext/Eingabe an den nächsten Agenten übergeben.
2. Die Agentendefinition
Sehen wir uns an, wie die Pipeline am Ende von multimedia_agent.py zusammengesetzt wird: 👉💻 Öffnen Sie die Datei im Terminal im Cloud Shell-Editor, indem Sie Folgendes ausführen:
cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py
Sie empfängt Eingaben aus beiden vorherigen Schritten. Suchen Sie den Kommentar # TODO: REPLACE_ORCHESTRATION. Ersetzen Sie diese gesamte Zeile durch den folgenden Code:
sub_agents=[upload_agent, extraction_agent, spanner_agent, summary_agent]
3. Mit Root-Agent verbinden
👉💻 Öffnen Sie die Datei im Terminal im Cloud Shell-Editor, indem Sie Folgendes ausführen:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
Suchen Sie den Kommentar # TODO: REPLACE_ADD_SUBAGENT. Ersetzen Sie diese gesamte Zeile durch den folgenden Code:
sub_agents=[multimedia_agent],
Dieses einzelne Objekt bündelt effektiv vier „Experten“ in einer aufrufbaren Entität.
4. Datenfluss zwischen KI-Agenten
Jeder Agent speichert seine Ausgabe in einem freigegebenen Kontext, auf den nachfolgende Agenten zugreifen können:

5. Anwendung öffnen (überspringen, wenn die App noch ausgeführt wird)
👉💻 App starten:
cd ~/way-back-home/level_2/
./start_app.sh
👉 Klicken Sie im Terminal auf Local: http://localhost:5173/.
6. Testbild hochladen
👉 Wählen Sie in der Chatoberfläche eines der Fotos aus und laden Sie es in die Benutzeroberfläche hoch:
Geben Sie in der Chatoberfläche den Kontext an:
Here is the survivor note
Hängen Sie das Bild hier an.


👉💻 Wenn Sie mit dem Testen fertig sind, drücken Sie im Terminal „Strg + C“, um den Prozess zu beenden.
6. Multimodales Hochladen in GCS-Bucket prüfen
- Öffnen Sie den Storage-Browser der Google Cloud Console.
- „Bucket“ in Cloud Storage auswählen

- Wählen Sie Ihren Bucket aus und klicken Sie auf
media.

- Hier kannst du dir dein hochgeladenes Bild ansehen.

7. Multimodalen Upload in Spanner prüfen (optional)
Unten sehen Sie eine Beispielausgabe in der Benutzeroberfläche für test_photo1.
- Öffnen Sie Spanner in der Google Cloud Console.
- Wählen Sie Ihre Instanz aus:
Survivor Network - Wählen Sie Ihre Datenbank aus:
graph-db - Klicken Sie in der linken Seitenleiste auf Spanner Studio.
👉 Fragen Sie in Spanner Studio die neuen Daten ab:
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;
Wir können das anhand des folgenden Ergebnisses überprüfen:

12. ☕️ [Optional] Memory Bank mit Agent Engine
1. So funktioniert die Funktion „Memory“
Das System verwendet einen Dual-Memory-Ansatz, um sowohl den unmittelbaren Kontext als auch das langfristige Lernen zu verarbeiten.

2. Was sind Themen der gemerkten Informationen?
Memory-Themen definieren die Kategorien von Informationen, die sich der Agent über Unterhaltungen hinweg merken soll. Sie können sich diese als Aktenschränke für verschiedene Arten von Nutzereinstellungen vorstellen.
Unsere beiden Themen:
search_preferences: Wie der Nutzer am liebsten sucht- Bevorzugen sie die Stichwortsuche oder die semantische Suche?
- Nach welchen Fähigkeiten/Biomen suchen sie oft?
- Beispiel für gemerkte Informationen: „Nutzer bevorzugt semantische Suche nach medizinischen Fähigkeiten“
urgent_needs_context: Welche Krisen werden verfolgt?- Welche Ressourcen werden überwacht?
- Um welche Überlebenden machen sie sich Sorgen?
- Beispiel für gemerkte Informationen: „Nutzer verfolgt Medikamentenmangel im Northern Camp“
3. Themen für gemerkte Informationen einrichten
Benutzerdefinierte Themen für gemerkte Informationen definieren, was sich der Agent merken soll. Diese werden bei der Bereitstellung der Agent Engine konfiguriert.
👉💻 Öffnen Sie die Datei im Terminal im Cloud Shell-Editor, indem Sie Folgendes ausführen:
cloudshell edit ~/way-back-home/level_2/backend/deploy_agent.py
Dadurch wird ~/way-back-home/level_2/backend/deploy_agent.py im Editor geöffnet.
Wir definieren MemoryTopic-Strukturobjekte, um dem LLM mitzuteilen, welche Informationen extrahiert und gespeichert werden sollen.
👉 Ersetzen Sie in der Datei deploy_agent.py die # TODO: SET_UP_TOPIC durch Folgendes:
# 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. Integration von KI-Agenten
Der Agentencode muss die Memory Bank kennen, um Informationen speichern und abrufen zu können.
👉💻 Öffnen Sie die Datei im Terminal im Cloud Shell-Editor, indem Sie Folgendes ausführen:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
Dadurch wird ~/way-back-home/level_2/backend/agent/agent.py im Editor geöffnet.
KI-Agenten erstellen
Beim Erstellen des KI-Agenten übergeben wir die after_agent_callback, damit Sitzungen nach Interaktionen im Speicher abgelegt werden. Die Funktion add_session_to_memory wird asynchron ausgeführt, um die Chatantwort nicht zu verlangsamen.
👉 Suchen Sie in der Datei agent.py nach dem Kommentar # TODO: REPLACE_ADD_SESSION_MEMORY und ersetzen Sie die gesamte Zeile durch den folgenden Code:
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")
Speichern im Hintergrund
👉 Suchen Sie in der Datei agent.py nach dem Kommentar # TODO: REPLACE_ADD_MEMORY_BANK_TOOL und ersetzen Sie die gesamte Zeile durch den folgenden Code:
if USE_MEMORY_BANK:
agent_tools.append(PreloadMemoryTool())
👉 Suchen Sie in der Datei agent.py nach dem Kommentar # TODO: REPLACE_ADD_CALLBACK und ersetzen Sie die gesamte Zeile durch den folgenden Code:
after_agent_callback=add_session_to_memory if USE_MEMORY_BANK else None
Vertex AI-Sitzungsdienst einrichten
👉💻 Öffnen Sie im Terminal die Datei chat.py im Cloud Shell-Editor, indem Sie Folgendes ausführen:
cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py
👉 Suchen Sie in der Datei chat.py nach dem Kommentar # TODO: REPLACE_VERTEXAI_SERVICES und ersetzen Sie die gesamte Zeile durch den folgenden Code:
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. ☕️ [Optional] Agenten mit der Agent Engine verknüpfen
1. Einrichtung und Bereitstellung
Bevor Sie die Funktionen für gemerkte Informationen testen, müssen Sie den Agenten mit den neuen Themen für gemerkte Informationen bereitstellen und dafür sorgen, dass Ihre Umgebung richtig konfiguriert ist.
Wir haben ein praktisches Skript für diesen Prozess bereitgestellt.
Bereitstellungsscript ausführen
👉💻 Führen Sie im Terminal das Bereitstellungsscript aus:
cd ~/way-back-home/level_2
./deploy_and_update_env.sh
Dieses Script führt die folgenden Aktionen aus:
- Führt
backend/deploy_agent.pyaus, um den Agenten und die gemerkten Themen bei Vertex AI zu registrieren. - Erfasst die neue Agent Engine-ID.
- Aktualisiert die Datei
.envautomatisch mitAGENT_ENGINE_ID. - Prüft, ob
USE_MEMORY_BANK=TRUEin der Datei.envfestgelegt ist.
[!WICHTIG] Wenn Sie Änderungen an custom_topics in deploy_agent.py vornehmen, müssen Sie dieses Script noch einmal ausführen, um die Agent-Engine zu aktualisieren.
Memory Bank überprüfen
Jetzt können Sie prüfen, ob die Memory Bank funktioniert. Bringen Sie dem Agenten dazu eine Präferenz bei und prüfen Sie, ob sie über Sitzungen hinweg erhalten bleibt.
Schritt 1: Anwendung öffnen
Öffnen Sie die Anwendung noch einmal, indem Sie der folgenden Anleitung folgen: Wenn das vorherige Terminal noch ausgeführt wird, beenden Sie es, indem Sie Ctrls+C drücken.
👉💻 App starten:
cd ~/way-back-home/level_2/
./start_app.sh
👉 Klicken Sie im Terminal auf Local: http://localhost:5173/.
Schritt 2: Memory Bank mit Text testen
Geben Sie in der Chatoberfläche den Kontext an:
"I'm planning a medical rescue mission in the mountains. I need survivors with first aid and climbing skills."
👉 Warten Sie etwa 30 Sekunden, bis die gemerkten Informationen im Hintergrund verarbeitet wurden.
Schritt 3: Neue Sitzung starten
Aktualisieren Sie die Seite, um den aktuellen Unterhaltungsverlauf (Kurzzeitgedächtnis) zu löschen.
Stellen Sie eine Frage, die sich auf den zuvor bereitgestellten Kontext bezieht:
"What kind of missions am I interested in?"
Erwartete Antwort:
„Basierend auf Ihren vorherigen Unterhaltungen interessieren Sie sich für:
- Medizinische Rettungseinsätze
- Einsätze in den Bergen/in großer Höhe
- Erforderliche Fähigkeiten: Erste Hilfe, Klettern
Soll ich nach Überlebenden suchen, die diesen Kriterien entsprechen?"
Schritt 4: Mit Bildupload testen
Laden Sie ein Bild hoch und fragen Sie:
remember this
Sie können ein beliebiges Foto von hier oder ein eigenes Foto auswählen und in die Benutzeroberfläche hochladen:
Schritt 5: In Vertex AI Agent Engine prüfen
Rufen Sie die Agent Engine in der Google Cloud Console auf.
- Wählen Sie das Projekt oben links in der Projektauswahl aus:

- Prüfen Sie die Agent Engine, die Sie gerade mit dem vorherigen Befehl
use_memory_bank.shbereitgestellt haben:
Klicken Sie auf die Agent Engine, die Sie gerade erstellt haben. - Klicken Sie bei diesem bereitgestellten KI-Agenten auf den Tab
Memories. Hier können Sie alle gemerkten Informationen ansehen.
👉💻 Wenn Sie mit dem Testen fertig sind, drücken Sie im Terminal „Strg + C“, um den Prozess zu beenden.
🎉 Glückwunsch! Sie haben die Memory Bank gerade an Ihren KI-Agenten angehängt.
14. ☕️ [Optional] In Cloud Run bereitstellen
1. Bereitstellungsscript ausführen
👉💻 Führen Sie das Bereitstellungsscript aus:
cd ~/way-back-home/level_2
./deploy_cloud_run.sh
Nach der erfolgreichen Bereitstellung erhalten Sie die URL. Das ist die bereitgestellte URL für Sie: 
👉💻 Bevor Sie die URL abrufen, erteilen Sie die Berechtigung, indem Sie Folgendes ausführen:
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
Rufen Sie die bereitgestellte URL auf. Dort sehen Sie Ihre Anwendung live.
2. Informationen zur Build-Pipeline
In der Datei cloudbuild.yaml werden die folgenden sequenziellen Schritte definiert:
- Backend Build: Erstellt das Docker-Image aus
backend/Dockerfile. - Backend Deploy: Stellt den Backend-Container in Cloud Run bereit.
- Capture URL: Ruft die neue Backend-URL ab.
- Frontend-Build:
- Installiert Abhängigkeiten.
- Erstellt die React-Anwendung und fügt
VITE_API_URL=ein.
- Frontend Image: Erstellt das Docker-Image aus
frontend/Dockerfile(Paketierung der statischen Assets). - Frontend Deploy: Stellt den Frontend-Container bereit.
3. Deployment prüfen
Sobald der Build abgeschlossen ist (prüfen Sie den vom Script bereitgestellten Link zu den Logs), können Sie Folgendes prüfen:
- Rufen Sie die Cloud Run Console auf.
- Suchen Sie nach dem Dienst
survivor-frontend. - Klicken Sie auf die URL, um die Anwendung zu öffnen.
- Führen Sie eine Suchanfrage aus, um zu prüfen, ob das Frontend mit dem Backend kommunizieren kann.
(OPTIONAL) 4. Manuelle Bereitstellung
Wenn Sie die Befehle lieber manuell ausführen oder den Prozess besser verstehen möchten, finden Sie hier eine Anleitung zur direkten Verwendung von cloudbuild.yaml.
cloudbuild.yaml wird geschrieben
Eine cloudbuild.yaml-Datei teilt Google Cloud Build mit, welche Schritte ausgeführt werden sollen.
- steps: Eine Liste aufeinanderfolgender Aktionen. Jeder Schritt wird in einem Container ausgeführt (z.B.
docker,gcloud,node,bash). - substitutions: Variablen, die während des Builds übergeben werden können (z.B.
$_REGION). - workspace: Ein freigegebenes Verzeichnis, in dem Schritte Dateien freigeben können (z. B. wie wir
backend_url.txtfreigeben).
Bereitstellung ausführen
Wenn Sie die Bereitstellung manuell ohne das Script durchführen möchten, verwenden Sie den Befehl gcloud builds submit. Sie MÜSSEN die erforderlichen Ersatzvariablen übergeben.
# 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. Fazit
1. Was Sie erstellt haben
✅ Graphdatenbank: Spanner mit Knoten (Überlebende, Fähigkeiten) und Kanten (Beziehungen)
✅ KI-Suche: Keyword-, semantische und hybride Suche mit Einbettungen
✅ Multimodale Pipeline: Entitäten aus Bildern/Videos mit Gemini extrahieren
✅ Multi-Agenten-System: Koordinierter Workflow mit ADK
✅ Memory Bank: Langfristige Personalisierung mit Vertex AI
✅ Produktionsbereitstellung: Cloud Run + Agent Engine
2. Architekturzusammenfassung

3. Wichtige Erkenntnisse
- Graph RAG: Kombiniert die Struktur einer Graphdatenbank mit semantischen Einbettungen für eine intelligente Suche.
- Multi-Agenten-Muster: Sequenzielle Pipelines für komplexe, mehrstufige Workflows
- Multimodale KI: Strukturierte Daten aus unstrukturierten Medien (Bilder/Videos) extrahieren
- Zustandsorientierte KI-Agenten: Memory Bank ermöglicht die Personalisierung über Sitzungen hinweg.
4. Workshop-Inhalte
- Level0: Identifizieren Sie sich
- Level1: Standort bestimmen
- Level 2: Multimodalen KI-Agenten mit Graph RAG, ADK und Memory Bank erstellen
- Level3: Building an ADK Bi-Directional Streaming Agent
- Level4: Live Bidirectional Multi-Agent system
- Level5 Ereignisgesteuerte Architektur mit Google ADK, A2A und Kafka