🤖 Tworzenie multimodalnego agenta AI z użyciem RAG opartego na grafach, ADK i pamięci

1. Wprowadzenie

cover utworu

1. Wyzwanie

W scenariuszach reagowania na katastrofy koordynowanie działań osób, które przeżyły, mających różne umiejętności, zasoby i potrzeby, w wielu lokalizacjach wymaga inteligentnego zarządzania danymi i możliwości wyszukiwania. Podczas tych warsztatów nauczysz się tworzyć produkcyjny system AI, który łączy:

  1. 🗄️ Grafowa baza danych (Spanner): przechowuj złożone relacje między ocalałymi, umiejętnościami i zasobami.
  2. 🔍 Wyszukiwanie oparte na AI: wyszukiwanie hybrydowe semantyczne i oparte na słowach kluczowych z użyciem wektorów dystrybucyjnych.
  3. 📸 Przetwarzanie multimodalne: wyodrębnianie uporządkowanych danych z obrazów, tekstu i filmów.
  4. 🤖 Administracja wieloma agentami: koordynuj wyspecjalizowanych agentów w ramach złożonych przepływów pracy.
  5. 🧠 Pamięć długoterminowa: personalizacja za pomocą banku zapamiętanych informacji Vertex AI

rozmowa

2. Co utworzysz

bazę danych grafu sieci ocalałych zawierającą:

  • 🗺️ Interaktywna wizualizacja grafu 3D przedstawiająca relacje między ocalałymi.
  • 🔍 Inteligentne wyszukiwanie (słowa kluczowe, semantyczne i hybrydowe)
  • Multimodalny potok przesyłania (wyodrębnianie encji z obrazów i filmów)
  • 🤖 system wieloagentowy do koordynowania złożonych zadań;
  • 🧠 integracja z Bankiem zapamiętanych informacji na potrzeby spersonalizowanych interakcji.

3. Core Technologies

Komponent

Technologia

Cel

Baza danych

Cloud Spanner Graph

Przechowywanie węzłów (ocalałych, umiejętności) i krawędzi (relacji)

Wyszukiwarka AI

Gemini + wektory dystrybucyjne

Zrozumienie semantyczne i wyszukiwanie podobieństw

Agent Framework

ADK (Agent Development Kit)

Zarządzanie przepływami pracy AI

Pamięć

Bank pamięci Vertex AI

Długoterminowe przechowywanie preferencji użytkownika

Frontend

React + Three.js

Interaktywna wizualizacja grafu 3D

2. 🛠️ Przygotowanie środowiska (pomiń, jeśli uczestniczysz w warsztatach)

Część 1. Włącz konto rozliczeniowe

Aby uruchomić tego ćwiczenia, potrzebujesz konta rozliczeniowego z pewnymi środkami. Aby rozpocząć, użyj środków z banera u góry tego ćwiczenia. Jeśli masz już połączenie z kontem rozliczeniowym, możesz pominąć ten krok.

Część 2. Otwórz środowisko

  1. 👉 Kliknij ten link, aby przejść bezpośrednio do edytora Cloud Shell.
  2. 👉 Jeśli w którymś momencie pojawi się prośba o autoryzację, kliknij Autoryzuj, aby przejść dalej. Kliknij, aby uwierzytelnić się w Cloud Shell
  3. 👉 Jeśli terminal nie pojawia się u dołu ekranu, otwórz go:
    • Kliknij Wyświetl.
    • Kliknij Terminal.Otwieranie nowego terminala w edytorze Cloud Shell
  4. 👉💻 W terminalu sprawdź, czy uwierzytelnianie zostało już przeprowadzone, a projekt jest ustawiony na Twój identyfikator projektu, używając tego polecenia:
    gcloud auth list
    
  5. 👉💻 Sklonuj projekt bootstrap z GitHuba:
    git clone https://github.com/gca-americas/way-back-home.git
    

Część 3. Tworzenie nowego projektu

👉💻 W terminalu zmień skrypt inicjujący na wykonywalny i uruchom go:

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

3. 🛠️ Konfiguracja środowiska

1. Otwórz Cloud Shell

Jeśli terminal edytora Cloud Shell nie jest widoczny u dołu ekranu, otwórz go:

  • Kliknij Wyświetl.
  • Kliknij Terminal.

Otwieranie nowego terminala w edytorze Cloud Shell

2. Konfigurowanie projektu

👉💻 W terminalu ustaw identyfikator projektu:

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

👉💻 Włącz wymagane interfejsy API (zajmie to około 2–3 minut):

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. Uruchamianie skryptu konfiguracyjnego

👉💻 Wykonaj skrypt konfiguracyjny:

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

Spowoduje to utworzenie .env. W Cloud Shell otwórz projekt way_back_home. W folderze level_2 zobaczysz utworzony plik .env. Jeśli nie możesz go znaleźć, kliknij View -> Toggle Hidden File, aby go wyświetlić. open_project

4. Wczytaj przykładowe dane

👉💻 Przejdź do backendu i zainstaluj zależności:

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

👉💻 Wczytaj początkowe dane o osobach, które przeżyły:

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

W ten sposób powstają:

  • Instancja Spannera (survivor-network)
  • Baza danych (graph-db)
  • Wszystkie tabele węzłów i krawędzi
  • Wykresy właściwości do wykonywania zapytań Oczekiwane dane wyjściowe:
============================================================
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

Jeśli klikniesz link po Access your database at w danych wyjściowych, możesz otworzyć Spannera w konsoli Google Cloud.

open_spanner

W konsoli Google Cloud zobaczysz Spanner.

spanner

4. 🚀 Wizualizacja danych grafu w Spanner Studio

