Database come strumento: RAG agentica con ADK, MCP Toolbox e Cloud SQL

1. Introduzione

Gli agenti AI sono utili solo in base ai dati a cui possono accedere. La maggior parte dei dati reali si trova nei database e il collegamento degli agenti ai database in genere comporta la scrittura della gestione delle connessioni, della logica delle query e delle pipeline di incorporamento all'interno del codice dell'agente. Ogni agente che necessita dell'accesso al database ripete questa operazione e ogni modifica della query richiede il nuovo deployment dell'agente.

Questo codelab mostra un approccio diverso. Dichiari gli strumenti del database in un file YAML, ovvero query SQL standard, ricerca di somiglianza vettoriale e persino generazione automatica di embedding, e MCP Toolbox for Databases gestisce tutte le operazioni del database come server MCP. Il codice dell'agente rimane minimale: carica gli strumenti e lascia che Gemini decida quale chiamare.

Cosa creerai

Un assistente per bacheche di lavoro intelligenti per "TechJobs", un agente ADK basato su Gemini che aiuta gli sviluppatori a sfogliare gli annunci di lavoro nel settore tecnologico utilizzando filtri standard (ruolo, stack tecnologico) e a scoprire lavori tramite descrizioni in linguaggio naturale come "Voglio un lavoro da remoto che mi permetta di lavorare su chatbot AI". L'agente legge e scrive in un database Cloud SQL PostgreSQL interamente tramite MCP Toolbox for Databases, che gestisce tutto l'accesso al database, inclusa la generazione automatica di incorporamenti per la ricerca vettoriale. Alla fine, sia Toolbox che l'agente vengono eseguiti su Cloud Run.

Cosa imparerai a fare

In che modo MCP (Model Context Protocol) standardizza l'accesso agli strumenti per gli agenti AI e in che modo MCP Toolbox for Databases lo applica alle operazioni del database
Configura MCP Toolbox for Databases come middleware tra un agente ADK e Cloud SQL PostgreSQL
Definisci gli strumenti di database in modo dichiarativo in tools.yaml: nessun codice di database nell'agente
Crea un agente ADK che carica gli strumenti da un server Toolbox in esecuzione utilizzando ToolboxToolset
Genera vector embedding utilizzando la funzione embedding() integrata di Cloud SQL e abilita la ricerca semantica con pgvector
Utilizza la funzionalità valueFromParam per l'importazione automatica di vettori nelle operazioni di scrittura
Esegui il deployment sia del server Toolbox che dell'agente ADK in Cloud Run

Prerequisiti

Un account Google Cloud con un account di fatturazione di prova
Conoscenza di base di Python e SQL
Non è richiesta alcuna esperienza pregressa con ADK, MCP Toolbox o pgvector

2. Configura l'ambiente

NOTE IMPORTANTI:

Questo tutorial richiede un progetto Google Cloud con un account di fatturazione attivo. Se non ne hai ancora uno, segui i passaggi riportati di seguito per ottenere un account di fatturazione di prova che può essere utilizzato per questo tutorial:

Apri finestra di navigazione in incognito
Se partecipi a una sessione di workshop, l'URL del portale di utilizzo viene in genere fornito durante la sessione. In alternativa, puoi accedere a questo portale di utilizzo dell'account di fatturazione di prova.
Accedi utilizzando il tuo account Gmail personale ( le email di Google Workspace o di altri servizi non funzionano). )
Segui le istruzioni di utilizzo passo passo per creare un nuovo progetto Google Cloud collegato all'account di fatturazione di prova rivendicato in precedenza per questo tutorial.

Questo passaggio prepara l'ambiente Cloud Shell, configura il progetto Google Cloud e clona il repository di riferimento.

Apri Cloud Shell

Apri Cloud Shell nel browser. Cloud Shell fornisce un ambiente preconfigurato con tutti gli strumenti necessari per questo codelab. Quando richiesto, fai clic su Autorizza.

Poi fai clic su "Visualizza" -> "Terminale" per aprire il terminale.L'interfaccia dovrebbe avere un aspetto simile a questo

Questa sarà la nostra interfaccia principale, con l'IDE in alto e il terminale in basso.

Configurare la directory di lavoro

