🤖 Crea un agente AI multimodale con Graph RAG, ADK e Memory Bank

1. Introduzione

cover

1. La sfida

Negli scenari di risposta ai disastri, il coordinamento dei sopravvissuti con competenze, risorse ed esigenze diverse in più località richiede funzionalità intelligenti di gestione e ricerca dei dati. Questo workshop ti insegna a creare un sistema di AI di produzione che combina:

  1. 🗄️ Database a grafo (Spanner): archivia relazioni complesse tra sopravvissuti, abilità e risorse
  2. 🔍 Ricerca basata sull'AI: ricerca ibrida semantica + per parole chiave utilizzando gli embedding
  3. 📸 Elaborazione multimodale: estrai dati strutturati da immagini, testo e video
  4. 🤖 Orchestrazione multi-agente: coordina agenti specializzati per workflow complessi
  5. 🧠 Memoria a lungo termine: personalizzazione con Vertex AI Memory Bank

conversazione

2. Cosa creerai

Un database di grafi della rete di sopravvissuti con:

  • 🗺️ Visualizzazione interattiva di grafici 3D delle relazioni tra i sopravvissuti
  • 🔍 Ricerca intelligente (per parole chiave, semantica e ibrida)
  • 📸 Pipeline di caricamento multimodale (estrazione di entità da immagini/video)
  • 🤖 Sistema multi-agente per l'orchestrazione di attività complesse
  • 🧠 Integrazione con Memory Bank per interazioni personalizzate

3. Tecnologie di base

Componente

Tecnologia

Finalità

Database

Cloud Spanner Graph

Archivia i nodi (sopravvissuti, abilità) e gli archi (relazioni)

Ricerca AI

Gemini + Embeddings

Comprensione semantica + ricerca per somiglianza

Framework dell'agente

ADK (Agent Development Kit)

Orchestra i workflow di AI

Memoria

Vertex AI Memory Bank

Archiviazione a lungo termine delle preferenze dell'utente

Frontend

React + Three.js

Visualizzazione interattiva di grafici 3D

2. 🛠️ Preparazione dell'ambiente (salta se partecipi al workshop)

Parte 1: attiva l'account di fatturazione

Per eseguire questo codelab, devi disporre di un account di fatturazione con un po' di credito. Per iniziare, utilizza i crediti del banner nella parte superiore di questo codelab. Se hai già un collegamento a un account di fatturazione, puoi saltare questo passaggio.

Parte 2: Ambiente aperto

  1. 👉 Fai clic su questo link per andare direttamente all'editor di Cloud Shell
  2. 👉 Se ti viene richiesto di concedere l'autorizzazione in qualsiasi momento oggi, fai clic su Autorizza per continuare. Fai clic per autorizzare Cloud Shell
  3. 👉 Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
    • Fai clic su Visualizza.
    • Fai clic su TerminaleApri un nuovo terminale nell'editor di Cloud Shell
  4. 👉💻 Nel terminale, verifica di aver già eseguito l'autenticazione e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:
    gcloud auth list
    
  5. 👉💻 Clona il progetto bootstrap da GitHub:
    git clone https://github.com/gca-americas/way-back-home.git
    

Parte 3: crea un nuovo progetto

👉💻 Nel terminale, rendi eseguibile lo script init ed eseguilo:

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

3. 🛠️ Configurazione dell'ambiente

1. Apri Cloud Shell

Nel terminale dell'editor di Cloud Shell, se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:

  • Fai clic su Visualizza.
  • Fai clic su Terminale.

Apri un nuovo terminale nell'editor di Cloud Shell

2. Configura il progetto

👉💻 Nel terminale, imposta l'ID progetto:

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

👉💻 Abilita le API richieste (questa operazione richiede circa 2-3 minuti):

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. Esegui lo script di configurazione

👉💻 Esegui lo script di configurazione:

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

Verrà creato .env per te. In Cloud Shell, apri il progetto way_back_home. Nella cartella level_2, puoi vedere che è stato creato un file .env. Se non riesci a trovarlo, puoi fare clic su View -> Toggle Hidden File per visualizzarlo. open_project

4. Carica dati di esempio

👉💻 Vai al backend e installa le dipendenze:

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

👉💻 Carica i dati iniziali dei sopravvissuti:

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

In questo modo vengono creati:

  • Istanza Spanner (survivor-network)
  • Database (graph-db)
  • Tutte le tabelle di nodi e archi
  • Grafici delle proprietà per le query Risultato previsto:
============================================================
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

Se fai clic sul link dopo Access your database at nell'output, puoi aprire Spanner nella console Google Cloud.

open_spanner

Vedrai Spanner nella console Google Cloud.

spanner

4. 🚀 Visualizzazione dei dati del grafo in Spanner Studio

Questa guida ti aiuta a visualizzare e interagire con i dati del grafo della rete di sopravvissuti direttamente nella console Google Cloud utilizzando Spanner Studio. Questo è un ottimo modo per verificare i dati e comprendere la struttura del grafo prima di creare l'agente AI.

