Baza danych jako narzędzie: RAG z agentem z ADK, MCP Toolbox i Cloud SQL

1. Wprowadzenie

Agenty AI są przydatne tylko w zakresie danych, do których mają dostęp. Większość danych w świecie rzeczywistym znajduje się w bazach danych, a łączenie agentów z bazami danych zwykle oznacza pisanie kodu zarządzania połączeniami, logiki zapytań i potoków osadzania w kodzie agenta. Każdy agent, który potrzebuje dostępu do bazy danych, powtarza tę pracę, a każda zmiana zapytania wymaga ponownego wdrożenia agenta.

W tym laboratorium znajdziesz inne podejście. Narzędzia do obsługi baz danych deklarujesz w pliku YAML – zapytania w standardowej wersji SQL, wyszukiwanie podobieństwa wektorowego, a nawet automatyczne generowanie osadzania. MCP Toolbox for Databases obsługuje wszystkie operacje na bazie danych jako serwer MCP. Kod agenta pozostaje minimalny: wczytaj narzędzia i pozwól Gemini zdecydować, które z nich wywołać.

Co utworzysz

Asystent Smart Job Board dla „TechJobs” – agent ADK oparty na Gemini, który pomaga deweloperom przeglądać oferty pracy w branży technicznej za pomocą standardowych filtrów (stanowisko, stos technologiczny) i odkrywać oferty pracy na podstawie opisów w języku naturalnym, np. „Chcę pracować zdalnie nad chatbotami AI”. Agent odczytuje dane z bazy danych Cloud SQL PostgreSQL i zapisuje w niej dane w całości za pomocą MCP Toolbox for Databases, który obsługuje cały dostęp do bazy danych, w tym automatyczne generowanie osadzania na potrzeby wyszukiwania wektorowego. Na koniec zarówno Toolbox, jak i agent będą działać w Cloud Run.

Czego się nauczysz

Jak protokół MCP (Model Context Protocol) standaryzuje dostęp do narzędzi dla agentów AI i jak MCP Toolbox for Databases stosuje to w przypadku operacji na bazach danych
Konfigurowanie MCP Toolbox for Databases jako oprogramowania pośredniczącego między agentem ADK a Cloud SQL PostgreSQL
Zdefiniuj narzędzia bazy danych deklaratywnie w tools.yaml – w agencie nie ma kodu bazy danych.
Tworzenie agenta ADK, który wczytuje narzędzia z uruchomionego serwera Toolbox za pomocą ToolboxToolset
Generowanie wektorów dystrybucyjnych za pomocą wbudowanej funkcji embedding() w Cloud SQL i włączanie wyszukiwania semantycznego za pomocą funkcji pgvector
Użyj funkcji valueFromParam do automatycznego wczytywania wektorów podczas operacji zapisu.
Wdrażanie serwera Toolbox i agenta ADK w Cloud Run

Wymagania wstępne

Konto Google Cloud z próbnym kontem rozliczeniowym
podstawowa znajomość Pythona i SQL,
Nie jest wymagane wcześniejsze doświadczenie z ADK, MCP Toolbox ani pgvector.

2. Konfigurowanie środowiska

WAŻNE UWAGI:

Aby wykonać zadania z tego samouczka, musisz mieć projekt Google Cloud z aktywnym kontem rozliczeniowym. Jeśli jeszcze go nie masz, wykonaj poniższe czynności, aby uzyskać próbne konto rozliczeniowe, którego możesz użyć w tym samouczku:

Otwórz okno incognito
Jeśli bierzesz udział w warsztatach, adres URL portalu do wykorzystania kodu zostanie zwykle podany podczas sesji. W przeciwnym razie możesz przejść do portalu do wykorzystania kodu na próbne konto rozliczeniowe.
Zaloguj się przy użyciu osobistego konta Gmail ( Google Workspace / inne adresy e-mail nie będą działać! )
Aby w tym samouczku utworzyć nowy projekt Google Cloud połączony z wcześniej wykorzystanym kontem rozliczeniowym w okresie próbnym, postępuj zgodnie z instrukcjami dotyczącymi wykorzystania.

Ten krok przygotowuje środowisko Cloud Shell, konfiguruje projekt Google Cloud i klonuje repozytorium referencyjne.

Otwórz Cloud Shell

Otwórz Cloud Shell w przeglądarce. Cloud Shell zapewnia wstępnie skonfigurowane środowisko ze wszystkimi narzędziami potrzebnymi do tego ćwiczenia. Gdy pojawi się prośba o autoryzację, kliknij Autoryzuj.