Crea la directory di lavoro. Tutto il codice che scrivi in questo codelab si trova qui:

mkdir -p ~/build-agent-adk-toolbox-cloudsql
cloudshell workspace ~/build-agent-adk-toolbox-cloudsql && cd ~/build-agent-adk-toolbox-cloudsql

Configura il progetto Google Cloud

Crea il file .env con le variabili di località:

# For Vertex AI / Gemini API calls
echo "GOOGLE_CLOUD_LOCATION=global" > .env
# For Cloud SQL, Cloud Run, Artifact Registry
echo "REGION=us-central1" >> .env

Scarica lo script di configurazione del progetto nella directory di lavoro:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

Esegui lo script. Verifica il tuo account di fatturazione di prova, crea un nuovo progetto (o ne convalida uno esistente), salva l'ID progetto in un file .env nella directory corrente e imposta il progetto attivo in gcloud.

bash setup_verify_trial_project.sh && source .env

Lo script:

Verificare di avere un account di fatturazione di prova attivo
Controlla se esiste un progetto in .env (se presente)
Crea un nuovo progetto o riutilizza quello esistente
Collega l'account di fatturazione di prova al tuo progetto
Salva l'ID progetto in .env
Imposta il progetto come progetto gcloud attivo

Verifica che il progetto sia impostato correttamente controllando il testo giallo accanto alla directory di lavoro nel prompt del terminale Cloud Shell. Dovrebbe essere visualizzato l'ID progetto.

Se la sessione di Cloud Shell viene reimpostata in qualsiasi momento di questo codelab, torna alla directory di lavoro ed esegui di nuovo bash setup_verify_trial_project.sh && source .env per ripristinare la configurazione del progetto. Verifica che il testo giallo dell'ID progetto venga visualizzato di nuovo nel prompt del terminale.

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com

API Vertex AI (aiplatform.googleapis.com): l'agente utilizza i modelli Gemini e Toolbox utilizza l'API Embedding per la ricerca vettoriale.
API Cloud SQL Admin (sqladmin.googleapis.com): esegui il provisioning e la gestione di un'istanza PostgreSQL.
API Compute Engine (compute.googleapis.com): necessaria per creare istanze Cloud SQL.
Cloud Run, Cloud Build, Artifact Registry: utilizzati nel passaggio di deployment più avanti in questo codelab

3. Crea l'istanza di database

Questo passaggio configura la creazione dell'istanza Cloud SQL in background, che viene eseguita mentre continui il tutorial.

Avvia la creazione dell'istanza

Aggiungi la password del database al file .env e ricaricalo:

echo "DB_PASSWORD=techjobs-pwd-2025" >> .env
source .env

Avvia la creazione dell'istanza Cloud SQL. Questa operazione viene eseguita in background, così puoi continuare a lavorare:

gcloud sql instances create jobs-instance \
  --database-version=POSTGRES_17 \
  --tier=db-custom-1-3840 \
  --edition=ENTERPRISE \
  --region=$REGION \
  --root-password=$DB_PASSWORD \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on \
  --quiet &

db-custom-1-3840 è il livello Cloud SQL con core dedicati più piccolo (1 vCPU, 3,75 GB di RAM) nella versione ENTERPRISE. Puoi leggere maggiori dettagli qui. Per l'integrazione di Vertex AI ML è necessario un core dedicato. I livelli con core condiviso (db-f1-micro, db-g1-small) non lo supportano.
--root-password imposta la password per l'utente postgres predefinito.
--enable-google-ml-integration consente l'integrazione integrata di Cloud SQL con Vertex AI, che ti consente di chiamare i modelli di embedding direttamente da SQL utilizzando la funzione embedding().
& esegue il comando in background.

Questa operazione verrà eseguita in background. Ora scarichiamo il file binario di MCP Toolbox. Puoi farlo nello stesso terminale

Scarica il binario di Toolbox

In questo tutorial utilizzeremo MCP Toolbox, che fortunatamente include un binario precompilato pronto per essere utilizzato nell'ambiente Linux. Scarichiamolo in background perché ci vuole un po' di tempo

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox &

Consente di eseguire questo processo nella scheda corrente (lo eseguiamo già in background, ma l'output verrà comunque visualizzato). Apriamo una nuova scheda del terminale in Cloud Shell (fai clic sull'icona +) per concentrarci meglio.

