Creazione di un semplice agente di viaggi con ADK e Gemini CLI

1. Introduzione

Ultimo aggiornamento: 02/02/2026

Creazione di un semplice agente di viaggi con ADK

Ti diamo il benvenuto a questo workshop su ADK Python(*) con batterie incluse, grazie a Gemini CLI.

Questo codelab è suddiviso in due 🏅 traguardi:

Un percorso di apprendimento comune e semplice: configurazione e gratificazione immediata.
Un percorso personalizzato in cui scegli una missione da risolvere con l'aiuto di Gemini CLI

La seconda parte rende questo codelab perfetto per un hackathon (e premi per le soluzioni più creative).

Milestone1: Your first agent with ADK and Gemini CLI

L'obiettivo di questa tappa fondamentale è creare un semplice agente di viaggi con ADK passo dopo passo.

Per farlo, vogliamo prima configurare Gemini CLI in modo che ci aiuti a programmare con ADK. In questo modo, la shell locale potrà scegliere la versione più recente di Python ADK, inserire il codice e la documentazione e fornire il codice più recente/migliore con cui lavorare per raggiungere il tuo obiettivo.

Si tratta di una parte guidata manualmente in cui otteniamo un'app completamente funzionante attraverso incrementi piccoli e semplici. In genere questa operazione richiede circa un'ora (più il tempo di installazione).

Milestone 2: Extending your agent

Dopodiché, ti offriamo una dozzina di opzioni (di varia difficoltà) per estendere l'app a tuo piacimento. In questo modo puoi esplorare diversi aspetti (UI, operazioni, interazioni complesse con gli agenti, ecc.).

Cosa creerai

In questo codelab, creerai un'app per agenti di viaggio utilizzando ADK e Gemini CLI. La tua app sarà in grado di:

Connettiti alle API Airbnb tramite Airbnb MCP.
Cercare online informazioni aggiornate (meteo, date e così via)
Esegui strumenti personalizzati.
Crea immagini degli appartamenti/delle camere utilizzando Nano Banana.

Gemini CLI ti guiderà in tutto questo: scrivi/esamina il codice e trova la documentazione più recente in un mirror locale del repository ADK (in Python o nel tuo linguaggio preferito).

Cosa imparerai a fare

Come creare un'app con ADK
Come utilizzare Gemini CLI per programmare app basate su documenti locali.
Come interagire con un server MCP per connettersi a origini dati esterne in tempo reale, ad esempio:

Che cosa ti serve

Un computer che ti consente di installare pacchetti (ad es. npm install ..)
Capacità di programmazione di base in Python, TypeScript, Go o Java.
È consigliato vivamente un IDE di qualche tipo ( Antigravity, vscode, IntelliJ, vim).

Perché ADK + Gemini CLI?

Alcuni di voi potrebbero chiedersi: perché devo utilizzare ADK (un SDK per la creazione di agenti) insieme a un helper di codice agentico locale (come la CLI di Gemini)? Il motivo è che entrambi gli strumenti sono incredibilmente potenti, ma la loro interazione non è banale; molte persone hanno provato a utilizzarli insieme senza riuscirci (principalmente a causa di problemi di "loop in un loop"). Questo codelab cerca di condividere alcuni suggerimenti su come rendere possibile questa coesistenza.

2. Preparazione

Scegli una delle seguenti opzioni: Configurazione dell'ambiente autonomo se vuoi eseguire questa

codelab sulla tua macchina oppure avvia Cloud Shell se vuoi eseguire questo codelab interamente nel cloud.

Configurazione dell'ambiente autonoma

Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Google Workspace, devi crearne uno.

Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID). Se non ti piace l'ID generato, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto.
Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.

Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare addebiti oltre a quelli previsti in questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono usufruire del programma prova senza costi di 300$.

Avvia Cloud Shell

Sebbene Google Cloud possa essere gestito da remoto dal tuo laptop, in questo codelab utilizzerai Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.

Nella console Google Cloud, fai clic sull'icona di Cloud Shell nella barra degli strumenti in alto a destra:

Attiva Cloud Shell

Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere un risultato simile a questo:

Screenshot del terminale Google Cloud Shell che mostra che l'ambiente è connesso

Questa macchina virtuale è caricata con tutti gli strumenti per sviluppatori di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione della rete. Tutto il lavoro in questo codelab può essere svolto all'interno di un browser. Non devi installare nulla.

