Creazione di agenti personalizzati con ADK, MCP e Memory Bank

1. Introduzione

Lo stack di agenti moderni

La creazione di un agente AI di livello di produzione richiede più di un semplice modello linguistico di grandi dimensioni (LLM). Mentre un LLM fornisce le capacità di ragionamento, un agente solido deve interagire con il mondo esterno, gestire lo stato della conversazione e ricordare le preferenze dell'utente nel tempo.

In questo workshop imparerai a progettare e creare un sistema agentico completo utilizzando tre tecnologie fondamentali:

1. Connettività (MCP): per consentire all'agente di accedere a strumenti e dati locali.
2. Orchestrazione (ADK): per gestire il ciclo di ragionamento e lo stato dell'agente.
3. Memoria (Memory Bank): per fornire un contesto personalizzato a lungo termine.

Concetti principali

Componente	Funzione
Model Context Protocol (MCP)	Uno standard universale che collega i modelli di AI a sistemi esterni (database, file system, API) senza integrazioni personalizzate.
Agent Development Kit (ADK)	Un framework che fornisce l'ambiente di runtime per gli agenti, gestendo il ciclo degli eventi, le transizioni di stato e l'esecuzione degli strumenti.
Session Service	Gli handle memorizzano a breve termine. Conserva il contesto immediato della conversazione (ad es. "Cosa ha appena chiesto l'utente?") ma viene cancellata al termine della sessione.
Vertex AI Memory Bank	Gestisce la memoria a lungo termine. Conserva fatti e preferenze specifici dell'utente (ad es. "User prefers Python") indefinitely, allowing the agent to personalize future interactions.
Vertex AI Agent Engine	Il servizio di infrastruttura gestita che ospita i componenti di logica e memoria dell'agente su larga scala.

Cosa creerai

Per dimostrare questi concetti, creerai un assistente per la progettazione di decorazioni per le festività. Questo agente sarà in grado di accettare richieste utente di alto livello e orchestrare autonomamente gli strumenti Python locali per generare codice e immagini personalizzati.

Avanzerai in tre fasi:

1. Livello di strumentazione: crea un server MCP per esporre le funzioni Python locali all'AI.
2. Livello dell'agente: utilizza ADK per creare un agente che pianifichi ed esegua workflow in più passaggi.
3. Livello di memoria: integra Memory Bank per consentire all'agente di apprendere e ricordare le preferenze di stile dell'utente.

2. Configura

Per alimentare i nostri agenti AI, abbiamo bisogno di due cose: un progetto Google Cloud per fornire le basi.

Parte 1: abilita l'account di fatturazione

• Per richiedere il tuo account di fatturazione con un credito di 5 $, ti servirà per il deployment. Assicurati di accedere al tuo account Gmail.

Nessuna carta di credito o pagamento necessario: riceverai 5 crediti senza costi. Ci vogliono meno di due minuti: basta inserire il tuo nome e accettare i crediti.

Parte 2: Open Environment

1. 👉 Fai clic su questo link per passare direttamente all'editor di Cloud Shell
2. 👉 Se ti viene richiesto di concedere l'autorizzazione in qualsiasi momento della giornata, fai clic su Autorizza per continuare.
3. 👉 Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
   • Fai clic su Visualizza.
   • Fai clic su Terminale.
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 di bootstrap da GitHub:

   git clone https://github.com/cuppibla/holiday_workshop
   

6. 👉💻 Esegui lo script di configurazione dalla directory del progetto.

   cd ~/holiday_workshop
   ./init.sh
   

   ⚠️ Nota sull'ID progetto: lo script suggerirà un ID progetto predefinito generato in modo casuale. Puoi premere Invio per accettare questa impostazione predefinita.

   Tuttavia, se preferisci creare un nuovo progetto specifico, puoi digitare l'ID progetto che preferisci quando ti viene richiesto dallo script.

   Lo script gestirà automaticamente il resto della procedura di configurazione.
7. 👉💻 Imposta l'ID progetto necessario:

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