Następnie kliknij „Widok” –> „Terminal”, aby otworzyć terminal.Interfejs powinien wyglądać podobnie do tego:

Będzie to nasz główny interfejs: IDE u góry, terminal u dołu.

Konfigurowanie katalogu roboczego

Utwórz katalog roboczy. Cały kod, który napiszesz w tym ćwiczeniu, będzie się znajdować tutaj:

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

Konfigurowanie projektu Google Cloud

Utwórz plik .env ze zmiennymi lokalizacji:

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

Pobierz skrypt konfiguracji projektu do katalogu roboczego:

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

Uruchom skrypt. Weryfikuje ono Twoje próbne konto rozliczeniowe, tworzy nowy projekt (lub weryfikuje istniejący), zapisuje identyfikator projektu w pliku .env w bieżącym katalogu i ustawia aktywny projekt w gcloud.

bash setup_verify_trial_project.sh && source .env

Skrypt wykona te działania:

Sprawdź, czy masz aktywne konto rozliczeniowe w wersji próbnej
Sprawdź, czy w .env istnieje projekt (jeśli tak)
Utwórz nowy projekt lub użyj istniejącego.
Połącz próbne konto rozliczeniowe z projektem
Zapisz identyfikator projektu w .env.
Ustaw projekt jako aktywny projekt gcloud.

Sprawdź, czy projekt jest prawidłowo ustawiony, sprawdzając żółty tekst obok katalogu roboczego w wierszu poleceń terminala Cloud Shell. Powinien wyświetlać identyfikator projektu.

Jeśli sesja Cloud Shell zostanie w dowolnym momencie zresetowana, wróć do katalogu roboczego i ponownie uruchom polecenie bash setup_verify_trial_project.sh && source .env, aby przywrócić konfigurację projektu. Sprawdź, czy w prompcie terminala ponownie pojawił się żółty tekst identyfikatora projektu.

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

Vertex AI API (aiplatform.googleapis.com) – Twój agent korzysta z modeli Gemini, a Toolbox używa interfejsu Embedding API do wyszukiwania wektorowego.
Cloud SQL Admin API (sqladmin.googleapis.com) – możesz udostępniać instancję PostgreSQL i nią zarządzać.
Compute Engine API (compute.googleapis.com) – wymagany do tworzenia instancji Cloud SQL.
Cloud Run, Cloud Build, Artifact Registry – używane w kroku wdrażania w dalszej części tego laboratorium

3. Tworzenie instancji bazy danych

Ten krok powoduje utworzenie w tle instancji Cloud SQL – jest ona udostępniana podczas kontynuowania samouczka.

Rozpoczęcie tworzenia instancji

Dodaj hasło do bazy danych do pliku .env i załaduj go ponownie:

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

Rozpocznij tworzenie instancji Cloud SQL. Działa w tle, więc możesz kontynuować pracę:

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 to najmniejszy poziom Cloud SQL z dedykowanymi rdzeniami (1 procesor wirtualny, 3,75 GB pamięci RAM) w wersji ENTERPRISE. Więcej informacji znajdziesz tutaj. Integracja z Vertex AI ML wymaga dedykowanego rdzenia. Nie jest obsługiwana w przypadku warstw z rdzeniem współdzielonym (db-f1-micro, db-g1-small).
--root-password ustawia hasło domyślnego użytkownika postgres.
--enable-google-ml-integration włącza wbudowaną integrację Cloud SQL z Vertex AI, która umożliwia wywoływanie modeli osadzania bezpośrednio z SQL za pomocą funkcji embedding().
& uruchamia polecenie w tle.

Będzie on działać w tle. Następnie pobierzmy plik binarny MCP Toolbox. Możesz to zrobić w tym samym terminalu.

Pobierz plik binarny Toolbox

W tym samouczku użyjemy zestawu narzędzi MCP. Na szczęście zawiera on gotowy plik binarny, który można wykorzystać w środowisku Linux. Pobierzmy go w tle, ponieważ zajmie to trochę czasu.

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

Pozwól, aby ten proces działał na bieżącej karcie (działa już w tle, ale dane wyjściowe będą nadal wyświetlane). Otwórzmy nową kartę terminala w Cloud Shell (kliknij ikonę +) dla większej wygody.

Ponownie przejdź do katalogu roboczego i aktywuj projekt za pomocą poprzedniego skryptu konfiguracji.

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

Ten krok konfiguruje projekt Pythona, instaluje zależności i tworzy szkielet katalogu agenta ADK.

4. Inicjowanie projektu agenta

Konfigurowanie projektu w Pythonie