Prerequisiti (installazione)

Per questo tutorial, devi installare:

1. Python e uv

python e uv (gestore dei pacchetti per Python). Questo è necessario per l'ADK. Assicurati di aver installato uv:

$ curl -LsSf https://astral.sh/uv/install.sh | sh

Perché UV? Sebbene tu possa utilizzare il gestore Python che preferisci, l'utilizzo di uv garantisce che la configurazione ENV/PATH per Python sia uguale per te e per Gemini CLI, in modo che la tua esperienza shell sia per lo più la stessa di Gemini CLI. Se utilizzi virtualenv , ad esempio, Gemini CLI sarà costretta a eseguire operazioni come "source .env/venv/bin/activate && my-original-command" per simulare il tuo ambiente.

2. Gemini CLI

Per gemini CLI, trova le istruzioni di installazione qui: https://github.com/google-gemini/gemini-cli .

Nota: per questa operazione è necessario che npm o npx siano installati.

npm install -g @google/gemini-cli

Su Mac, puoi utilizzare brew come indicato nella documentazione ufficiale.
Su Windows, puoi utilizzare chocolatey o semplicemente scaricare il file eseguibile da https://nodejs.org/en/download.

Per il passaggio 4 (più avanti), dovrai installare anche npx. Sia npm sia npx dovrebbero essere disponibili in modo naturale in Gemini CLI. In caso contrario, chiedi all'interfaccia a riga di comando di Gemini di aiutarti qui.

In alternativa, potresti anche installare just, un Makefile più avanzato e auto-documentato. Anche qui: chiedi a Gemini CLI di aiutarti a installare questo componente, può farlo per te.

Autenticazione.

Devi disporre di un progetto Google Cloud con Vertex AI abilitato o di una chiave API Google AI Studio.

Opzione A (consigliata per il workshop): esporta la chiave API:

export GOOGLE_API_KEY="your-api-key"

Opzione B (Vertex AI): esegui l'autenticazione con gcloud:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
export GOOGLE_GENAI_USE_VERTEXAI=true
gcloud auth application-default login

Configurare l'ambiente di lavoro

Creerai la TUA soluzione in mysolution/, quindi creiamo la cartella e i due file di cui abbiamo bisogno.

Questo è il momento in cui puoi aprire il tuo IDE (Visual Studio Code, IntelliJ, RubyMine, ..) e aprire la cartella.

# 1. Find an empty directory, and download this repo.
git clone https://github.com/palladius/ai-friendly-agents/
cd ai-friendly-agents/adk/workshops/simple-travel-agent/

# 2. Create your solution empty skeleton
mkdir -p mysolution/
touch mysolution/__init__.py mysolution/agent.py

# 3. This installs ADK and MCP via `uv` by reading pyproject.toml
uv sync

# 4. Call Gemini CLI
gemini  # This runs Gemini CLI under the simple-travel-agent/ folder.
# Login with your GMail account.

uv sync non è strettamente necessario, ma se non va a buon fine, sai che devi correggere l'installazione di Python o uv.

Soluzioni disponibili

Il codice è contenuto in 📂 steps/. Puoi copiare il codice da lì.

Questo codelab non riguarda l'apprendimento di come scrivere un buon codice ADK, ma la configurazione dell'ambiente per ottenere automaticamente un BUON codice scritto sotto la tua direzione.

Installa il software
configurarlo / farlo funzionare e
inserendo un ciclo di feedback virtuoso

Questo è ciò che vogliamo che impari qui. Puoi anche testarli tutti contemporaneamente tramite $ just web-4steps.

3. Passaggio 1: agente di base

Iniziamo creando un agente di base in grado di sostenere una conversazione.

Modifica il file denominato mysolution/__init__.py aggiungendo i seguenti contenuti:

from .agent import root_agent

È davvero semplice. In questo modo ADK sa dove si trova il tuo codice: in agent.py.

Modifica il file denominato mysolution/agent.py aggiungendo i seguenti contenuti:

from google.adk.agents import Agent

root_agent = Agent(
    name="travel_basic",
    model="gemini-2.5-flash",
    instruction="You are a helpful travel assistant." +
    "You can help with general travel advice based on your knowledge.",
)

Test dell'agente

Questo vale per tutti i passaggi. L'ADK ti consente di testare l'agente in due modi: CLI e web.

