ADK Crash Course - From Beginner To Expert

1. Cosa imparerai a fare

Ti diamo il benvenuto in ADK Master Class: il tuo viaggio nei sistemi multi-agente

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

Questo codelab principale sarà un percorso pratico e ti guiderò attraverso due notebook Colab principali che contengono tutto il codice e gli esempi per le nostre sessioni. Colab 1: Tools & Memory, Colab 2: MultiAgents

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.
• Padroneggia gli strumenti personalizzati: libera la vera potenza degli agenti collegandoli alle tue funzioni e API personalizzate. Insegnerai al tuo agente a recuperare dati in tempo reale, come le previsioni meteo.
• Costruisci 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 flussi di lavoro 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.
• Dai una memoria ai tuoi agenti: scopri il ruolo fondamentale della memoria conversazionale, che consente agli agenti di gestire le domande di approfondimento, imparare dai feedback e gestire le attività in più passaggi senza problemi.

Iniziamo. 🚀

2. Configura Google Cloud e la chiave API Gemini

Configurazione del progetto GCP e della chiave API Gemini

Per alimentare i nostri agenti AI, abbiamo bisogno di due cose: un progetto Google Cloud per fornire le basi e una chiave API Gemini per accedere ai potenti modelli di Google.

Passaggio 1: attiva 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.

Passaggio 2: crea un nuovo progetto GCP

• Vai alla console Google Cloud e crea un nuovo progetto.

• Vai alla console Google Cloud e crea un nuovo progetto.
• Apri il riquadro a sinistra, fai clic su Billing e verifica se l'account di fatturazione è collegato a questo account GCP.

Se visualizzi questa pagina, controlla manage billing account, scegli la prova di Google Cloud e collegala.

Passaggio 3: genera la chiave API Gemini

Prima di poter proteggere la chiave, devi averne una.

• Vai a Google AI Studio : https://aistudio.google.com/
• Accedi con il tuo account Gmail.
• Fai clic sul pulsante "Ottieni chiave API", di solito nel riquadro di navigazione a sinistra o nell'angolo in alto a destra.
• Nella finestra di dialogo "Chiavi API", fai clic su "Crea chiave API nel nuovo progetto".
• Scegli il nuovo progetto che hai creato con l'account di fatturazione configurato.
• Verrà generata una nuova chiave API. Copia immediatamente questa chiave e conservala temporaneamente in un luogo sicuro (ad esempio un software di gestione delle password o una nota protetta). Questo è il valore che utilizzerai nei passaggi successivi.

3. Sessione 1: il tuo primo agente con Runner

Iniziamo dalle basi. Qui creiamo il nostro primo agente semplice, day_trip_agent. Lo scopo di questo agente è generare un itinerario di viaggio di un giorno intero in base alla richiesta di un utente, tenendo conto anche del budget. Questo esempio introduce i tre componenti principali di qualsiasi interazione dell'agente nell'ADK:

• Agente: il cervello principale dell'operazione. È definito dalle sue istruzioni (la sua personalità e la sua missione), dal modello di AI che utilizza (come Gemini) e dagli strumenti a cui può accedere.
• Sessione: la memoria della conversazione. Memorizza la cronologia delle interazioni (messaggi dell'utente e risposte dell'agente), consentendo un dialogo continuo.
• Runner: il motore che esegue l'attività. Prende l'agente e la sessione, elabora la nuova query dell'utente e coordina i passaggi per generare una risposta.

➡️ Dove trovarlo nel notebook

👉 Corrisponde alle celle della parte 1: il tuo primo agente, il genio delle gite di un giorno 🧞.🌟

• Definizione dell'agente: cerca la funzione create_day_trip_agent(). È qui che viene definito l'agente. Nota la stringa di istruzioni dettagliate: questo è il prompt che indica all'agente come comportarsi. Inoltre, le forniamo il suo primo strumento: la Ricerca Google.
• Funzione helper: la funzione helper run_agent_query() è definita qui. Utilizzeremo questa utilità in tutto il notebook per semplificare l'esecuzione delle query.
• Test Run: la funzione run_day_trip_genie() simula un utente che chiede una gita di un giorno "economica" e "rilassante". L'agente utilizza le sue istruzioni e lo strumento di ricerca Google per trovare luoghi adatti e creare un itinerario formattato in Markdown.

➡️ Azione: esamina il prompt delle istruzioni per day_trip_agent. Scopri in che modo la richiesta di un viaggio "economico" nella query di test si ricollega direttamente alla linea guida dell'agente di essere "attento al budget".