uv to szybki menedżer pakietów i projektów Pythona napisany w Rust ( dokumentacja uv ). W tych ćwiczeniach z programowania używamy go ze względu na szybkość i prostotę.

Zainicjuj projekt w Pythonie i dodaj wymagane zależności:

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

google-adk – pakiet Google Agent Development Kit, w tym pakiet Gemini SDK.
toolbox-adk – integracja ADK z zestawem narzędzi MCP dla baz danych.

Tworzenie struktury katalogów agenta

ADK oczekuje określonego układu folderów: katalogu o nazwie agenta zawierającego pliki __init__.py, agent.py i .env. Aby Ci w tym pomóc, ma wbudowane polecenie, które pozwala szybko utworzyć strukturę:

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

Twój katalog powinien teraz wyglądać tak:

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

5. Wypełnianie bazy danych z ofertami pracy

Ten krok zapisuje dane początkowe, czeka na zakończenie udostępniania instancji Cloud SQL i wczytuje do tabeli jobs 15 ofert pracy wraz z ich opisami.

Napisz początkowy kod SQL

W edytorze Cloud Shell utworzymy plik o nazwie seed.sql z treścią listy zadań. Spowoduje to utworzenie jobs tabeli z pgvector obsługą i wstawienie 15 ofert pracy w firmach technologicznych.

Najpierw utwórz plik seed.sql za pomocą tego polecenia:

cloudshell edit seed.sql

Następnie skopiuj te skrypty do pliku.

-- 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.');

Skrypt początkowy instaluje 2 rozszerzenia PostgreSQL:

google_ml_integration – udostępnia funkcję SQL embedding(), która wywołuje modele wektorów dystrybucyjnych Vertex AI bezpośrednio z SQL. Jest to rozszerzenie na poziomie bazy danych, które udostępnia funkcje ML w jobs_db. Flaga na poziomie instancji (--enable-google-ml-integration) ustawiona podczas tworzenia instancji umożliwia maszynie wirtualnej Cloud SQL dostęp do Vertex AI – rozszerzenie udostępnia funkcje SQL w tej konkretnej bazie danych.
vector (pgvector) – dodaje typ danych vector i operatory odległości do przechowywania i wysyłania zapytań dotyczących osadzania.

Kolumna description_embedding to vector(3072) – kolumna pgvector, która przechowuje wektory 3072-wymiarowe. Obecnie ma wartość NULL. W następnym kroku wygenerujesz i wypełnisz wektory za pomocą funkcji embedding().

Dokończ konfigurację bazy danych

Tworzenie instancji Cloud SQL rozpoczęte w poprzednim kroku może nadal trwać i nie być jeszcze zakończone. Sprawdź, czy instancja jest gotowa:

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

Powinny pojawić się te dane wyjściowe:

RUNNABLE

Następnie przyznaj kontu usługi instancji Cloud SQL uprawnienia do wywoływania Vertex AI. Jest to wymagane w przypadku wbudowanej funkcji embedding(), której użyjesz w następnym kroku:

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

Następnie utwórz dedykowaną bazę danych dla ofert pracy:

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

Powinny się wyświetlić dane wyjściowe potwierdzające utworzenie bazy danych:

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

Połącz się z bazą danych i ją zainicjuj

Uruchom serwer proxy uwierzytelniania Cloud SQL (cloud-sql-proxy jest wstępnie zainstalowany w Cloud Shell). Zapewnia to bezpieczne, uwierzytelnione połączenie z Cloud Shell z instancją Cloud SQL:

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

Jeśli serwer proxy się uruchomi, w terminalu powinny się pojawić te dane wyjściowe:

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

W bieżącym terminalu dziennik serwera proxy Cloud SQL jest teraz wyświetlany w sposób ciągły. Otwórzmy nową kartę terminala w Cloud Shell (kliknij ikonę +) dla większej wygody.

Ponownie przejdź do katalogu roboczego i aktywuj projekt za pomocą poprzedniego skryptu konfiguracji.

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

Następnie uruchom skrypt początkowy.

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

Zobaczysz dane wyjściowe terminala podobne do tych:

CREATE EXTENSION
CREATE EXTENSION
CREATE TABLE
INSERT 0 15

Sprawdźmy dane

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;"

Powinno się wyświetlić 15 ofert pracy na różnych stanowiskach:

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

Generowanie wektorów dystrybucyjnych dla opisów stanowisk