La CLI è ideale per test rapidi e automatizzati
Web è la migliore per vedere visivamente cosa sta succedendo, utilizzare il microfono (!) e risolvere i problemi.

Suggerimento: ai fini di questo esercizio, per svolgere qualsiasi attività (tranne i test unitari), utilizza il web. È davvero incredibile. Utilizza la CLI solo per i test automatizzati.

Un buon prompt che testa correttamente i passaggi 1-2-3-4 può essere questo (il "prompt di prova" intelligente):

# <!– litmus prompt –> Hi, I'd like to book a hotel in Paris for tomorrow evening alone, one night, in Paris city center. In posizione ideale vicino alla stazione ferroviaria Gare de Lyon. Budget: meno di 200 € a notte.

Dimmi qual è la data AAAAMMGG e il giorno della settimana di domani.
Dimmi quali hotel vedi per domani (almeno 3). Voglio vedere: > prezzo, indirizzo, una valutazione (nel formato XX/YY, ad es. "4,7/5" - da Google Hotels, Booking o Airbnb), numero di recensioni. Forniscimi i dati in formato TABULARE. Idealmente, il nome dell'hotel deve essere collegato a un URL dell'hotel (non preoccuparti di aggiungere una colonna URL). Assicurati che il link sia legittimo (funzioni e la pagina rimandi alle informazioni sull'hotel).

Questo è un prompt intelligente perché testa l'ora e gli hotel e avrà esito negativo in modo diverso nei passaggi 1, 2 e 3 e dovrebbe avere esito positivo solo nel passaggio 4. Naturalmente, puoi utilizzare qualsiasi prompt tu voglia.

Esegui il comando da bash (CLI):

# 1. If ADK was installed:
adk run mysolution/
# ... but if you get: -bash: adk: command not found"
# 2. Call ADK cli script through UV to avoid python install nightmares.
uv run adk run mysolution/

Prova a utilizzare il "prompt litmus" riportato sopra.

Probabilmente non riuscirà a conoscere date specifiche. Dobbiamo insegnargli a riconoscere la data.

Per il web, puoi:

uv run adk web . : esegue tutti gli agenti in questa cartella. Vuoi indirizzarlo alla sottocartella "mysolution/"
scegli mysolution/ in alto a destra (vedi l'immagine a lato)
Poni la tua domanda in formato di testo o tramite microfono, qualcosa del tipo "richiesta di verifica".

TODO(ricc): <image here>

Tieni presente che devi chiamare adk web dalla cartella superiore, rispetto alla versione della CLI.

Ecco una possibile soluzione, con una semi-allucinazione della data. Nota: 3 dei 5 link di prenotazione funzionano. Non male.

4. Passaggio 2: aggiungi lo strumento now()

L'agente non sa cosa significa "oggi". Diamo un'occhiata a uno strumento.

TODO(image): ricc put here image of step2.

Aggiungi questa funzione a agent.py appena prima della definizione di root_agent:

from datetime import datetime

def now() -> dict:
    """Returns the current date and time."""
    my_datetime = ... # Ask Gemini CLI to help you!
    return {
        "status": "success",
        "current_time": my_datetime
    }

Aggiorna la definizione dell'agente in modo che includa lo strumento:

  # file XXX.py

  travel_agent = LlmAgent(
        name="..",
        model="..",
        instruction="..",
        tools=[now] # <== This is the only line you want to add.
    )

Esegui di nuovo il test e fai la stessa domanda. Ora dovrebbe conoscere la data (bene) ed essere vaga sugli hotel (male).

Puoi anche testarlo con un comando simile a questo:

# Let's pretend we're in Milan. This should call the tool
# and respond correctly (possibly with some TZ math issues)

echo "What time is it in Milan?" | uv run adk run mysolution/

5. Passaggio 3: cambiamo marcia: google_search

Ora che sappiamo come creare uno strumento personalizzato, vediamo come utilizzare uno dei potenti strumenti integrati forniti da ADK: google_search. In questo modo, il nostro agente può accedere a informazioni in tempo reale dal web.

Il tuo compito è modificare l'agente del passaggio 2. Anziché utilizzare lo strumento now, importerai e utilizzerai lo strumento google_search dalla libreria ADK.

# Full Code: `steps/step03_search/agent.py`
# Remember to REMOVE the now() tool here. See above why.
from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="travel_agent",
    model="gemini-2.5-flash",
    tools=[google_search],
    instruction="""You are a travel agent.
Your job is to help the user plan a trip.
You have access to a search engine.
If you don't know the answer, you can use the search engine.
When you are done, reply with "DONE".""",
)

Come eseguire

Come nel passaggio 1.

Solo esperti. Per un'integrazione più avanzata (utilizzando google_search e now insieme), controlla il codice in steps/step03b_search_and_tool/agent.py ed eseguilo con just run-step3b. Questa opzione è del tutto facoltativa.

6. Passaggio 4: uno strumento più sofisticato: MCP

TODO(ricc): add image 4

Ora che abbiamo visto gli strumenti personalizzati e quelli integrati, passiamo a qualcosa di più potente: il pattern Model-as-a-Tool utilizzando il Model Context Protocol (MCP).

Per mantenere questo passaggio incentrato sulle potenti funzionalità di MCP, sostituiremo nuovamente il nostro strumento precedente (google_search). Reintrodurremo il nostro semplice strumento now da utilizzare insieme allo strumento airbnb_mcp. Questo dimostra come un agente possa utilizzare più strumenti compatibili (in questo caso, un FunctionTool e un MCPToolset) per eseguire attività complesse.

# Full Code: steps/step04_mcp/agent.py
# ... Imports as before
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

def now() -> dict:
    # ... as before

# Configure the Airbnb MCP Toolset
airbnb_mcp = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command='npx',
            args=["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"],
        ),
    )
)