4. Sessione 2: Strumenti personalizzati 🛠️

Sebbene la Ricerca Google sia potente, il vero potenziale degli agenti AI si sblocca quando li connetti alle tue origini dati, API o logica personalizzata uniche. In questa sezione creeremo uno strumento personalizzato da una semplice funzione Python.

La parte più importante di uno strumento di funzione è la relativa docstring. L'ADK analizza automaticamente la docstring per capire cosa fa lo strumento, quali parametri accetta (Args) e cosa restituisce (Returns). Il modello linguistico di grandi dimensioni (LLM) legge questa descrizione per decidere quando e come utilizzare lo strumento.

➡️ Dove trovarlo nel notebook

👉 Corrisponde alle celle in 2.1 The Simple FunctionTool: Calling a Real-Time Weather API. 🌟

• Definizione dello strumento: la funzione get_live_weather_forecast(location: str) è il fulcro del nostro strumento personalizzato. Prende il nome di una città, chiama l'API pubblica del National Weather Service e restituisce un dizionario con la temperatura e le previsioni.
• Definizione dell'agente: l'agente weather_agent viene creato e dotato del nostro nuovo strumento passando tools=[get_live_weather_forecast] durante l'inizializzazione. Le istruzioni dell'agente gli dicono esplicitamente di utilizzare questo strumento prima di suggerire attività all'aperto.
• Test Run: la query "Voglio fare un'escursione vicino al Lago Tahoe, che tempo fa?" attiva direttamente l'agente per utilizzare lo strumento get_live_weather_forecast perché le sue istruzioni lo richiedono.

➡️ Azione: leggi la docstring della funzione get_live_weather_forecast e le istruzioni per weather_agent. Tieni presente la relazione diretta tra loro.

5. Sessione 3: Agente come strumento 🧑‍🍳

Perché creare un singolo agente monolitico quando puoi creare un team di specialisti? Il pattern Agent-as-a-Tool è un modo efficace per creare sistemi complessi in cui un agente principale, spesso chiamato Orchestratore o Router, delega le attività ad altri agenti più mirati.

Questo pattern ti consente di creare agenti modulari e riutilizzabili. Ad esempio, puoi avere un agente esperto in query di database, un altro esperto in scrittura creativa e un terzo che funge da concierge. Il compito dell'orchestratore è comprendere la richiesta dell'utente e indirizzarla allo specialista corretto.

➡️ Dove trovarlo nel notebook

👉 Corrisponde alle celle della sezione 2.2 L'agente come strumento: consulenza con uno specialista 🧑‍🍳.🌟

Questo esempio crea un sistema di agenti sofisticato e multilivello:

• Gli specialisti:
  • food_critic_agent: un agente altamente specializzato che fornisce solo suggerimenti sui ristoranti.
  • db_agent: un agente simulato che finge di eseguire query su un database per ottenere informazioni sugli hotel.
  • concierge_agent: un agente di livello intermedio che funge da concierge educato. Fondamentalmente, ha food_critic_agent come strumento proprio.
• L'agente di orchestrazione (trip_data_concierge_agent): è l'agente di primo livello con cui interagisce l'utente. Le sue istruzioni lo rendono un "pianificatore di viaggi principale" e gli vengono forniti due strumenti che chiamano gli altri agenti:
  • call_db_agent: una funzione che chiama db_agent.
  • call_concierge_agent: una funzione che chiama concierge_agent.
• Il flusso: l'esecuzione del test in run_trip_data_concierge() mostra l'intera catena di delega.
  • Un utente chiede all'orchestratore un hotel e un ristorante nelle vicinanze.
  • Le istruzioni dell'orchestratore indicano di utilizzare prima lo strumento call_db_agent per ottenere i dati degli hotel.
  • L'orchestratore utilizza quindi lo strumento call_concierge_agent per ottenere un suggerimento.
  • concierge_agent, dopo aver ricevuto la richiesta, utilizza il proprio strumento, food_critic_agent, per trovare un'idea per un ristorante.

La risposta del critico gastronomico viene restituita al concierge, che la formatta in modo educato e la invia all'orchestratore, che infine la presenta all'utente.

➡️ Azione: traccia il flusso di esecuzione nell'esecuzione di test in run_trip_data_concierge(). Osserva come le stampe TOOL CALLED mostrano la catena di delega dall'orchestratore agli specialisti. Si tratta di una catena di comando sequenziale.

