🤖 Multimodalen KI‑Agenten mit Graph RAG, ADK und Memory Bank erstellen

1. Einführung

Coverversion

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:

  1. 🗄️ Graphdatenbank (Spanner): Speichern komplexer Beziehungen zwischen Überlebenden, Fähigkeiten und Ressourcen
  2. 🔍 KI-basierte Suche: Hybride Suche mit Semantik und Keywords unter Verwendung von Einbettungen
  3. 📸 Multimodale Verarbeitung: Strukturierte Daten aus Bildern, Text und Videos extrahieren
  4. 🤖 Orchestrierung mehrerer KI-Agenten: Koordinieren Sie spezialisierte KI-Agenten für komplexe Workflows.
  5. 🧠 Langzeitgedächtnis: Personalisierung mit Vertex AI Memory Bank

Konversation

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

  1. 👉 Klicken Sie auf diesen Link, um direkt zum Cloud Shell-Editor zu gelangen.
  2. 👉 Wenn Sie heute zu irgendeinem Zeitpunkt zur Autorisierung aufgefordert werden, klicken Sie auf Autorisieren, um fortzufahren. Klicken Sie, um Cloud Shell zu autorisieren.
  3. 👉 Wenn das Terminal nicht unten auf dem Bildschirm angezeigt wird, öffnen Sie es:
    • Klicken Sie auf Ansehen.
    • Klicken Sie auf Terminal.Neues Terminal im Cloud Shell-Editor öffnen
  4. 👉💻 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
    
  5. 👉💻 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.

Neues Terminal im Cloud Shell-Editor öffnen

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

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.

open_spanner

Spanner wird in der Google Cloud Console angezeigt.

spanner

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

  1. Klicken Sie im letzten Schritt auf den Link, um Spanner Studio zu öffnen.

spanner_studio

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: Standortbestimmung
  • SurvivorHasSkill: Inventar der Fähigkeiten
  • SurvivorHasNeed: Liste der aktiven Probleme
  • SurvivorFoundResource: Inventar der Artikel
  • SurvivorCanHelp: 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: query1

👉 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: query2

👉 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: query3

🔎 [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: query4

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:

  1. Ähnliche Diagrammabfrage ausführen
  2. Rückgabe: „Dr. Frost hat eine medizinische Ausbildung und kann Captain Tanaka helfen.“
  3. 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

spanner_embedding

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.

project_id

👉 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-004 von 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.PREDICT verwenden.
  • 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:

spanner_result

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:

embedding_result

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:

skills_result

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:

spanner_result

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):

spanner_result

7. Gemini-Modell für die Analyse erstellen

spanner_gemini

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

spanner_result

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.

architecture_hybrid_search

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.

adk web

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

adk_ui

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.

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.

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

architecture_fullstack

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: fronted

👉 Klicken Sie im Terminal auf Local: http://localhost:5173/.

Konversation

Abfrage:

Find skills similar to healing

Chat

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)

Abfrage:

Find medical skills in the mountains

Was passiert?:

  1. Keyword-Komponente: Nach category='medical' filtern
  2. Semantische Komponente: „medizinisch“ einbetten und nach Ähnlichkeit sortieren
  3. 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!

Endergebnis

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:

architecture_uploading

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 an generate_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: multimedia_agent.py)

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.

agent_diagram

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

extraction_tools.py + gcs_service.py

Wie – Hochladen, extrahieren, speichern

Agentenmodus

multimedia_agent.py

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:

  1. Sie können erst dann Daten extrahieren, wenn Sie die Datei haben (Upload).
  2. Sie können Daten erst speichern, wenn Sie sie extrahiert haben (Extraktion).
  3. 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:

architecture_uploading

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.

upload_input

upload_result

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

gcs

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

Medien

  • Hier kannst du dir dein hochgeladenes Bild ansehen. uploaded_img

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:

spanner_verify

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.

memory_bank

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:

  1. 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“
  2. 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.py aus, um den Agenten und die gemerkten Themen bei Vertex AI zu registrieren.
  • Erfasst die neue Agent Engine-ID.
  • Aktualisiert die Datei .env automatisch mit AGENT_ENGINE_ID.
  • Prüft, ob USE_MEMORY_BANK=TRUE in der Datei .env festgelegt 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.

  1. Wählen Sie das Projekt oben links in der Projektauswahl aus:Projektauswahl
  2. Prüfen Sie die Agent Engine, die Sie gerade mit dem vorherigen Befehl use_memory_bank.sh bereitgestellt haben:Agent EngineKlicken Sie auf die Agent Engine, die Sie gerade erstellt haben.
  3. Klicken Sie bei diesem bereitgestellten KI-Agenten auf den Tab Memories. Hier können Sie alle gemerkten Informationen ansehen.Erinnerung 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: bereitgestellt

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

  1. Backend Build: Erstellt das Docker-Image aus backend/Dockerfile.
  2. Backend Deploy: Stellt den Backend-Container in Cloud Run bereit.
  3. Capture URL: Ruft die neue Backend-URL ab.
  4. Frontend-Build:
    • Installiert Abhängigkeiten.
    • Erstellt die React-Anwendung und fügt VITE_API_URL= ein.
  5. Frontend Image: Erstellt das Docker-Image aus frontend/Dockerfile (Paketierung der statischen Assets).
  6. 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:

  1. Rufen Sie die Cloud Run Console auf.
  2. Suchen Sie nach dem Dienst survivor-frontend.
  3. Klicken Sie auf die URL, um die Anwendung zu öffnen.
  4. 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.txt freigeben).

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

architecture_fullstack

3. Wichtige Erkenntnisse

  1. Graph RAG: Kombiniert die Struktur einer Graphdatenbank mit semantischen Einbettungen für eine intelligente Suche.
  2. Multi-Agenten-Muster: Sequenzielle Pipelines für komplexe, mehrstufige Workflows
  3. Multimodale KI: Strukturierte Daten aus unstrukturierten Medien (Bilder/Videos) extrahieren
  4. Zustandsorientierte KI-Agenten: Memory Bank ermöglicht die Personalisierung über Sitzungen hinweg.

4. Workshop-Inhalte

5. Ressourcen