Kolumna description_embedding w tabeli jobs ma obecnie wartość NULL. Wbudowane rozszerzenie google_ml_integration Cloud SQL udostępnia funkcję embedding(), która wywołuje Vertex AI bezpośrednio z SQL – nie wymaga skryptu w Pythonie ani zewnętrznego pakietu SDK.

Rozpocznij generowanie osadzania w tle. Wywołuje to Vertex AI, aby wygenerować 3072-wymiarowy wektor za pomocą modelu gemini-embedding-001 dla każdego z 15 opisów stanowisk:

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;" &

Skrypt wykonuje te działania:

embedding('gemini-embedding-001', description) – wywołuje model wektorów dystrybucyjnych Gemini w Vertex AI bezpośrednio z SQL, przekazując tekst description każdego zadania. Jest to rozszerzenie google_ml_integration zainstalowane w skrypcie początkowym.
::vector – rzutuje zwróconą tablicę liczb zmiennoprzecinkowych na typ vector pgvector, aby można było ją przechowywać i wykonywać na niej zapytania za pomocą operatorów odległości.
Model UPDATE działa na wszystkich 15 wierszach, generując 1 osadzenie o 3072 wymiarach dla każdego opisu stanowiska.
Symbol & uruchamia polecenie w tle, dzięki czemu możesz kontynuować pracę, podczas gdy Vertex AI przetwarza wektory.

Podobnie jak w przypadku poprzednich procesów działających w tle, w bieżącym terminalu zostanie wyświetlony dziennik procesu. Otwórzmy nową kartę terminala w Cloud Shell (kliknij ikonę +) dla większej wygody.

Ponownie przejdź do katalogu roboczego i aktywuj projekt za pomocą poprzedniego skryptu konfiguracji.

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

Następnie możemy przejść do kolejnego procesu

6. Konfigurowanie MCP Toolbox for Databases

Ten krok wprowadza MCP Toolbox for Databases, konfiguruje go pod kątem połączenia z instancją Cloud SQL i definiuje 2 standardowe narzędzia do wykonywania zapytań SQL.

Czym jest MCP i dlaczego warto korzystać z Toolbox?

MCP (Model Context Protocol) to otwarty protokół, który standaryzuje sposób, w jaki agenci AI wykrywają narzędzia zewnętrzne i wchodzą z nimi w interakcje. Definiuje model klient-serwer: agent hostuje klienta MCP, a narzędzia są udostępniane przez serwery MCP. Każdy klient zgodny z MCP może używać dowolnego serwera zgodnego z MCP – agent nie potrzebuje niestandardowego kodu integracji dla każdego narzędzia.

MCP Toolbox for Databases to serwer MCP typu open source stworzony specjalnie na potrzeby dostępu do baz danych. Bez niego musisz pisać funkcje Pythona, które otwierają połączenia z bazą danych, zarządzają pulami połączeń, tworzą zapytania parametryzowane, aby zapobiegać wstrzykiwaniu kodu SQL, obsługują błędy i osadzają cały ten kod w agencie. Każdy agent, który potrzebuje dostępu do bazy danych, powtarza tę pracę. Zmiana zapytania oznacza ponowne wdrożenie agenta.

W Toolboxie piszesz plik YAML. Każde narzędzie jest mapowane na sparametryzowaną instrukcję SQL. Zestaw narzędzi obsługuje pulę połączeń, zapytania parametryzowane, uwierzytelnianie i obserwację. Narzędzia są odłączone od agenta – możesz zaktualizować zapytanie, edytując tools.yaml i ponownie uruchamiając Toolbox, bez ingerowania w kod agenta. Te same narzędzia działają w przypadku ADK, LangGraph, LlamaIndex i dowolnej platformy zgodnej z MCP.

Zapisz konfigurację narzędzi

Teraz musimy utworzyć plik o nazwie tools.yaml w edytorze Cloud Shell, aby skonfigurować narzędzia.

cloudshell edit tools.yaml

Plik używa formatu YAML z wieloma dokumentami – każdy blok oddzielony znakiem --- jest samodzielnym zasobem. Każde źródło ma pole kind, które określa, czym jest (sources w przypadku połączeń z bazą danych, tools w przypadku działań wywoływanych przez agenta), oraz pole type, które określa backend (cloud-sql-postgres w przypadku źródła, postgres-sql w przypadku narzędzi opartych na SQL). Narzędzie odwołuje się do swojego źródła za pomocą znaku name. Dzięki temu Zestaw narzędzi wie, z której puli połączeń ma korzystać. Zmienne środowiskowe używają składni ${VAR_NAME} i są rozwiązywane podczas uruchamiania.

Teraz skopiuj te skrypty do pliku 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}

---