1. Wprowadzenie
W tym ćwiczeniu w Codelabs utworzysz agenta za pomocą zestawu Agent Development Kit (ADK), który korzysta z MCP Toolbox for Databases.
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 MCP Toolbox for Databases, 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 narzędzi Agent i MCP Toolbox for Databases lokalnie i w Google Cloud za pomocą usługi Cloud Run.
Co musisz zrobić
- Zaprojektuj, zbuduj 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.
- Zaprojektuj i opracuj agenta za pomocą pakietu Agent Development Kit (ADK), aby odpowiadać na zapytania użytkowników.
- Przetestuj narzędzia Agent i MCP Toolbox for Databases w środowisku lokalnym.
- (Opcjonalnie) wdróż narzędzia Agent i MCP Toolbox for Databases w Google Cloud.
Czego potrzebujesz
- przeglądarki Chrome,
- konto Gmail,
- Projekt w chmurze z włączonymi płatnościami
Ten przewodnik, przeznaczony dla deweloperó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 podstawowe umiejętności czytania kodu wystarczą do zrozumienia przedstawionych koncepcji.
2. Zanim zaczniesz
Utwórz projekt
- W konsoli Google Cloud na stronie selektora projektów 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 włączone są 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 jesteś już uwierzytelniony i czy projekt jest 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 zachowaj 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, zawsze 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, a także informacje o instancji Cloud SQL, takie jak NAME, DATABASE_VERSION, LOCATION itp.
4. Przygotowywanie bazy danych hoteli
Naszym zadaniem będzie teraz utworzenie przykładowych danych 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:
Zostaniesz poproszony(-a) 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:
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 MCP Toolbox for Databases
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 o jakości produkcyjnej. 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.
Toolbox pomaga tworzyć narzędzia oparte na generatywnej AI, które umożliwiają Twoim agentom dostęp do danych w bazie danych. Zestaw narzędzi zapewnia:
- Uproszczone tworzenie: zintegruj narzędzia z agentem w mniej niż 10 wierszach kodu, ponownie wykorzystuj narzędzia w wielu agentach lub platformach i łatwiej wdrażaj nowe wersje narzędzi.
- Lepsza wydajność: sprawdzone metody, takie jak pula 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 płaszczyznę sterowania, 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ę MCP Toolbox for Databases za pomocą skryptu podanego poniżej. Poniższe polecenie jest przeznaczone dla systemu Linux, ale jeśli używasz komputera Mac lub Windows, pobierz odpowiedni plik binarny. Odwiedź stronę z wersjami dla Twojego systemu operacyjnego i architektury i pobierz odpowiedni plik binarny.
export VERSION=0.13.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Mamy teraz gotową do użycia wersję binarną zestawu narzędzi. 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.
sources:
my-cloud-sql-source:
kind: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: "postgres"
tools:
search-hotels-by-name:
kind: 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 || '%';
search-hotels-by-location:
kind: 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;
toolsets:
my_first_toolset:
- 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. 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, 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.- 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.
Uruchomienie narzędzi MCP dla serwera baz danych
Aby uruchomić serwer, wykonaj to polecenie (w folderze mcp-toolbox):
./toolbox --tools-file "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:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z 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), zgodnie z poleceniem pokazanym poniżej. W kolejnych poleceniach używaj portu 7000 zamiast portu 5000.
./toolbox --tools-file "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:
Na końcu adresu URL w przeglądarce dodaj:
/api/toolset
Powinny się pojawić skonfigurowane obecnie narzędzia. Przykładowe dane wyjściowe są widoczne poniżej:
{
"serverVersion": "0.13.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location. Result is sorted by price from least to most expensive.",
"parameters": [
{
"name": "location",
"type": "string",
"required": true,
"description": "The location of the hotel.",
"authSources": []
}
],
"authRequired": []
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"required": true,
"description": "The name of the hotel.",
"authSources": []
}
],
"authRequired": []
}
}
}
Testowanie narzędzi w interfejsie MCP Toolbox for Databases
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 MCP Toolbox for Databases, która może być uruchomiona, i wpisz to polecenie:
./toolbox --tools-file "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.
2025-09-08T02:44:11.561572538Z INFO "Initialized 1 sources."
2025-09-08T02:44:11.561966395Z INFO "Initialized 0 authServices."
2025-09-08T02:44:11.562060934Z INFO "Initialized 2 tools."
2025-09-08T02:44:11.562105678Z INFO "Initialized 2 toolsets."
2025-09-08T02:44:11.568209923Z INFO "Server ready to serve!"
2025-09-08T02:44:11.568259411Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui"
Kliknij adres URL interfejsu i upewnij się, że na końcu adresu URL znajduje się znak /ui. Wyświetli się interfejs użytkownika, jak pokazano 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 przetestować narzędzie, podając wymagane wartości parametrów, a następnie kliknąć Uruchom narzędzie, aby zobaczyć wynik. Przykładowe uruchomienie:
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. Pominiemy ten krok i w następnej sekcji przejdziemy bezpośrednio do zestawu Agent Development Kit (ADK), który wykorzystuje te narzędzia.
6. 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.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Tworzenie pierwszej aplikacji agenta
Teraz użyjemy adk, aby utworzyć szkielet aplikacji Hotel Agent Application 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:
- 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.
Pierwszy to plik .env. Ich zawartość jest widoczna 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 jedno stwierdzenie importujące 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. Zgodnie z dokumentacją ADK na tej stronie 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, powszechnie znany jako Agent, wykorzystuje duże modele językowe (LLM) jako główny silnik do rozumienia języka naturalnego, wnioskowania, planowania, generowania odpowiedzi i dynamicznego decydowania o tym, 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 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.
7. Łączenie agenta z narzędziami
Wiesz już, jak napisać agenta i przetestować go lokalnie. Połączymy tego agenta z narzędziami. W kontekście ADK narzędzie reprezentuje konkretną funkcję udostępnianą agentowi AI, która umożliwia mu wykonywanie działań i interakcje ze światem wykraczające poza podstawowe możliwości generowania tekstu i wnioskowania.
W tym przypadku wyposażymy naszego agenta w narzędzia, które skonfigurowaliśmy w MCP Toolbox for Databases.
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 MCP Toolbox for Databases. 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 --tools_file "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:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
Gdy serwer MCP zostanie uruchomiony, w innym terminalu uruchom agenta w sposób opisany 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/
Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
Zwróć uwagę, że agent korzysta teraz z 2 narzędzi skonfigurowanych w przyborniku MCP dla baz danych (search-hotels-by-name i search-hotels-by-location) i podaje 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 zestawu Agent Development Kit (ADK) i wykorzystuje narzędzia skonfigurowane w MCP Toolbox for Databases.
8. (Opcjonalnie) Wdrażanie MCP Toolbox for Databases 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 Cloud Shell.
Możesz wdrożyć zarówno serwer MCP Toolbox, jak i agenta w usługach Google Cloud, które mogą hostować te aplikacje.
Hostowanie serwera Zestawu narzędzi MCP 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. Przejdź do folderu 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 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. Musimy zainstalować Toolbox w Cloud Run, więc 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="--tools_file=/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 wymieniony powyżej adres Service URL. Powinien wyświetlić się komunikat „Hello World”, który widzieliśmy wcześniej. Możesz też otworzyć ten adres URL, aby zobaczyć dostępne narzędzia:
SERVICE URL/api/toolset
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 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
Rozpocznie to proces wdrażania aplikacji Hotel Agent 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 zachowaj 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.
9. 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
10. Gratulacje
Gratulacje! Udało Ci się utworzyć agenta za pomocą zestawu Agent Development Kit (ADK), który korzysta z zestawu narzędzi MCP do baz danych.