Torna alla directory di lavoro e attiva il progetto utilizzando lo script di configurazione precedente.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Questo passaggio configura il progetto Python, installa le dipendenze e crea la struttura della directory dell'agente ADK

4. Inizializza il progetto dell'agente

Configurare il progetto Python

uv è un gestore di pacchetti e progetti Python veloce scritto in Rust ( documentazione di uv). Questo codelab lo utilizza per la velocità e la semplicità.

Inizializza un progetto Python e aggiungi le dipendenze richieste:

uv init
uv add google-adk==1.25.0 toolbox-adk==0.6.0

google-adk: Agent Development Kit di Google, incluso l'SDK Gemini
toolbox-adk: integrazione ADK per MCP Toolbox for Databases.

Creare la struttura di directory dell'agente

L'ADK prevede un layout di cartelle specifico: una directory denominata come l'agente contenente __init__.py, agent.py e .env. Per facilitare questa operazione, è stato integrato un comando per stabilire rapidamente la struttura:

uv run adk create jobs_agent \
    --model gemini-2.5-flash \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --region ${GOOGLE_CLOUD_LOCATION}

La directory dovrebbe ora avere il seguente aspetto:

build-agent-adk-toolbox-cloudsql/
├── jobs_agent/
│   ├── __init__.py
│   ├── agent.py
│   └── .env
├── pyproject.toml
├── .env              (project setup — already exists)
└── .venv/

5. Inserisci dati nel database degli elenchi di offerte di lavoro

Questo passaggio scrive i dati iniziali, attende il completamento del provisioning dell'istanza Cloud SQL e carica la tabella jobs con 15 offerte di lavoro e il relativo incorporamento della descrizione

Scrivi l'SQL iniziale

Creeremo un file denominato seed.sql nell'editor di Cloud Shell con i contenuti dell'elenco dei lavori. In questo modo viene creata la tabella jobs con il supporto di pgvector e vengono inserite 15 offerte di lavoro presso aziende tecnologiche.

Innanzitutto, crea il file seed.sql utilizzando il seguente comando:

cloudshell edit seed.sql

Poi copia questi script nel file

-- seed.sql
-- DISCLAIMER: These job listings are entirely fictional and created for tutorial
-- purposes only. Company names are used for illustrative context — the positions,
-- salaries, and descriptions do not reflect real openings.

CREATE EXTENSION IF NOT EXISTS google_ml_integration;
CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS jobs (
    id SERIAL PRIMARY KEY,
    title VARCHAR NOT NULL,
    company VARCHAR NOT NULL,
    role VARCHAR NOT NULL,
    tech_stack VARCHAR NOT NULL,
    salary_range VARCHAR NOT NULL,
    location VARCHAR NOT NULL,
    openings INTEGER NOT NULL,
    description TEXT NOT NULL,
    description_embedding vector(3072)
);

INSERT INTO jobs (title, company, role, tech_stack, salary_range, location, openings, description) VALUES
('Senior Backend Engineer', 'Stripe', 'Backend', 'Go, PostgreSQL, gRPC, Kubernetes', '$180-250K/year', 'San Francisco, Hybrid', 3,
 'Design and build high-throughput microservices powering payment infrastructure for millions of businesses. Optimize Go services for sub-100ms latency at scale, work with PostgreSQL and Redis for data persistence, and deploy on Kubernetes clusters handling billions of API calls.'),

('Machine Learning Engineer', 'Spotify', 'Data/AI', 'Python, TensorFlow, BigQuery, Vertex AI', '$170-230K/year', 'Stockholm, Remote', 2,
 'Build and deploy ML models for music recommendation and personalization systems serving hundreds of millions of listeners. Design feature pipelines in BigQuery, train models using distributed computing, and serve predictions through real-time APIs processing thousands of requests per second.'),

('Frontend Engineer', 'Vercel', 'Frontend', 'React, TypeScript, Next.js', '$140-190K/year', 'Remote', 4,
 'Build developer-facing dashboard interfaces and deployment tools used by millions of developers worldwide. Create responsive, accessible React components for project management, analytics, and real-time deployment monitoring with a focus on developer experience.'),