Parte 3: configurare l'autorizzazione

1. 👉💻 Abilita le API richieste utilizzando il seguente comando. L'operazione potrebbe richiedere alcuni minuti.

   gcloud services enable \
       cloudresourcemanager.googleapis.com \
       servicenetworking.googleapis.com \
       run.googleapis.com \
       aiplatform.googleapis.com \
       compute.googleapis.com
   

2. 👉💻 Concedi le autorizzazioni necessarie eseguendo questi comandi nel terminale:

   . ~/holiday_workshop/set_env.sh
   

Nota che viene creato un file .env. Vengono visualizzate le informazioni del progetto.

3. Potenziarsi con MCP

Il momento "USB-C" per l'AI

Immagina se ogni volta che acquisti un nuovo mouse, dovessi saldarlo alla scheda madre. Questo era lo stato degli strumenti di AI fino a poco tempo fa. Gli sviluppatori dovevano scrivere un "codice di collegamento" personalizzato per connettere gli LLM a database, filesystem o API.

Inserisci il Model Context Protocol (MCP). Pensa a MCP come alla porta USB-C per le applicazioni AI. Fornisce un modo standardizzato per connettere i modelli di AI a origini dati e strumenti.

Se crei un server MCP per i tuoi strumenti una sola volta, puoi collegarlo a Gemini CLI, a un IDE o a qualsiasi altro client conforme a MCP senza modificare una sola riga di codice.

Cosa creerai

In questo codelab, creerai un assistente per la progettazione di biglietti di auguri che:

1. Si connette al tuo ambiente locale (strumenti di Studio) utilizzando MCP.
2. Gestisce il contesto della conversazione in modo affidabile utilizzando l'Agent Development Kit (ADK).
3. Memorizza le tue preferenze (ad es. "Preferisco il codice Python") in diverse sessioni utilizzando Vertex AI Memory Bank.

Avviso: assicurati di aver autenticato Google Cloud CLI (gcloud auth login) prima di eseguire gli esempi di codice.

Creazione della logica del server

Abbiamo preparato l'ambiente, ma la logica del server è incompleta. Dobbiamo implementare i quattro strumenti specifici che il nostro Agente utilizzerà per creare il biglietto di auguri.

Parte 1: apri lo scheletro del server

Lavoreremo nella directory 01-MCP-Files-Testing/01-starter.

1. Nel terminale Cloud Shell, assicurati di trovarti nella directory corretta:

   cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
   

2. Apri il file nell'editor di Cloud Shell eseguendo:

   cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
   

Noterai che il codice boilerplate (configurazione del server MCP, gestione delle connessioni e inizializzazione del client Vertex AI) è già stato eseguito. Tuttavia, le quattro funzioni principali sono attualmente segnaposto vuoti.

Parte 2: implementa il generatore di scene delle festività

Innanzitutto, abbiamo bisogno di uno strumento che tenga conto degli interessi di un utente (ad es. "uccelli") e lo trasforma in un prompt ricco e dettagliato ottimizzato per la generazione di immagini.

Individua il commento #REPLACE_GENERATE_HOLIDAY_SCENE all'interno della funzione generate_holiday_scene.

Sostituisci l'intera riga con il seguente codice:

    prompt = (
        f"""
        Create a cozy, high-fidelity 3D render of a winter holiday scene.
        The scene should be warm and inviting with soft cinematic lighting.
        
        Seamlessly integrate the following specific theme/interest into the 
        holiday decor or landscape: {interest}.
        
        The style should be whimsical but detailed.
        Aspect Ratio: 16:9 Landscape.
        """
    )
    generate_image(prompt, "16:9", "static/generated_scene.png")
    return "Done! Saved at generated_scene.png"

Parte tre: implementa il risultato della foto finale

Infine, vogliamo assicurarci che l'illuminazione e lo stile siano fotorealistici e festivi.

Individua il commento #REPLACE_GENERATE_FINAL_PHOTO.

