1. Einführung
In diesem Codelab erstellen Sie einen Agenten mit dem Agent Development Kit (ADK), der die MCP Toolbox for Databases verwendet.
In diesem Codelab gehen Sie schrittweise so vor:
- Stellen Sie eine Cloud SQL for PostgreSQL-Datenbank mit der Hotels-Datenbank und Beispieldaten bereit.
- Richten Sie die MCP Toolbox for Databases ein, um auf die Daten zuzugreifen.
- Entwickeln Sie einen Agenten mit dem Agent Development Kit (ADK), der die MCP Toolbox verwendet, um Nutzeranfragen zu beantworten.
- Hier finden Sie Optionen zum lokalen Testen des Agents und der MCP Toolbox for Databases sowie in Google Cloud über den Cloud Run-Dienst.
Aufgabe
- Entwerfen, entwickeln und stellen Sie einen Agenten bereit, der Nutzeranfragen zu Hotels an einem bestimmten Ort beantwortet oder nach Hotels anhand des Namens sucht.
Lerninhalte
- Bereitstellung und Befüllung einer Cloud SQL for PostgreSQL-Datenbank mit Beispieldaten.
- Richten Sie die MCP Toolbox for Databases für die Cloud SQL for PostgreSQL-Datenbankinstanz ein.
- Mit dem Agent Development Kit (ADK) einen Agenten entwerfen und entwickeln, der Nutzeranfragen beantwortet.
- Agent und MCP Toolbox for Databases in der lokalen Umgebung testen
- Optional: Stellen Sie den Agenten und die MCP Toolbox for Databases in Google Cloud bereit.
Voraussetzungen
- Chrome-Webbrowser
- Ein Gmail-Konto
- Ein Cloud-Projekt mit aktivierter Abrechnung
In diesem Codelab, das sich an Entwickler aller Erfahrungsstufen (auch Anfänger) richtet, wird Python in der Beispielanwendung verwendet. Python-Kenntnisse sind jedoch nicht erforderlich. Grundlegende Kenntnisse im Lesen von Code reichen aus, um die vorgestellten Konzepte zu verstehen.
2. Hinweis
Projekt erstellen
- Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
- Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist .
- Sie verwenden Cloud Shell, eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und in der „bq“ vorinstalliert ist. Klicken Sie oben in der Google Cloud Console auf „Cloud Shell aktivieren“.
- Wenn Sie mit Cloud Shell verbunden sind, können Sie mit dem folgenden Befehl prüfen, ob Sie bereits authentifiziert sind und das Projekt auf Ihre Projekt-ID festgelegt ist:
gcloud auth list
- Führen Sie den folgenden Befehl in Cloud Shell aus, um zu bestätigen, dass der gcloud-Befehl Ihr Projekt kennt.
gcloud config list project
- Wenn Ihr Projekt nicht festgelegt ist, verwenden Sie den folgenden Befehl, um es festzulegen:
gcloud config set project <YOUR_PROJECT_ID>
- Aktivieren Sie die erforderlichen APIs mit dem unten gezeigten Befehl. Dies kann einige Minuten dauern.
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
Bei erfolgreicher Ausführung des Befehls sollte eine Meldung wie die unten gezeigte angezeigt werden:
Operation "operations/..." finished successfully.
Alternativ zum gcloud-Befehl können Sie in der Konsole nach den einzelnen Produkten suchen oder diesen Link verwenden.
Wenn eine API fehlt, können Sie sie jederzeit während der Implementierung aktivieren.
Informationen zu gcloud-Befehlen und deren Verwendung finden Sie in der Dokumentation.
3. Cloud SQL-Instanz erstellen
Wir verwenden eine Google Cloud SQL for PostgreSQL-Instanz zum Speichern unserer Hoteldaten. Cloud SQL for PostgreSQL ist ein vollständig verwalteter Datenbankdienst, mit dem Sie relationale PostgreSQL-Datenbanken auf der Google Cloud Platform einrichten, pflegen und verwalten können.
Führen Sie den folgenden Befehl in Cloud Shell aus, um die Instanz zu erstellen:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Die Ausführung dieses Befehls dauert etwa 3 bis 5 Minuten. Nachdem der Befehl erfolgreich ausgeführt wurde, sollte eine Ausgabe angezeigt werden, die angibt, dass der Befehl abgeschlossen ist, zusammen mit den Informationen zu Ihrer Cloud SQL-Instanz wie NAME, DATABASE_VERSION, LOCATION usw.
4. Hotels-Datenbank vorbereiten
Wir müssen nun einige Beispieldaten für unseren Hotel-Agenten erstellen.
Rufen Sie in der Cloud Console die Cloud SQL-Seite auf.Die hoteldb-instance sollte bereit und erstellt sein. Klicken Sie auf den Namen der Instanz (hoteldb-instance), wie unten dargestellt:
Rufen Sie im Cloud SQL-Menü auf der linken Seite die Menüoption Cloud SQL Studio auf, wie unten dargestellt:
Sie werden aufgefordert, sich in Cloud SQL Studio anzumelden. Dort geben wir einige SQL-Befehle ein. Wählen Sie für die Datenbankoption postgres aus. Für „Nutzer“ und „Passwort“ ist der zu verwendende Wert postgres. Klicken Sie auf AUTHENTICATE.
Erstellen wir zuerst die Hoteltabelle gemäß dem unten angegebenen Schema. Führen Sie in einem der Editorbereiche in Cloud SQL Studio den folgenden SQL-Code aus:
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
);
Füllen wir nun die Tabelle „hotels“ mit Beispieldaten. Führen Sie den folgenden SQL-Code aus:
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');
Wir validieren die Daten, indem wir eine SELECT-SQL-Anweisung wie unten gezeigt ausführen:
SELECT * FROM hotels;
In der Tabelle „Hotels“ sollten mehrere Einträge zu sehen sein, wie unten dargestellt:
Wir haben die Einrichtung einer Cloud SQL-Instanz abgeschlossen und unsere Beispieldaten erstellt. Im nächsten Abschnitt richten wir die MCP-Toolbox für Datenbanken ein.
5. MCP Toolbox for Databases einrichten
Die MCP-Toolbox für Datenbanken ist ein Open-Source-MCP-Server für Datenbanken, der für Unternehmen und die Produktion entwickelt wurde. Damit können Sie Tools einfacher, schneller und sicherer entwickeln, da Komplexitäten wie Connection Pooling und Authentifizierung abgedeckt werden.
Mit der Toolbox können Sie GenAI-Tools erstellen, mit denen Ihre Agents auf Daten in Ihrer Datenbank zugreifen können. Die Toolbox bietet:
- Vereinfachte Entwicklung: Sie können Tools mit weniger als 10 Zeilen Code in Ihren Agenten einbinden, Tools für mehrere Agenten oder Frameworks wiederverwenden und neue Versionen von Tools einfacher bereitstellen.
- Bessere Leistung: Best Practices wie Verbindungs-Pooling und Authentifizierung.
- Mehr Sicherheit: Integrierte Authentifizierung für einen sichereren Zugriff auf Ihre Daten
- Vollständige Beobachtbarkeit: Sofort einsatzbereite Messwerte und Tracing mit integrierter Unterstützung für OpenTelemetry.
Toolbox befindet sich zwischen dem Orchestrierungs-Framework Ihrer Anwendung und Ihrer Datenbank und bietet eine Steuerungsebene, mit der Tools geändert, verteilt oder aufgerufen werden können. Sie vereinfacht die Verwaltung Ihrer Tools, da Sie Tools zentral speichern und aktualisieren können. So können Sie Tools zwischen Agents und Anwendungen freigeben und aktualisieren, ohne Ihre Anwendung neu bereitstellen zu müssen.
Eine der von MCP Toolbox for Databases unterstützten Datenbanken ist Cloud SQL. Wir haben sie im vorherigen Abschnitt bereitgestellt.
Toolbox installieren
Öffnen Sie das Cloud Shell-Terminal und erstellen Sie einen Ordner mit dem Namen mcp-toolbox.
mkdir mcp-toolbox
Rufen Sie den Ordner mcp-toolbox über den unten gezeigten Befehl auf:
cd mcp-toolbox
Installieren Sie die binäre Version der MCP-Toolbox für Datenbanken über das unten angegebene Skript. Der unten angegebene Befehl ist für Linux. Wenn Sie einen Mac oder Windows verwenden, müssen Sie die richtige Binärdatei herunterladen. Laden Sie die richtige Binärdatei für Ihr Betriebssystem und Ihre Architektur herunter.
export VERSION=0.13.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Wir haben jetzt die Binärversion der Toolbox. Im nächsten Schritt konfigurieren Sie die Toolbox mit Ihren Datenquellen und anderen Einstellungen.
tools.yaml konfigurieren
Toolbox wird in erster Linie über die Datei tools.yaml konfiguriert. Erstellen Sie eine Datei mit dem Namen tools.yaml im selben Ordner, d. h. mcp-toolbox. Der Inhalt ist unten zu sehen.
Sie können den in Cloud Shell verfügbaren Nano-Editor verwenden. Der Nano-Befehl lautet: nano tools.yaml.
Denken Sie daran, den Wert YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID zu ersetzen.
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
Hier eine kurze Beschreibung der Datei:
Sourcesstellen Ihre verschiedenen Datenquellen dar, mit denen ein Tool interagieren kann. Eine Quelle ist eine Datenquelle, mit der ein Tool interagieren kann. Sie könnenSourcesals Karte im Abschnitt „sources“ Ihrer tools.yaml-Datei definieren. Normalerweise enthält eine Quellkonfiguration alle Informationen, die für die Verbindung mit der Datenbank und die Interaktion mit ihr erforderlich sind. In unserem Fall haben wir eine einzelne Quelle konfiguriert, die mit den Anmeldedaten auf unsere Cloud SQL for PostgreSQL-Instanz verweist. Weitere Informationen finden Sie in der Referenz zu Quellen.Toolsdefinieren Aktionen, die ein Agent ausführen kann, z. B. das Lesen und Schreiben in einer Quelle. Ein Tool stellt eine Aktion dar, die Ihr Agent ausführen kann, z. B. eine SQL-Anweisung. Sie könnenToolsals Karte im Abschnitt „tools“ Ihrer tools.yaml-Datei definieren. Normalerweise benötigt ein Tool eine Quelle, auf die es sich beziehen kann. In unserem Fall definieren wir zwei Tools:search-hotels-by-nameundsearch-hotels-by-location. Außerdem geben wir die Quelle an, auf die sich das Tool bezieht, sowie den SQL-Code und die Parameter. Weitere Informationen finden Sie in der Tools-Referenz.- Schließlich gibt es noch
Toolset, mit dem Sie Gruppen von Tools definieren können, die Sie gemeinsam laden möchten. Das kann nützlich sein, um verschiedene Gruppen basierend auf dem Agent oder der Anwendung zu definieren. In unserem Fall haben wir ein einzelnes Toolset namensmy_first_toolset, das die beiden von uns definierten Tools enthält.
Speichern Sie die Datei tools.yaml im Nano-Editor so:
- Drücken Sie
Ctrl + O(den Befehl „Write Out“ bzw. „Schreiben“). - Sie werden aufgefordert, den „File Name to Write“ (Dateiname zum Schreiben) zu bestätigen. Drücke einfach
Enter. - Drücke jetzt
Ctrl + X, um das Menü zu schließen.
MCP Toolbox for Databases-Server ausführen
Führen Sie den folgenden Befehl (aus dem Ordner mcp-toolbox) aus, um den Server zu starten:
./toolbox --tools-file "tools.yaml"
Im Idealfall wird eine Ausgabe angezeigt, die besagt, dass der Server eine Verbindung zu unseren Datenquellen herstellen und das Toolset und die Tools laden konnte. Hier ein Beispiel für eine Ausgabe:
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!"
Der MCP Toolbox-Server wird standardmäßig auf Port 5000 ausgeführt. Wenn Sie feststellen, dass Port 5000 bereits verwendet wird, können Sie einen anderen Port (z. B. 7000) verwenden, wie im folgenden Befehl gezeigt. Verwenden Sie dann 7000 anstelle des 5000-Ports in den nachfolgenden Befehlen.
./toolbox --tools-file "tools.yaml" --port 7000
Wir verwenden Cloud Shell, um dies zu testen.
Klicken Sie in Cloud Shell auf „Webvorschau“ (siehe unten):
Klicken Sie auf Port ändern, legen Sie den Port auf 5000 fest (siehe unten) und klicken Sie auf „Ändern und Vorschau“.
Dies sollte die folgende Ausgabe liefern:
Fügen Sie am Ende der Browser-URL Folgendes hinzu:
/api/toolset
Dadurch sollten die aktuell konfigurierten Tools angezeigt werden. Ein Beispiel für die Ausgabe sehen Sie unten:
{
"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": []
}
}
}
Tools über die MCP Toolbox for Databases-UI testen
Die Toolbox bietet eine visuelle Oberfläche (Toolbox-UI), über die Sie direkt mit Tools interagieren können. Dazu lassen sich Parameter ändern, Header verwalten und Aufrufe ausführen – alles über eine einfache Weboberfläche.
Wenn Sie das testen möchten, können Sie den vorherigen Befehl zum Starten des Toolbox-Servers mit der Option --ui ausführen.
Schalten Sie dazu die vorherige Instanz des MCP Toolbox for Databases-Servers ab, falls sie ausgeführt wird, und geben Sie den folgenden Befehl ein:
./toolbox --tools-file "tools.yaml" --ui
Im Idealfall wird eine Ausgabe angezeigt, die besagt, dass der Server eine Verbindung zu unseren Datenquellen herstellen und das Toolset und die Tools laden konnte. Unten sehen Sie eine Beispielausgabe, in der erwähnt wird, dass die Toolbox-Benutzeroberfläche ausgeführt wird.
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"
Klicken Sie auf die UI-URL und prüfen Sie, ob die URL mit /ui endet. Daraufhin wird eine Benutzeroberfläche wie unten dargestellt angezeigt:
Klicken Sie links auf die Option „Tools“, um die konfigurierten Tools aufzurufen. In unserem Fall sollten es zwei sein, nämlich search-hotels-by-name und search-hotels-by-location, wie unten dargestellt:
Klicken Sie einfach auf eines der Tools (search-hotels-by-location). Daraufhin wird eine Seite aufgerufen, auf der Sie das Tool testen können, indem Sie die erforderlichen Parameterwerte angeben und dann auf Tool ausführen klicken, um das Ergebnis zu sehen. Unten sehen Sie einen Beispielaufruf:
Das MCP Toolkit for Databases beschreibt auch eine Python-basierte Methode zum Validieren und Testen der Tools, die hier dokumentiert ist.
Wenn wir uns das Diagramm von oben noch einmal ansehen (siehe unten), haben wir die Datenbank und den MCP-Server eingerichtet und haben nun zwei Möglichkeiten:
- Informationen dazu, wie Sie den MCP-Server in einem KI-gestützten Terminal / einer IDE konfigurieren können, finden Sie in Schritt 6. Dabei wird beschrieben, wie wir unseren MCP Toolbox-Server in die Gemini CLI integrieren.
- Informationen zur Verwendung des Agent Development Kit (ADK) mit Python zum Schreiben eigener Agenten, die die MCP Server Toolbox als Tool nutzen können, um Fragen zum Datensatz zu beantworten, finden Sie in Schritt 7 und 8.
6. MCP-Toolbox in die Gemini-Befehlszeile einbinden
Gemini CLI ist ein Open-Source-KI-Agent, der die Leistungsfähigkeit von Gemini direkt in Ihr Terminal bringt. Sie können es sowohl für Programmier- als auch für andere Aufgaben verwenden. Es ist in verschiedene Tools integriert und bietet Unterstützung für MCP-Server.
Da wir einen funktionierenden MCP-Server haben, besteht unser Ziel in diesem Abschnitt darin, den MCP Toolbox for Databases-Server in der Gemini CLI zu konfigurieren und dann die Gemini CLI zu verwenden, um mit unseren Daten zu kommunizieren.
Als Erstes müssen wir prüfen, ob die Toolbox in einem der Cloud Shell-Terminals ausgeführt wird. Wenn Sie den Server am Standardport 5000 ausführen, ist die MCP-Serverschnittstelle am folgenden Endpunkt verfügbar: http://localhost:5000/mcp.
Öffnen Sie ein neues Terminal und erstellen Sie einen Ordner mit dem Namen my-gemini-cli-project. Rufen Sie auch den Ordner my-gemini-cli-project auf.
mkdir my-gemini-cli-project
cd my-gemini-cli-project
Geben Sie den folgenden Befehl ein, um den MCP-Server der Liste der in der Gemini CLI konfigurierten MCP-Server hinzuzufügen.
gemini mcp add --scope="project" --transport="http" "MCPToolbox" "http://localhost:5000/mcp"
Mit dem folgenden Befehl können Sie die aktuelle Liste der in der Gemini CLI konfigurierten MCP-Server aufrufen:
gemini mcp list
Idealerweise sehen Sie die von uns konfigurierte MCPToolbox mit einem grünen Häkchen daneben. Das bedeutet, dass die Gemini CLI eine Verbindung zum MCP-Server herstellen konnte.
Configured MCP servers:
✓ MCPToolbox: http://localhost:5000/mcp (http) - Connected
Prüfen Sie, ob Sie sich im selben Terminal im Ordner my-gemini-cli-project befinden. Starten Sie die Gemini-Befehlszeile mit dem Befehl gemini.
Dadurch wird die Gemini CLI-Oberfläche aufgerufen und Sie sehen, dass jetzt ein MCP-Server konfiguriert ist. Mit dem Befehl /mcp list können Sie die Liste der MCP-Server und Tools aufrufen. Hier ein Beispiel für eine Ausgabe:
Sie können jetzt einen der folgenden Prompts eingeben:
- Welche Hotels gibt es in Basel?
- Erzähl mir mehr über das Hyatt Regency.
Bei den oben genannten Anfragen wählt Gemini CLI das entsprechende Tool aus der MCPToolbox aus. Sie werden um Erlaubnis gebeten, das Tool auszuführen. Erteilen Sie die erforderliche Berechtigung. Die Ergebnisse werden dann aus der Datenbank zurückgegeben.
7. Agent mit dem Agent Development Kit (ADK) schreiben
Agent Development Kit (ADK) installieren
Öffnen Sie in Cloud Shell einen neuen Terminaltab und erstellen Sie einen Ordner mit dem Namen my-agents. Rufen Sie auch den Ordner my-agents auf.
mkdir my-agents
cd my-agents
Erstellen wir nun eine virtuelle Python-Umgebung mit venv:
python -m venv .venv
Aktivieren Sie die virtuelle Umgebung so:
source .venv/bin/activate
Installieren Sie das ADK und die MCP Toolbox for Databases-Pakete zusammen mit der Langchain-Abhängigkeit so:
pip install google-adk toolbox-core
Sie können das adk-Dienstprogramm jetzt so aufrufen.
adk
Eine Liste mit Befehlen wird angezeigt.
$ 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.
Erste Agent-Anwendung erstellen
Wir verwenden jetzt adk, um ein Gerüst für unsere Hotel-Agent-Anwendung über den Befehl adk create mit dem unten angegebenen App-Namen **(hotel-agent-app)**zu erstellen.
adk create hotel-agent-app
Folgen Sie der Anleitung und wählen Sie Folgendes aus:
- Gemini-Modell zum Auswählen eines Modells für den Stamm-Agent.
- Wählen Sie Vertex AI als Backend aus.
- Ihre Standard-Google-Projekt-ID und -Region werden angezeigt. Wählen Sie die Standardeinstellung aus.
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
Sehen Sie sich den Ordner an, in dem eine Standardvorlage und die erforderlichen Dateien für den Agent erstellt wurden.
Zuerst kommt die Datei .env. Der Inhalt ist unten zu sehen:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Die Werte geben an, dass wir Gemini über Vertex AI verwenden, zusammen mit den entsprechenden Werten für die Google Cloud-Projekt-ID und den Standort.
Dann gibt es noch die Datei __init__.py, die den Ordner als Modul kennzeichnet und eine einzelne Anweisung enthält, mit der der Agent aus der Datei agent.py importiert wird.
from . import agent
Sehen wir uns zum Schluss noch die Datei agent.py an. Der Inhalt wird unten angezeigt:
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',
)
Dies ist der einfachste Agent, den Sie mit dem ADK schreiben können. Laut der ADK-Dokumentationsseite ist ein Agent eine in sich geschlossene Ausführungseinheit, die autonom agiert, um bestimmte Ziele zu erreichen. Agents können Aufgaben ausführen, mit Nutzern interagieren, externe Tools verwenden und sich mit anderen Agents abstimmen.
Ein LLMAgent, der häufig als „Agent“ bezeichnet wird, nutzt Large Language Models (LLMs) als Kern-Engine, um natürliche Sprache zu verstehen, Schlussfolgerungen zu ziehen, Pläne zu erstellen, Antworten zu generieren und dynamisch zu entscheiden, wie vorgegangen werden soll oder welche Tools verwendet werden sollen. Daher sind sie ideal für flexible, sprachorientierte Aufgaben. Weitere Informationen zu LLM-Agents
Ändern wir den Code für agent.py so:
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.',
)
Agent-App lokal testen
Geben Sie im vorhandenen Terminalfenster den folgenden Befehl ein. Achten Sie darauf, dass Sie sich im übergeordneten Ordner (my-agents) befinden, der den Ordner hotel-agent-app enthält.
adk web
Unten sehen Sie ein Beispiel für die Ausführung:
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)
Klicken Sie auf den letzten Link. Daraufhin sollte eine Webkonsole angezeigt werden, in der Sie den Agent testen können. Im Browser sollte Folgendes angezeigt werden:
Oben links wird die hotel-agent-app angezeigt. Sie können jetzt mit dem Agenten sprechen. Geben Sie einige Prompts an, in denen Sie nach Städten fragen. Hier ein Beispiel für einen Dialog:
Sie können den im Cloud Shell-Terminal ausgeführten Prozess beenden (Strg+C).
Eine alternative Möglichkeit, den Agent zu testen, ist die Verwendung des Befehls adk run aus dem Ordner my-agents, wie unten beschrieben.
adk run hotel-agent-app
Probieren Sie den Befehl aus. Sie können dann über die Befehlszeile (das Terminal) mit dem Agent interagieren. Geben Sie exit ein, um die Unterhaltung zu schließen.
8. Agent mit Tools verbinden
Nachdem wir nun wissen, wie wir einen Agenten schreiben und lokal testen können, Wir verbinden diesen Agenten mit Tools. Im Kontext des ADK stellt ein Tool eine bestimmte Funktion dar, die einem KI-Agenten zur Verfügung gestellt wird, damit er Aktionen ausführen und mit der Welt interagieren kann, die über seine grundlegenden Fähigkeiten zur Textgenerierung und zum logischen Denken hinausgehen.
In unserem Fall statten wir unseren Agenten jetzt mit den Tools aus, die wir in der MCP Toolbox for Databases konfiguriert haben.
Ändern Sie die Datei agent.py mit dem folgenden Code. Im Code wird der Standardport 5000 verwendet. Wenn Sie einen anderen Port verwenden, müssen Sie diesen angeben.
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,
)
Wir können jetzt den Agent testen, der echte Daten aus unserer PostgreSQL-Datenbank abruft, die mit der MCP Toolbox for Databases konfiguriert wurde.
Gehen Sie dazu so vor:
Starten Sie die MCP Toolbox for Databases in einem Terminal von Cloud Shell. Möglicherweise wird sie bereits lokal auf Port 5000 ausgeführt, wie wir zuvor getestet haben. Wenn nicht, führen Sie den folgenden Befehl aus dem Ordner mcp-toolbox aus, um den Server zu starten:
./toolbox --tools_file "tools.yaml"
Im Idealfall wird eine Ausgabe angezeigt, die besagt, dass der Server eine Verbindung zu unseren Datenquellen herstellen und das Toolset und die Tools laden konnte. Hier ein Beispiel für eine Ausgabe:
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!"
Sobald der MCP-Server erfolgreich gestartet wurde, starten Sie den Agenten in einem anderen Terminal wie zuvor über den unten gezeigten Befehl adk run (aus dem Ordner my-agents). Sie können auch den Befehl adk web verwenden.
$ 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.
Der Agent verwendet jetzt die beiden Tools, die wir in der MCP Toolbox for Databases konfiguriert haben (search-hotels-by-name und search-hotels-by-location), und stellt uns die richtigen Optionen zur Verfügung. Anschließend kann es die Daten nahtlos aus der Datenbank der PostgreSQL-Instanz abrufen und die Antwort entsprechend formatieren.
Damit ist die lokale Entwicklung und das Testen unseres Hotel-Agents abgeschlossen. Wir haben ihn mit dem Agent Development Kit (ADK) erstellt und er wurde von Tools unterstützt, die wir in der MCP Toolbox for Databases konfiguriert haben.
9. (Optional) MCP Toolbox for Databases und Agent in Cloud Run bereitstellen
Im vorherigen Abschnitt haben wir das Cloud Shell-Terminal verwendet, um den MCP Toolbox-Server zu starten und die Tools mit dem Agent getestet. Dies wurde lokal in der Cloud Shell-Umgebung ausgeführt.
Sie haben die Möglichkeit, sowohl den MCP Toolbox-Server als auch den Agent in Google Cloud-Diensten bereitzustellen, die diese Anwendungen für uns hosten können.
MCP Toolbox-Server in Cloud Run hosten
Zuerst können wir mit dem MCP Toolbox-Server beginnen und ihn in Cloud Run hosten. So erhalten wir einen öffentlichen Endpunkt, den wir in jede andere Anwendung und/oder die Agent-Anwendungen einbinden können. Eine Anleitung zum Hosten in Cloud Run finden Sie hier. Wir gehen jetzt die wichtigsten Schritte durch.
Starten Sie ein neues Cloud Shell-Terminal oder verwenden Sie ein vorhandenes. Wechseln Sie zum Ordner mcp-toolbox, in dem sich die Binärdatei toolbox und tools.yaml befinden.
Führen Sie die folgenden Befehle aus (für jeden Befehl wird eine Erklärung bereitgestellt):
Legen Sie die Variable PROJECT_ID auf Ihre Google Cloud-Projekt-ID fest.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Prüfen Sie als Nächstes, ob die folgenden Google Cloud-Dienste im Projekt aktiviert sind.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Erstellen wir ein separates Dienstkonto, das als Identität für den Toolbox-Dienst dient, den wir in Google Cloud Run bereitstellen. Wir sorgen auch dafür, dass dieses Dienstkonto die richtigen Rollen hat, d.h. auf Secret Manager zugreifen und mit Cloud SQL kommunizieren kann.
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
Wir laden die Datei tools.yaml als Secret hoch. Da wir die Toolbox in Cloud Run installieren müssen, verwenden wir das neueste Container-Image für die Toolbox und legen es in der IMAGE-Variablen fest.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
Der letzte Schritt im bekannten Bereitstellungsbefehl für 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
Dadurch sollte der Prozess zum Bereitstellen des Toolbox-Servers mit unserer konfigurierten tools.yaml in Cloud Run gestartet werden. Bei erfolgreicher Bereitstellung wird eine Meldung ähnlich der folgenden angezeigt:
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
Sie können jetzt die oben aufgeführte Service URL im Browser aufrufen. Es sollte die Meldung „Hello World“ angezeigt werden, die wir zuvor gesehen haben. Unter der folgenden URL finden Sie eine Übersicht der verfügbaren Tools:
SERVICE URL/api/toolset
Sie können auch in der Google Cloud Console Cloud Run aufrufen. Der Toolbox-Dienst wird in der Liste der Dienste in Cloud Run angezeigt.
Hinweis: Wenn Sie Ihren Hotel-Agent weiterhin lokal ausführen und trotzdem eine Verbindung zum neu bereitgestellten Cloud Run-Dienst herstellen möchten, müssen Sie nur eine Änderung in der Datei my-agents/hotel-agent-app/agent.py vornehmen.
Anstelle von:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Ändern Sie sie in die Dienst-URL des Cloud Run-Dienstes, wie unten angegeben:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
Testen Sie die Agent-Anwendung mit adk run oder adk web, wie wir es zuvor gesehen haben.
Hotel-Agent-App in Cloud Run bereitstellen
Als Erstes müssen Sie die oben beschriebene Änderung in my-agents/hotel-agent-app/agent.py vornehmen, damit auf die Toolbox-Dienst-URL verwiesen wird, die in Cloud Run ausgeführt wird, und nicht auf den lokalen Host.
Prüfen Sie in einem neuen Cloud Shell-Terminal oder einer vorhandenen Terminalsitzung, ob Sie sich in der richtigen virtuellen Python-Umgebung befinden, die wir zuvor eingerichtet haben.
Erstellen wir zuerst eine requirements.txt-Datei im Ordner my-agents/hotel-agent-app, wie unten gezeigt:
google-adk
toolbox-core
Rufen Sie den Ordner my-agents auf und legen Sie zuerst die folgenden Umgebungsvariablen fest:
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
Stellen Sie die Agent-Anwendung schließlich mit dem adk deploy-Befehl cloud_run in Cloud Run bereit, wie unten beschrieben. Wenn Sie aufgefordert werden, nicht authentifizierte Aufrufe des Dienstes zuzulassen, geben Sie bitte vorerst „y“ als Wert an.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
Dadurch wird die Bereitstellung der Hotel-Agent-Anwendung in Cloud Run gestartet. Die Quellen werden hochgeladen, in einen Docker-Container verpackt, per Push in die Artifact Registry übertragen und der Dienst wird in Cloud Run bereitgestellt. Dies kann einige Minuten dauern.
Es sollte eine Meldung ähnlich der folgenden angezeigt werden:
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
Wenn die Bereitstellung erfolgreich war, erhalten Sie einen Wert für die Dienst-URL. Über diese URL können Sie im Browser auf dieselbe Webanwendung zugreifen, über die Sie mit dem Hotel-Agent gechattet haben, wie wir es bereits bei der lokalen Einrichtung gesehen haben.
10. Bereinigen
Damit Ihrem Google Cloud-Konto keine laufenden Gebühren in Rechnung gestellt werden, ist es wichtig, die Ressourcen zu löschen, die wir während dieses Workshops erstellt haben. Wir löschen die Cloud SQL-Instanz und optional auch die Dienste, wenn Sie die Toolbox und die Hotels App in Cloud Run bereitgestellt haben.
Prüfen Sie, ob die folgenden Umgebungsvariablen entsprechend Ihrem Projekt und Ihrer Region richtig festgelegt sind:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
Mit den folgenden beiden Befehlen werden die bereitgestellten Cloud Run-Dienste gelöscht:
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
Mit dem folgenden Befehl wird die Cloud SQL-Instanz gelöscht:
gcloud sql instances delete hoteldb-instance
11. Glückwunsch
Sie haben erfolgreich einen Agenten mit dem Agent Development Kit (ADK) erstellt, der die MCP Toolbox for Databases verwendet.