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

1. Introduzione

Ultimo aggiornamento: 22/06/2026

Creazione di una semplice agenzia viaggi con ADK

Ti diamo il benvenuto a questo workshop Python(*) ADK, che include tutto il necessario grazie a Gemini CLI.

Questo codelab è suddiviso in due 🏅 tappe:

1. Un percorso di apprendimento comune e semplice: configurazione + gratificazione immediata.
2. Un percorso personalizzato in cui scegli una quest da risolvere con l'assistenza di Gemini CLI

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

Traguardo 1: il tuo primo agente con ADK e Gemini CLI

L'obiettivo di questo passaggio è creare passo passo una semplice agenzia viaggi con ADK. Per farlo, dobbiamo prima configurare Gemini CLI in modo che ci aiuti a programmare con l'ADK. In questo modo, la tua shell locale potrà scegliere l'ultima versione di Python ADK, inserire il codice e i documenti e fornire il codice più recente/migliore per lavorare con l'ADK per il tuo obiettivo.

Questa è una parte guidata in cui otteniamo un'app completamente funzionante attraverso piccoli e semplici incrementi. In genere, l'operazione richiede circa un'ora (più il tempo di installazione).

Nota (*): anche se il codelab presuppone che tu stia utilizzando l'ADK Python, puoi farlo funzionare con Go, Java o TypeScript con pochissime modifiche. In realtà, se hai utilizzato l'ADK solo con Python, questo codelab è un'ottima opportunità per provare il percorso in un linguaggio diverso. Facci sapere cosa ne pensi tramite il link per il feedback di seguito.

Traguardo 2: estendi l'agente

Dopodiché, ti forniremo 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 e così via).

Cosa creerai

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

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

