Pattern di ADK Agentic con memoria e MCP

1. Cosa imparerai a fare

Ti diamo il benvenuto nella masterclass ADK: il tuo viaggio nei sistemi multi-agente

Stai per entrare nell'entusiasmante mondo degli agenti AI. Dimentica le semplici chatbot che si limitano a rispondere alle domande. Stiamo approfondendo l'Agent Development Kit (ADK) per creare sistemi autonomi e sofisticati in grado di ragionare, pianificare e utilizzare strumenti per svolgere attività complesse.

L'intero codelab sarà un percorso pratico, questo repository GitHub che contiene tutto il codice e gli esempi per le nostre sessioni. repository GitHub

Al termine di questo tutorial, sarai in grado di:

• Crea il tuo primo agente AI: parti da zero e crea un agente completamente funzionale in grado di comprendere le esigenze di un utente, utilizzare strumenti come la Ricerca Google e generare risposte dettagliate e utili.
• Crea sistemi multi-agente: scopri il pattern "Agente come strumento", un concetto rivoluzionario in cui gli agenti delegano le attività ad altri agenti specializzati, creando un team di esperti di AI che lavorano insieme.
• Orchestrare workflow complessi: vai oltre la semplice delega e padroneggia pattern avanzati come router, catene sequenziali, cicli ed esecuzione parallela per creare applicazioni robuste, efficienti e intelligenti in grado di gestire quasi tutte le richieste.
• Dotare gli agenti di memoria: scopri il ruolo fondamentale della memoria conversazionale, che consente agli agenti di gestire domande aggiuntive, imparare dai feedback e gestire attività complesse senza problemi.
• Connetti con MCP: connettiti con MCP Toolbox.

Iniziamo. 🚀

2. Configurazione: ottieni la chiave API

Configurazione della chiave API di Google AI Studio

Questo codelab viene eseguito interamente su una chiave API Google AI Studio senza costi. Non sono richiesti progetti Google Cloud, account di fatturazione o crediti. Ogni sessione, incluse Memory (Sessione 6) e MCP (Sessione 7), viene eseguita localmente rispetto alla chiave. Ogni studente utilizza la propria chiave, quindi la quota API è personale e non condivisa.

Che cosa ti serve:

• Python 3.9 o versioni successive (python3 --version per verificare)
• Un account Google (per creare la chiave AI Studio)
• Un terminale: la tua macchina locale o Cloud Shell
• ~10 minuti

Per alimentare i nostri agenti AI, abbiamo bisogno di una chiave API Gemini da Google AI Studio. Questo è il modo più rapido per iniziare.

Passaggio 1: ottieni la chiave API Gemini da AI Studio (1 minuto)

1. Apri https://aistudio.google.com/app/apikey in una nuova scheda del browser.
2. Esegui l'accesso con il tuo Account Google.
3. Fai clic su "Crea chiave API" (in alto a destra).
4. Si apre una finestra di dialogo con un menu a discesa dei progetti:

• Se hai già creato un progetto Google: selezionalo e fai clic su "Crea chiave API nel progetto esistente".
• Se NON è presente nell'elenco: fai clic su "Crea progetto".

5. Copia la chiave API visualizzata. Inizia con AIza... e contiene circa 40 caratteri.

✏️ Incollalo in un luogo sicuro: ti servirà nel passaggio 4 di seguito.

Tratta la chiave API come una password. Non incollarlo in chat pubbliche, screenshot o repository GitHub pubblici.

Passaggio 2: clona il repository (1 minuto)

👉💻 Apri il terminale (o Cloud Shell) e clona il repository del tutorial:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

Passaggio 3: crea l'ambiente virtuale e installa le dipendenze

👉💻 Crea e attiva un ambiente virtuale denominato .adk_env, quindi installa le dipendenze:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Dovresti visualizzare (.adk_env) all'inizio del prompt del terminale.

