1. Wprowadzenie
W tym ćwiczeniu utworzysz agenta za pomocą pakietu Agent Development Kit (ADK), który korzysta z MCP Toolbox for Databases.
W tym laboratorium wykonasz te czynności:
- Utwórz bazę danych Cloud SQL for PostgreSQL, która będzie zawierać bazę danych hoteli i przykładowe dane.
- Skonfiguruj MCP Toolbox for Databases, który zapewnia dostęp do danych.
- Zaprojektuj i utwórz agenta za pomocą pakietu Agent Development Kit (ADK), który będzie korzystać z zestawu narzędzi MCP do odpowiadania na zapytania użytkowników.
- 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 MCP Toolbox for Databases 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, przeznaczone dla programistów na wszystkich poziomach zaawansowania (w tym dla początkujących), wykorzystuje w przykładowej aplikacji język Python. Znajomość języka Python nie jest jednak wymagana, a podstawowa umiejętność czytania kodu wystarczy, aby zrozumieć przedstawione koncepcje.
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 każdej usługi 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. Utworzenie 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 baz 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 wyświetlić się dane wyjściowe wskazujące, że polecenie zostało wykonane, a także informacje o instancji Cloud SQL, takie jak NAME, DATABASE_VERSION, LOCATION itp.
4. Przygotowywanie bazy danych hoteli
Teraz musimy utworzyć przykładowe dane dla naszego 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 instrukcję SQL SELECT, jak pokazano poniżej:
SELECT * FROM hotels;
W tabeli hoteli powinna być widoczna liczba rekordów, jak pokazano poniżej:
Zakończyliśmy proces konfigurowania instancji Cloud SQL i utworzyliśmy przykładowe dane. W następnej sekcji skonfigurujemy MCP Toolbox for Databases.
5. Konfigurowanie zestawu narzędzi MCP dla baz danych
MCP Toolbox for Databases to serwer MCP typu open source przeznaczony do baz danych. Został zaprojektowany z myślą o zastosowaniach w przedsiębiorstwach i środowiskach produkcyjnych. Umożliwia łatwiejsze, szybsze i bezpieczniejsze tworzenie narzędzi dzięki obsłudze złożonych funkcji, takich jak pula połączeń czy uwierzytelnianie.
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.
- Lepsza wydajność: sprawdzone metody, takie jak agregacja połączeń, uwierzytelnianie i inne.
- Ulepszone zabezpieczenia: zintegrowane uwierzytelnianie zapewniające bezpieczniejszy dostęp do danych
- Kompleksowa dostrzegalność: 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.
Widzisz, że jedną z baz danych obsługiwanych przez MCP Toolbox for Databases jest Cloud SQL, którą skonfigurowaliśmy w poprzedniej sekcji.
Instalowanie Toolboxa
Otwórz terminal Cloud Shell i utwórz folder o nazwie mcp-toolbox.
mkdir mcp-toolbox
Przejdź do folderu mcp-toolbox za pomocą polecenia pokazanego poniżej:
cd mcp-toolbox
Zainstaluj binarną wersję zestawu narzędzi MCP Toolbox for Databases za pomocą skryptu podanego poniżej. Poniższe polecenie jest przeznaczone dla systemu Linux, ale jeśli używasz Maca lub Windowsa, pobierz odpowiedni plik binarny. Odwiedź stronę wersji dla Twojego systemu operacyjnego i architektury i pobierz odpowiedni plik binarny.
export VERSION=1.13.1
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ędzia został prawidłowo skonfigurowany i czy wskazuje właściwą wersję.
Aby sprawdzić wersję pakietu narzędzi, wpisz to polecenie:
./toolbox -v
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ótki opis pliku:
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. Zazwyczaj 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, które może wykonywać agent, np. odczytywanie i zapisywanie danych 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 narzędzi.- 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 MCP Toolbox for Databases
Aby uruchomić serwer, uruchom to polecenie (w folderze mcp-toolbox):
./toolbox --config "tools.yaml"
Powinien pojawić się komunikat informujący, że serwer połączył się ze źródłami danych i załadował zestaw narzędzi. Przykładowe dane wyjściowe:
2026-09-26T14:00:35.898358+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6"
2026-09-26T14:00:39.571556+05:30 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-09-26T14:00:39.571634+05:30 INFO "Initialized 0 authServices: "
2026-09-26T14:00:39.571648+05:30 INFO "Initialized 0 embeddingModels: "
2026-09-26T14:00:39.571728+05:30 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2026-09-26T14:00:39.571745+05:30 INFO "Initialized 0 prompts: "
2026-09-26T14:00:39.571756+05:30 INFO "Initialized 0 resources: "
2026-09-26T14:00:39.571767+05:30 INFO "Initialized 0 resource templates: "
2026-09-26T14:00:39.571851+05:30 INFO "Initialized 2 groups: my_first_toolset, default"
2026-09-26T14:00:39.571905+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses."
2026-09-26T14:00:39.571939+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains."
2026-09-26T14:00:39.572261+05:30 INFO "Server ready to serve!"
Serwer MCP Toolbox działa domyślnie na porcie 5000. Jeśli okaże się, że port 5000 jest już używany, możesz użyć innego portu (np. 7000), zgodnie z poleceniem pokazanym poniżej. W kolejnych poleceniach używaj portu 7000 zamiast portu 5000.
./toolbox --config "tools.yaml" --port 7000
Użyjemy Cloud Shell, aby to przetestować.
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 MCP Toolbox for Databases
Zestaw narzędzi udostępnia interfejs wizualny (interfejs zestawu 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 MCP Toolbox for Databases, 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ę ze źródłami danych i załadował zestaw narzędzi. Poniżej znajdziesz przykładowe dane wyjściowe. Zauważysz, że informują one o tym, że interfejs Toolbox działa.
2026-09-26T14:01:17.208487+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6"
2026-09-26T14:01:20.823447+05:30 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-09-26T14:01:20.82353+05:30 INFO "Initialized 0 authServices: "
2026-09-26T14:01:20.823545+05:30 INFO "Initialized 0 embeddingModels: "
2026-09-26T14:01:20.823629+05:30 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2026-09-26T14:01:20.823649+05:30 INFO "Initialized 0 prompts: "
2026-09-26T14:01:20.82366+05:30 INFO "Initialized 0 resources: "
2026-09-26T14:01:20.823671+05:30 INFO "Initialized 0 resource templates: "
2026-09-26T14:01:20.823745+05:30 INFO "Initialized 2 groups: my_first_toolset, default"
2026-09-26T14:01:20.823795+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses."
2026-09-26T14:01:20.823829+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains."
2026-09-26T14:01:20.824193+05:30 INFO "Server ready to serve!"
2026-09-26T14:01:20.824231+05:30 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 podobny do tego poniżej:
Po lewej stronie kliknij opcję Narzędzia, 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 je przetestować. Wpisz wymagane wartości parametrów, a potem kliknij Uruchom narzędzie, aby zobaczyć wynik. Przykładowe uruchomienie pokazano poniżej:
Wracając do wcześniejszego diagramu (jak pokazano poniżej), widzimy, że skonfigurowaliśmy już bazę danych i serwer MCP. Mamy teraz 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 MCP Server Toolbox 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ń Antigravity
Antigravity CLI to lekki interfejs użytkownika terminala (TUI) Antigravity. Zapewnia te same podstawowe funkcje agenta co Antigravity (takie jak wieloetapowe wnioskowanie, edytowanie wielu plików, wywoływanie narzędzi i historia rozmów) bezpośrednio w terminalu. Możesz go używać zarówno do zadań związanych z kodowaniem, jak i do innych. 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 MCP Toolbox for Databases w Antigravity CLI, a następnie użyjemy Antigravity CLI do komunikacji z naszymi danymi.
Najpierw sprawdzimy, czy masz uruchomiony zestaw narzędzi w jednym z terminali Cloud Shell. Jeśli serwer MCP działa na porcie domyślnym 5000, interfejs serwera MCP jest dostępny w tym punkcie końcowym: 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-agy-cli-project
cd my-agy-cli-project
Wydaj to polecenie, aby dodać serwer MCP do listy serwerów MCP skonfigurowanych w interfejsie Antigravity CLI.
agy mcp add "MCPToolbox" "http://localhost:5000/mcp"
Aktualną listę serwerów MCP skonfigurowanych w interfejsie Antigravity CLI możesz sprawdzić za pomocą tego polecenia:
agy mcp list
Obok skonfigurowanego przez nas narzędzia MCPToolbox powinien pojawić się zielony znacznik wyboru, który oznacza, że interfejs wiersza poleceń Gemini może połączyć się z serwerem MCP.
NAME TYPE STATUS COMMAND/URL
MCPToolbox http enabled http://localhost:5000/mcp
Zanim uruchomisz 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
Upewnij się, że na tym samym terminalu jesteś w folderze my-agy-cli-project. Uruchom interfejs wiersza poleceń Antigravity za pomocą polecenia agy.
Spowoduje to wyświetlenie interfejsu Antigravity CLI. Aby wyświetlić listę serwerów MCP i narzędzi, możesz użyć polecenia /mcp. Oto przykładowe dane wyjściowe:
MCP Servers
Plugins (~/.gemini/config/plugins)
> ✓ MCPToolbox Tools: search-hotels-by-location, search-hotels-by-name
Możesz teraz podać dowolny prompt:
Which hotels are there in Basel?Tell me more about the Hyatt Regency?
Zauważysz, że w przypadku powyższych zapytań interfejs Antigravity CLI wybierze odpowiednie narzędzie z MCPToolbox. Poprosi Cię o zezwolenie na uruchomienie narzędzia. Przyznaj mu niezbędne uprawnienia, a zobaczysz, ż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ń.
$ adk
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...
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...
run Runs an agent.
telemetry Manage telemetry settings.
test Runs pytest on agent test JSON files under the specified...
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 i wybierz:
- Wybierz model
gemini-3.8-flash, aby wybrać model dla agenta głównego. - Wybierz backend
Vertex AI. - Wyświetli się domyślny identyfikator projektu Google. Wybierz tę opcję.
- Wyświetli się bieżący region projektu Google Cloud. Wpisz
global.
Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2
1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 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]: global
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app:
- .env
- .gitignore
- __init__.py
- agent.py
Sprawdź folder, w którym utworzono szablon domyślny i wymagane pliki agenta. Pliki możesz wyświetlić za pomocą polecenia ls -al w terminalu w katalogu <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app.
Pierwszy jest 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_ENTERPRISE=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 w 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 jedno stwierdzenie importujące agenta z pliku agent.py.
from . import agent
Na koniec przyjrzyjmy się plikowi agent.py. Treść jest widoczna poniżej:
from google.adk.agents.llm_agent import Agent
root_agent = Agent(
model='gemini-3.8-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. Zgodnie z dokumentacją ADK agent to samodzielna jednostka wykonawcza zaprojektowana do autonomicznego działania w celu osiągnięcia określonych celów. Agenty 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żyć. 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.llm_agent import Agent
root_agent = Agent(
model='gemini-3.8-flash',
name='root_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.',
)
Testowanie aplikacji agenta lokalnie
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 [61397]
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:
Możesz zamknąć proces działający w terminalu Cloud Shell (Ctrl-C).
Innym sposobem na przetestowanie agenta jest użycie polecenia adk run podanego poniżej w folderze my-agents.
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
Wiemy już, jak napisać agenta i przetestować go lokalnie. Połączymy tego agenta z narzędziami. W kontekście ADK narzędzie to konkretna funkcja udostępniana agentowi AI, która umożliwia mu podejmowanie działań i interakcje ze światem wykraczające poza podstawowe możliwości generowania tekstu i rozumowania.
W tym przypadku wyposażymy naszego agenta w narzędzia, które skonfigurowaliśmy w zestawie narzędzi MCP dla baz danych.
Zmodyfikuj plik agent.py, wklejając do niego ten kod. Zwróć uwagę, że w kodzie używamy domyślnego portu 5000, ale jeśli używasz innego numeru portu, użyj 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-3.8-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 Toolbox for Databases. Może być już uruchomiony lokalnie na porcie 5000, ponieważ testowaliśmy go wcześniej. Jeśli nie, uruchom serwer, wykonując to polecenie (z poziomu folderu mcp-toolbox):
./toolbox --config "tools.yaml"
Powinien pojawić się komunikat informujący, że serwer połączył się ze źródłami danych i załadował zestaw narzędzi.
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 search for and find information about hotels! Specifically, I can:
* **Find hotels in a specific city or location:** Look up available hotels, sorted by price from least to most expensive.
* **Search for hotels by name:** Get details on a specific hotel you're interested in.
Feel free to tell me where you're planning to stay or which hotel you'd like to look up!
[user]: I would like to search for hotels?
[hotel_agent]: I'd be happy to help!
Where are you planning to travel, or is there a specific hotel name you have in mind?
[user]: I am planning to travel to Basel
[hotel_agent]: Here are the hotels available in **Basel**, listed from least to most expensive:
1. **Holiday Inn Basel**
* **Price Tier:** Upper Midscale
* **Available Dates:** April 9, 2024 – April 24, 2024
2. **Hyatt Regency Basel**
* **Price Tier:** Upper Upscale
* **Available Dates:** April 2, 2024 – April 20, 2024
3. **Hilton Basel**
* **Price Tier:** Luxury
* **Available Dates:** April 20, 2024 – April 22, 2024
Would you like more details about any of these hotels, or do you have specific travel dates in mind?
[user]:
. . .
Zwróć uwagę, że agent korzysta teraz z 2 narzędzi skonfigurowanych w zestawie narzędzi MCP Toolbox for Databases (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ł zbudowany przy użyciu pakietu Agent Development Kit (ADK) i oparty na narzędziach skonfigurowanych w MCP Toolbox for Databases.
9. (Opcjonalnie) Wdrażanie MCP Toolbox for Databases i agenta w Cloud Run
W poprzedniej sekcji użyliśmy terminala Cloud Shell, aby uruchomić serwer zestawu narzędzi MCP 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 i hostować go 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 tej aplikacji 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 tak, 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 działać jako tożsamość 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 Managera 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 tajny klucz. Ponieważ musimy zainstalować Toolbox w Cloud Run, użyjemy najnowszego obrazu kontenera dla 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ć się 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 w my-agents/hotel_agent_app/agent.py wprowadzono opisaną powyżej zmianę, aby wskazywał on adres URL usługi Toolbox działającej w Cloud Run, a nie host lokalny.
W nowym terminalu Cloud Shell lub w istniejącej sesji terminala sprawdź, czy korzystasz z właściwego wirtualnego środowiska Pythona, które zostało skonfigurowane wcześniej.
Najpierw utwórzmy 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_ENTERPRISE=1
Na koniec wdróż aplikację agenta w Cloud Run za pomocą polecenia adk deploy cloud_run, jak pokazano poniżej. Jeśli pojawi się pytanie o pozwolenie na nieuwierzytelnione wywołania usługi, na razie wpisz „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, przekaże 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
Poniższe polecenie usuwa instancję Cloud SQL:
gcloud sql instances delete hoteldb-instance
11. Gratulacje
Gratulacje! Udało Ci się utworzyć agenta turystycznego za pomocą pakietu Agent Development Kit (ADK), który korzysta z MCP Toolbox for Databases. Dowiedzieliśmy się też, jak łączyć agentów z własnymi bazami danych i opcjonalnie instalować agenta i zestaw narzędzi w Cloud Run.