Tworzenie agenta turystycznego za pomocą zestawu narzędzi MCP dla baz danych i zestawu narzędzi dla agentów (ADK)
Informacje o tym ćwiczeniu (w Codelabs)
1. Wprowadzenie
W tym ćwiczeniu w Codelab utworzysz agenta za pomocą pakietu Agent Development Kit (ADK), który korzysta z MCP Toolbox for Databases.
W ramach tego ćwiczenia będziesz wykonywać czynności krok po kroku:
- Zarezerwuj bazę danych Cloud SQL for PostgreSQL, która będzie zawierać bazę danych hoteli i przykładowe dane.
- Skonfiguruj narzędzie MCP Toolbox for Databases, które zapewnia dostęp do danych.
- Zaprojektuj i opublikuj agenta za pomocą pakietu deweloperskiego agenta (ADK), który będzie korzystać z skrzynki narzędzi MCP do odpowiadania na pytania użytkownika.
- Poznaj opcje testowania narzędzia Agent i MCP dla baz danych lokalnie i w Google Cloud za pomocą usługi Cloud Run.
Co musisz zrobić
- Zaprojektuj, zbuduj i wdróż agenta, który będzie odpowiadać na pytania użytkowników dotyczące hoteli w danej lokalizacji lub umożliwiać wyszukiwanie hoteli według nazwy.
Czego się nauczysz
- Prowadzenie wstępnej konfiguracji bazy danych Cloud SQL for PostgreSQL i wypełnianie jej przykładowymi danymi.
- Skonfiguruj narzędzie MCP Toolbox for Databases dla instancji bazy danych Cloud SQL for PostgreSQL.
- Zaprojektuj i opublikuj agenta za pomocą pakietu narzędzi dla deweloperów agentów (ADK), aby odpowiadał na pytania użytkowników.
- przetestuj narzędzia agenta i MCP do obsługi baz danych w środowisku lokalnym;
- (Opcjonalnie) Wdróż Agenta i MCP Toolbox dla baz danych w Google Cloud.
Czego potrzebujesz
- przeglądarka Chrome,
- konto Gmail,
- projekt w chmurze z włączonymi płatnościami,
Ten warsztat programistyczny przeznaczony dla deweloperów na wszystkich poziomach zaawansowania (w tym początkujących) używa Pythona w próbnej aplikacji. Jednak znajomość Pythona nie jest wymagana do zrozumienia omawianych zagadnień.
2. Zanim zaczniesz
Utwórz projekt
- W konsoli Google Cloud na stronie selektora 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 .
- Użyjesz Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud, które jest wstępnie wczytane w bq. Kliknij Aktywuj Cloud Shell u góry konsoli Google Cloud.
- Po połączeniu z Cloud Shell sprawdź, czy jesteś już uwierzytelniony i czy projekt jest ustawiony na identyfikator Twojego projektu, używając tego polecenia:
gcloud auth list
- Aby sprawdzić, czy 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:
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:
Operation "operations/..." finished successfully.
Alternatywą dla polecenia gcloud jest konsola, w której możesz wyszukać poszczególne usługi lub skorzystać z tego linku.
Jeśli pominiesz któryś interfejs API, zawsze możesz go włączyć w trakcie implementacji.
Informacje o poleceniach i użytkowaniu gcloud znajdziesz w dokumentacji.
3. Tworzenie instancji Cloud SQL
Do przechowywania danych o hotelach użyjemy instancji Google Cloud SQL for PostgreSQL. Cloud SQL for PostgreSQL to w pełni zarządzana usługa bazy danych, która ułatwia konfigurację i utrzymanie relacyjnych baz danych PostgreSQL w Google Cloud Platform, a także zarządzanie i administrowanie nimi.
Aby utworzyć instancję, uruchom w Cloud Shell to polecenie:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--cpu=2 \
--memory=8GiB \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Wykonanie tego polecenia zajmuje około 3–5 minut. Po wykonaniu polecenia powinny pojawić się dane wyjściowe potwierdzające jego wykonanie oraz informacje o instancji Cloud SQL, takie jak NAME, DATABASE_VERSION, LOCATION itp.
4. Przygotowanie bazy danych Hotels
Naszym zadaniem będzie teraz utworzenie przykładowych danych dla naszego pracownika obsługi klienta.
W konsoli Cloud otwórz Cloud SQL.Powinieneś zobaczyć gotową i utworzoną instancję hoteldb-instance. Kliknij nazwę instancji (hoteldb-instance), jak pokazano poniżej:
W menu po lewej stronie Cloud SQL kliknij Cloud SQL Studio, jak pokazano na ilustracji:
Pojawi się prośba o zalogowanie się w Cloud SQL Studio, za pomocą którego podamy kilka poleceń SQL. W przypadku opcji Baza danych wybierz wartość postgres, a w przypadku opcji Użytkownik i Hasło – wartość 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łnij tabelę „hotels” 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-22', '2024-04-20', 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-24', '2024-04-05', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', 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, wykonując zapytanie SQL SELECT, jak pokazano poniżej:
SELECT * FROM hotels;
W tabeli hotels powinno być widocznych kilka rekordów, jak pokazano poniżej:
Zakończyliśmy konfigurowanie instancji Cloud SQL i utworzyliśmy przykładowe dane. W następnej sekcji skonfigurujemy narzędzia MCP dla baz danych.
5. Konfigurowanie MCP Toolbox dla baz danych
MCP Toolbox for Databases to serwer MCP typu open source przeznaczony do baz danych. Został zaprojektowany z myślą o jakości na poziomie przedsiębiorstwa i produkcji. Dzięki temu możesz tworzyć narzędzia łatwiej, szybciej i bezpieczniej, ponieważ biblioteka ta obsługuje złożone zadania, takie jak łączenie połączeń i uwierzytelnianie.
Toolbox pomaga Ci tworzyć narzędzia oparte na generatywnej AI, które umożliwiają pracownikom obsługi klienta dostęp do danych w Twojej bazie danych. Zestaw narzędzi zawiera:
- Uproszczone tworzenie: integracja narzędzi z agentem w mniej niż 10 wierszach kodu, możliwość ponownego użycia narzędzi w różnych agentach lub ramach oraz łatwiejsze wdrażanie nowych wersji narzędzi.
- Większa wydajność: sprawdzone metody, takie jak grupowanie połączeń, uwierzytelnianie i inne.
- Ulepszone zabezpieczenia: zintegrowana autoryzacja zapewniająca bezpieczniejszy dostęp do danych
- Całkowita obserwowalność: gotowe wskaźniki i śledzenie z wbudowanym wsparciem dla OpenTelemetry.
Toolbox znajduje się między systemem orkiestracji aplikacji a bazą danych. Zapewnia płaszczyznę kontrolną, która służy do modyfikowania, rozpowszechniania i wywoływania narzędzi. Ułatwia zarządzanie narzędziami, ponieważ zapewnia scentralizowane miejsce do przechowywania i aktualizowania narzędzi. Umożliwia też udostępnianie narzędzi między pracownikami i aplikacji oraz aktualizowanie tych narzędzi 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ą zarezerwowaliś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 wersję binarną MCP Toolbox for Databases za pomocą podanego niżej skryptu:
export VERSION=0.6.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Mamy już gotową wersję binarną narzędzia. Następnym krokiem jest skonfigurowanie narzędzia za pomocą naszych źródeł danych i innych konfiguracji.
Konfigurowanie pliku tools.yaml
Głównym sposobem konfigurowania Toolboxa jest plik tools.yaml. Utwórz plik o nazwie tools.yaml w tym samym folderze, czyli mcp-toolbox. Jego treść została podana poniżej.
Możesz użyć edytora nano, który jest dostępny w Cloud Shell. Polecenie nano to „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.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Abyśmy mogli szybko zrozumieć plik:
Sourcesto różne źródła danych, z którymi narzędzie może wchodzić w interakcje. Źródło reprezentuje źródło danych, z którym narzędzie może wchodzić w interakcję. W sekcji źródeł w pliku tools.yaml możesz zdefiniowaćSourcesjako mapę. Konfiguracja źródła zawiera zwykle wszystkie informacje potrzebne do połączenia z bazą danych i interakcji z nią. W naszym przypadku skonfigurowaliśmy pojedyncze źródło, które wskazuje na naszą instancję Cloud SQL for PostgreSQL za pomocą danych logowania. Więcej informacji znajdziesz w materiałach źródłowych.Toolsdefiniuje działania, które może wykonywać agent, np. odczytywanie i zapisywanie w źródle. Narzędzie reprezentuje działanie, które może wykonać agent, np. uruchomienie instrukcji SQL. W sekcji narzędzi pliku tools.yaml możesz zdefiniowaćToolsjako mapę. Zwykle narzędzie wymaga źródła danych. W naszym przypadku definiujemy 2 narzędzia:search-hotels-by-nameisearch-hotels-by-location, a także źródło, na które działają, wraz z kodem SQL i parametrami. Więcej informacji znajdziesz w narzędziach.- Na koniec mamy
Toolset, który pozwala definiować grupy narzędzi, które chcesz ładować 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 zestawu narzędzi MCP dla serwera baz danych
Aby uruchomić serwer, uruchom to polecenie (z folderu mcp-toolbox):
./toolbox --tools-file "tools.yaml"
W idealnej sytuacji powinieneś zobaczyć, że serwer mógł połączyć się z naszym źródłem danych i wczytał zestaw narzędzi. Poniżej znajdziesz przykładowe dane wyjściowe:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z 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ż zajęty, możesz użyć innego portu (np. 7000) zgodnie z poleceniem pokazanym poniżej. W kolejnych poleceniach zamiast portu 5000 używaj portu 7000.
./toolbox --tools-file "tools.yaml" --port 7000
Zweryfikujmy to za pomocą 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, a następnie kliknij Zmień i wyświetl podgląd.
Powinny się wyświetlić te dane wyjściowe:
W adresie URL przeglądarki dodaj na końcu:
/api/toolset
Powinny się wyświetlić obecnie skonfigurowane narzędzia. Poniżej znajdziesz przykładowe dane wyjściowe:
{
"serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location.",
"parameters": [
{
"name": "location",
"type": "string",
"description": "The location of the hotel.",
"authSources": []
}
]
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"description": "The name of the hotel.",
"authSources": []
}
]
}
}
}
Zestaw narzędzi MCP do obsługi baz danych zawiera opis sposobu weryfikowania i testowania narzędzi za pomocą Pythona. Dokumentacja jest dostępna tutaj. Pomijamy to i w następnej sekcji przechodzimy bezpośrednio do pakietu narzędzi dewelopera (ADK), który wykorzystuje te narzędzia.
6. Tworzenie agenta za pomocą pakietu narzędzi dla programistów
Instalowanie zestawu do tworzenia aplikacji (ADK)
Otwórz nową kartę terminala w Cloud Shell i utwórz folder o nazwie my-agents w następujący sposób: Przejdź też do folderu my-agents.
mkdir my-agents
cd my-agents
Teraz utwórz wirtualne środowisko Pythona za pomocą venv w ten sposób:
python -m venv .venv
Aby aktywować środowisko wirtualne:
source .venv/bin/activate
Zainstaluj pakiety ADK i MCP Toolbox for Databases wraz z zależnościami językowymi w ten sposób:
pip install google-adk toolbox-core
Teraz możesz wywołać narzędzie adk w ten sposób.
adk
Wyświetli się lista poleceń.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--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 narzędzia adk do utworzenia szkieletu aplikacji dla agenta hotelowego za pomocą polecenia adk create z nazwą aplikacji **(hotel-agent-app)**podaną poniżej.
adk create hotel-agent-app
Wykonaj te czynności i wybierz:
- Model Gemini do wyboru modelu dla głównego agenta.
- Jako backend wybierz Vertex AI.
- Wyświetli się domyślny identyfikator projektu Google i region. Wybierz domyślną opcję.
Choose a model for the root agent:
1. gemini-2.0-flash-001
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 [gcp-experiments-349209]:
Enter Google Cloud region [us-central1]:
Agent created in /home/romin/hotel-agent-app:
- .env
- __init__.py
- agent.py
Sprawdź folder, w którym utworzono domyślny szablon i pliki wymagane do działania agenta.
Najpierw plik .env. Treści, które są wyświetlane poniżej:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Wartości wskazują, że będziemy używać Gemini przez Vertex AI, wraz z odpowiednimi wartościami identyfikatora projektu i lokalizacji Google Cloud.
Następnie mamy plik __init__.py, który oznacza folder jako moduł i zawiera pojedyncze polecenie, które importuje agenta z pliku agent.py.
from . import agent
Na koniec przyjrzyjmy się plikowi agent.py. Treści:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
To najprostszy agent, jaki można napisać za pomocą ADK. Jak czytamy na stronie z dokumentacją ADK, agent to samodzielna jednostka wykonawcza, która działa autonomicznie, aby osiągać określone cele. Może wykonywać zadania, wchodzić w interakcje z użytkownikami, korzystać z zewnętrznych narzędzi i współdziałać z innymi agentami.
W szczególności LLMAgent, który jest często nazywany po prostu „asystentem”, wykorzystuje duże modele językowe (LLM) jako główny mechanizm do rozumienia języka naturalnego, rozumowania, planowania, generowania odpowiedzi i dynamicznego podejmowania decyzji o tym, jak postępować lub których narzędzi używać. Dzięki temu jest idealny do wykonywania elastycznych zadań związanych z językiem. Więcej informacji o agentach LLM znajdziesz tutaj.
Zmieńmy kod w sekcji agent.py w ten sposób:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
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.',
)
Testowanie aplikacji agenta lokalnie
W oknie terminala wpisz to polecenie. Upewnij się, że jesteś w folderze nadrzędnym (my-agents) zawierającym folder hotel-agent-app.
adk web
Poniżej przedstawiamy przykład wykonania:
INFO: Started server process [5015]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
Kliknij ostatni link, aby otworzyć konsolę internetową, w której możesz przetestować agenta. W przeglądarce powinna się otworzyć strona podobna do tej:
Zwróć uwagę, że w lewym górnym rogu została zidentyfikowana aplikacja hotel-agent-app. Możesz teraz rozpocząć rozmowę z pracownikiem obsługi klienta. Zadaj kilka pytań dotyczących miast. Poniżej znajduje się przykładowa rozmowa:
Możesz zamknąć proces uruchomiony w terminalu Cloud Shell (Ctrl-C).
Innym sposobem testowania agenta jest użycie polecenia adk run, jak pokazano poniżej, z folderu my-agents.
adk run hotel-agent-app
Wypróbuj to polecenie, a potem możesz rozmawiać z agentem za pomocą wiersza poleceń (terminala). Aby zamknąć rozmowę, wpisz exit.
7. Łączenie pracownika obsługi klienta z narzędziami
Wiemy już, jak napisać agenta i przetestować go lokalnie. Połączymy tego pracownika obsługi klienta z zespołem narzędzi. W kontekście ADK narzędzie to określona funkcja udostępniana agentowi AI, która umożliwia mu wykonywanie działań i nawiązywanie interakcji ze światem poza podstawowymi możliwościami generowania tekstu i rozumowania.
W naszym przypadku chcemy teraz wyposażyć naszego agenta w narzędzia skonfigurowane w narzędziach MCP dla baz danych.
Zmodyfikuj plik agent.py, dodając do niego ten kod. W kodzie używamy domyślnego portu 5000, ale jeśli używasz innego 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-2.0-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ć:
W jednym terminalu Cloud Shell uruchom narzędzia MCP dla baz danych. Może ona już działać lokalnie na porcie 5000, jak miało to miejsce podczas wcześniejszego testowania. Jeśli nie, uruchom to polecenie (z folderu mcp-toolbox), aby uruchomić serwer:
./toolbox --tools_file "tools.yaml"
W idealnej sytuacji powinieneś zobaczyć, że serwer mógł połączyć się z naszym źródłem danych i wczytał zestaw narzędzi. Poniżej znajdziesz przykładowe dane wyjściowe:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
Gdy serwer MCP zostanie uruchomiony, w innym terminalu uruchom agenta, tak jak to zrobiliśmy wcześniej, za pomocą polecenia adk run (z folderu my-agents), jak pokazano 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 narzędziach MCP do obsługi baz danych (search-hotels-by-name i search-hotels-by-location) i podaje nam odpowiednie opcje. Następnie może bezproblemowo pobrać dane z bazy danych instancji PostgreSQL i odpowiednio sformatować odpowiedź.
To kończy lokalny rozwój i testowanie naszego agenta hotelowego, który został utworzony za pomocą pakietu narzędzi dla agentów (ADK) i wykorzystuje narzędzia skonfigurowane w narzędziu MCP Toolbox do obsługi baz danych.
8. (Opcjonalnie) Wdrażanie MCP Toolbox for Databases and Agent w Cloud Run
W poprzedniej sekcji użyliśmy terminala Cloud Shell do uruchomienia serwera MCP Toolbox i przetestowaliśmy narzędzia za pomocą agenta. Było ono uruchamiane lokalnie w środowisku 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
Najpierw możemy zacząć od serwera MCP Toolbox i hostować go w Cloud Run. Dzięki temu uzyskamy publiczny punkt końcowy, który można zintegrować z dowolną inną aplikacją lub aplikacjami agenta. Instrukcje dotyczące hostowania w Cloud Run znajdziesz tutaj. Teraz omówimy najważniejsze kroki.
Uruchom nowy terminal Cloud Shell lub użyj istniejącego terminalu Cloud Shell. Otwórz folder mcp-toolbox, w którym znajdują się pliki binarne toolbox i tools.yaml.
Uruchom te polecenia (obok każdego z nich znajdziesz wyjaśnienie):
Ustaw zmienną PROJECT_ID tak, aby wskazywała na identyfikator 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órz osobne konto usługi, które będzie pełnić funkcję tożsamości usługi Toolbox, którą będziemy wdrażać w Google Cloud Run. Sprawdzamy też, czy to konto usługi ma odpowiednie role, np. możliwość dostępu do usługi Secret Manager i korzystanie 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. Ponieważ musimy zainstalować Toolbox w Cloud Run, użyjemy najnowszego obrazu kontenera dla narzędzia 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 już 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
Powinien rozpocząć się proces wdrażania serwera Toolbox z skonfigurowanym tools.yaml do 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ć stronę Service URL wymienioną powyżej w przeglądarce. Powinien wyświetlić się komunikat „Hello World”. 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, a na liście usług w Cloud Run zobaczysz usługę Toolbox.
Uwaga: jeśli chcesz nadal uruchamiać Hotel Agent lokalnie i nawiązać połączenie z nowo wdrożonym wystąpieniem usługi Cloud Run, wystarczy, że wprowadzisz jedną zmianę w pliku my-agents/hotel-agent-app/agent.py.
Zamiast tego:
toolbox = ToolboxTool("http://127.0.0.1:5000")
Zmień go na adres URL usługi Cloud Run, jak pokazano poniżej:
toolbox = ToolboxTool("CLOUD_RUN_SERVICE_URL")
Przetestuj aplikację agenta, korzystając z aplikacji adk run lub adk web, jak widzieliśmy wcześniej.
Wdrażanie aplikacji Hotel Agent w Cloud Run
Najpierw sprawdź, czy w pliku my-agents/hotel-agent-app/agent.py zostały wprowadzone zmiany zgodnie z powyższymi instrukcjami, aby wskazywał on adres URL usługi Toolbox, która działa w Cloud Run, a nie w hostie lokalnym.
W nowym terminalu Cloud Shell lub istniejącej sesji terminala sprawdź, czy korzystasz z prawidłowego środowiska wirtualnego Pythona skonfigurowanego wcześniej.
Najpierw utwórz plik requirements.txt w folderze my-agents/hotel-agent-app:
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 wdrożymy aplikację agenta w Cloud Run za pomocą polecenia cloud_run adk deploy, jak pokazano poniżej. Jeśli pojawi się prośba o zezwolenie na wywoływanie usługi bez uwierzytelniania, podaj na razie 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 agenta hotelowego w Cloud Run. Prześle źródła, spakowane w kontener Dockera, do rejestru artefaktów, a następnie wdroży usługę w Cloud Run. Może to potrwać kilka minut, więc zachowaj cierpliwość.
Powinien wyświetlić się komunikat podobny do tego:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
| Building and deploying... Uploading sources.
| Uploading sources...
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/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623
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żliwiła Ci prowadzenie czatu z pracownikiem hotelu, jak widzieliśmy wcześniej w konfiguracji lokalnej.
9. Czyszczenie
Aby uniknąć ciągłych obciążeń konta Google Cloud, musisz usunąć zasoby utworzone podczas tego warsztatu. Usuniemy instancję Cloud SQL, a jeśli aplikacja Toolbox i Hotels została wdrożona do Cloud Run, usuniemy też te usługi.
Upewnij się, że te zmienne środowiskowe są prawidłowo skonfigurowane 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-app --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ą pakietu narzędzi dla deweloperów agentów (ADK), który korzysta z skrzynki narzędzi MCP do baz danych.