1. Introduzione
In questo codelab creerai un agente utilizzando l'Agent Development Kit (ADK) che utilizza l'MCP Toolbox for Databases.
Nel codelab, seguirai un approccio passo passo come segue:
- Esegui il provisioning di un database Cloud SQL per PostgreSQL che conterrà il database degli hotel e i dati di esempio.
- Configura MCP Toolbox for Databases, che fornisce l'accesso ai dati.
- Progetta e sviluppa un agente utilizzando Agent Development Kit (ADK) che utilizzerà MCP Toolbox per rispondere alle query dell'utente.
- Esplora le opzioni per testare Agent e MCP Toolbox for Databases localmente e su Google Cloud tramite il servizio Cloud Run.
Attività previste
- Progetta, crea e implementa un agente che risponderà alle query degli utenti sugli hotel in una località o cercherà hotel per nome.
Cosa imparerai a fare
- Provisioning e popolamento di un database Cloud SQL per PostgreSQL con dati di esempio.
- Configura MCP Toolbox for Databases per l'istanza di database Cloud SQL per PostgreSQL.
- Progetta e sviluppa un agente utilizzando Agent Development Kit (ADK) per rispondere alle query degli utenti.
- Prova l'agente e MCP Toolbox per i database nell'ambiente locale.
- (Facoltativo) Esegui il deployment dell'agente e di MCP Toolbox for Databases in Google Cloud.
Che cosa ti serve
- Browser web Chrome
- Un account Gmail
- Un progetto cloud con fatturazione abilitata
Questo codelab, progettato per sviluppatori di tutti i livelli (inclusi i principianti), utilizza Python nella sua applicazione di esempio. Tuttavia, non è necessaria la conoscenza di Python e la capacità di leggere il codice di base sarà sufficiente per comprendere i concetti presentati.
2. Prima di iniziare
Crea un progetto
- Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
- Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto .
- Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud precaricato con bq. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
- Una volta eseguita la connessione a Cloud Shell, verifica di essere già autenticato e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:
gcloud auth list
- Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.
gcloud config list project
- Se il progetto non è impostato, utilizza il seguente comando per impostarlo:
gcloud config set project <YOUR_PROJECT_ID>
- Abilita le API richieste tramite il comando mostrato di seguito. L'operazione potrebbe richiedere alcuni minuti.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudfunctions.googleapis.com \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com
Se il comando viene eseguito correttamente, dovresti visualizzare un messaggio simile a quello mostrato di seguito:
Operation "operations/..." finished successfully.
L'alternativa al comando gcloud è tramite la console, cercando ogni prodotto o utilizzando questo link.
Se manca un'API, puoi sempre abilitarla durante l'implementazione.
Consulta la documentazione per i comandi e l'utilizzo di gcloud.
3. Crea un'istanza Cloud SQL
Utilizzeremo un'istanza Google Cloud SQL per PostgreSQL per archiviare i dati degli hotel. Cloud SQL per PostgreSQL è un servizio di database completamente gestito che semplifica la configurazione, la manutenzione, la gestione e l'amministrazione dei database relazionali PostgreSQL su Google Cloud.
Esegui questo comando in Cloud Shell per creare l'istanza:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
L'esecuzione di questo comando richiede circa 3-5 minuti. Una volta eseguito correttamente il comando, dovresti visualizzare un output che indica che il comando è stato completato, insieme alle informazioni sull'istanza Cloud SQL, come NAME, DATABASE_VERSION, LOCATION e così via.
4. Prepara il database Hotels
Il nostro compito ora sarà quello di creare alcuni dati di esempio per il nostro agente di hotel.
Visita la pagina Cloud SQL nella console Cloud.Dovresti vedere hoteldb-instance pronto e creato. Fai clic sul nome dell'istanza (hoteldb-instance) come mostrato di seguito:
Dal menu a sinistra di Cloud SQL, visita l'opzione di menu Cloud SQL Studio come mostrato di seguito:
Ti verrà chiesto di accedere a Cloud SQL Studio, tramite il quale forniremo alcuni comandi SQL. Seleziona postgres per l'opzione Database e per Utente e Password, il valore da utilizzare è postgres. Fai clic su AUTHENTICATE.
Creiamo prima la tabella degli hotel in base allo schema riportato di seguito. In uno dei riquadri dell'editor di Cloud SQL Studio, esegui il seguente SQL:
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
Ora compiliamo la tabella degli hotel con dati di esempio. Esegui il seguente SQL:
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
Convalidiamo i dati eseguendo un'istruzione SQL SELECT come mostrato di seguito:
SELECT * FROM hotels;
Dovresti vedere una serie di record nella tabella degli hotel, come mostrato di seguito:
Abbiamo completato la procedura di configurazione di un'istanza Cloud SQL e creato i nostri dati di esempio. Nella sezione successiva configureremo MCP Toolbox for Databases.
5. Configurare MCP Toolbox per i database
MCP Toolbox for Databases è un server MCP open source per i database. È stato progettato pensando alla qualità di produzione e di livello aziendale. Ti consente di sviluppare strumenti in modo più semplice, rapido e sicuro gestendo le complessità come il pooling di connessioni, l'autenticazione e altro ancora.
Toolbox ti aiuta a creare strumenti di AI generativa che consentono ai tuoi agenti di accedere ai dati nel tuo database. Toolbox fornisce:
- Sviluppo semplificato: integra gli strumenti nel tuo agente con meno di 10 righe di codice, riutilizza gli strumenti tra più agenti o framework ed esegui il deployment più facilmente di nuove versioni degli strumenti.
- Prestazioni migliori: best practice come il pooling delle connessioni, l'autenticazione e altro ancora.
- Maggiore sicurezza: autenticazione integrata per un accesso più sicuro ai tuoi dati
- Osservabilità end-to-end: metriche e tracciamento preconfigurati con supporto integrato per OpenTelemetry.
Toolbox si trova tra il framework di orchestrazione dell'applicazione e il database, fornendo un control plane utilizzato per modificare, distribuire o richiamare gli strumenti. Semplifica la gestione degli strumenti fornendoti una posizione centralizzata per archiviarli e aggiornarli, consentendoti di condividerli tra agenti e applicazioni e di aggiornarli senza dover necessariamente eseguire nuovamente il deployment dell'applicazione.
Puoi notare che uno dei database supportati da MCP Toolbox for Databases è Cloud SQL, che abbiamo eseguito il provisioning nella sezione precedente.
Installare la cassetta degli attrezzi
Apri il terminale Cloud Shell e crea una cartella denominata mcp-toolbox.
mkdir mcp-toolbox
Vai alla cartella mcp-toolbox tramite il comando mostrato di seguito:
cd mcp-toolbox
Installa la versione binaria di MCP Toolbox for Databases tramite lo script riportato di seguito. Il comando riportato di seguito è per Linux, ma se utilizzi Mac o Windows, assicurati di scaricare il file binario corretto. Consulta la pagina delle release per il tuo sistema operativo e la tua architettura e scarica il file binario corretto.
export VERSION=0.13.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Ora abbiamo la versione binaria del toolbox pronta per l'uso. Il passaggio successivo consiste nel configurare la casella degli strumenti con le nostre origini dati e altre configurazioni.
Configurazione di tools.yaml
Il modo principale per configurare Toolbox è tramite il file tools.yaml. Crea un file denominato tools.yaml nella stessa cartella, ovvero mcp-toolbox, il cui contenuto è mostrato di seguito.
Puoi utilizzare l'editor nano disponibile in Cloud Shell. Il comando nano è il seguente: "nano tools.yaml".
Ricorda di sostituire il valore YOUR_PROJECT_ID con l'ID progetto Google Cloud.
sources:
my-cloud-sql-source:
kind: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: "postgres"
tools:
search-hotels-by-name:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
search-hotels-by-location:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Descrivici brevemente il file:
Sourcesrappresentano le diverse origini dati con cui uno strumento può interagire. Un'origine rappresenta un'origine dati con cui uno strumento può interagire. Puoi definireSourcescome mappa nella sezione delle origini del file tools.yaml. In genere, una configurazione dell'origine contiene tutte le informazioni necessarie per connettersi al database e interagire con esso. Nel nostro caso, abbiamo configurato una singola origine che punta alla nostra istanza Cloud SQL per PostgreSQL con le credenziali. Per ulteriori informazioni, consulta il riferimento Fonti.Toolsdefiniscono le azioni che un agente può intraprendere, ad esempio leggere e scrivere in un'origine. Uno strumento rappresenta un'azione che l'agente può intraprendere, ad esempio l'esecuzione di un'istruzione SQL. Puoi definireToolscome mappa nella sezione degli strumenti del file tools.yaml. In genere, uno strumento richiede un'origine su cui agire. Nel nostro caso, definiamo due strumenti:search-hotels-by-nameesearch-hotels-by-locatione specifichiamo l'origine su cui agisce, insieme a SQL e ai parametri. Per ulteriori informazioni, consulta il riferimento Strumenti.- Infine, abbiamo
Toolset, che ti consente di definire gruppi di strumenti che vuoi poter caricare insieme. Può essere utile per definire gruppi diversi in base all'agente o all'applicazione. Nel nostro caso, abbiamo un unico insieme di strumenti chiamatomy_first_toolset, che contiene i due strumenti che abbiamo definito.
Esegui il server MCP Toolbox for Databases
Esegui il comando seguente (dalla cartella mcp-toolbox) per avviare il server:
./toolbox --tools-file "tools.yaml"
Idealmente, dovresti visualizzare un output che indica che il server è riuscito a connettersi alle nostre origini dati e ha caricato il set di strumenti e gli strumenti. Di seguito è riportato un output di esempio:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
Per impostazione predefinita, il server MCP Toolbox viene eseguito sulla porta 5000. Se scopri che la porta 5000 è già in uso, puoi utilizzare un'altra porta (ad esempio 7000) come indicato nel comando riportato di seguito. Utilizza 7000 anziché la porta 5000 nei comandi successivi.
./toolbox --tools-file "tools.yaml" --port 7000
Utilizziamo Cloud Shell per testare questa funzionalità.
Fai clic su Anteprima web in Cloud Shell come mostrato di seguito:
Fai clic su Cambia porta e imposta la porta su 5000 come mostrato di seguito, poi fai clic su Cambia e visualizza anteprima.
Dovrebbe essere visualizzato il seguente output:
Nell'URL del browser, aggiungi quanto segue alla fine dell'URL:
/api/toolset
Dovresti visualizzare gli strumenti attualmente configurati. Di seguito è riportato un output di esempio:
{
"serverVersion": "0.13.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location. Result is sorted by price from least to most expensive.",
"parameters": [
{
"name": "location",
"type": "string",
"required": true,
"description": "The location of the hotel.",
"authSources": []
}
],
"authRequired": []
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"required": true,
"description": "The name of the hotel.",
"authSources": []
}
],
"authRequired": []
}
}
}
Testare gli strumenti tramite la UI di MCP Toolbox for Databases
Toolbox fornisce un'interfaccia visiva (interfaccia utente di Toolbox) per interagire direttamente con gli strumenti modificando i parametri, gestendo le intestazioni ed eseguendo le chiamate, il tutto all'interno di una semplice interfaccia utente web.
Se vuoi provarlo, puoi eseguire il comando precedente che abbiamo utilizzato per avviare Toolbox Server con l'opzione --ui.
Per farlo, arresta l'istanza precedente di MCP Toolbox for Databases Server che potresti avere in esecuzione ed esegui il seguente comando:
./toolbox --tools-file "tools.yaml" --ui
Idealmente, dovresti visualizzare un output che indica che il server è riuscito a connettersi alle nostre origini dati e ha caricato il set di strumenti e gli strumenti. Di seguito è riportato un output di esempio. Noterai che viene indicato che la GUI di Toolbox è in esecuzione.
2025-09-08T02:44:11.561572538Z INFO "Initialized 1 sources."
2025-09-08T02:44:11.561966395Z INFO "Initialized 0 authServices."
2025-09-08T02:44:11.562060934Z INFO "Initialized 2 tools."
2025-09-08T02:44:11.562105678Z INFO "Initialized 2 toolsets."
2025-09-08T02:44:11.568209923Z INFO "Server ready to serve!"
2025-09-08T02:44:11.568259411Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui"
Fai clic sull'URL dell'interfaccia utente e assicurati di avere /ui alla fine dell'URL. Verrà visualizzata un'interfaccia utente come mostrato di seguito:
Fai clic sull'opzione Strumenti a sinistra per visualizzare gli strumenti configurati. Nel nostro caso, dovrebbero essere due, ovvero search-hotels-by-name e search-hotels-by-location, come mostrato di seguito:
Basta fare clic su uno degli strumenti (search-hotels-by-location) per visualizzare una pagina in cui testare lo strumento fornendo i valori dei parametri richiesti e poi fare clic su Esegui strumento per visualizzare il risultato. Di seguito è riportato un esempio di esecuzione:
MCP Toolkit for Databases descrive anche un modo Pythonic per convalidare e testare gli strumenti, documentato qui. Saltiamo questo passaggio e passiamo direttamente all'Agent Development Kit (ADK) nella sezione successiva, che utilizzerà questi strumenti.
6. Scrittura dell'agente con Agent Development Kit (ADK)
Installare l'Agent Development Kit (ADK)
Apri una nuova scheda del terminale in Cloud Shell e crea una cartella denominata my-agents nel seguente modo. Vai anche alla cartella my-agents.
mkdir my-agents
cd my-agents
Ora creiamo un ambiente Python virtuale utilizzando venv come segue:
python -m venv .venv
Attiva l'ambiente virtuale come segue:
source .venv/bin/activate
Installa i pacchetti ADK e MCP Toolbox for Databases insieme alla dipendenza langchain come segue:
pip install google-adk toolbox-core
Ora potrai richiamare l'utilità adk nel seguente modo.
adk
Verrà visualizzato un elenco di comandi.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Creazione della nostra prima applicazione con agente
Ora utilizzeremo adk per creare una struttura per la nostra applicazione Hotel Agent tramite il comando adk create con un nome dell'app **(hotel-agent-app)**come indicato di seguito.
adk create hotel-agent-app
Segui i passaggi e seleziona quanto segue:
- Modello Gemini per la scelta di un modello per l'agente principale.
- Scegli Vertex AI per il backend.
- Verranno visualizzati l'ID progetto Google e la regione predefiniti. Seleziona il valore predefinito.
Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel-agent-app:
- .env
- __init__.py
- agent.py
Osserva la cartella in cui sono stati creati un modello predefinito e i file richiesti per l'agente.
Il primo è il file .env. I cui contenuti sono mostrati di seguito:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
I valori indicano che utilizzeremo Gemini tramite Vertex AI insieme ai rispettivi valori per l'ID progetto Google Cloud e la posizione.
Poi c'è il file __init__.py che contrassegna la cartella come modulo e contiene una singola istruzione che importa l'agente dal file agent.py.
from . import agent
Infine, diamo un'occhiata al file agent.py. Di seguito sono riportati i contenuti:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Questo è l'agente più semplice che puoi scrivere con ADK. Dalla pagina della documentazione dell'ADK, un agente è un'unità di esecuzione autonoma progettata per agire in modo autonomo per raggiungere obiettivi specifici. Gli agenti possono svolgere attività, interagire con gli utenti, utilizzare strumenti esterni e coordinarsi con altri agenti.
In particolare, un LLMAgent, comunemente indicato con l'alias Agent, utilizza modelli linguistici di grandi dimensioni (LLM) come motore principale per comprendere il linguaggio naturale, ragionare, pianificare, generare risposte e decidere in modo dinamico come procedere o quali strumenti utilizzare, il che lo rende ideale per attività flessibili e incentrate sul linguaggio. Scopri di più sugli agenti LLM qui.
Modifichiamo il codice per agent.py nel seguente modo:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='hotel_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
Testare l'app Agente in locale
Dalla finestra del terminale esistente, esegui il comando seguente. Assicurati di trovarti nella cartella principale (my-agents) contenente la cartella hotel-agent-app.
adk web
Di seguito è riportato un esempio di esecuzione:
INFO: Started server process [1478]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Fai clic sull'ultimo link per visualizzare una console web per testare l'agente. Dovresti visualizzare quanto segue nel browser, come mostrato di seguito:
Nota che in alto a sinistra è stato identificato il hotel-agent-app. Ora puoi iniziare a conversare con l'agente. Fornisci alcuni prompt che chiedono informazioni sulle città. Di seguito è riportata una conversazione di esempio:
Puoi arrestare il processo in esecuzione nel terminale Cloud Shell (Ctrl+C).
Un altro modo per testare l'agente è tramite il comando adk run, come indicato di seguito dalla cartella my-agents.
adk run hotel-agent-app
Prova il comando e potrai conversare con l'agente tramite la riga di comando (terminale). Digita exit per chiudere la conversazione.
7. Connessione dell'agente agli strumenti
Ora che sappiamo come scrivere un agente e testarlo localmente. Collegheremo questo agente a Strumenti. Nel contesto dell'ADK, uno strumento rappresenta una funzionalità specifica fornita a un agente AI, che gli consente di eseguire azioni e interagire con il mondo al di là delle sue capacità di generazione di testo e ragionamento di base.
Nel nostro caso, doteremo l'agente degli strumenti che abbiamo configurato in MCP Toolbox per i database.
Modifica il file agent.py con il seguente codice. Tieni presente che nel codice viene utilizzata la porta predefinita 5000, ma se utilizzi un numero di porta alternativo, utilizza quello.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-2.5-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
Ora possiamo testare l'agente che recupererà i dati reali dal nostro database PostgreSQL configurato con MCP Toolbox for Databases.
Per farlo, segui questa sequenza:
In un terminale di Cloud Shell, avvia MCP Toolbox for Databases. Potresti già averlo in esecuzione localmente sulla porta 5000, come abbiamo testato in precedenza. In caso contrario, esegui il seguente comando (dalla cartella mcp-toolbox) per avviare il server:
./toolbox --tools_file "tools.yaml"
Idealmente, dovresti visualizzare un output che indica che il server è riuscito a connettersi alle nostre origini dati e ha caricato il set di strumenti e gli strumenti. Di seguito è riportato un output di esempio:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
Una volta avviato correttamente il server MCP, in un altro terminale avvia l'agente come abbiamo fatto in precedenza tramite il comando adk run (dalla cartella my-agents) mostrato di seguito. Se vuoi, puoi anche utilizzare il comando adk web.
$ adk run hotel-agent-app/
Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
Nota che l'agente ora utilizza i due strumenti che abbiamo configurato in MCP Toolbox per i database (search-hotels-by-name e search-hotels-by-location) e ci fornisce le opzioni corrette. In questo modo, può recuperare facilmente i dati dal database dell'istanza PostgreSQL e formattare la risposta di conseguenza.
In questo modo si completa lo sviluppo e il test locali del nostro agente di hotel che abbiamo creato utilizzando l'Agent Development Kit (ADK) e che è stato alimentato da strumenti che abbiamo configurato in MCP Toolbox for Databases.
8. (Facoltativo) Deployment di MCP Toolbox for Databases e dell'agente in Cloud Run
Nella sezione precedente, abbiamo utilizzato il terminale Cloud Shell per avviare il server MCP Toolbox e abbiamo testato gli strumenti con l'agente. che veniva eseguito localmente nell'ambiente Cloud Shell.
Hai la possibilità di eseguire il deployment sia del server MCP Toolbox sia dell'agente nei servizi Google Cloud che possono ospitare queste applicazioni per nostro conto.
Ospitare il server MCP Toolbox su Cloud Run
Per prima cosa, possiamo iniziare con il server MCP Toolbox e ospitarlo su Cloud Run. In questo modo avremo un endpoint pubblico che potremo integrare con qualsiasi altra applicazione e/o con le applicazioni dell'agente. Le istruzioni per l'hosting su Cloud Run sono disponibili qui. Ora esamineremo i passaggi chiave.
Avvia un nuovo terminale Cloud Shell o utilizzane uno esistente. Vai alla cartella mcp-toolbox, in cui sono presenti il binario toolbox e tools.yaml.
Esegui i seguenti comandi (per ognuno è fornita una spiegazione):
Imposta la variabile PROJECT_ID in modo che punti al tuo ID progetto Google Cloud.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Successivamente, verifica che i seguenti servizi Google Cloud siano abilitati nel progetto.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Creiamo un service account separato che fungerà da identità per il servizio Toolbox che verrà sottoposto a deployment su Google Cloud Run. Ci assicuriamo inoltre che questo service account disponga dei ruoli corretti, ovvero la possibilità di accedere a Secret Manager e comunicare con Cloud SQL.
gcloud iam service-accounts create toolbox-identity
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/cloudsql.client
Caricheremo il file tools.yaml come secret e, poiché dobbiamo installare Toolbox in Cloud Run, utilizzeremo l'immagine container più recente per Toolbox e la imposteremo nella variabile IMAGE.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
L'ultimo passaggio del comando di deployment familiare in Cloud Run:
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
In questo modo dovrebbe iniziare il processo di deployment del server Toolbox con il nostro tools.yaml configurato su Cloud Run. Se il deployment va a buon fine, dovresti visualizzare un messaggio simile al seguente:
Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app
Ora puoi visitare la pagina Service URL elencata sopra nel browser. Dovrebbe essere visualizzato il messaggio "Hello World" che abbiamo visto in precedenza. Inoltre, puoi visitare il seguente URL per visualizzare gli strumenti disponibili:
SERVICE URL/api/toolset
Puoi anche visitare Cloud Run dalla console Google Cloud e vedrai il servizio Toolbox disponibile nell'elenco dei servizi in Cloud Run.
Nota: se vuoi continuare a eseguire l'agente hotel localmente e connetterti al servizio Cloud Run appena implementato, devi apportare una sola modifica al file my-agents/hotel-agent-app/agent.py.
Invece di quanto segue:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Modificalo con l'URL del servizio Cloud Run come indicato di seguito:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
Prova l'applicazione dell'agente utilizzando adk run o adk web, come abbiamo visto in precedenza.
Esecuzione del deployment dell'app Hotel Agent su Cloud Run
Il primo passaggio consiste nell'assicurarsi di aver apportato la modifica in my-agents/hotel-agent-app/agent.py come indicato sopra per puntare all'URL del servizio Toolbox in esecuzione su Cloud Run e non su localhost.
In un nuovo terminale Cloud Shell o in una sessione del terminale esistente, assicurati di trovarti nell'ambiente Python virtuale corretto che abbiamo configurato in precedenza.
Per prima cosa, creiamo un file requirements.txt nella cartella my-agents/hotel-agent-app come mostrato di seguito:
google-adk
toolbox-core
Vai alla cartella my-agents e impostiamo prima le seguenti variabili di ambiente:
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel-agent-app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
export GOOGLE_GENAI_USE_VERTEXAI=True
Infine, eseguiamo il deployment dell'applicazione agente su Cloud Run tramite il comando adk deploy cloud_run come indicato di seguito. Se ti viene chiesto di consentire chiamate non autenticate al servizio, per il momento fornisci "y" come valore.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
Verrà avviato il processo di deployment dell'applicazione Hotel Agent su Cloud Run. Caricherà le origini, le pacchettizzerà in un container Docker, eseguirà il push su Artifact Registry e poi eseguirà il deployment del servizio su Cloud Run. L'operazione potrebbe richiedere alcuni minuti.
Dovresti visualizzare un messaggio simile al seguente:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250905_132636
Copying agent source code...
Copying agent source code completed.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250905_132636/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_PROJECT_ID] region [us-central1]
- Building and deploying... Uploading sources.
- Uploading sources...
. Building Container...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/d1f7e76b-0587-4bb6-b9c0-bb4360c07aa0?project=415
458962931]. f
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00003-hrl] has been deployed and is serving 100 percent of traffic.
Service URL: <YOUR_CLOUDRUN_APP_URL>
INFO: Display format: "none"
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250905_132636
In caso di deployment riuscito, ti verrà fornito un valore per l'URL del servizio, a cui potrai accedere nel browser per visualizzare la stessa applicazione web che ti ha permesso di chattare con l'agente dell'hotel, come abbiamo visto in precedenza nella configurazione locale.
9. Esegui la pulizia
Per evitare addebiti continui al tuo account Google Cloud, è importante eliminare le risorse che abbiamo creato durante questo workshop. Elimineremo l'istanza Cloud SQL e, facoltativamente, se hai eseguito il deployment di Toolbox e dell'app Hotels su Cloud Run, elimineremo anche questi servizi.
Assicurati che le seguenti variabili di ambiente siano impostate correttamente, in base al progetto e alla regione:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
I due comandi seguenti eliminano i servizi Cloud Run di cui abbiamo eseguito il deployment:
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
Il comando seguente elimina l'istanza Cloud SQL:
gcloud sql instances delete hoteldb-instance
10. Complimenti
Congratulazioni, hai creato correttamente un agente utilizzando l'Agent Development Kit (ADK) che utilizza MCP Toolbox for Databases.