1. Wprowadzenie

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

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
- 👉 Kliknij ten link, aby przejść bezpośrednio do edytora Cloud Shell.
- 👉 Jeśli w którymś momencie pojawi się prośba o autoryzację, kliknij Autoryzuj, aby przejść dalej.

- 👉 Jeśli terminal nie pojawia się u dołu ekranu, otwórz go:
- Kliknij Wyświetl.
- Kliknij Terminal.

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

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

W konsoli Google Cloud zobaczysz 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
- W ostatnim kroku kliknij link i otwórz 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 lokalizacjiSurvivorHasSkill: spis umiejętnościSurvivorHasNeed: lista aktywnych problemówSurvivorFoundResource: 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: 
👉 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: 
👉 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: 
🔎 [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: 
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:
- Uruchamianie podobnego zapytania dotyczącego grafu
- Zwróć: „Dr Frost ma wykształcenie medyczne i może pomóc kapitanowi Tanace”.
- 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

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.

👉 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-004Google 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:

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:

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:

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:

6. Testowanie wyszukiwania semantycznego
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):

7. Tworzenie modelu Gemini do analizy

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

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.

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.

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

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.
🧬 A. Graph RAG (wyszukiwanie semantyczne)
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ą 🧬.
🔀 B. Wyszukiwanie hybrydowe
Łą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

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: 
👉 W terminalu kliknij Local: http://localhost:5173/.

2. Testowanie wyszukiwania semantycznego
Zapytanie:
Find skills similar to healing

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”)
3. Testowanie wyszukiwania hybrydowego
Zapytanie:
Find medical skills in the mountains
Skutki:
- Komponent słowa kluczowego: filtruj według
category='medical' - Komponent semantyczny: umieść „medyczny” i uporządkuj według podobieństwa.
- 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.

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:

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

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 |
| Jak – przesyłanie, wyodrębnianie, zapisywanie |
Agent |
| 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:
- Nie możesz wyodrębnić danych, dopóki nie masz pliku (przesyłanie).
- Nie możesz zapisać danych, dopóki ich nie wyodrębnisz (wyodrębnianie).
- 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:

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.


👉💻 Po zakończeniu testowania naciśnij „Ctrl+C” w terminalu, aby zakończyć proces.
6. Weryfikacja przesyłania multimodalnego w zasobniku GCS
- Otwórz konsolę Google Cloud Storage.
- Wybierz „zasobnik” w Cloud Storage.

- Wybierz zasobnik i kliknij
media.

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

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:

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.

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:
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”.
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
.envza pomocąAGENT_ENGINE_ID. - Sprawdź, czy w pliku
.envjest 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.
- Upewnij się, że wybierasz projekt w selektorze projektów w lewym górnym rogu:

- Sprawdź mechanizm agenta wdrożony za pomocą poprzedniego polecenia
use_memory_bank.sh:
Kliknij utworzony mechanizm agenta. - Kliknij kartę
Memorieswe wdrożonym agencie, aby wyświetlić całą pamięć.
👉💻 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.
👉💻 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:
- Backend Build: tworzy obraz Dockera z pliku
backend/Dockerfile. - Backend Deploy: wdraża kontener backendu w Cloud Run.
- Przechwyć URL: pobiera nowy URL backendu.
- Kompilacja interfejsu:
- Instaluje zależności.
- Tworzy aplikację React, wstrzykując
VITE_API_URL=.
- Frontend Image: tworzy obraz Dockera z pliku
frontend/Dockerfile(pakuje zasoby statyczne). - 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ć:
- Otwórz konsolę Cloud Run.
- Znajdź usługę
survivor-frontend. - Kliknij URL, aby otworzyć aplikację.
- 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

3. Najważniejsze wnioski
- Graph RAG: łączy strukturę bazy danych grafów z semantycznymi wektorami dystrybucyjnymi na potrzeby inteligentnego wyszukiwania.
- Wzorce z wieloma agentami: sekwencyjne potoki do złożonych, wieloetapowych przepływów pracy.
- Multimodalna AI: wyodrębnianie uporządkowanych danych z nieuporządkowanych multimediów (obrazów/filmów).
- Agenty stanowe: Bank zapamiętanych informacji umożliwia personalizację w różnych sesjach.
4. Treści warsztatowe
- Level0 Identyfikacja
- Level1: Dokładna lokalizacja
- Level2 This One: Build a Multimodal AI Agent with Graph RAG, ADK & Memory Bank
- Level3 tworzenie agenta strumieniowania dwukierunkowego ADK
- Level4 dwukierunkowy system wieloagentowy działający na żywo
- Level5 architektura oparta na zdarzeniach z Google ADK, A2A i Kafka