Ten przewodnik pomoże Ci wizualizować dane grafu Survivor Network i wchodzić z nimi w interakcje bezpośrednio w konsoli Google Cloud za pomocą Spanner Studio. To świetny sposób na zweryfikowanie danych i zrozumienie struktury wykresu przed utworzeniem agenta AI.

1. Uzyskiwanie dostępu do Spanner Studio

  1. W ostatnim kroku kliknij link i otwórz Spanner Studio.

spanner_studio

2. Struktura wykresu (ogólny zarys)

Zbiór danych Survivor Network można traktować jako łamigłówkę logiczną lub stan gry:

Jednostka

Rola w systemie

Analogy

Survivors

agenty/gracze,

Gracze

Biomy

lokalizację,

Strefy mapy

Umiejętności

Co mogą robić

Umiejętności

Needs

Czego im brakuje (kryzysy)

Zadania/misje

Materiały

Przedmioty znalezione w świecie

Zbierz łup

Cel: zadaniem agenta AI jest dopasowanie umiejętności (rozwiązań) do potrzeb (problemów) z uwzględnieniem biomów (ograniczeń lokalizacyjnych).

🔗 Krawędzie (relacje):

  • SurvivorInBiome: śledzenie lokalizacji
  • SurvivorHasSkill: spis umiejętności
  • SurvivorHasNeed: lista aktywnych problemów
  • SurvivorFoundResource: asortyment produktów,
  • SurvivorCanHelp: wywnioskowana relacja (obliczona przez AI).

3. Tworzenie zapytań dotyczących grafu

Uruchommy kilka zapytań, aby zobaczyć, jaką „historię” opowiadają dane.

Spanner Graph używa GQL (Graph Query Language). Aby uruchomić zapytanie, wpisz GRAPH SurvivorNetwork, a następnie wzorzec dopasowania.

👉 Zapytanie 1. Globalny grafik (kto gdzie jest?) To podstawa – znajomość lokalizacji jest kluczowa dla działań ratowniczych.

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

Powinien wyświetlić się taki wynik: query1

👉 Zapytanie 2: matryca umiejętności (możliwości) – teraz, gdy wiesz, gdzie wszyscy są, dowiedz się, co potrafią.

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

Powinien wyświetlić się taki wynik: query2

👉 Zapytanie 3. Kto jest w kryzysie? („Tablica misji”) – zobacz, którzy ocalali potrzebują pomocy i czego im brakuje.

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

Powinien wyświetlić się taki wynik: query3

🔎 [Opcjonalnie] Dopasowywanie – kto może komu pomóc?

W tym miejscu wykres staje się bardzo przydatny. To zapytanie znajduje ocalałych, którzy mają umiejętności pozwalające im zaspokoić potrzeby innych ocalałych.

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

Powinien wyświetlić się taki wynik: query4

aside positive Co robi to zapytanie:

Zamiast wyświetlać tylko „Pierwsza pomoc leczy oparzenia” (co jest oczywiste na podstawie schematu), to zapytanie znajduje:

  • Dr Elena Frost (która ma wykształcenie medyczne) → może leczyć → Kapitana Tanakę (który ma oparzenia)
  • David Chen (który ma umiejętność Pierwsza pomoc) → może leczyć → por. Park (który ma skręconą kostkę)

Dlaczego to jest ważne:

Co zrobi Twój agent AI:

Gdy użytkownik zapyta: „Kto może leczyć oparzenia?”, agent:

  1. Uruchamianie podobnego zapytania dotyczącego grafu
  2. Zwróć: „Dr Frost ma wykształcenie medyczne i może pomóc kapitanowi Tanace”.
  3. Użytkownik nie musi wiedzieć o tabelach pośrednich ani relacjach.

5. 🚀 Wektory dystrybucyjne oparte na AI w usłudze Spanner

1. Dlaczego wektory dystrybucyjne? (Brak działania, tylko do odczytu)

W sytuacji zagrożenia życia czas ma kluczowe znaczenie. Gdy osoba, która przeżyła, zgłasza sytuację alarmową, np. I need someone who can treat burns lub Looking for a medic, nie może marnować czasu na zgadywanie dokładnych nazw umiejętności w bazie danych.

Real Scenario: Survivor: Captain Tanaka has burns—we need medical help NOW!

Tradycyjne wyszukiwanie słowa kluczowego „lekarz” → 0 wyników ❌

Wyszukiwanie semantyczne z wektorami dystrybucyjnymi → znajduje „Szkolenie medyczne”, „Pierwsza pomoc” ✅

To jest dokładnie to, czego potrzebują agenci: inteligentne wyszukiwanie, które przypomina ludzkie i rozumie intencje, a nie tylko słowa kluczowe.

2. Tworzenie modelu wektora dystrybucyjnego

spanner_embedding

Teraz utwórzmy model, który konwertuje tekst na wektory dystrybucyjne za pomocą text-embedding-004 Google.

👉 W Spanner Studio uruchom ten kod SQL (zastąp $YOUR_PROJECT_ID rzeczywistym identyfikatorem projektu):

‼️ W edytorze Cloud Shell otwórz File -> Open Folder -> way-back-home/level_2, aby zobaczyć cały projekt.

project_id (identyfikator projektu),

👉 Uruchom to zapytanie w Spanner Studio, kopiując i wklejając je poniżej, a następnie klikając przycisk Uruchom:

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'
);

Co to daje:

  • tworzy model wirtualny w usłudze Spanner (wagi modelu nie są przechowywane lokalnie);
  • Wskazuje text-embedding-004 Google w Vertex AI
  • Definiuje umowę: dane wejściowe to tekst, dane wyjściowe to tablica zmiennoprzecinkowa o 768 wymiarach