Sostituisci l'intera riga con il seguente codice per eseguire il trasferimento e il rendering dello stile finale:

    prompt = (
        """
        Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
        
        Lighting: Warm, glowing ambient light from a fire below (out of frame).
        Background: Softly blurred (bokeh) pine garland and twinkling lights.
        
        Foreground Composition:
        1. A wooden picture frame containing the [attached selfie image]. 
           The face in the photo must be clearly visible.
        2. A folded holiday greeting card standing upright next to the frame. 
           The front of the card displays the [attached holiday scene image] as a print.
           
        Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
        """
    )
    generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
    return "Done! Saved at generated_final_photo.png"

Configurazione dell'ambiente

Ora che il codice è a posto, dobbiamo assicurarci che le dipendenze siano installate. Utilizzeremo uv, un gestore di progetti e pacchetti Python veloce.

👉💻 Nel terminale, esegui questo comando per aggiungere FastMCP come dipendenza del progetto:

cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp

Vedrai che al file ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml è stata aggiunta una nuova dipendenza fastmcp>=2.13.3.

4. Test con Gemini CLI per il server MCP

Ora che il codice del server è completo, come lo testiamo?

In genere, il test di un server di backend richiede la creazione di un'interfaccia utente frontend o la scrittura di richieste curl complesse. Tuttavia, qui possiamo utilizzare la CLI Gemini.

Che cos'è Gemini CLI?

Gemini CLI è uno strumento a riga di comando che ti consente di chattare direttamente con un modello Gemini nel tuo terminale, ma con un superpotere: può rilevare e utilizzare automaticamente gli strumenti in esecuzione sul server MCP locale.

Questa funzionalità è incredibilmente utile per lo sviluppo perché isola la logica. Puoi verificare che il modello comprenda i tuoi strumenti e li chiami correttamente prima di preoccuparti di creare un'interfaccia web o un framework di agenti.

Connetti ed esegui

Chiediamo a Gemini CLI di gestire il nostro server utilizzando il comando mcp add.

Nel terminale, esegui:

gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py

• add holidays: abbiamo dato al nostro server un soprannome ("vacanze").
• uv run ...: abbiamo fornito il comando esplicito per avviare il server Python che abbiamo appena modificato.

Creiamo contenuti fantastici!

Ora avvia la sessione di chat:

gemini

Prova il seguente prompt per verificare se Gemini riesce a "vedere" i tuoi nuovi strumenti. Tieni presente che potresti dover consentire all'interfaccia a riga di comando di Gemini di utilizzare il nostro strumento per le festività.

• 👉 Utente:

  "I want to create a festive holiday photo. I like birds a lot."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_holiday_scene(interest='birds')*
  
  Done! Saved at generated_scene.png
  

• 👉 Utente:

  "Great! Now generate a knitting pattern for a sweater with reindeer on it."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_sweater_pattern(motif='reindeer')*
  
  Done! Saved at generated_pattern.png
  

  Poiché hai utilizzato MCP, l'AI ha capito esattamente quale funzione Python chiamare per soddisfare la tua richiesta.

Rivedi l'immagine

• Termina Gemini CLI premendo Control+C.
• Controlla l'immagine generata nella cartella: ~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.

Controlla la tua foto qui:

Conclusione e passaggi successivi

Complimenti! Hai creato un server MCP funzionante. Ora hai un insieme funzionale di "strumenti AI" che possono generare pattern, immagini composite e perfezionare le scene.

Tuttavia, hai notato qualcosa nel test riportato sopra? Tu hai dovuto guidare la procedura. Dovevi chiedere la scena, poi chiedere il pattern, poi chiedere di combinarli.

Anche se Gemini è intelligente, per un flusso di lavoro di produzione complesso, in cui dobbiamo generare un pattern prima di poterlo applicare a un maglione e gestire gli errori in caso di mancata generazione dell'immagine, vogliamo un maggiore controllo. Vogliamo un sistema dedicato che possa pianificare, criticare il proprio lavoro e gestire lo stato del nostro biglietto di auguri senza che noi lo guidiamo passo dopo passo.