('DevOps Engineer', 'Datadog', 'DevOps', 'Terraform, GCP, Docker, Kubernetes, ArgoCD', '$160-220K/year', 'New York, Hybrid', 2,
 'Manage cloud infrastructure powering an observability platform used by thousands of engineering teams. Automate deployment pipelines with ArgoCD, manage multi-cloud Kubernetes clusters, and implement infrastructure-as-code with Terraform across production environments.'),

('Mobile Engineer (Android)', 'Grab', 'Mobile', 'Kotlin, Jetpack Compose, GraphQL', '$120-170K/year', 'Singapore, Hybrid', 3,
 'Develop features for a super-app serving millions of users across Southeast Asia. Build modern Android UIs with Jetpack Compose, integrate GraphQL APIs, and optimize app performance for diverse device capabilities and network conditions.'),

('Data Engineer', 'Airbnb', 'Data', 'Python, Apache Spark, Airflow, BigQuery', '$160-210K/year', 'San Francisco, Hybrid', 2,
 'Build data pipelines that process booking, search, and pricing data for a global travel marketplace. Design ETL workflows with Apache Spark and Airflow, maintain data warehouses in BigQuery, and ensure data quality for analytics and machine learning teams.'),

('Full Stack Engineer', 'Revolut', 'Full Stack', 'TypeScript, Node.js, React, PostgreSQL', '$130-180K/year', 'London, Remote', 5,
 'Build the next generation of financial products making banking accessible to millions of users across 35 countries. Develop real-time trading interfaces with React and WebSockets, build Node.js APIs handling market data streams, and design PostgreSQL schemas for financial transactions.'),

('Site Reliability Engineer', 'Cloudflare', 'SRE', 'Go, Prometheus, Grafana, GCP, Terraform', '$170-230K/year', 'Austin, Hybrid', 2,
 'Ensure 99.99% uptime for a global network handling millions of requests per second. Define SLOs, build monitoring dashboards with Prometheus and Grafana, manage incident response, and automate infrastructure scaling across 300+ data centers worldwide.'),

('Cloud Architect', 'Google Cloud', 'Cloud', 'GCP, Terraform, Kubernetes, Python', '$200-280K/year', 'Seattle, Hybrid', 1,
 'Help enterprises modernize their infrastructure on Google Cloud. Design multi-region architectures, lead migration projects from on-premises to GKE, and build reference implementations using Terraform and Cloud Foundation Toolkit.'),

('Backend Engineer (Payments)', 'Square', 'Backend', 'Java, Spring Boot, PostgreSQL, Kafka', '$160-220K/year', 'San Francisco, Hybrid', 3,
 'Build payment processing systems handling millions of transactions for businesses of all sizes. Design event-driven architectures using Kafka, implement idempotent payment flows with Spring Boot, and ensure PCI-DSS compliance across all services.'),

('AI Engineer', 'Hugging Face', 'Data/AI', 'Python, LangChain, Vertex AI, FastAPI, PostgreSQL', '$150-210K/year', 'Paris, Remote', 2,
 'Build AI-powered tools for the largest open-source ML community. Develop RAG pipelines that index and search model documentation, create conversational agents using LangChain, and deploy AI services with FastAPI on cloud infrastructure.'),

('Platform Engineer', 'Coinbase', 'Platform', 'Rust, Kubernetes, AWS, Terraform', '$180-250K/year', 'Remote', 0,
 'Build the infrastructure platform for a leading cryptocurrency exchange. Develop high-performance matching engines in Rust, manage Kubernetes clusters for microservices, and design CI/CD pipelines that enable rapid feature deployment with zero downtime.'),

('QA Automation Engineer', 'Shopify', 'QA', 'Python, Selenium, Cypress, Jenkins', '$110-160K/year', 'Toronto, Hybrid', 3,
 'Design and maintain automated test suites for a commerce platform powering millions of merchants. Build end-to-end test frameworks with Cypress and Selenium, integrate tests into Jenkins CI pipelines, and establish quality gates that prevent regressions in checkout and payment flows.'),

('Security Engineer', 'CrowdStrike', 'Security', 'Python, SIEM, Kubernetes, Penetration Testing', '$170-240K/year', 'Austin, On-site', 1,
 'Protect enterprise customers from cyber threats on a leading endpoint security platform. Conduct penetration testing, design security monitoring with SIEM tools, implement zero-trust networking in Kubernetes environments, and lead incident response for security events.'),