Dlaczego „OPCJE ZDALNE”?

  • Spanner nie uruchamia modelu samodzielnie.
  • Gdy korzystasz z ML.PREDICT, wywołuje Vertex AI przez interfejs API.
  • Zero-ETL: nie trzeba eksportować danych do Pythona, przetwarzać ich i ponownie importować.

Kliknij przycisk Run. Po zakończeniu operacji zobaczysz taki wynik:

spanner_result

3. Dodaj kolumnę wektorów dystrybucyjnych

👉 Dodaj kolumnę do przechowywania wektorów dystrybucyjnych:

ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;

Kliknij przycisk Run. Po zakończeniu operacji zobaczysz taki wynik:

embedding_result

4. Generowanie wektorów dystrybucyjnych

👉 Użyj AI do utworzenia wektorów dystrybucyjnych dla każdej umiejętności:

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

Kliknij przycisk Run. Po zakończeniu operacji zobaczysz taki wynik:

skills_result

Co się dzieje: każda nazwa umiejętności (np. „pierwsza pomoc”) jest konwertowana na wektor o 768 wymiarach, który reprezentuje jej znaczenie semantyczne.

5. Weryfikacja wektorów dystrybucyjnych

👉 Sprawdź, czy wektory dystrybucyjne zostały utworzone:

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

Oczekiwane dane wyjściowe:

spanner_result

Teraz przetestujemy konkretny przypadek użycia z naszego scenariusza: wyszukiwanie umiejętności medycznych za pomocą hasła „medic”.

👉 Znajdź umiejętności podobne do „ratownik medyczny”:

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;
  • Przekształca wyszukiwane przez użytkownika hasło „lekarz” w wektor dystrybucyjny.
  • zapisuje je w tabeli tymczasowej query_embedding,

Oczekiwane wyniki (mniejsza odległość = większe podobieństwo):

spanner_result

7. Tworzenie modelu Gemini do analizy

spanner_gemini

👉 Utwórz odwołanie do modelu generatywnej AI (zastąp $YOUR_PROJECT_ID rzeczywistym identyfikatorem projektu):

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

Różnica w porównaniu z modelem wektorów dystrybucyjnych:

  • Wektory dystrybucyjne: tekst → wektor (na potrzeby wyszukiwania podobieństwa)
  • Gemini tekst → wygenerowany tekst reklamy (na potrzeby wnioskowania/analizy)

spanner_result

8. Używanie Gemini do analizy zgodności

👉 Przeanalizuj pary ocalałych pod kątem zgodności z misją:

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

Oczekiwane dane wyjściowe:

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. 🚀 Tworzenie agenta Graph RAG z wyszukiwaniem hybrydowym

1. Omówienie architektury systemu

W tej sekcji utworzysz system wyszukiwania wykorzystujący wiele metod, który zapewni agentowi elastyczność w obsłudze różnych typów zapytań. System składa się z 3 warstw: warstwy agenta, warstwy narzędzi i warstwy usługi.

architecture_hybrid_search

Dlaczego 3 warstwy?

  • Rozdzielenie kwestii: agent koncentruje się na intencji, narzędzia na interfejsie, a usługa na implementacji.
  • Elastyczność: pracownik obsługi klienta może wymusić określone metody lub pozwolić AI na automatyczne przekierowywanie.
  • Optymalizacja: gdy metoda jest znana, można pominąć kosztowną analizę AI.

W tej sekcji wdrożysz głównie wyszukiwanie semantyczne (RAG), czyli znajdowanie wyników na podstawie znaczenia, a nie tylko słów kluczowych. Później wyjaśnimy, jak wyszukiwanie hybrydowe łączy wiele metod.

2. Implementacja usługi RAG

👉💻 W terminalu otwórz plik w edytorze Cloud Shell, uruchamiając polecenie:

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

Znajdź komentarz # TODO: REPLACE_SQL.

Zastąp cały ten wiersz tym kodem:

        # 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. Definicja narzędzia do wyszukiwania semantycznego

👉💻 W terminalu otwórz plik w edytorze Cloud Shell, uruchamiając polecenie:

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

W aplikacji hybrid_search_tools.py znajdź komentarz # TODO: REPLACE_SEMANTIC_SEARCH_TOOL

👉 Zastąp całą tę linię tym kodem:

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)}"

When Agent Uses:

  • zapytania o podobieństwo („znajdź podobne do X”);
  • zapytania koncepcyjne („zdolności lecznicze”),
  • Gdy zrozumienie znaczenia jest kluczowe

4. Przewodnik po decyzjach agenta (instrukcje)

W definicji agenta skopiuj i wklej część związaną z wyszukiwaniem semantycznym do instrukcji.

👉💻 W terminalu otwórz plik w edytorze Cloud Shell, uruchamiając polecenie:

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

Agent używa tej instrukcji, aby wybrać odpowiednie narzędzie:

👉 W pliku agent.py znajdź komentarz # TODO: REPLACE_SEARCH_LOGIC i zastąp cały ten wiersz tym kodem:

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

👉 Znajdź komentarz # TODO: ADD_SEARCH_TOOLReplace this whole line i zastąp go tym kodem:

    semantic_search,         # Force RAG

5. Jak działa wyszukiwanie hybrydowe (tylko do odczytu, nie wymaga działania)

W krokach 2–4 zaimplementowano wyszukiwanie semantyczne (RAG), czyli podstawową metodę wyszukiwania, która znajduje wyniki według znaczenia. Możesz jednak zauważyć, że system nazywa się „Wyszukiwanie hybrydowe”. Oto jak to wszystko działa:

Jak działa scalanie hybrydowe:

W pliku way-back-home/level_2/backend/services/hybrid_search_service.py, gdy wywoływana jest funkcja hybrid_search(), usługa przeprowadza OBA wyszukiwania i scala wyniki scalone:

# 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

W tym ćwiczeniu zaimplementowaliśmy komponent wyszukiwania semantycznego (RAG), który jest podstawą. Metody słów kluczowych i hybrydowe są już zaimplementowane w usłudze – agent może korzystać ze wszystkich 3 metod.

Gratulacje! Udało Ci się utworzyć agenta Graph RAG z wyszukiwaniem hybrydowym.

7. 🚀 Testowanie agenta za pomocą ADK Web

Najprostszym sposobem na przetestowanie agenta jest użycie polecenia adk web, które uruchamia agenta z wbudowanym interfejsem czatu.

1. Uruchamianie agenta

👉💻 Przejdź do katalogu backendu (w którym zdefiniowany jest agent) i uruchom interfejs internetowy:

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

To polecenie uruchamia agenta zdefiniowanego w pliku

agent/agent.py

i otwiera interfejs internetowy do testowania.

👉 Otwórz adres URL:

Polecenie wyświetli lokalny adres URL (zwykle http://127.0.0.1:8000 lub podobny). Otwórz go w przeglądarce.

adk web

Po kliknięciu adresu URL zobaczysz interfejs internetowy ADK. W lewym górnym rogu wybierz „agent”.

adk_ui

2. Możliwości wyszukiwania testów

Agent został zaprojektowany tak, aby inteligentnie kierować Twoje zapytania. Wpisz w oknie czatu poniższe dane wejściowe, aby zobaczyć różne metody wyszukiwania w działaniu.

Znajduje elementy na podstawie znaczenia i koncepcji, nawet jeśli słowa kluczowe nie pasują.

Przykładowe zapytania: (wybierz dowolne z poniższych)

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

Na co zwrócić uwagę:

  • W uzasadnieniu należy wspomnieć o wyszukiwaniu semantycznym lub RAG.
  • Powinny pojawić się wyniki powiązane koncepcyjnie (np. „Operacja” w przypadku pytania o „Pierwszą pomoc”).
  • Wyniki będą oznaczone ikoną 🧬.

Łączy filtry słów kluczowych ze zrozumieniem semantycznym w przypadku złożonych zapytań.

Przykładowe zapytania: (wybierz dowolne z poniższych)

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?

Na co zwrócić uwagę:

  • W uzasadnieniu należy wspomnieć o wyszukiwaniu hybrydowym.
  • Wyniki powinny spełniać OBA kryteria (koncepcja + lokalizacja/kategoria).
  • Wyniki znalezione za pomocą obu metod będą oznaczone ikoną 🔀 i będą miały najwyższą pozycję.

👉💻 Po zakończeniu testowania zakończ proces, naciskając Ctrl+C w wierszu poleceń.

8. 🚀 Uruchamianie pełnej aplikacji

Omówienie architektury Full Stack

architecture_fullstack

Dodawanie SessionService i Runner

👉💻 W terminalu otwórz plik chat.py w edytorze Cloud Shell, uruchamiając polecenie (zanim przejdziesz dalej, naciśnij „Ctrl + C”, aby zakończyć poprzedni proces):

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

👉 W pliku chat.py znajdź komentarz # TODO: REPLACE_INMEMORY_SERVICES i zastąp cały ten wiersz tym kodem:

    session_service = InMemorySessionService()
    memory_service = InMemoryMemoryService()

👉 W pliku chat.py znajdź komentarz # TODO: REPLACE_RUNNER i zastąp cały ten wiersz tym kodem:

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

1. Utwórz wniosek

Jeśli poprzedni terminal nadal działa, zakończ go, naciskając Ctrl+C.

👉💻 Uruchom aplikację:

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

Po pomyślnym uruchomieniu backendu zobaczysz Local: http://localhost:5173/", jak poniżej: fronted

👉 W terminalu kliknij Local: http://localhost:5173/.

rozmowa

Zapytanie:

Find skills similar to healing

czat

Skutki:

  • Agent rozpoznaje prośbę o podobieństwo
  • Generuje wektor dystrybucyjny dla „healing”
  • wykorzystuje odległość cosinusową do znajdowania umiejętności podobnych pod względem semantycznym;
  • Zwraca: pierwsza pomoc (mimo że nazwy nie pasują do „leczenia”)

Zapytanie:

Find medical skills in the mountains

Skutki:

  1. Komponent słowa kluczowego: filtruj według category='medical'
  2. Komponent semantyczny: umieść „medyczny” i uporządkuj według podobieństwa.
  3. Scalanie: łączenie wyników z priorytetem dla tych, które zostały znalezione za pomocą obu metod 🔀.

Zapytanie (opcjonalnie):

Who is good at survival and in the forest?

Skutki:

  • Znalezione słowa kluczowe: biome='forest'
  • Znaleziska semantyczne: umiejętności podobne do „survival”
  • Hybrydowy – łączy oba te tryby, aby zapewnić najlepsze wyniki.

👉💻 Po zakończeniu testowania zakończ je w terminalu, naciskając Ctrl+C.

4. (!ONLY FOR WORKSHOP ATTENDEE) Update your location

👉💻 Uruchom skrypt kończący:

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

Otwórz waybackhome.dev. Zobaczysz, że Twoja lokalizacja została zaktualizowana. Gratulujemy ukończenia poziomu 2.

wynik końcowy

9. ☕️ [Opcjonalnie] Potok multimodalny (tylko do odczytu) – warstwa narzędzi

Dlaczego potrzebujemy potoku multimodalnego?

Sieć przetrwania to nie tylko tekst. Osoby, które przeżyły, wysyłają nieuporządkowane dane bezpośrednio na czacie:

  • 📸 Obrazy: zdjęcia zasobów, zagrożeń lub sprzętu.
  • 🎥 Filmy: raporty o stanie lub transmisje SOS.
  • 📄 Tekst: notatki lub dzienniki terenowe.

Jakie pliki przetwarzamy?

W przeciwieństwie do poprzedniego kroku, w którym przeszukiwaliśmy istniejące dane, tutaj przetwarzamy pliki przesłane przez użytkownika. Interfejs chat.py dynamicznie obsługuje załączniki do plików:

Źródło

Treść

Cel

Załącznik użytkownika

Obraz/film/tekst

Informacje, które chcesz dodać do wykresu

Kontekst czatu

„Oto zdjęcie materiałów”

Zamiar i dodatkowe informacje

Planowane podejście: sekwencyjny potok agentów

Używamy agenta sekwencyjnego (multimedia_agent.py), który łączy wyspecjalizowanych agentów:

architecture_uploading

Jest to zdefiniowane w: backend/agent/multimedia_agent.py jako SequentialAgent.

Warstwa narzędzi zapewnia możliwości, które agenci mogą wywoływać. Narzędzia zajmują się „jak” – przesyłaniem plików, wyodrębnianiem encji i zapisywaniem w bazie danych.

1. Otwieranie pliku narzędzi

👉💻 Otwórz plik level_2/backend/agent/tools/extraction_tools.py lub wpisz w terminalu to polecenie: Otwórz nowy terminal. W terminalu otwórz plik w edytorze Cloud Shell:

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

2. Wdrażanie narzędzia upload_media

To narzędzie przesyła plik lokalny do Google Cloud Storage.

👉 W pliku def upload_media(file_path: str, survivor_id: Optional[str] = None) -> Dict[str, Any]: ten kod dotyczy przesyłania plików do GCS i wykrywania ich typu:

    """
    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. Wdrażanie narzędzia extract_from_media

To narzędzie jest routerem – sprawdza media_type i wysyła do odpowiedniego ekstraktora (tekstu, obrazu lub filmu).

👉 W pliku async def extract_from_media(gcs_uri: str, media_type: str, signed_url: Optional[str] = None) -> Dict[str, Any]: znajduje się kod, który pokazuje, jak wyodrębnić encje i relacje z przesłanych multimediów.

    """
    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)}