Passaggio 4: 🔥 IMPORTANTE: aggiungi la tua chiave API

⚠️ Non saltare questo passaggio. Crea un file .env nella root della cartella adk_tutorial. Questo file alimenta ogni sessione di questo codelab: le sessioni web ADK (1-5) e le sessioni da riga di comando Memory e MCP (6-7) lo leggono automaticamente.

👉💻 Crea il file .env con la tua chiave (sostituisci your_actual_api_key_here con la chiave del passaggio 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

Il tuo ~/adk_tutorial/.env ora dovrebbe contenere:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 CRITICO: sostituisci your_actual_api_key_here con la tua chiave API effettiva del passaggio 1 (inizia con AIza...).

⚠️ Assicurati che GOOGLE_GENAI_USE_VERTEXAI sia impostato su FALSE. In questo modo, l'ADK esegue l'autenticazione con la chiave API di Google AI Studio anziché con Vertex AI.

✅ Checkpoint:hai un file .env in ~/adk_tutorial/.env contenente la chiave AIza... e il prompt del terminale mostra (.adk_env). Ora puoi creare gli agenti.

3. Sessione 1: il tuo primo agente in ADK Web

Apri ADK Web eseguendo:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

Dopo aver eseguito i comandi, nel terminale dovresti visualizzare un output che indica che il server web ADK è stato avviato, simile a questo:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 Successivamente, apri il browser all'indirizzo http://localhost:8000 per accedere alla UI di sviluppo dell'ADK.

Esegui in Cloud Shell anziché localmente? Fai clic sull'icona Anteprima web nella barra degli strumenti di Cloud Shell (di solito in alto a destra), seleziona Cambia porta, imposta la porta su 8000 e fai clic su "Cambia e visualizza l'anteprima". Cloud Shell aprirà l'interfaccia utente di ADK Dev in una nuova scheda del browser.

👉 Il tuo rituale di evocazione è completo e l'agente è ora in esecuzione. La UI di sviluppo dell'ADK nel browser è la tua connessione diretta a Familiar.

Scegli il primo agente. Nel menu a discesa in alto nell'interfaccia utente, scegli a_single_agent.

Puoi selezionare a_single_agent qui:

Puoi visualizzare la traccia qui:

👉 Prompt di test:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. Sessione 2: Agente del workflow: agente sequenziale, agente parallelo, agente di loop

Apri la GUI web dell'ADK seguendo i passaggi della sessione 1.

Parallel Agent

Scegli l'agente del flusso di lavoro parallelo. Nel menu a discesa nella parte superiore dell'interfaccia utente, scegli b2_parallel_agent.

👉 Prompt di test:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

Puoi selezionare b2_parallel_agent qui:

Puoi visualizzare la traccia qui:

Agente sequenziale

Scegli l'agente del flusso di lavoro sequenziale. Nel menu a discesa nella parte superiore della UI, scegli b1_sequential_agent.

👉 Prompt di test:

Find a good sushi near Standford and tell me how to get there.

Puoi selezionare b1_sequential_agent qui:

Puoi visualizzare la traccia qui:

Agente Loop

Scegli l'agente del flusso di lavoro Loop. Nel menu a discesa nella parte superiore della UI, scegli b3_loop_agent.

👉 Prompt di test:

Plan a trip from Sunnyvale to San Francisco today.

Puoi selezionare b3_loop_agent qui:

Puoi visualizzare la traccia qui:

5. Sessione 3: Agente personalizzato

Apri la GUI web dell'ADK seguendo i passaggi della sessione 1.

Una volta aperta l'interfaccia utente web dell'ADK, scegli c_custom_agent dal menu a discesa.

👉 Prompt di test:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

Puoi selezionare c_custom_agent qui:

Puoi visualizzare la traccia qui:

6. Sessione 4: Orchestrator Pattern - Routing Agent

Apri la GUI web dell'ADK seguendo i passaggi della sessione 1.

Una volta aperta l'interfaccia utente web dell'ADK, scegli d_routing_agent dal menu a discesa.

👉 Prompt di test:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Puoi selezionare d_routing_agent qui:

Puoi visualizzare la traccia qui:

7. Sessione 5: Agente come strumento

Apri la GUI web dell'ADK seguendo i passaggi della sessione 1.

Una volta aperta l'interfaccia utente web dell'ADK, scegli e_agent_as_tool dal menu a discesa.

👉 Prompt di test:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Puoi selezionare e_agent_as_tool qui:

Puoi visualizzare la traccia qui:

8. Sessione 6: Agente con memoria a lungo termine

Viene eseguito completamente in locale. Questa sessione memorizza la memoria della conversazione in un database SQLite locale (in ~/.adk/), quindi le tue preferenze vengono mantenute anche dopo i riavvii senza che siano necessari Google Cloud, fatturazione o crediti. L'agente legge la chiave di AI Studio dal ~/adk_tutorial/.env che hai creato nella configurazione.

👉💻 Metti alla prova la tua memoria a lungo termine andando nella cartella e utilizzando lo strumento di esecuzione per potenziare l'agente:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Prompt di test:

I like Art and Italian food.

Poi termina la sessione premendo Ctrl+C. Riavvia la sessione:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Prompt di test:

Plan a trip to San Francisco based on my preference.

✅ L'agente deve ricordare "Arte e cibo italiano" dall'esecuzione precedente. Questa è la memoria a lungo termine che funziona tra le sessioni.

9. Sessione 7: potenzia il tuo agente con MCP

Viene eseguito completamente in locale. Questa sessione avvia un server MCP Toolbox locale che legge un database SQLite locale (destinations.db). Non sono richiesti Google Cloud, fatturazione o crediti. L'unico download esterno è il file binario open source di MCP Toolbox.

Passaggio 1: prepara il database locale

👉💻 Dalla radice del repository, crea il database di esempio:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

Viene creato destinations.db in ~/adk_tutorial/.

⚠️ Il database di esempio contiene solo quattro città: Parigi, Roma, New York e Tokyo (tipi di attrazioni: punto di riferimento, museo, parco). I prompt che fanno riferimento ad altre città (ad es. San Francisco o Sunnyvale) restituiranno correttamente nessun risultato, perché queste righe non esistono. Utilizza le quattro città sopra indicate per testare questa sessione.

Passaggio 2: installa ed esegui il server MCP Toolbox

👉💻 Scarica il file binario di MCP Toolbox per il tuo sistema operativo:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

al termine del download, quindi esegui

chmod +x toolbox

Non sai quale Mac hai? Run uname -m — arm64 = Apple Silicon, x86_64 = Intel. Su Windows, scarica .../windows/amd64/toolbox.exe ed eseguilo da PowerShell.

Passaggio 3

In un terminale esegui questo comando (lascialo in esecuzione. L'agente si connette a questo comando all'indirizzo http://127.0.0.1:7001):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

In un altro terminale, esegui questo comando

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Test Prompts (utilizza le città presenti nel database di esempio: Parigi, Roma, New York o Tokyo):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

Risoluzione dei problemi della sessione 7

• "Connection refused" (Connessione rifiutata) / l'agente non trova strumenti: il server Toolbox nel primo terminale non è in esecuzione. Riavvialo e verifica che sia in ascolto sulla porta 7001.
• Ogni query restituisce risultati vuoti:verifica di aver eseguito lo step 1 in modo che esista ~/adk_tutorial/destinations.db e che il prompt utilizzi una delle quattro città (Parigi, Roma, New York, Tokyo).
• toolbox: cannot execute binary file su macOS:hai scaricato la build Linux. Esegui di nuovo il passaggio 2 con OS=darwin/arm64 (Apple Silicon) o OS=darwin/amd64 (Intel).