6. Sessione 4: Memoria dell'agente 🧠

Un agente veramente intelligente deve fare di più che rispondere a query una tantum. Deve ricordare la conversazione, comprendere il contesto e adattarsi al feedback. Ciò si ottiene tramite una corretta gestione delle sessioni. Un "agente loop" è un agente coinvolto in un ciclo conversazionale continuo, alimentato dalla sua memoria.

Quando utilizzi lo stesso oggetto sessione per più query sequenziali, l'agente può "vedere" l'intera cronologia della conversazione. Ciò consente di gestire domande di approfondimento, correggersi in base al feedback e pianificare attività in più passaggi.

➡️ Dove trovarlo nel notebook

👉 Corrisponde alle celle della parte 3: Agente con una memoria: lo strumento di pianificazione adattivo 🗺️. 🌟

• Definizione dell'agente: la funzione create_multi_day_trip_agent() definisce un agente progettato per pianificare un viaggio in modo progressivo. Le sue istruzioni sottolineano l'importanza di ricordare il contesto, gestire i feedback e pianificare un giorno alla volta.

Scenario 3a: Agente CON memoria (✅)

Questo test viene eseguito nella funzione run_adaptive_memory_demonstration().

• Viene creato e riutilizzato un singolo trip_session per tre turni consecutivi.
• Turno 1: l'utente avvia un piano di viaggio di 2 giorni.
• Turno 2: l'utente fornisce un feedback ("I castelli non mi fanno impazzire"). Poiché l'agente ha in memoria la svolta 1, capisce quale parte del piano deve essere modificata e fornisce un'alternativa.
• Turno 3: l'utente conferma la modifica e chiede il passaggio successivo. L'agente ricorda tutto e procede a pianificare il giorno 2.

Scenario 3b: Agente SENZA memoria (❌)

Questo test viene eseguito nella funzione run_memory_failure_demonstration().

Ciò dimostra l'importanza fondamentale della gestione delle sessioni commettendo un errore di proposito. Viene creata una nuova sessione per ogni turno.

• Turno 1: l'utente inizia il viaggio in session_one. L'agente risponde correttamente.
• Turno 2: l'utente chiede di pianificare il giorno 2, ma la query viene inviata in una nuova sessione_due. Poiché questa nuova sessione non ha una cronologia, l'agente è confuso. Ha l'amnesia! Non sa quale viaggio viene pianificato.

Azione: confronta le risposte dell'agente in run_adaptive_memory_demonstration() e run_memory_failure_demonstration(). Questo è il concetto più importante del notebook: una conversazione continua richiede una sessione continua.

7. Sessione 5: The Router Agent 🚏

Un singolo agente può fare solo un numero limitato di cose. Per gestire le richieste degli utenti più complesse, abbiamo bisogno di un team di agenti specializzati. Ma come facciamo a sapere quale agente utilizzare per una determinata query? È qui che entra in gioco l'agente router.

L'agente router funge da agente "master" o dispatcher. Il suo unico scopo è analizzare una query utente in entrata e decidere quale agente specializzato (o flusso di lavoro di agenti) è il più adatto al lavoro. Non risponde alla query stessa, ma la indirizza semplicemente all'agente downstream corretto.

Ad esempio, una query su "il miglior sushi" deve essere inviata a un foodie_agent, mentre una domanda su "concerti questo fine settimana" deve essere gestita da un weekend_guide_agent.

➡️ Dove trovarlo nel notebook:

👉 Questo concetto è centrale per l'intero notebook, ma viene introdotto per la prima volta nella Parte 1: Multi-Agent Mayhem - Sequential Workflows 🧠→🤖→🤖 🌟

• Definizioni degli agenti: la cella di codice definisce più agenti specializzati (day_trip_agent, foodie_agent, transportation_agent) e, soprattutto, router_agent. Presta molta attenzione al prompt di istruzioni per router_agent, a cui viene chiesto esplicitamente di restituire solo il nome dell'agente migliore per il job.
• Logica di esecuzione: la funzione run_sequential_app mostra come chiamare prima router_agent per ottenere una decisione (chosen_route) e poi utilizzare questa decisione in un blocco if/elif per eseguire l'agente specializzato appropriato.

8. Sessione 6: SequentialAgent ⛓️

Alcune attività richiedono più passaggi in un ordine specifico. Ad esempio, "Trova il miglior sushi a Palo Alto e poi dimmi come arrivarci". Si tratta di una procedura in due passaggi: prima trova il ristorante, poi ottieni le indicazioni stradali.

