1. Wprowadzenie
W tym ćwiczeniu utworzysz agenta za pomocą pakietu Agent Development Kit (ADK), który korzysta z zestawu narzędzi MCP dla baz danych.
W ramach ćwiczeń z programowania będziesz wykonywać kolejne czynności:
- Utwórz bazę danych Cloud SQL for PostgreSQL, która będzie zawierać bazę danych hoteli i przykładowe dane.
- Skonfiguruj zestaw narzędzi MCP dla baz danych, który zapewnia dostęp do danych.
- Zaprojektuj i opracuj agenta za pomocą pakietu Agent Development Kit (ADK), który będzie korzystać z zestawu narzędzi MCP, aby odpowiadać na zapytania użytkownika.
- Poznaj opcje testowania agenta i MCP Toolbox for Databases lokalnie i w Google Cloud za pomocą usługi Cloud Run.
Co musisz zrobić
- Zaprojektuj, utwórz i wdroż agenta, który będzie odpowiadać na zapytania użytkowników dotyczące hoteli w danej lokalizacji lub wyszukiwać hotele według nazwy.
Czego się nauczysz
- udostępnianie bazy danych Cloud SQL for PostgreSQL i wypełnianie jej przykładowymi danymi;
- Skonfiguruj MCP Toolbox for Databases dla instancji bazy danych Cloud SQL for PostgreSQL.
- Projektowanie i tworzenie agenta za pomocą pakietu Agent Development Kit (ADK) w celu odpowiadania na zapytania użytkowników.
- Przetestuj agenta i zestaw narzędzi MCP dla baz danych w środowisku lokalnym.
- (Opcjonalnie) wdróż agenta i MCP Toolbox for Databases w Google Cloud.
Czego potrzebujesz
- przeglądarki Chrome,
- konto Gmail,
- Projekt Cloud z włączonymi płatnościami
To ćwiczenie jest przeznaczone dla programistów na wszystkich poziomach zaawansowania (w tym dla początkujących). W przykładowej aplikacji używa się języka Python. Znajomość języka Python nie jest jednak wymagana, a podstawowe umiejętności czytania kodu wystarczą do zrozumienia przedstawionych koncepcji.
2. Zanim zaczniesz
Utwórz projekt
- W konsoli Google Cloud na stronie wyboru projektu wybierz lub utwórz projekt Google Cloud.
- Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności .
- Będziesz używać Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud, które jest wstępnie załadowane narzędziem bq. U góry konsoli Google Cloud kliknij Aktywuj Cloud Shell.
- Po połączeniu z Cloud Shell sprawdź, czy uwierzytelnianie zostało już przeprowadzone, a projekt jest już ustawiony na Twój identyfikator projektu, używając tego polecenia:
gcloud auth list
- Aby potwierdzić, że polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:
gcloud config list project
- Jeśli projekt nie jest ustawiony, użyj tego polecenia, aby go ustawić:
gcloud config set project <YOUR_PROJECT_ID>
- Włącz wymagane interfejsy API za pomocą polecenia pokazanego poniżej. Może to potrwać kilka minut, więc prosimy o cierpliwość.
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
Po pomyślnym wykonaniu polecenia powinien wyświetlić się komunikat podobny do tego poniżej:
Operation "operations/..." finished successfully.
Alternatywą dla polecenia gcloud jest wyszukanie poszczególnych usług w konsoli lub skorzystanie z tego linku.
Jeśli pominiesz jakiś interfejs API, możesz go włączyć w trakcie wdrażania.
Informacje o poleceniach gcloud i ich użyciu znajdziesz w dokumentacji.
3. Tworzenie instancji Cloud SQL
Do przechowywania danych o hotelach będziemy używać instancji Google Cloud SQL for PostgreSQL. Cloud SQL for PostgreSQL to w pełni zarządzana usługa bazy danych, która pomaga w konfiguracji i utrzymaniu relacyjnych baz danych PostgreSQL w Google Cloud Platform, a także w zarządzaniu i administrowaniu takimi bazami.
Aby utworzyć instancję, uruchom w Cloud Shell to polecenie:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Wykonanie tego polecenia zajmuje około 3–5 minut. Po pomyślnym wykonaniu polecenia powinny się wyświetlić dane wyjściowe wskazujące, że polecenie zostało wykonane, oraz informacje o instancji Cloud SQL, takie jak NAME, DATABASE_VERSION, LOCATION itp.
4. Przygotowywanie bazy danych hoteli
Teraz musimy utworzyć przykładowe dane dla agenta hotelowego.
Otwórz stronę Cloud SQL w konsoli Cloud.Powinna być widoczna instancja hoteldb-instance, która jest gotowa i utworzona. Kliknij nazwę instancji (hoteldb-instance), jak pokazano poniżej:
W menu po lewej stronie Cloud SQL wybierz opcję Cloud SQL Studio, jak pokazano poniżej:
Poprosimy Cię o zalogowanie się w Cloud SQL Studio, w którym podamy kilka poleceń SQL. Wybierz postgres w przypadku opcji Baza danych, a w przypadku opcji Użytkownik i Hasło użyj wartości postgres. Kliknij AUTHENTICATE.
Najpierw utwórzmy tabelę hoteli zgodnie ze schematem podanym poniżej. W jednym z paneli Edytora w Cloud SQL Studio wykonaj ten kod 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
);
Teraz wypełnijmy tabelę hoteli przykładowymi danymi. Wykonaj ten kod SQL:
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
Sprawdźmy dane, uruchamiając zapytanie SQL SELECT, jak pokazano poniżej:
SELECT * FROM hotels;
W tabeli hoteli powinna być widoczna liczba rekordów, jak pokazano poniżej:
Proces konfigurowania instancji Cloud SQL został zakończony, a przykładowe dane zostały utworzone. W następnej sekcji skonfigurujemy zestaw narzędzi MCP dla baz danych.
5. Konfigurowanie zestawu narzędzi MCP dla baz danych
Narzędzia MCP dla baz danych to serwer MCP typu open source dla baz danych. Został zaprojektowany z myślą o zastosowaniach w przedsiębiorstwach i jakość produkcyjną. Umożliwia łatwiejsze, szybsze i bezpieczniejsze tworzenie narzędzi dzięki obsłudze złożonych procesów, takich jak pula połączeń, uwierzytelnianie i inne.
Zestaw narzędzi pomaga tworzyć narzędzia generatywnej AI, które umożliwiają agentom dostęp do danych w bazie danych. Zestaw narzędzi zapewnia:
- Uproszczone tworzenie: zintegruj narzędzia z agentem za pomocą mniej niż 10 wierszy kodu, ponownie wykorzystuj narzędzia w wielu agentach lub platformach i łatwiej wdrażaj nowe wersje narzędzi.
- Większa wydajność: sprawdzone metody, takie jak agregacja połączeń, uwierzytelnianie i inne.
- Ulepszone zabezpieczenia: zintegrowane uwierzytelnianie zapewniające bezpieczniejszy dostęp do danych
- Kompleksowa widoczność: gotowe wskaźniki i śledzenie z wbudowaną obsługą OpenTelemetry.
Toolbox znajduje się między platformą orkiestracji aplikacji a bazą danych, zapewniając platformę sterującą, która służy do modyfikowania, rozpowszechniania i wywoływania narzędzi. Upraszcza zarządzanie narzędziami, ponieważ zapewnia centralną lokalizację do przechowywania i aktualizowania narzędzi. Umożliwia też udostępnianie narzędzi agentom i aplikacjom oraz aktualizowanie ich bez konieczności ponownego wdrażania aplikacji.
Jak widać, jedną z baz danych obsługiwanych przez MCP Toolbox for Databases jest Cloud SQL, którą skonfigurowaliśmy w poprzedniej sekcji.
Instalowanie Zestawu narzędzi
Otwórz terminal Cloud Shell i utwórz folder o nazwie mcp-toolbox.
mkdir mcp-toolbox
Otwórz folder mcp-toolbox za pomocą tego polecenia:
cd mcp-toolbox
Zainstaluj binarną wersję zestawu narzędzi MCP dla baz danych za pomocą podanego poniżej skryptu. Poniższe polecenie jest przeznaczone dla systemu Linux, ale jeśli używasz komputera Mac lub Windows, pobierz odpowiedni plik binarny. Odwiedź stronę wydań dla swojego systemu operacyjnego i architektury i pobierz odpowiedni plik binarny.
export VERSION=1.1.0
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Mamy teraz gotową do użycia wersję binarną zestawu narzędzi. Sprawdźmy, czy plik binarny narzędzi został prawidłowo skonfigurowany i czy wskazuje właściwą wersję.
Aby sprawdzić wersję pakietu narzędzi, wpisz to polecenie:
./toolbox -v
Powinny zostać wyświetlone dane wyjściowe podobne do tych:
toolbox version 1.1.0+binary.linux.amd64.466aef0
Następnym krokiem jest skonfigurowanie skrzynki narzędziowej za pomocą naszych źródeł danych i innych ustawień.
Konfigurowanie pliku tools.yaml
Głównym sposobem konfigurowania Toolboxa jest plik tools.yaml. W tym samym folderze, czyli mcp-toolbox, utwórz plik o nazwie tools.yaml, którego zawartość jest pokazana poniżej.
Możesz użyć edytora nano dostępnego w Cloud Shell. Polecenie nano ma postać: „nano tools.yaml”.
Pamiętaj, aby zastąpić wartość YOUR_PROJECT_ID identyfikatorem projektu Google Cloud.
kind: source
name: my-cloud-sql-source
type: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: postgres
---
kind: tool
name: search-hotels-by-name
type: 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 || '%';
---
kind: tool
name: search-hotels-by-location
type: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
---
kind: toolset
name: my_first_toolset
tools:
- search-hotels-by-name
- search-hotels-by-location
Krótko opisz plik:
Sourcesreprezentują różne źródła danych, z którymi narzędzie może wchodzić w interakcje. Źródło to źródło danych, z którym narzędzie może wchodzić w interakcje. Możesz zdefiniowaćSourcesjako mapę w sekcji źródeł w pliku tools.yaml. Zwykle konfiguracja źródła zawiera wszystkie informacje potrzebne do połączenia z bazą danych i korzystania z niej. W naszym przypadku skonfigurowaliśmy jedno źródło, które wskazuje naszą instancję Cloud SQL for PostgreSQL z odpowiednimi danymi logowania. Więcej informacji znajdziesz w sekcji Źródła.Toolsokreślają działania, jakie może wykonać agent, np. odczytywanie i zapisywanie w źródle. Narzędzie reprezentuje działanie, które może wykonać agent, np. uruchomienie instrukcji SQL. Możesz zdefiniowaćToolsjako mapę w sekcji narzędzi w pliku tools.yaml. Zwykle narzędzie wymaga źródła, na którym ma działać. W naszym przypadku definiujemy 2 narzędzia:search-hotels-by-nameisearch-hotels-by-location, a także określamy źródło, na którym działają, wraz z kodem SQL i parametrami. Więcej informacji znajdziesz w dokumentacji.- Ostatnim elementem jest
Toolset, który umożliwia definiowanie grup narzędzi, które chcesz móc wczytywać razem. Może to być przydatne do definiowania różnych grup na podstawie agenta lub aplikacji. W naszym przypadku mamy jeden zestaw narzędzi o nazwiemy_first_toolset, który zawiera 2 zdefiniowane przez nas narzędzia.
Zapisz plik tools.yaml w edytorze nano, wykonując te czynności:
- Naciśnij
Ctrl + O(polecenie „Zapisz”). - Poprosimy Cię o potwierdzenie „Nazwy pliku do zapisu”. Wystarczy, że naciśniesz
Enter. - Teraz naciśnij
Ctrl + X, aby wyjść.
Uruchom serwer narzędzi MCP dla baz danych
Aby uruchomić serwer, wykonaj to polecenie (w folderze mcp-toolbox):
./toolbox --config "tools.yaml"
Powinien pojawić się komunikat informujący, że serwer połączył się z naszymi źródłami danych oraz załadował zestaw narzędzi i narzędzia. Przykładowe dane wyjściowe:
2026-04-25T09:08:00.738271-07:00 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-04-25T09:08:00.738397-07:00 INFO "Initialized 0 authServices: "
2026-04-25T09:08:00.738405-07:00 INFO "Initialized 0 embeddingModels: "
2026-04-25T09:08:00.738453-07:00 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2026-04-25T09:08:00.738497-07:00 INFO "Initialized 2 toolsets: my_first_toolset, default"
2026-04-25T09:08:00.738504-07:00 INFO "Initialized 0 prompts: "
2026-04-25T09:08:00.738517-07:00 INFO "Initialized 1 promptsets: default"
2026-04-25T09:08:00.738566-07:00 WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag"
2026-04-25T09:08:00.738625-07:00 WARN "wildcard (`*`) allows all hosts to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-hosts` flag to prevent DNS rebinding attacks"
2026-04-25T09:08:00.738909-07:00 INFO "Server ready to serve!"
Serwer MCP Toolbox działa domyślnie na porcie 5000. Jeśli port 5000 jest już używany, możesz użyć innego portu (np. 7000), jak pokazano w poniższym poleceniu. W kolejnych poleceniach używaj portu 7000 zamiast portu 5000.
./toolbox --config "tools.yaml" --port 7000
Aby to przetestować, użyjemy Cloud Shell.
W Cloud Shell kliknij Podgląd w przeglądarce, jak pokazano poniżej:
Kliknij Zmień port i ustaw port na 5000, jak pokazano poniżej. Następnie kliknij Zmień i wyświetl podgląd.
Powinny się wyświetlić te dane wyjściowe:
Testowanie narzędzi w interfejsie narzędzi MCP dla baz danych
Narzędzia udostępniają interfejs wizualny (interfejs narzędzi), który umożliwia bezpośrednie korzystanie z narzędzi przez modyfikowanie parametrów, zarządzanie nagłówkami i wykonywanie wywołań w prostym interfejsie internetowym.
Jeśli chcesz to przetestować, możesz uruchomić poprzednie polecenie, którego użyliśmy do uruchomienia serwera Toolbox, z opcją --ui.
Aby to zrobić, zamknij poprzednią instancję serwera narzędzi MCP dla baz danych, która może być uruchomiona, i wpisz to polecenie:
./toolbox --config "tools.yaml" --ui
Powinien pojawić się komunikat informujący, że serwer połączył się z naszymi źródłami danych oraz załadował zestaw narzędzi i narzędzia. Poniżej znajdziesz przykładowe dane wyjściowe. Zauważysz, że zawierają one informację o tym, że interfejs Narzędzi jest uruchomiony.
2026-04-25T09:17:45.54415-07:00 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-04-25T09:17:45.544225-07:00 INFO "Initialized 0 authServices: "
2026-04-25T09:17:45.544239-07:00 INFO "Initialized 0 embeddingModels: "
2026-04-25T09:17:45.544298-07:00 INFO "Initialized 2 tools: search-hotels-by-location, search-hotels-by-name"
2026-04-25T09:17:45.544345-07:00 INFO "Initialized 2 toolsets: default, my_first_toolset"
2026-04-25T09:17:45.544365-07:00 INFO "Initialized 0 prompts: "
2026-04-25T09:17:45.544393-07:00 INFO "Initialized 1 promptsets: default"
2026-04-25T09:17:45.544439-07:00 WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag"
2026-04-25T09:17:45.54448-07:00 WARN "wildcard (`*`) allows all hosts to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-hosts` flag to prevent DNS rebinding attacks"
2026-04-25T09:17:45.544887-07:00 INFO "Server ready to serve!"
2026-04-25T09:17:45.544908-07:00 INFO "Toolbox UI is up and running at: http://127.0.0.1:5000/ui"
Kliknij adres URL interfejsu i upewnij się, że masz
/ui
na końcu adresu URL (jeśli uruchamiasz to w Cloud Shell, przekierowanie w przeglądarce spowoduje, że na końcu nie będzie elementu /ui). Wyświetli się interfejs użytkownika, jak pokazano poniżej:
Kliknij opcję Narzędzia po lewej stronie, aby wyświetlić skonfigurowane narzędzia. W naszym przypadku powinny to być 2 narzędzia: search-hotels-by-name i search-hotels-by-location, jak pokazano poniżej:
Wystarczy kliknąć jedno z narzędzi (search-hotels-by-location), aby otworzyć stronę, na której możesz przetestować narzędzie, podając wymagane wartości parametrów, a następnie kliknąć Uruchom narzędzie, aby zobaczyć wynik. Przykładowe uruchomienie pokazano poniżej:
Zestaw narzędzi MCP do baz danych zawiera też opis sposobu weryfikacji i testowania narzędzi w języku Python. Więcej informacji znajdziesz tutaj.
Wracając do wcześniejszego diagramu (jak pokazano poniżej), mamy już skonfigurowaną bazę danych i serwer MCP. Przed nami są 2 ścieżki:
- Aby dowiedzieć się, jak skonfigurować serwer MCP w terminalu lub IDE z pomocą AI, przejdź do kroku 6. Dowiesz się z niego, jak zintegrować serwer MCP Toolbox z
Gemini CLI. - Aby dowiedzieć się, jak używać
Agent Development Kit (ADK) using Pythondo pisania własnych agentów, którzy mogą korzystać z zestawu narzędzi serwera MCP jako narzędzia do odpowiadania na pytania związane z zestawem danych, przejdź do kroków 7 i 8.
6. Integracja MCP Toolbox z interfejsem wiersza poleceń Gemini
Interfejs wiersza poleceń Gemini to agent AI o otwartym kodzie źródłowym, który udostępnia możliwości Gemini bezpośrednio w terminalu. Możesz go używać zarówno do zadań związanych z kodowaniem, jak i do innych zadań. Jest zintegrowany z różnymi narzędziami i obsługuje serwery MCP.
Mamy już działający serwer MCP, więc w tej sekcji skonfigurujemy serwer MCP Toolbox for Databases w interfejsie wiersza poleceń Gemini, a następnie użyjemy tego interfejsu do komunikacji z danymi.
Najpierw sprawdzimy, czy masz uruchomiony zestaw narzędzi w jednym z terminali Cloud Shell. Jeśli serwer MCP działa na domyślnym porcie 5000, interfejs serwera MCP jest dostępny pod tym adresem: http://localhost:5000/mcp.
Otwórz nowy terminal i utwórz folder o nazwie my-gemini-cli-project w ten sposób: Przejdź też do folderu my-gemini-cli-project.
mkdir my-gemini-cli-project
cd my-gemini-cli-project
Wpisz to polecenie, aby dodać serwer MCP do listy serwerów MCP skonfigurowanych w interfejsie wiersza poleceń Gemini.
gemini mcp add --scope="project" --transport="http" "MCPToolbox" "http://localhost:5000/mcp"
Aktualną listę serwerów MCP skonfigurowanych w interfejsie wiersza poleceń Gemini możesz sprawdzić za pomocą tego polecenia:
gemini mcp list
Powinien pojawić się skonfigurowany przez nas MCPToolbox z zielonym znacznikiem wyboru obok, co oznacza, że interfejs wiersza poleceń Gemini połączył się z serwerem MCP.
Configured MCP servers:
✓ MCPToolbox: http://localhost:5000/mcp (http) - Connected
Zanim uruchomimy interfejs wiersza poleceń Gemini, możesz ustawić te zmienne środowiskowe, aby pomóc interfejsowi wiersza poleceń Gemini kierować żądania do odpowiedniego modelu.
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=global
Na tym samym terminalu upewnij się, że jesteś w folderze my-gemini-cli-project. Uruchom interfejs wiersza poleceń Gemini za pomocą polecenia gemini.
Spowoduje to wyświetlenie interfejsu wiersza poleceń Gemini. Zobaczysz, że jest w nim teraz skonfigurowany 1 serwer MCP. Aby wyświetlić listę serwerów MCP i narzędzi, możesz użyć polecenia /mcp list. Oto przykładowe dane wyjściowe:
Możesz teraz wydać dowolne z tych poleceń:
Which hotels are there in Basel?Tell me more about the Hyatt Regency?
Zauważysz, że w przypadku powyższych zapytań interfejs wiersza poleceń Gemini wybierze odpowiednie narzędzie z MCPToolbox. Pojawi się prośba o zezwolenie na uruchomienie narzędzia. Przyznaj mu niezbędne uprawnienia, a zauważysz, że wyniki są zwracane z bazy danych.
7. Tworzenie agenta za pomocą pakietu Agent Development Kit (ADK)
Instalowanie pakietu Agent Development Kit (ADK)
Otwórz nową kartę terminala w Cloud Shell i utwórz folder o nazwie my-agents w ten sposób: Przejdź też do folderu my-agents.
mkdir my-agents
cd my-agents
Teraz utwórzmy wirtualne środowisko Pythona za pomocą narzędzia venv:
python -m venv .venv
Aktywuj środowisko wirtualne w ten sposób:
source .venv/bin/activate
Zainstaluj pakiety ADK i MCP Toolbox for Databases wraz z zależnością langchain w ten sposób:
pip install google-adk toolbox-core
Narzędzie adk możesz teraz wywołać w ten sposób.
adk
Wyświetli się lista poleceń.
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
conformance Conformance testing tools for ADK.
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.
eval_set Manage Eval Sets.
migrate ADK migration commands.
optimize Optimizes the root agent instructions using the GEPA optimizer.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Tworzenie pierwszej aplikacji agenta
Teraz użyjemy adk, aby utworzyć szkielet aplikacji agenta hotelowego za pomocą polecenia adk create z nazwą aplikacji **(hotel_agent_app)**jak poniżej.
adk create hotel_agent_app
Wykonaj te czynności:
- Model Gemini do wybierania modelu dla agenta głównego.
- Wybierz Vertex AI jako backend.
- Wyświetli się domyślny identyfikator projektu Google i region. Wybierz domyślne ustawienie.
Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app:
- .env
- __init__.py
- agent.py
Sprawdź folder, w którym utworzono szablon domyślny i wymagane pliki dla agenta. Pliki możesz wyświetlić za pomocą polecenia ls -al w terminalu w katalogu <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app.
Pierwszy z nich to plik .env. Ten plik został już utworzony, jak wspomnieliśmy wcześniej. Możesz po prostu wyświetlić jego zawartość, która jest pokazana poniżej:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Wartości te wskazują, że będziemy korzystać z Gemini przez Vertex AI wraz z odpowiednimi wartościami identyfikatora projektu Google Cloud i lokalizacji.
Następnie mamy plik __init__.py, który oznacza folder jako moduł i zawiera pojedynczą instrukcję importującą agenta z pliku agent.py.
from . import agent
Na koniec przyjrzyjmy się plikowi agent.py. Treści są widoczne poniżej:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Jest to najprostszy agent, jakiego możesz napisać za pomocą pakietu ADK. Z dokumentacji pakietu ADK wynika, że agent to samodzielna jednostka wykonawcza zaprojektowana do autonomicznego działania w celu osiągnięcia określonych celów. Agenci mogą wykonywać zadania, wchodzić w interakcje z użytkownikami, korzystać z narzędzi zewnętrznych i współpracować z innymi agentami.
W szczególności LLMAgent, zwykle nazywany Agentem, wykorzystuje duże modele językowe (LLM) jako główny silnik do rozumienia języka naturalnego, wnioskowania, planowania, generowania odpowiedzi i dynamicznego decydowania, jak postępować lub których narzędzi używać. Dzięki temu idealnie nadaje się do elastycznych zadań związanych z językiem. Więcej informacji o agentach LLM znajdziesz tutaj.
Zmodyfikujmy kod dla elementu agent.py w ten sposób:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='hotel_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
Lokalne testowanie aplikacji agenta
W otwartym oknie terminala wpisz to polecenie. Upewnij się, że jesteś w folderze nadrzędnym (my-agents) zawierającym folder hotel_agent_app.
adk web
Przykładowe wykonanie jest pokazane poniżej:
INFO: Started server process [1478]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Kliknij ostatni link. Powinna się otworzyć konsola internetowa, w której możesz przetestować agenta. W przeglądarce powinna się otworzyć strona podobna do tej poniżej:
Zwróć uwagę, że w lewym górnym rogu został rozpoznany symbol hotel_agent_app. Możesz teraz rozpocząć rozmowę z agentem. Podaj kilka promptów z pytaniami o miasta. Przykładowa rozmowa jest pokazana poniżej:
Możesz zamknąć proces działający w terminalu Cloud Shell (Ctrl-C).
Innym sposobem przetestowania agenta jest użycie polecenia adk run w folderze my-agents, jak pokazano poniżej.
adk run hotel_agent_app
Wypróbuj to polecenie i rozmawiaj z agentem za pomocą wiersza poleceń (terminala). Aby zamknąć rozmowę, wpisz exit.
8. Łączenie agenta z narzędziami
Wiesz już, jak napisać agenta i przetestować go lokalnie. Połączymy tego agenta z narzędziami. W kontekście pakietu ADK narzędzie to konkretna zdolność udostępniana agentowi AI, która umożliwia mu wykonywanie działań i interakcje ze światem wykraczające poza podstawowe możliwości generowania tekstu i rozumowania.
W tym przypadku wyposażymy teraz naszego agenta w narzędzia, które skonfigurowaliśmy w zestawie narzędzi MCP dla baz danych.
Zmodyfikuj plik agent.py, dodając do niego ten kod. Zwróć uwagę, że w kodzie używamy domyślnego portu 5000, ale jeśli używasz innego numeru portu, wpisz go.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-2.5-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
Możemy teraz przetestować agenta, który będzie pobierać rzeczywiste dane z naszej bazy danych PostgreSQL skonfigurowanej za pomocą MCP Toolbox for Databases.
Aby to zrobić, wykonaj te czynności:
W jednym z terminali Cloud Shell uruchom Narzędzia MCP dla baz danych. Może być już uruchomiony lokalnie na porcie 5000, ponieważ testowaliśmy go wcześniej. Jeśli nie, uruchom to polecenie (z folderu mcp-toolbox), aby uruchomić serwer:
./toolbox --config "tools.yaml"
Powinien pojawić się komunikat informujący, że serwer połączył się z naszymi źródłami danych oraz załadował zestaw narzędzi i narzędzia.
Gdy serwer MCP zostanie uruchomiony, w innym terminalu uruchom agenta, tak jak wcześniej, za pomocą polecenia adk run (z folderu my-agents) pokazanego poniżej. Możesz też użyć polecenia adk web.
$ adk run hotel_agent_app/
...
Running agent hotel_agent, type exit to exit.
[user]: what can you do for me ?
[hotel_agent]: I can help you find hotels by location or by name.
[user]: I would like to search for hotels?
[hotel_agent]: Great! Do you want to search by location or by hotel name?
[user]: I'd like to search in Basel
[hotel_agent]: Here are some hotels in Basel:
* Holiday Inn Basel (Upper Midscale)
* Hyatt Regency Basel (Upper Upscale)
* Hilton Basel (Luxury)
[user]:
Zwróć uwagę, że agent korzysta teraz z 2 narzędzi skonfigurowanych w zestawie narzędzi MCP dla baz danych (search-hotels-by-name i search-hotels-by-location) i podaje nam prawidłowe opcje. Następnie może bezproblemowo pobrać dane z bazy danych instancji PostgreSQL i odpowiednio sformatować odpowiedź.
W ten sposób zakończyliśmy lokalne tworzenie i testowanie agenta hotelowego, który został utworzony za pomocą pakietu Agent Development Kit (ADK) i korzysta z narzędzi skonfigurowanych w zestawie narzędzi MCP dla baz danych.
9. (Opcjonalnie) Wdrażanie narzędzi MCP dla baz danych i agenta w Cloud Run
W poprzedniej sekcji użyliśmy terminala Cloud Shell, aby uruchomić serwer MCP Toolbox i przetestować narzędzia za pomocą agenta. Działało to lokalnie w środowisku powłoki Cloud Shell.
Możesz wdrożyć serwer MCP Toolbox i agenta w usługach Google Cloud, które mogą hostować te aplikacje.
Hostowanie serwera MCP Toolbox w Cloud Run
Na początek możemy uruchomić serwer MCP Toolbox w Cloud Run. Dzięki temu uzyskamy publiczny punkt końcowy, który możemy zintegrować z dowolną inną aplikacją lub aplikacjami agenta. Instrukcje dotyczące hostowania tego w Cloud Run znajdziesz tutaj. Omówimy teraz najważniejsze kroki.
Uruchom nowy terminal Cloud Shell lub użyj istniejącego. Otwórz folder mcp-toolbox, w którym znajdują się pliki binarne toolbox i tools.yaml.
Uruchom te polecenia (wyjaśnienie każdego z nich znajdziesz poniżej):
Ustaw zmienną PROJECT_ID, aby wskazywała identyfikator Twojego projektu Google Cloud.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Następnie sprawdź, czy w projekcie są włączone te usługi Google Cloud:
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Utwórzmy osobne konto usługi, które będzie tożsamością usługi Toolbox, którą wdrożymy w Google Cloud Run. Dbamy też o to, aby to konto usługi miało odpowiednie role, czyli możliwość dostępu do Secret Manager i komunikowania się z 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
Prześlemy plik tools.yaml jako klucz tajny. Ponieważ musimy zainstalować Toolbox w Cloud Run, użyjemy najnowszego obrazu kontenera Toolbox i ustawimy go w zmiennej IMAGE.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
Ostatni krok w znanym poleceniu wdrażania w Cloud Run:
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
Powinno to rozpocząć proces wdrażania serwera Toolbox z naszym skonfigurowanym tools.yaml w Cloud Run. Po pomyślnym wdrożeniu powinien wyświetlić się komunikat podobny do tego:
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
Możesz teraz otworzyć w przeglądarce adres Service URL podany powyżej. Powinien wyświetlić się komunikat „Hello World”, który widzieliśmy wcześniej.
Możesz też otworzyć Cloud Run w konsoli Google Cloud. Usługa Toolbox będzie widoczna na liście usług w Cloud Run.
Uwaga: jeśli chcesz nadal uruchamiać agenta hoteli lokalnie, ale połączyć go z nowo wdrożoną usługą Cloud Run, musisz wprowadzić tylko jedną zmianę w pliku my-agents/hotel_agent_app/agent.py.
Zamiast tego:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Zmień go na adres URL usługi Cloud Run podany poniżej:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
Przetestuj aplikację agenta, używając adk run lub adk web, jak widzieliśmy wcześniej.
Wdrażanie aplikacji agenta hotelowego w Cloud Run
Pierwszym krokiem jest upewnienie się, że zmiana została wprowadzona w my-agents/hotel_agent_app/agent.py zgodnie z powyższymi instrukcjami, aby wskazywała adres URL usługi Toolbox działającej w Cloud Run, a nie hosta lokalnego.
W nowym terminalu Cloud Shell lub w istniejącej sesji terminala upewnij się, że korzystasz z prawidłowego środowiska wirtualnego Pythona, które zostało skonfigurowane wcześniej.
Najpierw utwórz plik requirements.txt w folderze my-agents/hotel_agent_app, jak pokazano poniżej:
google-adk
toolbox-core
Przejdź do folderu my-agents i najpierw ustaw te zmienne środowiskowe:
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
Na koniec wdróż aplikację agenta w Cloud Run za pomocą polecenia adk deploy cloud_run, jak pokazano poniżej. Jeśli pojawi się prośba o zezwolenie na nieuwierzytelnione wywołania usługi, na razie podaj wartość „y”.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
Spowoduje to rozpoczęcie procesu wdrażania aplikacji agenta hotelowego w Cloud Run. Prześle źródła, spakuje je w kontenerze Dockera, wypchnie go do Artifact Registry, a następnie wdroży usługę w Cloud Run. Może to potrwać kilka minut, więc prosimy o cierpliwość.
Wyświetli się komunikat podobny do tego poniżej:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250905_132636
Copying agent source code...
Copying agent source code completed.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250905_132636/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_PROJECT_ID] region [us-central1]
- Building and deploying... Uploading sources.
- Uploading sources...
. Building Container...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/d1f7e76b-0587-4bb6-b9c0-bb4360c07aa0?project=415
458962931]. f
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00003-hrl] has been deployed and is serving 100 percent of traffic.
Service URL: <YOUR_CLOUDRUN_APP_URL>
INFO: Display format: "none"
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250905_132636
Po pomyślnym wdrożeniu otrzymasz wartość adresu URL usługi, do której możesz uzyskać dostęp w przeglądarce, aby wyświetlić tę samą aplikację internetową, która umożliwiała Ci czatowanie z pracownikiem hotelu, jak widzieliśmy wcześniej w konfiguracji lokalnej.
10. Czyszczenie
Aby uniknąć obciążania konta Google Cloud bieżącymi opłatami, usuń zasoby utworzone podczas tych warsztatów. Usuniemy instancję Cloud SQL, a jeśli wdrożysz Toolbox i aplikację Hotels w Cloud Run, usuniemy też te usługi.
Sprawdź, czy te zmienne środowiskowe są prawidłowo ustawione zgodnie z projektem i regionem:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
Te 2 polecenia usuwają wdrożone przez nas usługi Cloud Run:
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
To polecenie usuwa instancję Cloud SQL:
gcloud sql instances delete hoteldb-instance
11. Gratulacje
Gratulacje! Udało Ci się utworzyć agenta za pomocą pakietu Agent Development Kit (ADK), który korzysta z zestawu narzędzi MCP dla baz danych.