1. Accedi a Spanner Studio

  1. Nell'ultimo passaggio, assicurati di fare clic sul link e di aprire Spanner Studio.

spanner_studio

2. Informazioni sulla struttura del grafico (il "quadro generale")

Pensa al set di dati Survivor Network come a un puzzle logico o a uno stato del gioco:

Entità

Ruolo nel sistema

Analogia

Survivors

Gli agenti/giocatori

Giocatori

Biomi

Dove si trovano

Zone della mappa

Skill

Cosa possono fare

Funzionalità

Esigenze

Cosa manca (crisi)

Missioni

Risorse

Elementi trovati nel mondo

Loot - Una fortuna

L'obiettivo: il compito dell'agente AI è collegare le Competenze (Soluzioni) alle Esigenze (Problemi), tenendo conto dei Biomi (Vincoli di posizione).

🔗 Archi (relazioni):

  • SurvivorInBiome: monitoraggio della posizione
  • SurvivorHasSkill: Inventario delle abilità
  • SurvivorHasNeed: elenco dei problemi attivi
  • SurvivorFoundResource: inventario degli elementi
  • SurvivorCanHelp: relazione dedotta (calcolata dall'AI)

3. Esecuzione di query sul grafico

Eseguiamo alcune query per vedere la "storia" nei dati.

Spanner Graph utilizza GQL (Graph Query Language). Per eseguire una query, utilizza GRAPH SurvivorNetwork seguito dal pattern di corrispondenza.

👉 Query 1: The Global Roster (Who is where?) Questa è la base: comprendere la posizione è fondamentale per le operazioni di soccorso.

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

Dovresti vedere un risultato simile al seguente: query1

👉 Query 2: The Skill Matrix (Capabilities) Now that you know where everyone is, find out what they can do.

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

Dovresti vedere un risultato simile al seguente: query2

👉 Query 3: Who is in Crisis? (La "Bacheca delle missioni") Scopri i sopravvissuti che hanno bisogno di aiuto e di cosa hanno bisogno.

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

Dovresti vedere un risultato simile al seguente: query3

🔎 [Facoltativo] Matchmaking: chi può aiutare chi?

È qui che il grafico diventa potente. Questa query trova i sopravvissuti che hanno competenze che possono soddisfare le esigenze di altri sopravvissuti.

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

Dovresti vedere un risultato simile al seguente: query4

aside positive What This Query Does:

Anziché mostrare semplicemente "First Aid treats burns" (che è ovvio dallo schema), questa query trova:

  • Dott. ssa Elena Frost (che ha una formazione medica) → può curare → Capitano Tanaka (che ha delle ustioni)
  • David Chen (che ha un kit di pronto soccorso) → può curare → Lt. Park (che ha una distorsione alla caviglia)

Perché è importante:

Cosa farà l'agente AI:

Quando un utente chiede "Chi può curare le ustioni?", l'agente:

  1. Esegui una query sul grafico simile
  2. Risposta: "Il dottor Frost ha una formazione medica e può aiutare il capitano Tanaka"
  3. L'utente non ha bisogno di conoscere le tabelle o le relazioni intermedie.

5. 🚀 Embedding basati sull'AI in Spanner

1. Perché gli incorporamenti? (Nessuna azione, sola lettura)

In uno scenario di sopravvivenza, il tempo è fondamentale. Quando un sopravvissuto segnala un'emergenza, come I need someone who can treat burns o Looking for a medic, non può perdere tempo a indovinare i nomi esatti delle competenze nel database.

Scenario reale: Sopravvissuto: Captain Tanaka has burns—we need medical help NOW!

Ricerca tradizionale per parole chiave per "medico" → 0 risultati ❌

Ricerca semantica con embedding → Trova "Formazione medica", "Primo soccorso" ✅

Questo è esattamente ciò di cui hanno bisogno gli agent: una ricerca intelligente e simile a quella umana che comprenda l'intento, non solo le parole chiave.

2. Crea modello di embedding

spanner_embedding

Ora creiamo un modello che converte il testo in embedding utilizzando text-embedding-004 di Google.

👉 In Spanner Studio, esegui questo SQL (sostituisci $YOUR_PROJECT_ID con l'ID progetto effettivo):

‼️ Nell'editor di Cloud Shell, apri File -> Open Folder -> way-back-home/level_2 per visualizzare l'intero progetto.

project_id

👉 Esegui questa query in Spanner Studio copiando e incollando la query di seguito, quindi fai clic sul pulsante Esegui:

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

Cosa fa:

  • Crea un modello virtuale in Spanner (nessun peso del modello archiviato localmente)
  • Indica il modello text-embedding-004 di Google su Vertex AI
  • Definisce il contratto: l'input è un testo, l'output è un array di numeri in virgola mobile a 768 dimensioni

Perché "OPZIONI REMOTE"?

  • Spanner non esegue il modello
  • Chiama Vertex AI tramite API quando utilizzi ML.PREDICT
  • Zero-ETL: non è necessario esportare i dati in Python, elaborarli e reimportarli

Fai clic sul pulsante Run. Una volta completata l'operazione, puoi visualizzare il risultato come di seguito:

spanner_result

3. Aggiungi colonna di embedding

👉 Aggiungi una colonna per archiviare gli embedding:

ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;

Fai clic sul pulsante Run. Una volta completata l'operazione, puoi visualizzare il risultato come di seguito:

embedding_result

4. Genera embedding

👉 Usa l'AI per creare vector embedding per ogni competenza:

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

Fai clic sul pulsante Run. Una volta completata l'operazione, puoi visualizzare il risultato come di seguito:

skills_result

Cosa succede: ogni nome di competenza (ad es. "pronto soccorso") viene convertito in un vettore di 768 dimensioni che ne rappresenta il significato semantico.

5. Verifica gli embedding

👉 Verifica che gli embedding siano stati creati:

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

Output previsto:

spanner_result

Ora testiamo il caso d'uso esatto del nostro scenario: trovare competenze mediche utilizzando il termine "medic".

👉 Trova skill simili a "medico":

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;
  • Converte il termine di ricerca dell'utente "medico" in un embedding
  • Lo archivia nella tabella temporanea query_embedding

Risultati previsti (distanza minore = maggiore somiglianza):

spanner_result

7. Crea un modello Gemini per l'analisi

spanner_gemini

👉 Crea un riferimento al modello di AI generativa (sostituisci $YOUR_PROJECT_ID con l'ID progetto effettivo):

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

Differenza rispetto al modello di embedding:

  • Embedding: testo → vettore (per la ricerca di somiglianze)
  • Gemini: testo → testo generato (per ragionamento/analisi)

spanner_result

8. Utilizza Gemini per l'analisi della compatibilità

👉 Analizza le coppie di sopravvissuti per verificare la compatibilità con la missione:

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

Output previsto:

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. 🚀 Creazione dell'agente Graph RAG con la ricerca ibrida

1. Panoramica dell'architettura del sistema

Questa sezione crea un sistema di ricerca multimetodo che offre all'agente la flessibilità necessaria per gestire diversi tipi di query. Il sistema ha tre livelli: Agent Layer, Tool Layer, Service Layer.

architecture_hybrid_search

Perché tre livelli?

  • Separazione delle responsabilità: l'agente si concentra sull'intent, gli strumenti sull'interfaccia e il servizio sull'implementazione
  • Flessibilità: l'agente può forzare metodi specifici o consentire all'AI di eseguire il routing automatico
  • Ottimizzazione: può saltare la costosa analisi AI quando il metodo è noto

In questa sezione implementerai principalmente la ricerca semantica (RAG), ovvero la ricerca di risultati in base al significato, non solo alle parole chiave. Più avanti spiegheremo come la ricerca ibrida unisce più metodi.

2. Implementazione del servizio RAG

👉💻 Nel terminale, apri il file nell'editor di Cloud Shell eseguendo:

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

Individua il commento # TODO: REPLACE_SQL

Sostituisci l'intera riga con il seguente codice:

        # 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. Definizione dello strumento di ricerca semantica

👉💻 Nel terminale, apri il file nell'editor di Cloud Shell eseguendo:

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

In hybrid_search_tools.py, individua il commento # TODO: REPLACE_SEMANTIC_SEARCH_TOOL

👉Sostituisci l'intera riga con il seguente codice:

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

Quando l'agente utilizza:

  • Query che richiedono somiglianze ("trova elementi simili a X")
  • Query concettuali ("capacità di guarigione")
  • Quando comprendere il significato è fondamentale

4. Guida alle decisioni dell'agente (istruzioni)

Nella definizione dell'agente, copia e incolla la parte relativa alla ricerca semantica nell'istruzione.

👉💻 Nel terminale, apri il file nell'editor di Cloud Shell eseguendo:

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

L'agente utilizza questa istruzione per selezionare lo strumento giusto:

👉Nel file agent.py, individua il commento # TODO: REPLACE_SEARCH_LOGIC, Sostituisci l'intera riga con il seguente codice:

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

👉Trova il commento # TODO: ADD_SEARCH_TOOLReplace this whole line con il seguente codice:

    semantic_search,         # Force RAG

5. Understanding How Hybrid Search Works (Read Only, No Action Needed)

Nei passaggi 2-4, hai implementato la ricerca semantica (RAG), il metodo di ricerca principale che trova i risultati in base al significato. Tuttavia, avrai notato che il sistema si chiama "Ricerca ibrida". Ecco come si integrano:

Come funziona l'unione ibrida:

Nel file way-back-home/level_2/backend/services/hybrid_search_service.py, quando viene chiamato hybrid_search(), il servizio esegue ENTRAMBE le ricerche e unisce i risultati:

# 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

Per questo codelab, hai implementato il componente di ricerca semantica (RAG), che è la base. I metodi basati su parole chiave e ibridi sono già implementati nel servizio: il tuo agente può utilizzarli tutti e tre.

Complimenti! Hai completato l'agente Graph RAG con la ricerca ibrida.

7. 🚀 Test dell'agente con ADK Web

Il modo più semplice per testare l'agente è utilizzare il comando adk web, che avvia l'agente con un'interfaccia di chat integrata.

1. Esecuzione dell'agente

👉💻 Vai alla directory del backend (dove è definito l'agente) e avvia l'interfaccia web:

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

Questo comando avvia l'agente definito in

agent/agent.py

e apre un'interfaccia web per i test.

👉 Apri l'URL:

Il comando restituirà un URL locale (di solito http://127.0.0.1:8000 o simile). Apri questo link nel browser.

adk web

Una volta fatto clic sull'URL, vedrai l'interfaccia utente web dell'ADK. Assicurati di selezionare "agent" nell'angolo in alto a sinistra.

adk_ui

2. Test delle funzionalità di ricerca

L'agente è progettato per indirizzare in modo intelligente le tue query. Prova i seguenti input nella finestra della chat per vedere in azione i diversi metodi di ricerca.

Trova elementi in base al significato e al concetto, anche se le parole chiave non corrispondono.

Query di test: (scegli una delle seguenti)

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

Cosa cercare:

  • Il ragionamento deve menzionare la ricerca semantica o RAG.
  • Dovresti visualizzare risultati concettualmente correlati (ad es. "Chirurgia" quando chiedi "Pronto soccorso").
  • I risultati avranno l'icona 🧬.

Combina i filtri per parole chiave con la comprensione semantica per query complesse.

Query di test: (scegli una delle seguenti)

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?

Cosa cercare:

  • Il ragionamento deve menzionare la ricerca ibrida.
  • I risultati devono corrispondere a ENTRAMBI i criteri (concetto + località/categoria).
  • I risultati trovati con entrambi i metodi avranno l'icona 🔀 e verranno classificati con il ranking più alto.

👉💻 Al termine del test, termina il processo premendo Ctrl+C nella riga di comando.

8. 🚀 Esecuzione dell'applicazione completa

Panoramica dell'architettura full stack

architecture_fullstack

Aggiungi SessionService e Runner

👉💻 Nel terminale, apri il file chat.py nell'editor di Cloud Shell eseguendo il comando seguente (assicurati di aver premuto "Ctrl+C" per terminare il processo precedente prima di procedere):

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

👉Nel file chat.py, individua il commento # TODO: REPLACE_INMEMORY_SERVICES, Sostituisci l'intera riga con il seguente codice:

    session_service = InMemorySessionService()
    memory_service = InMemoryMemoryService()

👉Nel file chat.py, individua il commento # TODO: REPLACE_RUNNER, Sostituisci l'intera riga con il seguente codice:

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

1. Avvia la domanda di partecipazione

Se il terminale precedente è ancora in esecuzione, terminalo premendo Ctrl+C.

👉💻 Avvia l'app:

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

Quando il backend viene avviato correttamente, vedrai Local: http://localhost:5173/" come di seguito: fronted

👉 Fai clic su Local: http://localhost:5173/ dal terminale.

conversazione

Query:

Find skills similar to healing

chat

Che cosa succede:

  • L'agente riconosce la richiesta di somiglianza
  • Genera l'embedding per "healing"
  • Utilizza la distanza del coseno per trovare competenze semanticamente simili
  • Restituisce: primo soccorso (anche se i nomi non corrispondono a "guarigione")

Query:

Find medical skills in the mountains

Che cosa succede:

  1. Componente di parole chiave: filtra per category='medical'
  2. Componente semantico: incorpora "medico" e classifica in base alla somiglianza
  3. Unisci: combina i risultati, dando la priorità a quelli trovati da entrambi i metodi 🔀

Query (facoltativa):

Who is good at survival and in the forest?

Che cosa succede:

  • Risultati per la parola chiave: biome='forest'
  • Risultati semantici: skill simili a "sopravvivenza"
  • Ibrido: combina entrambi per ottenere risultati ottimali

👉💻 Al termine del test, nel terminale, terminalo premendo Ctrl+C.

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

👉💻 Esegui lo script di completamento:

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

Ora apri waybackhome.dev e vedrai che la tua posizione è stata aggiornata. Congratulazioni per aver completato il livello 2.

risultato finale

9. ☕️ [Optional] Multimodal Pipeline (Read Only) — Tooling Layer

Perché abbiamo bisogno di una pipeline multimodale?

La rete di sopravvivenza non è solo testo. I sopravvissuti sul campo inviano dati non strutturati direttamente tramite la chat:

  • 📸 Immagini: foto di risorse, pericoli o attrezzature
  • 🎥 Video: report sullo stato o trasmissioni SOS
  • 📄 Testo: note o log sul campo

Quali file elaboriamo?

A differenza del passaggio precedente, in cui abbiamo eseguito ricerche nei dati esistenti, qui elaboriamo i file caricati dagli utenti. L'interfaccia chat.py gestisce gli allegati dei file in modo dinamico:

Origine

Contenuti

Obiettivo

Allegato dell'utente

Immagine/video/testo

Informazioni da aggiungere al grafico

Contesto della chat

"Ecco una foto dei materiali"

Intent e dettagli aggiuntivi

L'approccio pianificato: pipeline di agenti sequenziali

Utilizziamo un agente sequenziale (multimedia_agent.py) che concatena agenti specializzati:

architecture_uploading

Questo è definito in backend/agent/multimedia_agent.py come SequentialAgent.

Il livello degli strumenti fornisce le funzionalità che gli agenti possono richiamare. Gli strumenti gestiscono il "come": caricamento dei file, estrazione delle entità e salvataggio nel database.

1. Apri il file Tools

👉💻 Apri il file level_2/backend/agent/tools/extraction_tools.py o digita il seguente comando nel terminale. Apri un nuovo terminale. Nel terminale, apri il file nell'editor di Cloud Shell:

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

2. Implementa lo strumento upload_media

Questo strumento carica un file locale su Google Cloud Storage.

👉 In def upload_media(file_path: str, survivor_id: Optional[str] = None) -> Dict[str, Any]:, il seguente codice riguarda il caricamento dei file su GCS e il rilevamento del tipo:

    """
    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. Implementa lo strumento extract_from_media

Questo strumento è un router: controlla il media_type e lo invia all'estrattore corretto (testo, immagine o video).

👉 In async def extract_from_media(gcs_uri: str, media_type: str, signed_url: Optional[str] = None) -> Dict[str, Any]:, il seguente codice mostra come estrarre entità e relazioni dai contenuti multimediali caricati.

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

Dettagli chiave dell'implementazione:

  • Input multimodale: passiamo sia il prompt testuale (_get_extraction_prompt()) sia l'oggetto immagine a generate_content.
  • Output strutturato: response_mime_type="application/json" garantisce che l'LLM restituisca un JSON valido, fondamentale per la pipeline.
  • Visual Entity Linking: il prompt include entità note in modo che Gemini possa riconoscere personaggi specifici.

4. Implementa lo strumento save_to_spanner

Questo strumento conserva le entità e le relazioni estratte nel database Spanner Graph.

👉 In def save_to_spanner(extraction_result: Any, survivor_id: Optional[str] = None) -> Dict[str, Any]:, il seguente codice mostra come salvare le entità e le relazioni estratte nel database 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)}

Fornendo agli agenti strumenti di alto livello, garantiamo l'integrità dei dati sfruttando al contempo le capacità di ragionamento dell'agente.

5. Aggiorna il servizio GCS

GCSService gestisce il caricamento effettivo del file su Google Cloud Storage.

👉💻 Apri il file level_2/backend/services/gcs_service.py oppure digita nel terminale per aprire il file nell'editor di Cloud Shell:

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

👉 In def upload_file(self, file_path: str, survivor_id: Optional[str] = None) -> Tuple[str, MediaType, str]:, il seguente codice mostra come salvare le entità e le relazioni estratte nel database Spanner Graph.

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

Astrarre questo processo in un servizio evita all'agente di dover conoscere i bucket GCS, i nomi dei blob o la generazione di URL firmati. Chiede solo di "caricare".

6. Perché l'Agentic Workflow è migliore degli approcci tradizionali?

Il vantaggio degli agenti:

Funzionalità

Pipeline batch

Basato su eventi

Agentic Workflow

complessità

Bassa (1 script)

Alto (più di 5 servizi)

Basso (1 file Python: multimedia_agent.py)

Gestione dello stato

Variabili globali

Rigido (disaccoppiato)

Unificato (stato dell'agente)

Gestione degli errori

Arresti anomali

Log silenziosi

Interattivo ("Non sono riuscito a leggere il file")

Feedback dell'utente

Stampe della console

Polling necessario

Immediata (parte della chat)

Adattabilità

Logica fissa

Funzioni rigide

Intelligente (l'LLM decide il passaggio successivo)

Consapevolezza del contesto

Nessuno

Nessuno

Completa (conosce l'user intent)

Perché è importante: utilizzando multimedia_agent.py (un SequentialAgent con 4 sub-agenti: Upload → Extract → Save → Summary), sostituiamo un'infrastruttura complessa E script fragili con una logica applicativa intelligente e conversazionale.

10. ☕️ [Optional] Multimodal Pipeline (Read Only) — Agent Layer

Il livello degli agenti definisce l'intelligence, ovvero gli agenti che utilizzano gli strumenti per svolgere le attività. Ogni agente ha un ruolo specifico e passa il contesto a quello successivo. Di seguito è riportato il diagramma dell'architettura per il sistema multiagente.

agent_diagram

1. Apri il file dell'agente

👉💻 Apri il file level_2/backend/agent/multimedia_agent.py o digita il seguente comando nel terminale. Apri un nuovo terminale. Nel terminale, apri il file nell'editor di Cloud Shell:

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

2. Definisci l'agente di caricamento

Questo agente estrae un percorso file dal messaggio dell'utente e lo carica su GCS.

👉Nel file multimedia_agent.py, con il seguente codice, viene creato upload_agent che viene caricato su 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. Definisci l'agente di estrazione

Questo agente "vede" i contenuti multimediali caricati ed estrae i dati strutturati utilizzando Gemini Vision.

👉Nel file multimedia_agent.py, con il seguente codice, viene creato extraction_agent che estrae informazioni dai contenuti multimediali caricati:

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

Nota come instruction fa riferimento a {upload_result}: è così che lo stato viene passato tra gli agenti in ADK.

4. Definisci l'agente Spanner

Questo agente salva le entità e le relazioni estratte nel database del grafo.

👉Nel file multimedia_agent.py, con il seguente codice, viene creato spanner_agent che salva le informazioni estratte nel database:

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

Questo agente riceve il contesto da entrambi i passaggi precedenti (upload_result e extraction_result).

5. Definisci l'agente di riepilogo

Questo agente sintetizza i risultati di tutti i passaggi precedenti in una risposta facile da usare.

👉Nel file multimedia_agent.py, con il seguente codice, definisce il prompt per summary_agent che riassume il risultato:

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

Questo agente non ha bisogno di strumenti: legge semplicemente il contesto condiviso e genera un riepilogo chiaro per l'utente.

🧠 Riepilogo dell'architettura

incorporato

File

Responsabilità

Strumenti

extraction_tools.py + gcs_service.py

Come: carica, estrai, salva

Agent

multimedia_agent.py

Cosa: orchestrare la pipeline

11. 🚀 Pipeline di dati multimodali - Orchestrazione

Il fulcro del nostro nuovo sistema è MultimediaExtractionPipeline definito in backend/agent/multimedia_agent.py. Utilizza il pattern Sequential Agent dell'ADK (Agent Development Kit).

1. Perché sequenziale?

L'elaborazione di un caricamento è una catena di dipendenze lineare:

  1. Non puoi estrarre i dati finché non hai il file (caricamento).
  2. Non puoi salvare i dati finché non li estrai (estrazione).
  3. Non puoi riassumere finché non hai i risultati (Salva).

Un SequentialAgent è perfetto per questo. Passa l'output di un agente come contesto/input all'agente successivo.

2. Definizione dell'agente

Vediamo come viene assemblata la pipeline nella parte inferiore di multimedia_agent.py: 👉💻 Nel terminale, apri il file nell'editor di Cloud Shell eseguendo:

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

Riceve gli input da entrambi i passaggi precedenti. Individua il commento # TODO: REPLACE_ORCHESTRATION. Sostituisci l'intera riga con il seguente codice:

    sub_agents=[upload_agent, extraction_agent, spanner_agent, summary_agent]

3. Connettiti con l'agente principale

👉💻 Nel terminale, apri il file nell'editor di Cloud Shell eseguendo:

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

Individua il commento # TODO: REPLACE_ADD_SUBAGENT. Sostituisci l'intera riga con il seguente codice:

    sub_agents=[multimedia_agent],

Questo singolo oggetto raggruppa efficacemente quattro "esperti" in un'unica entità richiamabile.

4. Flusso di dati tra gli agenti

Ogni agente archivia il proprio output in un contesto condiviso a cui possono accedere gli agenti successivi:

architecture_uploading

5. Apri l'applicazione (salta se l'app è ancora in esecuzione)

👉💻 Avvia l'app:

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

👉 Fai clic su Local: http://localhost:5173/ dal terminale.

6. Caricamento immagine di prova

👉 Nell'interfaccia della chat, scegli una delle foto qui sotto e caricala nell'interfaccia utente:

Nell'interfaccia di chat, comunica all'agente il tuo contesto specifico:

Here is the survivor note

Poi allega l'immagine qui.

upload_input

upload_result

👉💻 Nel terminale, al termine del test, premi "Ctrl+C" per terminare il processo.

6. Verifica il caricamento multimodale nel bucket GCS

gcs

  • Seleziona il bucket e fai clic su media.

media

  • Visualizza l'immagine caricata qui. uploaded_img

7. (Facoltativo) Verifica il caricamento multimodale in Spanner

Di seguito è riportato un esempio di output nell'interfaccia utente per test_photo1.

  • Apri Spanner nella console Google Cloud.
  • Seleziona l'istanza: Survivor Network
  • Seleziona il tuo database: graph-db
  • Nella barra laterale a sinistra, fai clic su Spanner Studio.

👉 In Spanner Studio, esegui una query sui nuovi dati:

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;

Possiamo verificarlo osservando il risultato di seguito:

spanner_verify

12. ☕️ [Facoltativo] Memory Bank con Agent Engine

1. Come funziona la memoria

Il sistema utilizza un approccio a doppia memoria per gestire sia il contesto immediato sia l'apprendimento a lungo termine.

memory_bank

2. Che cosa sono gli argomenti della memoria?

Gli argomenti della memoria definiscono le categorie di informazioni che l'agente deve ricordare tra una conversazione e l'altra. Immagina che siano come degli schedari per diversi tipi di preferenze degli utenti.

I nostri due argomenti:

  1. search_preferences: come l'utente preferisce eseguire le ricerche
    • Preferiscono la ricerca per parole chiave o la ricerca semantica?
    • Quali abilità/biomi cercano spesso?
    • Esempio di memoria: "L'utente preferisce la ricerca semantica per le competenze mediche"
  2. urgent_needs_context: quali crisi stanno monitorando
    • Quali risorse stanno monitorando?
    • Quali sopravvissuti li preoccupano?
    • Esempio di memoria: "L'utente sta monitorando la carenza di farmaci nel campo nord"

3. Configurazione degli argomenti della memoria

Gli argomenti della memoria personalizzata definiscono cosa l'agente deve ricordare. Questi vengono configurati durante il deployment di Agent Engine.

👉💻 Nel terminale, apri il file nell'editor di Cloud Shell eseguendo:

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

Viene aperto ~/way-back-home/level_2/backend/deploy_agent.py nell'editor.

Definiamo gli oggetti della struttura MemoryTopic per guidare l'LLM sulle informazioni da estrarre e salvare.

👉Nel file deploy_agent.py, sostituisci # TODO: SET_UP_TOPIC con quanto segue:

# 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. Integrazione con l'agente

Il codice dell'agente deve essere a conoscenza della Memory Bank per salvare e recuperare le informazioni.

👉💻 Nel terminale, apri il file nell'editor di Cloud Shell eseguendo:

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

Viene aperto ~/way-back-home/level_2/backend/agent/agent.py nell'editor.

Creazione di agenti

Durante la creazione dell'agente, passiamo after_agent_callback per garantire che le sessioni vengano salvate in memoria dopo le interazioni. La funzione add_session_to_memory viene eseguita in modo asincrono per evitare di rallentare la risposta della chat.

👉Nel file agent.py, individua il commento # TODO: REPLACE_ADD_SESSION_MEMORY, Sostituisci l'intera riga con il seguente codice:

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

Salvataggio in background

👉Nel file agent.py, individua il commento # TODO: REPLACE_ADD_MEMORY_BANK_TOOL, Replace this whole line con il seguente codice:

if USE_MEMORY_BANK:
    agent_tools.append(PreloadMemoryTool())

👉Nel file agent.py, individua il commento # TODO: REPLACE_ADD_CALLBACK, Replace this whole line con il seguente codice:

    after_agent_callback=add_session_to_memory if USE_MEMORY_BANK else None

Configura il servizio di sessione Vertex AI

👉💻 Nel terminale, apri il file chat.py nell'editor di Cloud Shell eseguendo:

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

👉Nel file chat.py, individua il commento # TODO: REPLACE_VERTEXAI_SERVICES, Sostituisci l'intera riga con il seguente codice:

    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. ☕️ [Facoltativo] Collega l'agente con Agent Engine

1. Configurazione e deployment

Prima di testare le funzionalità di memoria, devi eseguire il deployment dell'agente con i nuovi argomenti di memoria e assicurarti che l'ambiente sia configurato correttamente.

Abbiamo fornito uno script di convenienza per gestire questo processo.

Esecuzione dello script di deployment

👉💻 Nel terminale, esegui lo script di deployment:

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

Questo script esegue le seguenti azioni:

  • Esegue backend/deploy_agent.py per registrare gli argomenti dell'agente e della memoria con Vertex AI.
  • Acquisisce il nuovo ID Agent Engine.
  • Aggiorna automaticamente il file .env con AGENT_ENGINE_ID.
  • Assicura che USE_MEMORY_BANK=TRUE sia impostato nel file .env.

[!IMPORTANT] Se apporti modifiche a custom_topics in deploy_agent.py, devi eseguire nuovamente questo script per aggiornare l'Agent Engine.

Verifica Memory Bank

Ora puoi verificare che la banca della memoria funzioni insegnando all'agente una preferenza e controllando se persiste tra le sessioni.

Passaggio 1. Apri l'applicazione

Apri di nuovo l'applicazione seguendo le istruzioni riportate di seguito: se il terminale precedente è ancora in esecuzione, terminalo premendo Ctrls+C.

👉💻 Avvia l'app:

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

👉 Fai clic su Local: http://localhost:5173/ dal terminale.

Passaggio 2. Test di Memory Bank con testo

Nell'interfaccia di chat, comunica all'agente il tuo contesto specifico:

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

👉 Attendi circa 30 secondi per l'elaborazione del ricordo in background.

Passaggio 3. Avvia una nuova sessione

Aggiorna la pagina per cancellare la cronologia della conversazione corrente (memoria a breve termine).

Fai una domanda che si basa sul contesto che hai fornito in precedenza:

"What kind of missions am I interested in?"

Risposta prevista:

"In base alle nostre conversazioni precedenti, ti interessano:

  • Missioni di soccorso medico
  • Operazioni in montagna/ad alta quota
  • Competenze richieste: primo soccorso, arrampicata

Vuoi che trovi i sopravvissuti che corrispondono a questi criteri?"

Passaggio 4. Test con caricamento immagine

Carica un'immagine e chiedi:

remember this

Puoi scegliere una delle foto qui o una tua e caricarla nell'interfaccia utente:

Passaggio 5. Verifica in Vertex AI Agent Engine

Vai ad Agent Engine nella console Google Cloud

  1. Assicurati di selezionare il progetto dal selettore di progetti in alto a sinistra:selettore di progetti
  2. Verifica l'engine dell'agente di cui hai appena eseguito il deployment con il comando precedente use_memory_bank.sh:motore agenteFai clic sull'engine dell'agente appena creato.
  3. Fai clic sulla scheda Memories in questo agente di cui è stato eseguito il deployment. Qui puoi visualizzare tutta la memoria.visualizza ricordo

👉💻 Al termine del test, nel terminale, premi "Ctrl + C" per terminare il processo.

🎉 Complimenti! Hai appena collegato la banca della memoria al tuo agente.

14. ☕️ [Facoltativo] Esegui il deployment in Cloud Run

1. Esegui lo script di deployment

👉💻 Esegui lo script di deployment:

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

Una volta eseguito il deployment, avrai l'URL, ovvero l'URL di cui è stato eseguito il deployment. deployment eseguito

👉💻 Prima di recuperare l'URL, concedi l'autorizzazione eseguendo:

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

Vai all'URL di cui è stato eseguito il deployment e vedrai la tua applicazione pubblicata.

2. Informazioni sulla pipeline di build

Il file cloudbuild.yaml definisce i seguenti passaggi sequenziali:

  1. Backend Build: crea l'immagine Docker da backend/Dockerfile.
  2. Deployment del backend: esegue il deployment del container di backend in Cloud Run.
  3. Acquisisci URL: recupera il nuovo URL di backend.
  4. Build frontend:
    • Installa le dipendenze.
    • Crea la build dell'app React, inserendo VITE_API_URL=.
  5. Frontend Image: crea l'immagine Docker da frontend/Dockerfile (pacchettizzazione degli asset statici).
  6. Frontend Deploy: esegue il deployment del container frontend.

3. Verifica il deployment

Una volta completata la build (controlla il link ai log fornito dallo script), puoi verificare:

  1. Vai alla console Cloud Run.
  2. Trova il servizio survivor-frontend.
  3. Fai clic sull'URL per aprire l'applicazione.
  4. Esegui una query di ricerca per assicurarti che il frontend possa comunicare con il backend.

(FACOLTATIVO) 4. Deployment manuale

Se preferisci eseguire i comandi manualmente o comprendere meglio il processo, ecco come utilizzare direttamente cloudbuild.yaml.

Sto scrivendo cloudbuild.yaml

Un file cloudbuild.yaml indica a Google Cloud Build quali passaggi eseguire.

  • steps: un elenco di azioni sequenziali. Ogni passaggio viene eseguito in un container (ad es. docker, gcloud, node, bash).
  • substitutions: variabili che possono essere passate in fase di build (ad es. $_REGION).
  • workspace: una directory condivisa in cui i passaggi possono condividere file (come condividiamo backend_url.txt).

Esecuzione del deployment

Per eseguire il deployment manualmente senza lo script, utilizza il comando gcloud builds submit. DEVI passare le variabili di sostituzione richieste.

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

1. Cosa hai creato

✅ Database a grafo: Spanner con nodi (sopravvissuti, competenze) e archi (relazioni)
✅ Ricerca AI: ricerca per parole chiave, semantica e ibrida con embedding
✅ Pipeline multimodale: estrazione di entità da immagini/video con Gemini
✅ Sistema multi-agente: flusso di lavoro coordinato con ADK
✅ Memory Bank: personalizzazione a lungo termine con Vertex AI
✅ Deployment in produzione: Cloud Run + Agent Engine

2. Riepilogo dell'architettura

architecture_fullstack

3. Nozioni principali

  1. Graph RAG: combina la struttura del database dei grafi con gli embedding semantici per una ricerca intelligente
  2. Pattern multi-agente: pipeline sequenziali per workflow complessi in più passaggi
  3. AI multimodale: estrai dati strutturati da contenuti multimediali non strutturati (immagini/video)
  4. Agenti stateful: Memory Bank consente la personalizzazione tra le sessioni

4. Contenuti del workshop

5. Risorse