Najważniejsze informacje o implementacji:

  • Multimodalne dane wejściowe: do modelu generate_content przekazujemy zarówno prompt tekstowy (_get_extraction_prompt()), jak i obiekt obrazu.
  • Ustrukturyzowane dane wyjściowe: response_mime_type="application/json" zapewnia, że LLM zwraca prawidłowy kod JSON, co jest kluczowe dla potoku.
  • Visual Entity Linking: prompt zawiera znane elementy, dzięki czemu Gemini może rozpoznawać konkretne postacie.

4. Wdrażanie narzędzia save_to_spanner

To narzędzie zapisuje wyodrębnione encje i relacje w bazie danych Spanner Graph.

👉 W pliku def save_to_spanner(extraction_result: Any, survivor_id: Optional[str] = None) -> Dict[str, Any]: znajduje się kod, który pokazuje, jak zapisać wyodrębnione encje i relacje w bazie danych Spanner Graph.

    """
    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)}

Udostępniając agentom narzędzia wysokiego poziomu, zapewniamy integralność danych, a jednocześnie wykorzystujemy możliwości rozumowania agenta.

5. Aktualizowanie usługi GCS

GCSService obsługuje przesyłanie plików do Google Cloud Storage.

👉💻 Otwórz plik level_2/backend/services/gcs_service.py lub wpisz w terminalu polecenie, aby otworzyć plik w edytorze Cloud Shell:

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

👉 W pliku def upload_file(self, file_path: str, survivor_id: Optional[str] = None) -> Tuple[str, MediaType, str]: znajduje się kod, który pokazuje, jak zapisać wyodrębnione encje i relacje w bazie danych Spanner Graph.

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

Dzięki abstrakcji tej funkcji w usługę agent nie musi wiedzieć o zasobnikach GCS, nazwach obiektów blob ani generowaniu podpisanych adresów URL. Wyświetla się tylko prośba o przesłanie.

6. Dlaczego Agentic Workflows > podejście tradycyjne?

Przewaga agentowa:

Funkcja

Potok wsadowy

Oparte na zdarzeniach

Agentic Workflow

Złożoność

Niska (1 skrypt)

Wysoki (co najmniej 5 usług)

Niski (1 plik Pythona: multimedia_agent.py)

Zarządzanie stanem

Zmienne globalne

Sztywne (rozdzielone)

Unified (stan agenta)

Obsługa błędów

Awarie

Ciche logi

Interaktywne („Nie udało mi się odczytać tego pliku”)

Opinie użytkowników

Wydruki konsoli

Wymaga ankiety

Natychmiastowe (część czatu)

Możliwość dostosowania

Naprawiono logikę

Funkcje sztywne

Inteligentny (LLM decyduje o następnym kroku)

Świadomość kontekstu

Brak

Brak

Pełna (zna intencję użytkownika)

Dlaczego to ważne: używając multimedia_agent.py (SequentialAgent z 4 podagentami: Upload → Extract → Save → Summary), zastępujemy złożoną infrastrukturę ORAZ niestabilne skrypty inteligentną, konwersacyjną logiką aplikacji.

10. ☕️ [Opcjonalnie] Potok multimodalny (tylko do odczytu) – warstwa agenta

Warstwa agentów definiuje inteligencję – agenty, które używają narzędzi do wykonywania zadań. Każdy agent ma określoną rolę i przekazuje kontekst następnemu. Poniżej znajduje się schemat architektury systemu wieloagentowego.

agent_diagram

1. Otwieranie pliku agenta

👉💻 Otwórz plik level_2/backend/agent/multimedia_agent.py lub wpisz w terminalu to polecenie: Otwórz nowy terminal. W terminalu otwórz plik w edytorze Cloud Shell:

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

2. Definiowanie agenta przesyłania

Ten agent wyodrębnia ścieżkę pliku z wiadomości użytkownika i przesyła ją do GCS.

👉W pliku multimedia_agent.py za pomocą tego kodu tworzony jest obiekt upload_agent, który jest przesyłany do GCS:

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. Definiowanie agenta wyodrębniania

Ten agent „widzi” przesłane multimedia i wyodrębnia uporządkowane dane za pomocą Gemini Vision.

👉 W pliku multimedia_agent.py za pomocą tego kodu tworzy extraction_agent, który wyodrębnia informacje z przesłanych multimediów:

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

Zwróć uwagę, że instruction odwołuje się do {upload_result} – w ten sposób stan jest przekazywany między agentami w ADK.

4. Definiowanie agenta Spannera

Ten agent zapisuje wyodrębnione encje i relacje w bazie danych grafu.

👉 W pliku multimedia_agent.py za pomocą tego kodu tworzy spanner_agent, który zapisuje wyodrębnione informacje w bazie danych:

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

Ten agent otrzymuje kontekst z obu poprzednich kroków (upload_result i extraction_result).

5. Definiowanie agenta podsumowującego

Ten agent syntetyzuje wyniki ze wszystkich poprzednich kroków w przyjazną dla użytkownika odpowiedź.

👉 W pliku multimedia_agent.py za pomocą tego kodu definiuje prompta dla summary_agent, który podsumowuje wynik:

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

Ten agent nie potrzebuje narzędzi – po prostu odczytuje udostępniony kontekst i generuje dla użytkownika przejrzyste podsumowanie.

🧠 Podsumowanie architektury

Warstwa

Plik

Odpowiedzialność

Narzędzia

extraction_tools.py + gcs_service.py

Jak – przesyłanie, wyodrębnianie, zapisywanie

Agent

multimedia_agent.py

Co – zarządzanie potokiem.

11. 🚀 Multimodalny potok danych – administracja

Podstawą naszego nowego systemu jest MultimediaExtractionPipeline zdefiniowany w backend/agent/multimedia_agent.py. Wykorzystuje on wzorzec agenta sekwencyjnego z pakietu Agent Development Kit (ADK).

1. Dlaczego warto korzystać z sekwencyjnego wyświetlania?

Przetwarzanie przesłanego pliku to liniowy łańcuch zależności:

  1. Nie możesz wyodrębnić danych, dopóki nie masz pliku (przesyłanie).
  2. Nie możesz zapisać danych, dopóki ich nie wyodrębnisz (wyodrębnianie).
  3. Nie możesz podsumować, dopóki nie uzyskasz wyników (Zapisz).

SequentialAgent jest do tego idealny. Przekazuje dane wyjściowe jednego agenta jako kontekst lub dane wejściowe do następnego.

2. Definicja agenta

Zobaczmy, jak potok jest składany na dole pliku multimedia_agent.py: 👉💻 W terminalu otwórz plik w edytorze Cloud Shell, uruchamiając polecenie:

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

Otrzymuje dane wejściowe z obu poprzednich kroków. Znajdź komentarz # TODO: REPLACE_ORCHESTRATION. Zastąp cały ten wiersz tym kodem:

    sub_agents=[upload_agent, extraction_agent, spanner_agent, summary_agent]

3. Połącz z agentem głównym

👉💻 W terminalu otwórz plik w edytorze Cloud Shell, uruchamiając polecenie:

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

Znajdź komentarz # TODO: REPLACE_ADD_SUBAGENT. Zastąp cały ten wiersz tym kodem:

    sub_agents=[multimedia_agent],

Ten pojedynczy obiekt skutecznie łączy 4 „ekspertów” w jedną encję, którą można wywołać.

4. Przepływ danych między agentami

Każdy agent przechowuje swoje dane wyjściowe we wspólnym kontekście, do którego mogą uzyskać dostęp kolejne agenty:

architecture_uploading

5. Otwórz aplikację (pomiń, jeśli aplikacja jest nadal uruchomiona).

👉💻 Uruchom aplikację:

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

👉 W terminalu kliknij Local: http://localhost:5173/.

6. Przesyłanie obrazu testowego

👉 W interfejsie czatu wybierz dowolne zdjęcie i prześlij je do interfejsu:

W interfejsie czatu opisz agentowi swój konkretny kontekst:

Here is the survivor note

Następnie załącz obraz tutaj.

upload_input

upload_result

👉💻 Po zakończeniu testowania naciśnij „Ctrl+C” w terminalu, aby zakończyć proces.

6. Weryfikacja przesyłania multimodalnego w zasobniku GCS

gcs

  • Wybierz zasobnik i kliknij media.

media

  • Tutaj możesz wyświetlić przesłany obraz. uploaded_img

7. Weryfikowanie przesyłania multimodalnego w Spannerze (opcjonalnie)

Poniżej znajdziesz przykładowe dane wyjściowe w interfejsie dla test_photo1.

  • Otwórz Spanner w konsoli Google Cloud.
  • Wybierz instancję: Survivor Network
  • Wybierz bazę danych: graph-db
  • Na pasku bocznym po lewej stronie kliknij Spanner Studio.

👉 W Spanner Studio utwórz zapytanie dotyczące nowych danych:

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;

Możemy to sprawdzić, patrząc na wynik poniżej:

spanner_verify

12. ☕️ [Opcjonalnie] Bank zapamiętanych informacji z Agent Engine

1. Jak działa pamięć

System wykorzystuje podejście oparte na 2 rodzajach pamięci, aby obsługiwać zarówno natychmiastowy kontekst, jak i uczenie się długoterminowe.

memory_bank

2. Czym są tematy wspomnień?

Tematy pamięci określają kategorie informacji, które agent powinien zapamiętywać podczas rozmów. Można je traktować jako magazyny plików z różnymi typami preferencji użytkowników.

2 tematy:

  1. search_preferences: jak użytkownik lubi wyszukiwać;
    • Czy wolą wyszukiwanie słów kluczowych czy wyszukiwanie semantyczne?
    • Jakich umiejętności lub biomów często szukają?
    • Przykładowa pamięć: „Użytkownik preferuje wyszukiwanie semantyczne w przypadku umiejętności medycznych”.
  2. urgent_needs_context: jakie kryzysy śledzą,
    • Jakie zasoby monitorują?
    • O które osoby, które przeżyły, się martwią?
    • Przykładowe zapamiętane informacje: „Użytkownik śledzi niedobory leków w Northern Camp”.

3. Konfigurowanie tematów wspomnień

Niestandardowe tematy pamięci określają, co agent powinien zapamiętać. Są one konfigurowane podczas wdrażania silnika agenta.

👉💻 W terminalu otwórz plik w edytorze Cloud Shell, uruchamiając polecenie:

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

Spowoduje to otwarcie pliku ~/way-back-home/level_2/backend/deploy_agent.py w edytorze.

Definiujemy obiekty struktury MemoryTopic, aby wskazać LLM, jakie informacje ma wyodrębnić i zapisać.

👉 W pliku deploy_agent.py zastąp # TODO: SET_UP_TOPIC tym kodem:

# 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. Integracja z agentem

Kod agenta musi mieć dostęp do banku zapamiętanych informacji, aby zapisywać i pobierać informacje.

👉💻 W terminalu otwórz plik w edytorze Cloud Shell, uruchamiając polecenie:

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

Spowoduje to otwarcie pliku ~/way-back-home/level_2/backend/agent/agent.py w edytorze.

Tworzenie agentów

Podczas tworzenia agenta przekazujemy after_agent_callback, aby sesje były zapisywane w pamięci po interakcjach. Funkcja add_session_to_memory działa asynchronicznie, aby nie spowalniać odpowiedzi czatu.

👉 W pliku agent.py znajdź komentarz # TODO: REPLACE_ADD_SESSION_MEMORY i zastąp cały ten wiersz tym kodem:

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

Zapisywanie w tle

👉 W pliku agent.py znajdź komentarz # TODO: REPLACE_ADD_MEMORY_BANK_TOOL i zastąp cały ten wiersz tym kodem:

if USE_MEMORY_BANK:
    agent_tools.append(PreloadMemoryTool())

👉 W pliku agent.py znajdź komentarz # TODO: REPLACE_ADD_CALLBACK i zastąp cały ten wiersz tym kodem:

    after_agent_callback=add_session_to_memory if USE_MEMORY_BANK else None

Konfigurowanie usługi sesji Vertex AI

👉💻 W terminalu otwórz plik chat.py w edytorze Cloud Shell, uruchamiając polecenie:

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

👉 W pliku chat.py znajdź komentarz # TODO: REPLACE_VERTEXAI_SERVICES i zastąp cały ten wiersz tym kodem:

    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. ☕️ [Opcjonalnie] Dołączanie agenta za pomocą Agent Engine

1. Konfiguracja i wdrożenie

Zanim przetestujesz funkcje pamięci, musisz wdrożyć agenta z nowymi tematami pamięci i upewnić się, że środowisko jest prawidłowo skonfigurowane.

Aby ułatwić ten proces, udostępniliśmy skrypt.

Uruchamianie skryptu wdrażania

👉💻 W terminalu uruchom skrypt wdrażania:

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

Skrypt wykonuje te działania:

  • Uruchamia backend/deploy_agent.py, aby zarejestrować agenta i tematy pamięci w Vertex AI.
  • Przechwytuje nowy identyfikator silnika agenta.
  • Automatycznie aktualizuje plik .env za pomocą AGENT_ENGINE_ID.
  • Sprawdź, czy w pliku .env jest ustawiona wartość USE_MEMORY_BANK=TRUE.

[!IMPORTANT] Jeśli wprowadzisz zmiany w custom_topics w deploy_agent.py, musisz ponownie uruchomić ten skrypt, aby zaktualizować silnik agenta.

Weryfikacja banku zapamiętanych informacji

Teraz możesz sprawdzić, czy bank pamięci działa, ucząc agenta preferencji i sprawdzając, czy są one zachowywane między sesjami.

Krok 1. Otwórz aplikację

Otwórz aplikację ponownie, wykonując te instrukcje: jeśli poprzedni terminal nadal działa, zakończ jego działanie, naciskając Ctrls+C.

👉💻 Uruchom aplikację:

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

👉 W terminalu kliknij Local: http://localhost:5173/.

Krok 2. Testowanie banku zapamiętanych informacji z tekstem

W interfejsie czatu opisz agentowi swój konkretny kontekst:

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

👉 Poczekaj około 30 sekund, aż pamięć zostanie przetworzona w tle.

Krok 3. Rozpoczynanie nowej sesji

Odśwież stronę, aby wyczyścić historię bieżącej rozmowy (pamięć krótkotrwałą).

Zadaj pytanie, które opiera się na podanym wcześniej kontekście:

"What kind of missions am I interested in?"

Oczekiwana odpowiedź:

„Na podstawie Twoich poprzednich rozmów interesują Cię:

  • misje ratownictwa medycznego,
  • Działania w górach lub na dużych wysokościach
  • Wymagane umiejętności: pierwsza pomoc, wspinaczka

Czy chcesz, żebym znalazł ocalałych spełniających te kryteria?"

Krok 4. Testowanie za pomocą przesyłania obrazów

Prześlij obraz i zapytaj:

remember this

Możesz wybrać dowolne zdjęcie z tej strony lub własne i przesłać je do interfejsu:

Krok 5. Weryfikacja w Vertex AI Agent Engine

Otwórz Agent Engine w konsoli Google Cloud.

  1. Upewnij się, że wybierasz projekt w selektorze projektów w lewym górnym rogu:selektor projektów
  2. Sprawdź mechanizm agenta wdrożony za pomocą poprzedniego polecenia use_memory_bank.sh:silnik agentaKliknij utworzony mechanizm agenta.
  3. Kliknij kartę Memories we wdrożonym agencie, aby wyświetlić całą pamięć.wyświetl wspomnienie

👉💻 Po zakończeniu testowania naciśnij w terminalu „Ctrl + C”, aby zakończyć proces.

🎉 Gratulacje! Właśnie udało Ci się dołączyć bank zapamiętanych informacji do agenta.

14. ☕️ [Opcjonalnie] Wdrażanie w Cloud Run

1. Uruchamianie skryptu wdrażania

👉💻 Uruchom skrypt wdrażania:

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

Po pomyślnym wdrożeniu otrzymasz adres URL. To jest adres URL wdrożenia.wdrożono

👉💻 Zanim pobierzesz adres URL, przyznaj uprawnienia, uruchamiając polecenie:

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

Otwórz wdrożony adres URL, aby zobaczyć działającą aplikację.

2. Informacje o potoku kompilacji

Plik cloudbuild.yaml definiuje te kolejne kroki:

  1. Backend Build: tworzy obraz Dockera z pliku backend/Dockerfile.
  2. Backend Deploy: wdraża kontener backendu w Cloud Run.
  3. Przechwyć URL: pobiera nowy URL backendu.
  4. Kompilacja interfejsu:
    • Instaluje zależności.
    • Tworzy aplikację React, wstrzykując VITE_API_URL=.
  5. Frontend Image: tworzy obraz Dockera z pliku frontend/Dockerfile (pakuje zasoby statyczne).
  6. Frontend Deploy: wdraża kontener frontendu.

3. Sprawdzanie wdrożenia

Po zakończeniu kompilacji (sprawdź link do logów podany przez skrypt) możesz sprawdzić:

  1. Otwórz konsolę Cloud Run.
  2. Znajdź usługę survivor-frontend.
  3. Kliknij URL, aby otworzyć aplikację.
  4. Wykonaj zapytanie wyszukiwania, aby sprawdzić, czy frontend może komunikować się z backendem.

(OPCJONALNIE) 4. Wdrażanie ręczne

Jeśli wolisz uruchamiać polecenia ręcznie lub chcesz lepiej zrozumieć ten proces, poniżej znajdziesz instrukcje, jak bezpośrednio używać narzędzia cloudbuild.yaml.

Zapisuję plik cloudbuild.yaml

Plik cloudbuild.yaml informuje Google Cloud Build, jakie kroki należy wykonać.

  • steps: lista działań sekwencyjnych. Każdy krok jest wykonywany w kontenerze (np. docker, gcloud, node, bash).
  • substitutions: zmienne, które można przekazać w czasie kompilacji (np. $_REGION).
  • workspace: katalog współdzielony, w którym kroki mogą udostępniać pliki (podobnie jak udostępniamy backend_url.txt).

Uruchamianie wdrożenia

Aby wdrożyć ręcznie bez skryptu, użyj polecenia gcloud builds submit. MUSISZ przekazać wymagane zmienne do podstawienia.

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

1. Co udało Ci się utworzyć

✅ Grafowa baza danych: Spanner z węzłami (osoby, które przeżyły, umiejętności) i krawędziami (relacje)
✅ Wyszukiwarka AI: wyszukiwanie słów kluczowych, semantyczne i hybrydowe z wektorami dystrybucyjnymi
✅ Potok multimodalny: wyodrębnianie encji z obrazów/filmów za pomocą Gemini
✅ System wieloagentowy: skoordynowany przepływ pracy z ADK
✅ Bank pamięci: długoterminowa personalizacja za pomocą Vertex AI
✅ Wdrożenie produkcyjne: Cloud Run + Agent Engine

2. Podsumowanie architektury

architecture_fullstack

3. Najważniejsze wnioski

  1. Graph RAG: łączy strukturę bazy danych grafów z semantycznymi wektorami dystrybucyjnymi na potrzeby inteligentnego wyszukiwania.
  2. Wzorce z wieloma agentami: sekwencyjne potoki do złożonych, wieloetapowych przepływów pracy.
  3. Multimodalna AI: wyodrębnianie uporządkowanych danych z nieuporządkowanych multimediów (obrazów/filmów).
  4. Agenty stanowe: Bank zapamiętanych informacji umożliwia personalizację w różnych sesjach.

4. Treści warsztatowe

5. Zasoby