Nella sezione successiva, metteremo ordine in questo caos creativo. Implementeremo l'Agent Development Kit (ADK) per creare un agente strutturato che coordini questi strumenti MCP in una pipeline di produzione perfetta.

5. Vibe-Coding di un agente ADK

Abbiamo un insieme di strumenti funzionanti (il nostro server MCP), ma al momento siamo noi a fare tutto il lavoro pesante, dicendo a Gemini esattamente quale strumento chiamare e quando.

In questa sezione creeremo un agente AI: un sistema in grado di ragionare, pianificare ed eseguire autonomamente attività in più passaggi. A questo scopo, utilizzeremo l'Agent Development Kit (ADK).

Che cos'è un agente?

Se gli strumenti MCP sono le "mani" (che svolgono il lavoro), l'agente è il "cervello". Un agente utilizza un LLM per comprendere l'intent di un utente ("Crea un biglietto di auguri"), lo suddivide in passaggi ("Prima mi serve una scena, poi un pattern…") e decide quali strumenti utilizzare per raggiungere l'obiettivo.

Che cos'è ADK?

Agent Development Kit (ADK) è un framework di Google che semplifica la creazione di questi agenti. Gestisce le complesse "tubature", come la gestione della cronologia della chat, la connessione agli strumenti e il passaggio da un modello all'altro, in modo che tu possa concentrarti sulla personalità e sulla logica della tua app.

Vibe Coding basato sul contesto

È una pratica comune utilizzare un unico prompt di grandi dimensioni per generare codice. Tuttavia, quando crei applicazioni complesse, spesso è meglio trattare l'AI come un partner che mantiene il contesto nel tempo.

Utilizzeremo le funzionalità di Memoria di Gemini CLI per preparare il terreno prima di scrivere una sola riga di codice.

1. Prepara l'ambiente

Apri il terminale e vai alla directory iniziale:

cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter

Avvia Gemini CLI:

gemini

2. Gestione del contesto e della memoria

Quando esegue il vibe coding, l'AI deve sapere chi è e cosa sa. Gemini CLI ci consente di gestire questo aspetto in modo esplicito.

• /memory show: digita questo comando per vedere cosa sa attualmente l'AI del tuo progetto e della tua sessione.
• /memory add: utilizza questo campo per inserire le conoscenze di base che l'AI deve ricordare durante la conversazione.

Iniziamo definendo la persona del nostro partner di programmazione. Esegui questo comando all'interno di Gemini CLI:

/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."

Gemini ora comprende il suo ruolo. Questo contesto influenzerà ogni risposta successiva, garantendo un codice di alta qualità conforme all'ADK.

3. Passaggio 1: codifica delle vibrazioni dell'agente di base

Invece di provare a generare l'intero sistema contemporaneamente, iniziamo con la struttura. Vogliamo stabilire la struttura dei file e la personalità di base dell'agente.

Inserisci il seguente prompt in Gemini CLI:

Let's start by building the basic agent structure. 

Please create a file structure for a `root_agent`. 
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant". 
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.

Gemini genererà la struttura dei file e il codice Python iniziale. Esaminalo per assicurarti che sia corretto, quindi applica/accetta le modifiche.

4. Passaggio 2: aggiungi il server MCP (gli strumenti)

Ora che abbiamo un agente di base, dobbiamo dargli delle "mani". Dobbiamo connettere l'agente al server MCP che abbiamo creato nel lab precedente.

Inserisci il seguente prompt in Gemini CLI:

Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.

Gemini ora eseguirà il refactoring del tuo agent.py esistente per includere le definizioni degli strumenti e la logica di connessione.

Nota:se vuoi controllare il tuo lavoro o se il codice generato non funziona come previsto, puoi confrontare i tuoi file con la soluzione di riferimento che si trova in: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution

6. Esegui l'interfaccia web dell'agente

L'ADK è dotato di un'interfaccia di test integrata chiamata adk web. In questo modo si apre una UI di chat leggera per poter parlare immediatamente con il nostro agente.