Gemini CLI ti guiderà in tutto questo: scrittura/revisione del codice e ricerca della 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.
• È vivamente consigliato 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 assistente di codice agentico locale (come Gemini CLI)? Il motivo è che entrambi gli strumenti sono incredibilmente potenti, ma la loro interazione non è banale; molte persone hanno provato a lavorare con entrambi in combinazione e hanno fallito (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 questo codelab sulla tua macchina o Avvia Cloud Shell se vuoi eseguire questo codelab interamente nel cloud.

Configurazione dell'ambiente autonomo

1. 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 progetto è il nome visualizzato per i partecipanti di questo progetto. Si tratta di una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarla.
• L'ID progetto è univoco per 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 è importante sapere qual è. Nella maggior parte dei codelab, dovrai fare riferimento al tuo ID progetto (in genere identificato come PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare a inserire un nome di dominio di tua scelta e verificare se è disponibile. Non può essere modificato dopo questo passaggio e rimane invariato 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.

Attenzione: un ID progetto è univoco a livello globale e non può essere utilizzato da nessun altro dopo che lo hai selezionato. Sei l'unico utente di questo ID. Anche se un progetto viene eliminato, l'ID non può essere riutilizzato

Nota: se utilizzi un account Gmail, puoi lasciare la località predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una località adatta alla tua organizzazione.

2. Successivamente, dovrai abilitare la fatturazione nella console Cloud per utilizzare le risorse/API Cloud. L'esecuzione di questo codelab non costerà molto, se non addirittura nulla. Per arrestare le risorse ed evitare che ti vengano addebitati costi oltre a quelli di questo tutorial, puoi eliminare le risorse che hai creato o eliminare il progetto. I nuovi utenti Google Cloud possono usufruire del programma di prova senza costi di 300 $.

Avvia Cloud Shell

Sebbene Google Cloud possa essere utilizzato 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:

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

In questa macchina virtuale sono caricati 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 di questo codelab può essere svolto all'interno di un browser. Non devi installare nulla.

3. Prerequisiti (installazione)

Nota: se decidi di eseguire questo codelab su Cloud Shell, Python, uv e Gemini CLI (gemini) sono già preinstallati.

Per questo tutorial, devi installare:

1. Python e uv

python e uv (gestore di 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 garantirà che la configurazione ENV/PATH per Python sia la stessa per te e per Gemini CLI, in modo che la tua esperienza con la shell sia sostanzialmente la stessa di Gemini CLI. Ad esempio, se utilizzi virtualenv, 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, consulta le istruzioni di installazione qui: https://github.com/google-gemini/gemini-cli.

# Note: This requires having npm or npx installed.
npm install -g @google/gemini-cli

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

Per il passaggio 4 (più avanti), dovrai anche installare npx. Sia npm che npx dovrebbero essere disponibili naturalmente come parte di Gemini CLI. In caso contrario, chiedi a Gemini CLI di aiutarti qui.

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

Configura 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/adk-gemini-cli-workshop
cd adk-gemini-cli-workshop/

# 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 init
uv sync

# 4. Call Gemini CLI
gemini  # This runs Gemini CLI under the adk-gemini-cli-workshop/ folder.
# Login with your GMail account.

uv sync non è strettamente necessario, ma se non va a buon fine, significa che devi correggere l'installazione di Python o uv. In questo modo, adk e altri script utili dovrebbero essere installati nella cartella ./.venv/bin/.

Per testare la configurazione, puoi semplicemente eseguire make test-step1 e verificare di non ricevere un 403 PERMISSION DENIED.

Importante. Assicurati di eseguire Gemini CLI dalla cartella 📁 adk-gemini-cli-workshop/. Inoltre, l'IDE dovrebbe mostrare questo nome come nome principale. In questo modo, Gemini CLI utilizza la configurazione corretta. Puoi sempre aggiungere cartelle esterne tramite /dir add /your/other/folder, ma 📁 adk-gemini-cli-workshop/ fornisce la posizione iniziale migliore.

Soluzioni disponibili

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

Questo codelab non spiega come scrivere un buon codice ADK, ma come configurare l'ambiente per ottenere un codice BUONO scritto automaticamente sotto la tua direzione.

1. Installa il software
2. la configurazione/messa in funzione e
3. entrando in un Feedback Loop virtuoso

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

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

Semplicissimo, vero? 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: tramite l'interfaccia a riga di comando e sul web.

• L'CLI è ideale per test rapidi e automatici
• Web è la soluzione migliore per vedere visivamente cosa sta succedendo, utilizzare il microfono (!) e risolvere i problemi.

Suggerimento: ai fini di questo esercizio, per eseguire qualsiasi operazione (ad eccezione dei test delle unità), utilizza il web. È davvero fantastico! Utilizza l'interfaccia a riga di comando solo per i test automatici.

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

Ciao, vorrei prenotare un hotel a Parigi per domani sera, solo per me, una notte, nel centro di Parigi. In posizione ideale vicino alla stazione ferroviaria Gare de Lyon. Budget: meno di 200 € a notte.

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

Questo è un prompt smart perché testa l'ora e gli hotel e non riuscirà in modo diverso nei passaggi 1,2 e 3,mentre dovrebbe riuscire completamente solo nel passaggio 4. Ovviamente puoi utilizzare qualsiasi prompt tu voglia.

Eseguilo da bash (interfaccia a riga di comando):

# 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 utilizzarlo con il "prompt di prova" riportato sopra.

Probabilmente non sarà in grado di conoscere date specifiche. Dobbiamo insegnarle a riconoscere la data.

Per il web, puoi procedere nel seguente modo:

1. uv run adk web . : esegue tutti gli agenti in questa cartella. Vuoi indirizzarlo alla sottocartella "mysolution/"
2. scegli mysolution/ in alto a destra (vedi l'immagine accanto)
3. Fai la tua domanda tramite testo o microfono, ad esempio "prompt di verifica".

Tieni presente che devi chiamare adk web dalla cartella superiore, rispetto alla versione dell'interfaccia a riga di comando.

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

5. Passaggio 2: aggiungi lo strumento now()

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 per includere lo strumento:

  # file XXX.py

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

Eseguilo di nuovo e fai la stessa domanda. Ora dovrebbe conoscere la data (bene) ed essere vago sugli hotel (male).

Puoi anche testarlo con un comando simile al seguente:

# 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/

6. Passaggio 3: cambiamo marcia: google_search

google_search. In questo modo, il nostro agente può accedere a informazioni in tempo reale dal web.

Nota: 🚨 i modelli gemini-2.x non possono combinare in modo nativo la Ricerca Google con strumenti personalizzati (vedi Problema n. 969), quindi sostituiremo now() con google_search per semplicità. Per maggiori dettagli, consulta il file ISSUES.md.

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 make run-step3b. Questa è una scelta completamente facoltativa.

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

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

Per mantenere l'attenzione sulle potenti funzionalità di MCP, sostituiremo ancora una volta il nostro strumento precedente (google_search). Reintrodurremo il nostro semplice strumento now da eseguire insieme allo strumento airbnb_mcp. Questo dimostra come un agente può 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 tuo sistema. Per il resto, è uguale a quanto sopra.

Precisazioni/errori

1. Se ricevi un errore di limitazione robots.txt, puoi applicare una patch all'MCP con un'istruzione robots per ignorare. Per maggiori dettagli, leggi la documentazione: https://github.com/openbnb-org/mcp-server-airbnb
2. Se ricevi un errore timeout (5 secondi sono troppo pochi per consentire ad Airbnb di ricevere risposte), consulta la documentazione di ADK su come aumentare il timeout, ad esempio a 30 secondi. In alternativa, utilizza Gemini CLI per farlo. Tieni presente che il 3 dicembre 2025 Cloud Shell mi ha restituito un errore di timeout, ho corretto l'errore di timeout e ho continuato a ricevere errori finché non ho forzato la versione precedente: args=["-y", "@openbnb/mcp-server-airbnb@0.1.2", "--ignore-robots-txt"].

8. 🏅 Traguardo 1 completato!

🏅 Complimenti! 🏅 Ora sei un esperto di ADK! Hai completato la prima parte del workshop e hai creato e testato con successo 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ò eseguire ricerche sul web. Non ci sono più limiti!

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

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

Ora passiamo alla parte interessante del workshop.

1. assicurati di aver git committo il codice in un luogo sicuro. Puoi creare un fork del codice originale o creare un branch: non preoccuparti, Gemini CLI è un ottimo strumento per aiutarti in questo.
2. Trova un'💡 idea da implementare. Puoi consultare le idee di seguito, trovarne una tu o chiedere a Gemini di esaminare la documentazione in rag/ e proporre alcune idee intelligenti.
3. Segui i prerequisiti per assicurarti che Gemini possa leggere i documenti ADK e poi potrai iniziare.

💡 Idee

1. 🟢 [easy] Are you a language polyglot? Vuoi dare go, java o TypeScript? Rifattorizzare il codice esistente è molto semplice. Assicurati di scaricare l'ADK appropriato e chiedi a Gemini CLI di eseguire la traduzione.
2. 🟢 [Facile] Aggiungi emoji o specifica un formato di output che preferisci (ad esempio, una tabella con l'emoji dell'hotel, seguita dal prezzo, seguita da emoji da 1 a 5 stelle con 🌕🌕🌕🌗🌑 per fare anche le mezze stelle).
3. 🟢 [Facile] Modifica il prompt per insegnargli cosa stai cercando o cosa vuoi evitare (adatto agli animali domestici, non al piano terra, silenzioso, vicino ai trasporti pubblici…) 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.
4. 🟢 [easy] Any Operator in the room? 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?
5. 🟢 [Facile] Integra adk run con 🍌 NanoBanana MCP. Richiede una chiave API Gemini. Qui potrai creare immagini, ma non visualizzarle. Vedi di seguito una variante più difficile.
6. 🟡 [medium] Create a subagent who does the HotelSearch and create a BudgetAgent or a LocationAgent which can double down and iterate over hotels respecting your location needs, eg "not more than X km from LOCATION". Se l'API non lo consente, potrebbe essere necessario un po' di avanti e indietro con l'aiuto della Ricerca Google. Nota: Gemini CLI può aiutarti.
7. 🟡 [medium] Implement a AirbnbReviewAgent which goes into the reviews and summarize positives and negatives in a few color-coded bullets, for 1 or N hotels reslting from a search. Hai già due ingredienti (GoogleSearch e MCP Airbnb), quindi devi collegarli all'agente principale e magari inventare un tipo di protocollo per farli comunicare.
8. 🟡 [medium] Integrazione con A2A. Rendilo un agente A2A. Anche in questo caso, chiedi aiuto all'interfaccia a riga di comando di Gemini.
9. Puoi eseguire l'integrazione con Voli o altre funzionalità di MCP per creare un'agenzia viaggi multifunzionale e poliedrica.
10. 🔴 [complesso] Integra ADK web con 🍌 NanoBanana MCP. Questo è più difficile di quello precedente e puoi trovare alcuni suggerimenti su https://github.com/palladius/ai-friendly-agents/issues/11. Questo ha richiesto all'autore 3 ore di avanti e indietro con Gemini CLI, Gemini3 e la lettura di documenti/codice da rag/ da parte di entrambi.

Cerchi altra ispirazione?

1. Consulta il tutorial ufficiale di ADK per alcune idee.
2. Chiedi a Gemini CLI di trovare idee consultando la documentazione in rag/: un possibile prompt 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 "RAG" di ADK

Per vibe coding una funzionalità, ti consigliamo di scaricare l'intero ADK Python (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 il file .gemini/settings.json contenga quanto segue:

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

Why? Vogliamo che Gemini sia in grado di leggere questi file, anche se sono ignorati in modo sicuro da Git. Tecnicamente, potresti anche mostrare tutti i file .gitignore impostando context.fileFiltering.respectGitIgnore su false, ma questo apre molti file spazzatura node_modules/ e __pycache__/, quindi l'inclusione esplicita delle cartelle è l'opzione preferita.

10. Passaggi successivi

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

Lezioni apprese

Abbiamo imparato ad accoppiare ADK con Gemini CLI

Letture aggiuntive

• Dai un'occhiata a questi due codelab ufficiali di Antigravity:
  • Introduzione a Google Antigravity
  • Build with Google Antigravity
  • Crea ed esegui il deployment su Google Cloud con Antigravity
• Consulta il tutorial ufficiale di ADK per alcune idee.