1. Introduzione
In questo codelab, utilizzerai MCP Toolbox for Databases per rendere disponibili i tuoi set di dati BigQuery.
Nel codelab, seguirai un approccio passo passo come segue:
- Identifica un set di dati BigQuery specifico ("Note di rilascio di Google Cloud") dal programma per i set di dati pubblici BigQuery.
- Configura MCP Toolbox for Databases, che si connette al set di dati BigQuery.
- Sviluppa un agente utilizzando l'Agent Development Kit (ADK) che utilizzerà MCP Toolbox per rispondere alle query dell'utente sulle note di rilascio di Google Cloud
Attività previste
- Configura MCP Toolbox for Databases per esporre le note di rilascio di Google Cloud, un set di dati BigQuery pubblico, come interfaccia MCP ad altri client MCP (IDE, strumenti e così via).
Cosa imparerai a fare
- Esplora i set di dati pubblici BigQuery e scegli un set di dati specifico.
- Configura MCP Toolbox for Databases per il set di dati pubblico BigQuery che vogliamo rendere disponibile ai clienti MCP.
- 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.
Che cosa ti serve
- Browser web Chrome.
- Un ambiente di sviluppo Python locale.
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>
Consulta la documentazione per i comandi e l'utilizzo di gcloud.
3. Set di dati delle note di rilascio di Google e clienti MCP
Per prima cosa, diamo un'occhiata alle note di rilascio di Google Cloud, che vengono aggiornate regolarmente nella pagina web ufficiale delle note di rilascio di Google Cloud, di cui è mostrato uno screenshot di seguito:
Potresti abbonarti all'URL del feed, ma cosa succederebbe se potessimo semplicemente chiedere nella chat con l'agente informazioni su queste note di rilascio? Magari una semplice query come "Aggiornami sulle note di rilascio di Google Cloud".
4. MCP Toolbox for Databases
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 semplifica la connessione dei database a qualsiasi assistente AI compatibile con MCP, anche a quelli presenti nell'IDE.
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.
Per riassumere in parole semplici:
- MCP Toolbox è disponibile come binario, immagine container oppure puoi compilarlo dal codice sorgente.
- Espone un insieme di strumenti che configuri tramite un file tools.yaml. Gli strumenti possono essere considerati come connessioni alle origini dati. Puoi visualizzare le varie origini dati supportate : AlloyDB, BigQuery e così via.
- Poiché questo toolkit ora supporta MCP, hai automaticamente un endpoint del server MCP che può essere utilizzato dagli agenti (IDE) oppure puoi utilizzarli durante lo sviluppo delle applicazioni di agenti utilizzando vari framework come Agent Development Kit (ADK).
In questo post del blog ci concentreremo sulle aree evidenziate di seguito:
In sintesi, creeremo una configurazione in MCP Toolbox for Databases che sappia come connettersi al nostro set di dati BigQuery. Svilupperemo quindi un agente utilizzando Agent Development Kit (ADK) che si integrerà con l'endpoint di MCP Toolbox e ci consentirà di inviare query naturali per porre domande sul nostro set di dati. Considerala come un'applicazione autonoma che stai sviluppando, che sa come comunicare con il tuo set di dati BigQuery ed esegue alcune query.
5. Set di dati BigQuery per le note di rilascio di Google Cloud
Il programma per i set di dati pubblici di Google Cloud è un programma che rende disponibile una serie di set di dati per le tue applicazioni. Uno di questi set di dati è il database delle note di rilascio di Google Cloud. Questo set di dati fornisce le stesse informazioni della pagina web ufficiale delle note di rilascio di Google Cloud ed è disponibile come set di dati interrogabile pubblicamente.
Come test, convalido semplicemente il set di dati eseguendo una semplice query mostrata di seguito:
SELECT
product_name,description,published_at
FROM
`bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
WHERE
DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY product_name,description,published_at
ORDER BY published_at DESC
In questo modo ottengo un elenco di record del set di dati Note di rilascio pubblicati negli ultimi 7 giorni.
Sostituiscilo con qualsiasi altro set di dati a tua scelta e con le rispettive query e parametri che preferisci. Ora non ci resta che configurarlo come origine dati e strumento in MCP Toolbox for Databases. Vediamo come fare.
6. Installazione di MCP Toolbox for Databases
Apri un terminale sulla tua macchina locale 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.
7. Configurazione di MCP Toolbox for Databases
Ora dobbiamo definire il set di dati e gli strumenti BigQuery nel file tools.yaml
necessario per MCP Toolbox for Database. Il file tools.yaml
è il modo principale per configurare Toolbox.
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-bq-source:
kind: bigquery
project: YOUR_PROJECT_ID
tools:
search_release_notes_bq:
kind: bigquery-sql
source: my-bq-source
statement: |
SELECT
product_name,description,published_at
FROM
`bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
WHERE
DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY product_name,description,published_at
ORDER BY published_at DESC
description: |
Use this tool to get information on Google Cloud Release Notes.
toolsets:
my_bq_toolset:
- search_release_notes_bq
Descrivici brevemente il file:
- Le origini rappresentano le diverse origini dati con cui uno strumento può interagire. Un'origine rappresenta un'origine dati con cui uno strumento può interagire. Puoi definire le origini come una 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 definito un'origine BigQuery
my-bq-source
e devi fornire l'ID progetto Google Cloud. Per ulteriori informazioni, consulta il riferimento Fonti. - Gli strumenti definiscono le azioni che un agente può intraprendere, ad esempio leggere e scrivere in una sorgente. Uno strumento rappresenta un'azione che l'agente può intraprendere, ad esempio l'esecuzione di un'istruzione SQL. Puoi definire gli strumenti come una mappa nella sezione degli strumenti del file tools.yaml. In genere, uno strumento richiede un'origine su cui agire. Nel nostro caso, definiamo un unico strumento
search_release_notes_bq
. Questo fa riferimento all'origine BigQuerymy-bq-source
che abbiamo definito nel primo passaggio. Contiene anche l'affermazione e l'istruzione che verranno utilizzate dai client AI Agent. Per ulteriori informazioni, consulta il riferimento Strumenti. - Infine, abbiamo il 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 una definizione del set di strumenti in cui al momento abbiamo definito solo uno strumento esistente
search_release_notes_bq
. Puoi avere più di un insieme di strumenti, che include una combinazione di strumenti diversi.
Al momento, quindi, abbiamo definito un solo strumento che recupera le note di rilascio degli ultimi 7 giorni in base alla query. Tuttavia, puoi avere anche varie combinazioni con i parametri.
Consulta altri dettagli di configurazione ( Origine, Strumenti) nella configurazione dell'origine dati BigQuery in MCP Toolbox for Databases.
8. Test di MCP Toolbox per i database
Abbiamo scaricato e configurato Toolbox con il file tools.yaml
nella cartella mcp-toolbox
. Eseguiamolo prima in locale.
Esegui questo comando:
./toolbox --tools-file="tools.yaml"
Se l'esecuzione va a buon fine, dovresti vedere l'avvio del server con un output di esempio simile al seguente:
2025-09-08T03:56:45.772489914Z INFO "Initialized 1 sources."
2025-09-08T03:56:45.772682659Z INFO "Initialized 0 authServices."
2025-09-08T03:56:45.772735103Z INFO "Initialized 1 tools."
2025-09-08T03:56:45.772774639Z INFO "Initialized 2 toolsets."
2025-09-08T03:56:45.777711644Z 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_release_notes_bq": {
"description": "Use this tool to get information on Google Cloud Release Notes.\n",
"parameters": [],
"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-08T03:59:34.856476253Z INFO "Initialized 1 sources."
2025-09-08T03:59:34.856546526Z INFO "Initialized 0 authServices."
2025-09-08T03:59:34.856577586Z INFO "Initialized 1 tools."
2025-09-08T03:59:34.856641568Z INFO "Initialized 2 toolsets."
2025-09-08T03:59:34.86133344Z INFO "Server ready to serve!"
2025-09-08T03:59:34.861366205Z 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, dovrebbe essercene solo uno, ovvero search_release_notes_bq
, come mostrato di seguito:
Basta fare clic sugli strumenti (search_release_notes_bq
) per visualizzare una pagina in cui testare lo strumento. Poiché non ci sono parametri da fornire, puoi semplicemente 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.
9. 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:
--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 di base per l'applicazione agente delle note di rilascio di Google Cloud tramite il comando adk
create
con un nome dell'app **(gcp-releasenotes-agent-app)
**come indicato di seguito.
adk create gcp-releasenotes-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 [YOUR_GOOGLE_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in ../my-agents/gcp-releasenotes-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.0-flash-001',
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.
In questo modo, lo scaffolding per generare un agente di base utilizzando Agent Development Kit (ADK) è completato. Ora collegheremo il nostro agente alla casella degli strumenti MCP, in modo che possa utilizzare questo strumento per rispondere alle query dell'utente (in questo caso, saranno le note di rilascio di Google Cloud).
10. Connessione dell'agente agli strumenti
Ora collegheremo questo agente agli 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 all the tools
tools = toolbox.load_toolset('my_bq_toolset')
root_agent = Agent(
name="gcp_releasenotes_agent",
model="gemini-2.0-flash",
description=(
"Agent to answer questions about Google Cloud Release notes."
),
instruction=(
"You are a helpful agent who can answer user questions about the Google Cloud Release notes. Use the tools to answer the question"
),
tools=tools,
)
Ora possiamo testare l'agente che recupererà i dati reali dal nostro set di dati BigQuery 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:
./toolbox --tools-file "tools.yaml"
2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources."
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices."
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools."
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets."
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!"
Una volta avviato correttamente il server MCP, in un altro terminale avvia l'agente tramite il comando adk run
(dalla cartella my-agents
) mostrato di seguito. Se vuoi, puoi anche utilizzare il comando adk web
.
$ adk run gcp-releasenotes-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 gcp_releasenotes_agent, type exit to exit.
[user]: get me the google cloud release notes
[gcp_releasenotes_agent]: Here are the Google Cloud Release Notes.
Google SecOps SOAR: Release 6.3.49 is being rolled out to the first phase of regions. This release contains internal and customer bug fixes. Published: 2025-06-14
Compute Engine: Dynamic NICs let you add or remove network interfaces to or from an instance without having to restart or recreate the instance. You can also use Dynamic NICs when you need more network interfaces. The maximum number of vNICs for most machine types in Google Cloud is 10; however, you can configure up to 16 total interfaces by using Dynamic NICs. Published: 2025-06-13
Compute Engine: General purpose C4D machine types, powered by the fifth generation AMD EPYC processors (Turin) and Google Titanium, are generally available. Published: 2025-06-13
Google Agentspace: Google Agentspace Enterprise: App-level feature management. As an Agentspace administrator, you can choose to turn the following features on or off for your end users in the web app: Agents gallery, Prompt gallery, No-code agent, NotebookLM Enterprise. Published: 2025-06-13
Cloud Load Balancing: Cloud Load Balancing supports load balancing to multi-NIC instances that use Dynamic NICs. This capability is in Preview. Published: 2025-06-13
Virtual Private Cloud: Dynamic Network Interfaces (NICs) are available in Preview. Dynamic NICs let you update an instance to add or remove network interfaces without having to restart or recreate the instance. Published: 2025-06-13
Security Command Center: The following Event Threat Detection detectors for Vertex AI have been released to Preview:
- `Persistence: New Geography for AI Service`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Admin Activity`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Data Access`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Admin Activity`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Data Access`
- `Privilege Escalation: Anomalous Impersonation of Service Account for AI Admin Activity`
- `Persistence: New AI API Method`
......
......
Tieni presente che l'agente utilizza lo strumento che abbiamo configurato in MCP Toolbox for Databases (search_release_notes_bq
) e recupera i dati dal set di dati BigQuery e formatta la risposta di conseguenza.
11. Complimenti
Congratulazioni, hai configurato correttamente MCP Toolbox for Databases e un set di dati BigQuery per l'accesso all'interno dei client MCP.