L'ADK fornisce un modo semplice e potente per gestire questa situazione con SequentialAgent. Si tratta di un agente del flusso di lavoro speciale che esegue un elenco di subagenti in un ordine predefinito.

La magia sta nello stato condiviso. L'output di un agente nella sequenza può essere salvato automaticamente in un dizionario di stato condiviso e poi utilizzato come input per l'agente successivo, eliminando la necessità di un codice manuale complesso per passare le informazioni tra i passaggi.

➡️ Dove trovarlo nel notebook:

👉 Questo argomento è trattato nella parte 2 (Il metodo ADK): caos multi-agente con SequentialAgent 🧠→⛓️→🤖. 🌟

• Refactoring dell'agente:nella prima cella di codice di questa sezione, nota le modifiche chiave apportate a foodie_agent e transportation_agent:
  • foodie_agent ora ha un output_key="destination". In questo modo, l'ADK salva la risposta finale in una variabile denominata destination nello stato condiviso.
  • transportation_agent ora ha il segnaposto {destination} nel prompt delle istruzioni. L'ADK inserisce automaticamente il valore dello stato condiviso in questo segnaposto.
• Definizione del flusso di lavoro: find_and_navigate_agent è definito come SequentialAgent, con i relativi sub_agent impostati su [foodie_agent, transportation_agent], in modo che vengano eseguiti in questo ordine esatto.
• Esecuzione semplificata: consulta la funzione run_sequential_app in questa sezione. La complessa logica if/elif è sparita. L'find_and_navigate_agent ora viene trattato come un'unica unità chiamabile e l'ADK gestisce automaticamente i passaggi sequenziali interni.

9. Sessione 7: LoopAgent 🔁

Non tutti i problemi hanno una soluzione semplice e immediata. A volte dobbiamo proporre una soluzione, criticarla e perfezionarla finché non soddisfa un vincolo specifico.

A questo scopo, l'ADK offre LoopAgent. Questo agente del workflow esegue ripetutamente una sequenza di subagenti finché non viene soddisfatta una condizione specifica. È perfetto per creare agenti "perfezionisti" in grado di pianificare, criticare e migliorare il proprio lavoro.

Il diagramma mostra Planner Agent che crea prima un piano. Poi inseriamo LoopAgent. Il Critic Agent controlla il piano. Se è imperfetto, Refiner Agent crea una nuova versione e il ciclo si ripete. Se il piano è valido, Refiner Agent chiama lo strumento exit_loop e viene restituito il piano finale con la convalida.

➡️ Dove trovarlo nel notebook:

👉 Questo è spiegato in Idee iterative con LoopAgent 🧠→🔁→🤖. 🌟

• Gli agenti principali: il flusso di lavoro utilizza planner_agent, critic_agent e refiner_agent.
• Definizione del ciclo: refinement_loop è definito come un LoopAgent che orchestra critic_agent, refiner_agent e sets max_iterations=3.
• La condizione di uscita: il ciclo termina quando critic_agent approva il piano, il che porta refiner_agent a chiamare lo strumento personalizzato exit_loop.

10. Sessione 8: ParallelAgent ⚡️

L'efficienza è fondamentale. Se un utente chiede più informazioni non correlate contemporaneamente, l'esecuzione di queste ricerche una alla volta sarebbe lenta.

La soluzione è ParallelAgent. Questo agente del flusso di lavoro esegue un elenco di subagenti contemporaneamente. Una volta completate tutte le attività parallele, i risultati possono essere raccolti e sintetizzati in un'unica risposta completa.

Questo diagramma mostra ParallelAgent che prende una singola query e divide il lavoro in tre tracce simultanee. museum_finder, concert_finder e restaurant_finder vengono eseguiti contemporaneamente. Una volta completate tutte e tre, i risultati individuali (salvati nello stato condiviso) vengono uniti e passati all'agente di sintesi finale, che li combina in un'unica risposta.

➡️ Dove trovarlo nel notebook:

👉 Questo flusso di lavoro è descritto in dettaglio nella sezione Parallel Power con ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟

• Agenti specializzati: sono definiti tre agenti specializzati, ognuno con una output_key univoca (ad es. museum_result).
• Il flusso di lavoro parallelo: parallel_research_agent è definito come ParallelAgent, con i tre agenti di ricerca elencati come sub_agents.
• Il passaggio di sintesi: dopo il passaggio parallelo, un agente di sintesi finale raccoglie tutti i risultati dallo stato condiviso utilizzando segnaposto ({museum_result}, {concert_result} e così via) per formattare un riepilogo ordinato.