root_agent = Agent(
    name="travel_mcp",
    model="gemini-2.5-flash",
    instruction="You are a helpful travel assistant. You can find accommodation using Airbnb, and have access to the current time.",
    tools=[now, airbnb_mcp],
)

Come eseguire

Questo passaggio richiede l'installazione di npx sul sistema. Per il resto, la procedura è la stessa descritta sopra.

Avvertenze/ errori

Se ricevi un errore di limitazione robots.txt, puoi applicare una patch al MCP con una direttiva di ignoranza dei robot. Per ulteriori dettagli, leggi la documentazione: https://github.com/openbnb-org/mcp-server-airbnb
Se ricevi un errore timeout (5 secondi sono troppo pochi per Airbnb per ricevere risposte), consulta la documentazione dell'ADK su come aumentare il timeout, ad esempio a 30 secondi. In alternativa, usa Gemini CLI. Tieni presente che il 3 dicembre 2025 Cloud Shell ha restituito un errore di timeout. Ho risolto il problema, ma ho continuato a ricevere errori finché non ho forzato il ritorno alla versione precedente: args=["-y", "@openbnb/mcp-server-airbnb@0.1.2", "--ignore-robots-txt"].

7. 🏅 Traguardo 1 completato.

🏅 Complimenti! 🏅 Ora sei un esperto dell'ADK. Hai completato la prima parte del workshop e hai creato e testato agenti AI con strumenti personalizzati, strumenti integrati e strumenti MCP avanzati. Ora puoi creare i tuoi fantastici agenti con Google Agent Development Kit.

Ora hai un agente di viaggio funzionale che conosce l'ora e può cercare sul web. Ora non ci sono più limiti.

Ora è il momento di aggiungere una funzionalità aggiuntiva con "Gemini CLI".

8. 🏅 Traguardo 2: vibe coding con ADK tramite Gemini CLI

Ora passiamo alla parte interessante del workshop.

assicurati di aver git committo il codice in un luogo sicuro. Puoi creare un fork del codice originale o creare un ramo: non preoccuparti, Gemini CLI è un ottimo strumento per aiutarti in questo.
Trova un'💡 idea da implementare. Puoi controllare le idee riportate di seguito, trovarne una tu o chiedere a Gemini di esaminare la documentazione in RAG e proporre alcune idee intelligenti.
Segui i prerequisiti per assicurarti che Gemini possa leggere i documenti dell'ADK. A questo punto, puoi iniziare.

💡 Idee

Ecco un menu con alcune idee di diversa complessità.