('Product Engineer', 'GitLab', 'Full Stack', 'Go, React, PostgreSQL, Redis, GCP', '$140-200K/year', 'Remote', 4,
 'Own features end-to-end for an all-in-one DevSecOps platform used by millions of developers. Build Go microservices for CI/CD pipelines, create React frontends for code review and project management, and collaborate with product managers to iterate on user-facing features using data-driven development.');

Lo script seed installa due estensioni PostgreSQL:

google_ml_integration: fornisce la funzione SQL embedding(), che chiama i modelli di incorporamento Vertex AI direttamente da SQL. Si tratta di un'estensione a livello di database che rende disponibili le funzioni di ML all'interno di jobs_db. Il flag a livello di istanza (--enable-google-ml-integration) che imposti durante la creazione dell'istanza consente alla VM Cloud SQL di raggiungere Vertex AI. L'estensione rende disponibili le funzioni SQL all'interno di questo database specifico.
vector (pgvector): aggiunge il tipo di dati vector e gli operatori di distanza per archiviare ed eseguire query sugli incorporamenti.

La colonna description_embedding è vector(3072), una colonna pgvector che archivia vettori tridimensionali. Per ora è NULL; genererai e compilerai gli incorporamenti nel passaggio successivo utilizzando la funzione embedding().

Completare la configurazione del database

La creazione dell'istanza Cloud SQL che hai avviato nel passaggio precedente potrebbe essere ancora in esecuzione e non essere ancora terminata. Verifica che l'istanza sia pronta:

gcloud sql instances describe jobs-instance --format="value(state)"

Dovresti vedere l'output seguente

RUNNABLE

Successivamente, concedi al service account dell'istanza Cloud SQL l'autorizzazione per chiamare Vertex AI. Questo passaggio è necessario per la funzione embedding() integrata che utilizzerai nel passaggio successivo:

