Crea un agente di viaggio utilizzando MCP Toolbox per i database e Agent Development Kit (ADK)
Informazioni su questo codelab
1. Introduzione
In questo codelab, creerai un agente utilizzando l'Agent Development Kit (ADK) che utilizza la MCP Toolbox for Databases.
Nel codelab, utilizzerai un approccio passo passo come segue:
- Provisiona un database Cloud SQL per PostgreSQL che conterrà il database degli hotel e i dati di esempio.
- Configura MCP Toolbox per i database, che fornisce l'accesso ai dati.
- Progetta e sviluppa un agente utilizzando l'Agent Development Kit (ADK) che utilizzerà la cassetta degli attrezzi MCP per rispondere alle query dell'utente.
- Esplora le opzioni per testare l'Agent e la Toolbox MCP per i database localmente e su Google Cloud tramite il servizio Cloud Run.
Attività previste
- Progetta, crea e implementa un agente che risponda alle query degli utenti sugli hotel in una località o che cerchi hotel per nome.
Cosa imparerai a fare
- Esegui il provisioning e compila 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 l'Agent Development Kit (ADK) per rispondere alle query degli utenti.
- Testa la cassetta degli attrezzi dell'agente e dell'MCP per i database nell'ambiente locale.
- (Facoltativo) Esegui il deployment di Agent e MCP Toolbox per i database in Google Cloud.
Che cosa ti serve
- Browser web Chrome
- Un account Gmail
- Un progetto Cloud con la fatturazione abilitata
Questo codelab, progettato per sviluppatori di tutti i livelli (inclusi i principianti), utilizza Python nella sua applicazione di esempio. Tuttavia, la conoscenza di Python non è necessaria 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 è attivata in 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 connesso a Cloud Shell, verifica di aver già eseguito l'autenticazione e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:
gcloud auth list
- Esegui il seguente 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
Al termine dell'esecuzione del comando, dovresti visualizzare un messaggio simile a quello mostrato di seguito:
Operation "operations/..." finished successfully.
L'alternativa al comando gcloud è tramite la console cercando ciascun prodotto o utilizzando questo link.
Se manca un'API, puoi sempre attivarla 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 dei nostri 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 sulla piattaforma Google Cloud.
Esegui il comando seguente in Cloud Shell per creare l'istanza:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--cpu=2 \
--memory=8GiB \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
L'esecuzione di questo comando richiede circa 3-5 minuti. Una volta eseguito 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 Hotel
Ora dobbiamo creare alcuni dati di esempio per il nostro agente hotel.
Vai alla 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:
Nel menu a sinistra di Cloud SQL, vai all'opzione di menu Cloud SQL Studio come mostrato di seguito:
Ti verrà chiesto di accedere a Cloud SQL Studio tramite il quale daremo alcuni comandi SQL. Seleziona postgres per l'opzione Database e per Utente e Password, il valore da utilizzare è postgres. Fai clic su AUTHENTICATE.
Creiamo innanzitutto la tabella 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 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-22', '2024-04-20', 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-24', '2024-04-05', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', 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 SELECT SQL come mostrato di seguito:
SELECT * FROM hotels;
Nella tabella hotels dovresti vedere una serie di record come mostrato di seguito:
Abbiamo completato la procedura di configurazione di un'istanza Cloud SQL e abbiamo creato i dati di esempio. Nella sezione successiva, configureremo la cassetta degli attrezzi MCP per i database.
5. Configurare Toolbox MCP per i database
MCP Toolbox for Databases è un server MCP open source per i database. È stato progettato per garantire qualità di produzione e di livello enterprise. Ti consente di sviluppare strumenti in modo più semplice, rapido e sicuro gestendo complessità come il pooling delle connessioni, l'autenticazione e altro ancora.
Toolbox ti aiuta a creare strumenti di IA generativa che consentono ai tuoi agenti di accedere ai dati nel tuo database. Toolbox fornisce:
- Sviluppo semplificato: integra gli strumenti nell'agente in meno di 10 righe di codice, riutilizza gli strumenti tra più agenti o framework ed esegui più facilmente il deployment di nuove versioni degli strumenti.
- Miglioramento delle prestazioni: best practice come il pooling delle connessioni, l'autenticazione e altro ancora.
- Maggiore sicurezza: autenticazione integrata per un accesso più sicuro ai dati
- Osservabilità end-to-end: metriche e monitoraggio immediati con il supporto integrato di OpenTelemetry.
Toolbox si trova tra il framework di orchestrazione dell'applicazione e il database e fornisce un piano di controllo utilizzato per modificare, distribuire o richiamare gli strumenti. Semplifica la gestione degli strumenti fornendoti un luogo centralizzato per archiviarli e aggiornarli, consentendoti di condividerli tra agenti e applicazioni e di aggiornarli senza necessariamente eseguire nuovamente il deployment dell'applicazione.
Puoi vedere che uno dei database supportati da MCP Toolbox for Databases è Cloud SQL e che ne 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:
export VERSION=0.6.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Ora abbiamo la versione binaria della cassetta degli attrezzi pronta per l'uso. Il passaggio successivo consiste nel configurare la cassetta degli attrezzi 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, i cui contenuti sono riportati 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 il tuo 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.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Ecco una breve descrizione del 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 sources 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 la sezione di riferimento Origini.Toolsdefiniscono le azioni che un agente può eseguire, ad esempio la lettura e la scrittura in un'origine. Uno strumento rappresenta un'azione che l'agente può intraprendere, ad esempio l'esecuzione di un'istruzione SQL. Puoi definireToolscome una mappa nella sezione degli strumenti del file tools.yaml. In genere, uno strumento richiede un'origine su cui intervenire. Nel nostro caso, stiamo definendo due strumenti:search-hotels-by-nameesearch-hotels-by-locatione specificando la sorgente su cui agiscono, insieme a SQL e ai parametri. Per ulteriori informazioni, consulta la sezione di riferimento Strumenti.- Infine, abbiamo
Toolset, che ti consente di definire gruppi di strumenti che vuoi poter caricare insieme. Questo può essere utile per definire gruppi diversi in base all'agente o all'applicazione. Nel nostro caso, abbiamo un unico set di strumenti chiamatomy_first_toolset, che contiene i due strumenti che abbiamo definito.
Esegui il server MCP Toolbox for Databases
Esegui il seguente comando (dalla cartella mcp-toolbox) per avviare il server:
./toolbox --tools-file "tools.yaml"
Idealmente, dovresti vedere un output che indica che il server è stato in grado di connettersi alle nostre origini dati e ha caricato lo strumento e gli strumenti. Di seguito è riportato un output di esempio:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
Per impostazione predefinita, il server MCP Toolbox viene eseguito sulla porta 5000. Se la porta 5000 è già in uso, non esitare a utilizzare un'altra porta (ad esempio 7000) come indicato nel comando di seguito. Utilizza 7000 anziché la porta 5000 nei comandi successivi.
./toolbox --tools-file "tools.yaml" --port 7000
Utilizziamo Cloud Shell per provarlo.
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.
Dovresti visualizzare 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.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location.",
"parameters": [
{
"name": "location",
"type": "string",
"description": "The location of the hotel.",
"authSources": []
}
]
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"description": "The name of the hotel.",
"authSources": []
}
]
}
}
}
MCP Toolkit for Databases descrive un modo in Python per convalidare e testare gli strumenti, la cui documentazione è disponibile qui. Salteremo questo passaggio e passeremo direttamente all'Agent Development Kit (ADK) nella sezione successiva, che utilizzerà questi strumenti.
6. Scrittura del nostro agente con Agent Development Kit (ADK)
Installa l'Agent Development Kit (ADK)
Apri una nuova scheda del terminale in Cloud Shell e crea una cartella denominata my-agents come segue. Vai anche alla cartella my-agents.
mkdir my-agents
cd my-agents
Ora, crea 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:
--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 prima applicazione agente
Ora utilizzeremo adk per creare uno scheletro per la nostra applicazione agente di hotel 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.0-flash-001
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 [gcp-experiments-349209]:
Enter Google Cloud region [us-central1]:
Agent created in /home/romin/hotel-agent-app:
- .env
- __init__.py
- agent.py
Controlla la cartella in cui sono stati creati un modello predefinito e i file richiesti per l'agente.
Innanzitutto, il file .env. I cui contenuti sono riportati 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 e la posizione di Google Cloud.
Poi abbiamo il file __init__.py che contrassegna la cartella come modulo e contiene un'unica istruzione che importa l'agente dal file agent.py.
from . import agent
Infine, diamo un'occhiata al file agent.py. I contenuti sono riportati di seguito:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Si tratta dell'agente più semplice che puoi scrivere con ADK. Nella pagina della documentazione ADK, un agente è un'unità di esecuzione autosufficiente progettata per agire in modo autonomo al fine di raggiungere obiettivi specifici. Gli agenti possono eseguire attività, interagire con gli utenti, utilizzare strumenti esterni e coordinarsi con altri agenti.
Nello specifico, un LLMAgent, comunemente noto come Agent, utilizza i modelli linguistici di grandi dimensioni (LLM) come motore principale per comprendere il linguaggio naturale, ragionare, pianificare, generare risposte e decidere dinamicamente come procedere o quali strumenti utilizzare, il che li rende ideali per attività flessibili incentrate sul linguaggio. Scopri di più sugli agenti LLM qui.
Modifichiamo il codice per agent.py come segue:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
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.',
)
Testa l'app agente localmente
Dalla finestra del terminale esistente, dai il seguente comando. Assicurati di trovarti nella cartella principale (my-agents) contenente la cartella hotel-agent-app.
adk web
Di seguito è riportata un'esecuzione di esempio:
INFO: Started server process [5015]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
Fai clic sull'ultimo link per aprire una console web per testare l'agente. Dovresti vedere quanto segue nel browser, come mostrato di seguito:
Tieni presente che in alto a sinistra è stata identificata l'app hotel-agent. Ora puoi iniziare a parlare con l'agente. Fornisci alcuni prompt che richiedono informazioni sulle città. Di seguito è riportato un esempio di conversazione:
Puoi arrestare il processo in esecuzione nel terminale Cloud Shell (Ctrl-C).
Un modo alternativo per testare l'agente è tramite il comando adk run riportato di seguito dalla cartella my-agents.
adk run hotel-agent-app
Prova il comando e potrai interagire con l'agente tramite la riga di comando (terminale). Digita exit per chiudere la conversazione.
7. Collegamento del nostro agente agli strumenti
Ora che sappiamo come scrivere un agente e testarlo localmente, Collegheremo questo agente a Strumenti. Nel contesto di ADK, uno strumento rappresenta una funzionalità specifica fornita a un agente AI, che gli consente di eseguire azioni e interagire con il mondo oltre le sue capacità di ragionamento e generazione di testo di base.
Nel nostro caso, ora doteremo il nostro agente degli strumenti che abbiamo configurato nella cassetta degli attrezzi MCP per i database.
Modifica il file agent.py con il seguente codice. Tieni presente che nel codice utilizziamo la porta predefinita 5000, ma se utilizzi un numero di porta alternativo, utilizzalo.
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.0-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 la Toolbox MCP per i database.
Per farlo, segui questa sequenza:
In un terminale di Cloud Shell, avvia MCP Toolbox per i database. Potresti già averlo eseguito 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 vedere un output che indica che il server è stato in grado di connettersi alle nostre origini dati e ha caricato lo strumento e gli strumenti. Di seguito è riportato un output di esempio:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z 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.
Tieni presente che ora l'agente utilizza i due strumenti che abbiamo configurato nella cassetta degli attrezzi MCP per i database (search-hotels-by-name e search-hotels-by-location) e ci fornisce le opzioni corrette. È quindi in grado di recuperare facilmente i dati dal database dell'istanza PostgreSQL e formattare la risposta di conseguenza.
In questo modo, vengono completati lo sviluppo e il test locale del nostro agente hotel che abbiamo creato utilizzando l'Agent Development Kit (ADK) e che è stato basato su strumenti che abbiamo configurato nella cassetta degli attrezzi MCP per i database.
8. (Facoltativo) Esegui il deployment di MCP Toolbox per database e 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. L'app era in esecuzione 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 noi.
Hosting del server MCP Toolbox su Cloud Run
Innanzitutto, possiamo iniziare con il server MCP Toolbox e ospitarlo su Cloud Run. In questo modo avremo un endpoint pubblico che possiamo integrare con qualsiasi altra applicazione e/o anche con le applicazioni Agent. Le istruzioni per l'hosting su Cloud Run sono riportate 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 i file binari toolbox e tools.yaml.
Esegui i seguenti comandi (è fornita una spiegazione per ogni comando):
Imposta la variabile PROJECT_ID in modo che punti all'ID progetto Google Cloud.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Successivamente, verifica che i seguenti servizi Google Cloud siano attivati nel progetto.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Creiamo un account di servizio separato che fungerà da identità per il servizio Toolbox che eseguiremo su Google Cloud Run. Inoltre, ci assicuriamo che questo account di servizio 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 segreto e, poiché dobbiamo installare la cassetta degli attrezzi in Cloud Run, utilizzeremo l'immagine container più recente per la cassetta degli attrezzi 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
Dovrebbe iniziare la procedura di deployment del server Toolbox con il nostro tools.yaml configurato in Cloud Run. Al termine del deployment, 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 il sito Service URL elencato sopra nel browser. Dovresti visualizzare 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 Hotel Agent localmente e connetterti al servizio Cloud Run appena disegnato, devi apportare una sola modifica al file my-agents/hotel-agent-app/agent.py.
Invece di quanto segue:
toolbox = ToolboxTool("http://127.0.0.1:5000")
Sostituiscilo con l'URL del servizio Cloud Run come indicato di seguito:
toolbox = ToolboxTool("CLOUD_RUN_SERVICE_URL")
Prova l'applicazione agente utilizzando adk run o adk web, come abbiamo visto in precedenza.
Eseguire il 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 in modo che indichi l'URL del servizio Toolbox in esecuzione su Cloud Run e non sull'host locale.
In un nuovo terminale Cloud Shell o in una sessione del terminale esistente, assicurati di trovarti nell'ambiente virtuale Python corretto che abbiamo configurato in precedenza.
Per prima cosa, crea 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 imposta 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, esegui il deployment dell'applicazione agente in 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 in Cloud Run. Carica le origini, le pacchettizza in un contenitore Docker, le invia ad Artifact Registry e poi esegue 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/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
| Building and deploying... Uploading sources.
| Uploading sources...
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/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623
Al termine del deployment, 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 che al tuo account Google Cloud vengano addebitati costi, è 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 in 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 che abbiamo disegnato:
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-app --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
Il comando seguente elimina l'istanza Cloud SQL:
gcloud sql instances delete hoteldb-instance
10. Complimenti
Complimenti, hai creato correttamente un agente utilizzando l'Agent Development Kit (ADK) che utilizza la Toolbox MCP per i database.