11. Appendice: ADK Web - 🍎 Per Mac/Linux

Questa guida ti illustrerà la configurazione e l'esecuzione dell'agente ADK per la pianificazione di gite di un giorno sulla tua macchina locale.

Prerequisiti

• Python 3.8 o versioni successive
  • Python 3.9+: installa google-adk==1.5.0 (ultima versione con funzionalità complete)
  • Python 3.8: installa google-adk==0.3.0 (versione compatibile)
• Chiave API Google AI Studio
• Connessione a Internet

Passaggio 1: clona il repository

Apri Terminale ed esegui:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

Passaggio 2: configura l'ambiente virtuale e installa le dipendenze

Opzione A: configurazione automatica (consigliata)

# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

Opzione B: configurazione manuale

# Create virtual environment
python3 -m venv .adk_env

# Activate virtual environment
source .adk_env/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Passaggio 3: 🔥 IMPORTANTE - Crea le variabili di ambiente

⚠️ Non saltare questo passaggio. Crea un file .env nella directory agent/:

# Create the .env file
touch agent/.env

# Open it in your default text editor
open agent/.env

Aggiungi queste righe al file:

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.

Passaggio 4: attiva l'ambiente virtuale (se non è già attivo)

source .adk_env/bin/activate

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

Passaggio 5: esegui l'interfaccia web dell'ADK

adk web

Passaggio 6: apri il browser

1. Apri il browser e vai all'URL mostrato nel terminale (di solito http://localhost:8000)
2. Nel menu a discesa in alto a sinistra, seleziona agent.
3. Inizia a chattare con l'agente per la pianificazione delle gite giornaliere.

Vedrai una conversazione come questa:

Disattivazione dell'ambiente

Al termine del lavoro sul progetto:

deactivate

Questo comando funziona allo stesso modo su Mac/Linux e Windows. Noterai che il prefisso (.adk_env) scompare dal prompt del terminale.

Risoluzione dei problemi su Mac

• Python non trovato: utilizza python3 anziché python
• Autorizzazione negata: esegui chmod +x setup_venv.sh prima di eseguire lo script

12. Appendice: ADK Web - 🪟 Per gli utenti Windows

Questa guida ti illustrerà la configurazione e l'esecuzione dell'agente ADK per la pianificazione di gite di un giorno sulla tua macchina locale.

Prerequisiti

• Python 3.8 o versioni successive
  • Python 3.9+: installa google-adk==1.5.0 (ultima versione con funzionalità complete)
  • Python 3.8: installa google-adk==0.3.0 (versione compatibile)
• Chiave API Google AI Studio
• Connessione a Internet

Passaggio 1: clona il repository

Apri il prompt dei comandi o PowerShell ed esegui:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

Passaggio 2: configura l'ambiente virtuale e installa le dipendenze

Opzione A: configurazione automatica (consigliata)

# Run the setup script in Command Prompt
setup_venv.bat

Opzione B: configurazione manuale

Per il prompt dei comandi:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Per PowerShell:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\Activate.ps1

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Passaggio 3: 🔥 IMPORTANTE - Crea le variabili di ambiente

⚠️ Non saltare questo passaggio. Crea un file .env nella directory agent/:

# Create the .env file
type nul > agent\.env

# Open it in Notepad
notepad agent\.env

Aggiungi queste righe al file:

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.

Passaggio 4: attiva l'ambiente virtuale (se non è già attivo)

Prompt dei comandi:

.adk_env\Scripts\activate

PowerShell:

.adk_env\Scripts\Activate.ps1

Dovresti vedere (.adk_env) all'inizio del prompt.

Passaggio 5: esegui l'interfaccia web dell'ADK

adk web

Passaggio 6: apri il browser

1. Apri il browser e vai all'URL mostrato nel terminale (di solito http://localhost:8000)
2. Nel menu a discesa in alto a sinistra, seleziona agent.
3. Inizia a chattare con l'agente per la pianificazione delle gite giornaliere.

Risoluzione dei problemi di Windows

• Errore dei criteri di esecuzione di PowerShell: esegui Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Vedrai una conversazione come questa:

Disattivazione dell'ambiente

Al termine del lavoro sul progetto:

deactivate

Questo comando funziona allo stesso modo su Mac/Linux e Windows. Noterai che il prefisso (.adk_env) scompare dal prompt del terminale.