1. Se GeminiCLI è ancora aperto, premi control+C per chiuderlo. Ora nel terminale(nella cartella solution, puoi andare a starter per testare il codice eseguendo uv run adk web nella cartella starter), esegui:

   cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution
   uv run adk web --port 8000
   

2. Cloud Shell ti avviserà che un servizio è in esecuzione sulla porta 8000. Fai clic su "Anteprima web" -> "Anteprima sulla porta 8000".

Testare l'agente

Ora dovresti vedere un'interfaccia di chat. Vediamo se il nostro agente segue le nuove istruzioni e accede correttamente agli strumenti MCP.

Prova questi prompt:

• "Ciao! Chi sei?"
  • (Aspettati una risposta festosa ed entusiasta).
• "Ho bisogno di uno sfondo per il mio biglietto di auguri. Crea un villaggio innevato".
  • (L'agente deve chiamare generate_holiday_scene. Nota come applichi automaticamente lo stile "carino/cartone animato" definito nelle istruzioni di sistema.
• "Genera un modello per un maglione con piccole fette di pizza."
  • (L'agente deve chiamare generate_sweater_pattern).

Puoi visualizzare l'immagine generata qui:

Premi Control+C per uscire al termine del test.

Conclusione e passaggi successivi

Ora hai codificato correttamente un agente Google ADK utilizzando un approccio sensibile al contesto.

• Abbiamo stabilito il contesto:abbiamo utilizzato /memory add per definire una persona esperta.
• Abbiamo creato Iterativamente:abbiamo creato prima la struttura e poi aggiunto le connessioni agli strumenti.

L'anteprima web dell'ADK integrato è ideale per i test, ma per il nostro prodotto finale vogliamo un'esperienza personalizzata e brandizzata. Nella sezione successiva, integreremo questo agente in un frontend web personalizzato.

Se hai riscontrato Unexpected response from metadata server: service account info is missing 'email' field in qualsiasi momento del workshop, significa che devi aggiornare Cloud Shell ed eseguire di nuovo gcloud config set project $(cat ~/project_id.txt) --quiet per impostare project id prima di continuare.

7. Connessione di ADK con l'interfaccia utente

Ora che abbiamo una definizione dell'agente, dobbiamo eseguirla. È qui che entrano in gioco Runner e Session Service.

Implementazione

1. 👉 Digita quanto segue nel comando:

   cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py
   

   Si apre ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py nell'editor.
2. Sostituisci # TODO: Create Session Service con quanto segue:

   from google.adk.sessions import InMemorySessionService
   from google.adk.memory import InMemoryMemoryService
   session_service = InMemorySessionService()
   memory_service = InMemoryMemoryService()
   

   Il servizio di sessione è la "memoria di lavoro " dell'agente.

   • Ruolo: memorizza la cronologia immediata e disordinata della conversazione corrente (ad es. "Che cosa ho appena chiesto?"
   • Due gusti:
   • InMemorySessionService: veloce, facile, ma amnesico. Se riavvii il server, l'agente dimentica tutto. Ideale per i test.
   • VertexAiSessionService: solido, basato su database. Salva lo stato su Google Cloud, in modo che la conversazione possa continuare settimane dopo o dopo i riavvii del server.
3. Sostituisci # TODO: Initialize Runner con quanto segue:

   runner = Runner(
       app_name="agents",
       agent=christmas_agent,
       session_service=session_service,
       memory_service=memory_service,
   )
   

Il Runner: se l'agente è il "cervello", il Runner è il "cuore". Mantiene il sangue in circolo. Il Runner è responsabile di:

• Associazione dell'agente a un utente e a una sessione.
• Esecuzione del loop di eventi.
• Gestione delle transizioni di stato.

4. Rivedi la riga 158 a questo ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(non è necessaria alcuna azione): se ti chiedi come l'applicazione ottiene la risposta finale. Di seguito è riportato il ciclo di eventi basato su runner:

   async for event in runner.run_async(
       user_id=user_id,
       session_id=session_id,
       new_message=content
   )
   

Gli agenti ADK non si limitano a "rispondere". Pensano in loop. Quando chiami runner.run_async():

1. User Input entra nel ciclo.
2. Pianificazione: l'agente prende in considerazione i suoi strumenti e i suoi obiettivi.
3. Agisci: se appropriato, chiama uno strumento (ad es. list_files).
4. Osserva: legge l'output dello strumento.
5. Rifletti: decide se ha bisogno di più informazioni o se può rispondere.
6. Loop: ripete i passaggi da 2 a 5 finché non è soddisfatto.
7. Rispondi: fornisce la risposta finale all'utente.

Approfondimento: architettura e deployment

Utilizziamo FastAPI per pubblicare questo agente.

• Perché FastAPI?: Gli agenti sono spesso vincolati all'I/O (in attesa di LLM). La natura asincrona di FastAPI gestisce perfettamente questa situazione.
• Condizione stateless: nota che il nostro endpoint API è stateless. Non salviamo le variabili nell'ambito globale. Ci basiamo su session_id e SessionService per ricostruire lo stato di ogni singola richiesta. Ciò significa che puoi eseguire il deployment in Cloud Run (serverless) e scalare a zero.

8. Prova l'applicazione con la magia dell'agente

1. 👉💻 Digita quanto segue nel comando:

   cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter
   ./start_app.sh
   

   Si apre ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py nell'editor.
2. Vedrai il risultato come di seguito:👉👉 Assicurati di fare clic su http://localhost:5173/ o di aprire una nuova finestra e digitare http://localhost:5173/.

   Tieni presente che NON è il link del server di backend: Uvicorn running on http://0.0.0.0:8000

3. Poi vedrai il sito web con l'interfaccia di chat:
4. Esegui il test caricando un'immagine(puoi caricare una tua foto o quella del tuo animale domestico)
5. 👉 Poi chiedi

   Can you generate a picture my cat wearing snowflake pattern sweater?
   

   Qui vedrai l'immagine generata:
6. 👉💻 Al termine del test, premi control+C nel terminale per terminare la procedura.

Se non vedi le cose funzionare come previsto, puoi andare su ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution, eseguire ./start_app.sh e poi ripetere i passaggi precedenti.

9. Vertex AI Memory Bank

Memoria a breve termine e memoria a lungo termine

• Contesto a breve termine: "Che cosa ho appena detto?" (Cronologia delle sessioni). Queste informazioni vengono perse quando la finestra della chat si chiude.
• Memoria a lungo termine: "Qual è il mio linguaggio di programmazione preferito?" (Preferenze utente). Questo dovrebbe persistere per sempre.

Vertex AI Memory Bank fornisce questo spazio di archiviazione a lungo termine. Consente all'agente di memorizzare e recuperare informazioni personalizzate sull'utente.

Sessioni e Memory Bank

• Sessioni (VertexAiSessionService): questo è il log. Memorizza la sequenza cronologica non elaborata di ogni messaggio, chiamata allo strumento ed evento (AppendEvent, ListEvents). Fornisce la verità di base su cosa è successo.
• Banca della memoria (VertexAiMemoryBankService): si tratta della conoscenza. Memorizza fatti sintetizzati a lungo termine (GenerateMemories, RetrieveMemories). È limitato a un user_id specifico, garantendo privacy e isolamento.

1. 👉💻 Digita quanto segue nel comando:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py
   

   Si apre ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py nell'editor.
2. Trova # TODO: Create Vertex AI Session Service & Memory Bank Service, sostituisci l'intera riga con la seguente:

       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
       )
   
   

3. 👉💻 Digita quanto segue nel comando:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py
   

   Si apre ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py nell'editor.
4. Sostituisci # TODO: Set Up Configuration con quanto segue:

   # Basic configuration types
   MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig
   SimilaritySearchConfig = (
       types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig
   )
   GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig
   
   # Advanced configuration types
   CustomizationConfig = types.MemoryBankCustomizationConfig
   MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic
   CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic
   GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample
   ConversationSource = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource
   )
   ConversationSourceEvent = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent
   )
   ExampleGeneratedMemory = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory
   )
   