🟢 [facile] Sei un poliglotta? Vuoi dare go, java o Typescript? Il refactoring del codice esistente è molto semplice. Assicurati solo di scaricare l'ADK corretto e chiedi a Gemini CLI di eseguire la traduzione.
🟢 [facile] Aggiungi emoji o specifica un formato di output che ti piace (ad es. una tabella con l'emoji dell'hotel, seguita dal prezzo, seguita da emoji a 1-5 stelle con 🌕🌕🌕🌗🌑 per fare anche le metà).
🟢 [facile] Modifica il prompt per insegnare all'app le cose che cerchi o che non cerchi (animali ammessi, niente piano terra, silenzioso, vicino ai trasporti pubblici, ecc.) e testalo. Magari aggiungi una valutazione personale come "una valutazione di YOUR_NAME da 1 a 10" in base a quanto sopra e ordina in base a questa valutazione.
🟢 [facile] C'è un operatore nella stanza? Esegui il deployment in Cloud Run. o a Vertex AI Agent Engine. Sapevi che puoi integrare questo agente e chiamarlo direttamente dal nuovo Gemini Enterprise?
🟢 [facile] Integra `adk run`` con 🍌 NanoBanana MCP. Richiede una chiave API Gemini. Qui potrai creare immagini, ma non visualizzarle. Di seguito è riportata una variante più difficile.
🟡 [medio] Crea un subagente che esegua l'operazione HotelSearch e crea un BudgetAgent o un LocationAgent che possa raddoppiare e iterare sugli hotel rispettando le tue esigenze di località, ad esempio "non più di X km da LOCATION". Se l'API non lo consente, potrebbe essere necessario un intervento di Google Search. Nota: Gemini CLI può aiutarti.
🟡 [media] Implementa un AirbnbReviewAgent che analizzi le recensioni e riassuma gli aspetti positivi e negativi in alcuni punti elenco codificati per colore, per 1 o N hotel risultanti da una ricerca. Hai già due ingredienti (GoogleSearch e MCP Airbnb), quindi devi collegarli all'agente principale e magari inventare una sorta di protocollo per la comunicazione.
🟡 [medio] Eseguire l'integrazione con A2A. Rendilo un agente A2A. Anche in questo caso, chiedi aiuto all'interfaccia a riga di comando di Gemini.
🔴 [complesso] Puoi eseguire l'integrazione con Voli o altre funzionalità MCP per creare un agente di viaggi multifunzionale e sfaccettato.
🔴 [complesso] Integra ADK web con 🍌 NanoBanana MCP. Questo è più difficile di quello precedente e puoi trovare alcuni suggerimenti all'indirizzo https://github.com/palladius/ai-friendly-agents/issues/11 . L'autore ha impiegato 3 ore di scambi con Gemini CLI, Gemini 3 e entrambi abbiamo letto documenti/codice da rag/.

Cerchi altra ispirazione?

Dai un'occhiata al fantastico tutorial ADK di Maurizio per trovare qualche idea.
Chiedi a Gemini CLI di trovare idee esaminando la documentazione in rag/: un prompt possibile potrebbe essere: Is there a feature in here which seems very succulent to you? Give me 3 proposals and let's implement together the one I choose.

Prerequisiti per l'ADK "RAG"

Per creare il codice di una funzionalità, ti consigliamo di scaricare l'intero ADK python ADK (nota: può essere adattato molto facilmente al tuo linguaggio preferito, come Java o Go).

Il codice si trova in ./rag e può essere scaricato con ./download-adk.sh.

Poiché la cartella rag è elencata nel file .gitignore, assicurati che .gemini/settings.json contenga quanto segue:

{
 "context": {
   "includeDirectories": ["rag"]
 }
}

Why? Vogliamo che Gemini possa leggere questi file, che vengono ignorati in modo sicuro da Git. Tecnicamente potresti anche mostrare tutti i file .gitignore impostando context.fileFiltering.respectGitIgnore su false, ma in questo modo si aprono molti file node_modules/ e __pycache__/ inutili, quindi l'inclusione esplicita delle cartelle è l'opzione preferita.

9. Passaggi successivi

Curiosità: questo workshop è stato creato con l'aiuto di Gemini CLI. Se ti incuriosisce, puoi scoprire come ho fatto esaminando GEMINI.md e WORKSHOP_PLAN.md in questa cartella.

Lezioni apprese

Abbiamo imparato ad accoppiare l'ADK con Gemini CLI

Letture aggiuntive

Dai un'occhiata a questi due fantastici codelab di Antigravity di Romin e Mete:
Guida introduttiva a Google Antigravity
Creare con Google Antigravity
Crea ed esegui il deployment su Google Cloud con Antigravity
Dai un'occhiata al fantastico tutorial ADK di Maurizio per trovare qualche idea.