SERVICE_ACCOUNT=$(gcloud sql instances describe jobs-instance --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

Dopodiché, crea un database dedicato per gli annunci di lavoro:

gcloud sql databases create jobs_db --instance=jobs-instance

Dovresti visualizzare un output che conferma la creazione del database:

Creating Cloud SQL database...done.                                                                         
Created database [jobs_db].
instance: jobs-instance
name: jobs_db
project: workshop-xxxxxxx

Connetti e inizializza il database

Avvia il proxy di autenticazione Cloud SQL (cloud-sql-proxy è preinstallato in Cloud Shell). In questo modo, viene fornita una connessione sicura e autenticata da Cloud Shell all'istanza Cloud SQL:

cloud-sql-proxy ${GOOGLE_CLOUD_PROJECT}:${REGION}:jobs-instance --port 5432 &

Se il proxy viene avviato, dovresti vedere questo output nel terminale:

... Authorizing with Application Default Credentials
... [workshop-xxxxxx:your-location:jobs-instance] Listening on 127.0.0.1:5432
... The proxy has started successfully and is ready for new connections!

Ora il terminale corrente restituisce continuamente il log del proxy Cloud SQL. Apriamo una nuova scheda del terminale in Cloud Shell (fai clic sull'icona +) per concentrarci meglio.

Torna alla directory di lavoro e attiva il progetto utilizzando lo script di configurazione precedente.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Quindi, esegui lo script seed

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" -f seed.sql

Vedrai un output del terminale simile al seguente:

CREATE EXTENSION
CREATE EXTENSION
CREATE TABLE
INSERT 0 15

Verifichiamo i dati

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" \
  -c "SELECT title, company, role, openings FROM jobs ORDER BY role, title;"

Dovresti visualizzare 15 offerte di lavoro per più ruoli:

             title              |    company     |   role    | openings
---------------------------------+----------------+-----------+----------
 Senior Backend Engineer         | Stripe         | Backend   |        3
 Backend Engineer (Payments)     | Square         | Backend   |        3
 Cloud Architect                 | Google Cloud   | Cloud     |        1
 ...
(15 rows)

Generare embedding per le descrizioni dei ruoli

La colonna description_embedding nella tabella jobs è attualmente NULL. L'estensione google_ml_integration integrata di Cloud SQL fornisce una funzione embedding() che chiama Vertex AI direttamente da SQL, senza bisogno di script Python o SDK esterni.

Avvia la generazione degli incorporamenti in background. Viene chiamata Vertex AI per generare un vettore a 3072 dimensioni utilizzando il modello gemini-embedding-001 per ciascuna delle 15 descrizioni di lavoro:

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" \
  -c "UPDATE jobs SET description_embedding = embedding('gemini-embedding-001', description)::vector;" &

Ecco cosa fa lo script:

embedding('gemini-embedding-001', description): chiama il modello di embedding Gemini di Vertex AI direttamente da SQL, passando il testo description di ogni annuncio di lavoro. Questa è l'estensione google_ml_integration che hai installato nello script seed.
::vector: esegue il cast dell'array float restituito al tipo vector di pgvector in modo che possa essere archiviato ed eseguito query con gli operatori di distanza.
UPDATE viene eseguito su tutte le 15 righe, generando un embedding a 3072 dimensioni per ogni descrizione del lavoro.
& esegue il comando in background, così puoi continuare a lavorare mentre Vertex AI elabora gli incorporamenti.

Come per l'esecuzione precedente del processo in background, il terminale corrente restituirà il log del processo. Apriamo una nuova scheda del terminale in Cloud Shell (fai clic sull'icona +) per concentrarci meglio.

Torna alla directory di lavoro e attiva il progetto utilizzando lo script di configurazione precedente.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Poi possiamo continuare con la procedura successiva

6. Configura MCP Toolbox for Databases

Questo passaggio introduce MCP Toolbox for Databases, lo configura per la connessione all'istanza Cloud SQL e definisce due strumenti di query SQL standard.

Che cos'è MCP e perché utilizzare Toolbox?

MCP (Model Context Protocol) è un protocollo aperto che standardizza il modo in cui gli agenti AI scoprono e interagiscono con strumenti esterni. Definisce un modello client-server: l'agente ospita un client MCP e gli strumenti vengono esposti dai server MCP. Qualsiasi client compatibile con MCP può utilizzare qualsiasi server compatibile con MCP. L'agente non ha bisogno di codice di integrazione personalizzato per ogni strumento.

MCP Toolbox for Databases è un server MCP open source creato appositamente per l'accesso al database. Senza, dovresti scrivere funzioni Python che aprono connessioni al database, gestiscono pool di connessioni, creano query parametrizzate per impedire l'iniezione SQL, gestiscono gli errori e incorporano tutto questo codice all'interno dell'agente. Ogni agente che ha bisogno dell'accesso al database ripete questa operazione. La modifica di una query comporta il nuovo deployment dell'agente.

Con Toolbox, scrivi un file YAML. Ogni strumento viene mappato a un'istruzione SQL con parametri. Toolbox gestisce il pool di connessioni, le query parametrizzate, l'autenticazione e l'osservabilità. Gli strumenti sono separati dall'agente: aggiorna una query modificando tools.yaml e riavviando Toolbox, senza toccare il codice dell'agente. Gli stessi strumenti funzionano con ADK, LangGraph, LlamaIndex o qualsiasi framework compatibile con MCP.

Scrivere la configurazione degli strumenti

Ora dobbiamo creare un file denominato tools.yaml nell'editor di Cloud Shell per configurare gli strumenti.

cloudshell edit tools.yaml

Il file utilizza YAML multi-documento: ogni blocco separato da --- è una risorsa autonoma. Ogni risorsa ha un kind che dichiara di cosa si tratta (sources per le connessioni al database, tools per le azioni chiamabili dall'agente) e un type che specifica il backend (cloud-sql-postgres per l'origine, postgres-sql per gli strumenti basati su SQL). Uno strumento fa riferimento alla sua origine tramite name, in modo che Toolbox sappia su quale pool di connessioni eseguire l'operazione. Le variabili di ambiente utilizzano la sintassi ${VAR_NAME} e vengono risolte all'avvio.

Ora, copia prima i seguenti script nel file tools.yaml

# tools.yaml

# --- Data Source ---
kind: sources
name: jobs-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: jobs-instance
database: jobs_db
user: postgres
password: ${DB_PASSWORD}

---