Funzionalità principali

Vertex AI Memory Bank non è solo un database, ma un servizio cognitivo attivo.

• Estrazione della memoria: il sistema utilizza un LLM per leggere la conversazione ed estrarre informazioni significative in base agli schemi CustomMemoryTopic che abbiamo definito (ad es. "Sweater Preferences" (Preferenze per i maglioni). Ignora le chiacchiere e salva il segnale.
• Consolidamento della memoria: unisce automaticamente i nuovi fatti a quelli vecchi. Se un utente dice "Mi piace il rosso" e poi "In realtà preferisco il blu", Memory Bank modifica il record della memoria anziché creare duplicati in conflitto.
• Generazione asincrona: i ricordi vengono generati in background. L'agente non si blocca mentre la Banca della memoria "riflette" sulla conversazione.

5. 👉 Nello stesso file: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Cerca # TODO: Set up topic, sostituisci l'intera riga con quanto segue:

       custom_topics = [
           # Topic 1: Sweater Preference
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="sweater_preference",
                   description="""Extract the user's preferences for sweater styles, patterns, and designs. Include:
                   - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.)
                   - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted)
                   - Color preferences (red, green, navy, pastel, etc.)
                   - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft)
                   - Themes (retro, modern, ugly christmas sweater, elegant)
   
                   Example: "User wants a retro style sweater with a pixelated reindeer pattern."
                   Example: "User prefers dark blue colors and hates itchy wool."
                   """,
               )
           ),
           # Topic 2: Personal Context
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="personal_context",
                   description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include:
                   - Hobbies and activities (skiing, reading, gaming, cooking, etc.)
                   - Pets (type, breed, name, color)
                   - Job or profession if relevant to their style
                   - General interests (sci-fi, nature, vintage, tech)
                   - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach)
   
                   Example: "User has a golden retriever named Max."
                   Example: "User loves skiing and wants a snowy mountain background."
                   Example: "User is a software engineer who likes cyberpunk aesthetics."
                   """,
               )
           )
       ]
   

6. 👉 Nello stesso file: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Cerca # TODO: Create Agent Engine , sostituisci l'intera riga con quanto segue:

       agent_engine = client.agent_engines.create(
           config={
               "display_name": AGENT_DISPLAY_NAME,
               "context_spec": {
                   "memory_bank_config": {
                       "generation_config": {
                           "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
                       },
                       "customization_configs": [customization_config]
                   }
               },
           }
       )
   

Motore agente

Agent Engine è l'hardware del cervello nel cloud. Gestisce:

• Database vettoriale: per archiviare i ricordi.
• Indicizzazione: per rendere le informazioni salvate ricercabili.
• API: per consentire all'agente di eseguire query. Quando esegui deploy_agent.py, esegui il provisioning di questo hardware.

Perché non utilizzare semplicemente il prompt?

Potresti chiederti: "Perché non incolliamo semplicemente la cronologia dell'utente nel prompt?"

• Limiti di dimensione: le finestre contestuali sono grandi, ma non infinite. Non puoi inserire 5 anni di cronologia.
• Costo: l'elaborazione di 1 milione di token per ogni "Hello" è proibitiva.
• Focus: Memory Bank funge da motore di ricerca per il tuo agente. Recupera solo i fatti pertinenti.

7. 👉💻 Digita quanto segue nel comando:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py
   

   Si apre ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py nell'editor.
8. Nel file ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py, sostituisci # TODO: Add PreloadMemoryTool con quanto segue:

   if USE_MEMORY_BANK:
       agent_tools.append(PreloadMemoryTool())
   

PreloadMemoryTool e add_session_to_memory

In agent.py, vedrai due componenti chiave:

• PreloadMemoryTool: si tratta di uno strumento che consente all'agente di "cercare su Google". Se l'utente chiede qualcosa di vago come "Preparami il mio solito caffè", l'agente può utilizzare questo strumento per interrogare la Banca della memoria in merito alle "preferenze per il caffè" prima di rispondere.
• add_session_to_memory: Questo è un callback in background.
  • Perché Async? Il salvataggio della memoria richiede tempo (riepilogo della chat, estrazione dei fatti). Non vogliamo che l'utente aspetti. Lo eseguiamo in background (add_session_to_memory) utilizzando after_agent_callback.

10. Memory Bank In Action

1. 👉💻 Digita quanto segue nel comando:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./use_memory_bank.sh
   

   Vedrai il risultato come di seguito:

   Questo script use_memory_bank.sh utilizza prima il file 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py per collegare Agent Engine al tuo agente, in modo che possa utilizzare Vertex AI Memory Bank. e poi aggiornerà il file .env in modo che l'ID motore dell'agente venga salvato come environmental variable.

   Controlla il file ~/holiday_workshop/.env, vedrai (nessuna azione necessaria)

   USE_MEMORY_BANK=TRUE
   AGENT_ENGINE_ID={agent_engine_id}
   

2. 👉💻 Testa la memoria con l'interfaccia utente dell'applicazione. Digita quanto segue nel comando:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./start_app.sh
   

   Assicurati di fare clic su http://localhost:5173/ o di aprire una nuova finestra e digitare http://localhost:5173/. Tieni presente che Uvicorn running on http://0.0.0.0:8000 è solo il server di backend, non il link effettivo su cui vogliamo fare clic. Ora l'interfaccia di chat nel sito web è diventata il tuo agente personalizzato.
3. 👉 Prova la memoria. Se digiti nell'interfaccia utente:

   I want a sweater that matches my dog. He's a golden retriever.
   

   I'm a programmer, so I want something geeky. Maybe a matrix style?
   

   I like snowflake sweater pattern
   

L'agente lo identificherà come preferenza e lo memorizzerà nel Memory Bank.

La settimana successiva(o ogni volta che riavvii l'applicazione entro le Control+C e le ./start_app.sh), se chiedi:

what is my preference on sweater pattern?

L'agente eseguirà una query sul Memory Bank, visualizzerà le tue preferenze e genererà il modello del maglione senza che tu glielo chieda.

Personalizzazione: è fondamentale per creare agenti utili. Ricordando le preferenze dell'utente (motivo del maglione, contesto personale), l'agente diventa più efficiente e utile nel tempo.

4. Verifica in Vertex AI Agent Engine andando alla console Google Cloud Agent Engine
   • Assicurati di selezionare il progetto dal selettore di progetti in alto a sinistra:
   • Verifica il motore dell'agente che hai appena eseguito il deployment dal comando precedente use_memory_bank.shFai clic sul motore dell'agente che hai appena creato.
5. Fai clic sulla scheda Memories in questo agente di cui è stato eseguito il deployment per visualizzare tutte le memorie.

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

11. Conclusione

Riepilogo

Hai progettato e creato correttamente un sistema agentico completo.

• Connettività: hai utilizzato MCP per standardizzare il modo in cui l'agente accede agli strumenti locali.
• Orchestrazione: hai utilizzato l'ADK per gestire il complesso ciclo di ragionamento richiesto per le attività in più passaggi.
• Personalizzazione: hai utilizzato Memory Bank per creare un livello di apprendimento persistente che memorizza il contesto dell'utente.

Passaggi successivi

• Crea il tuo server MCP: crea un server per il tuo database o la tua API interna.
• Esplora i pattern dell'ADK: scopri di più su "Cicli di ragionamento" e "Orchestrazione" nella documentazione dell'ADK.
• Deployment: trasferisci l'agente da uno script locale a un servizio di produzione su Cloud Run.

Continua a creare. La combinazione di MCP per la connettività e Memory Bank per la personalizzazione crea le basi per la prossima generazione di applicazioni intelligenti.