Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

AlloyDB Omni mit MCP Toolbox für die Agentenintegration verwenden

1. Einführung

Wenn Sie KI-Agenten wie der Antigravity CLI sicheren, strukturierten Zugriff auf Ihre Datenbank gewähren möchten, können Sie AlloyDB Omni in die MCP Toolbox for Databases einbinden.

AlloyDB Omni ist eine herunterladbare, containerisierte Version von AlloyDB for PostgreSQL, die überall ausgeführt werden kann – lokal, auf Entwickler-Workstations, am Edge oder in der Cloud – und gleichzeitig PostgreSQL-Leistung und -Kompatibilität auf Unternehmensniveau bietet.

Die MCP Toolbox for Databases ist ein Open-Source-Server von Google, der das Model Context Protocol (MCP) implementiert, um die Erstellung generativer KI-Tools, die mit Datenbanken interagieren, einfacher, schneller und sicherer zu machen. Sie befindet sich zwischen dem Orchestrierungs-Framework Ihres KI-Agenten und Ihrer Datenbank und bietet die folgenden Funktionen:

Vereinfachte Entwicklung: Vordefinierte oder benutzerdefinierte Datenbanktools, die mit minimaler Konfiguration mit Ihrem Agenten verbunden und für mehrere Agenten oder Frameworks wiederverwendet werden können.
Bessere Leistung: Integrierte Best Practices wie Verbindungs-Pooling und Lebenszyklusverwaltung.
Höhere Sicherheit: Durch die zentrale Verwaltung von Anmeldedaten und Authentifizierung benötigen Agenten keine Rohdaten für die Datenbankanmeldung.
End-to-End-Beobachtbarkeit: Sofort einsatzbereite Messwerte und Tracing mit integrierter Unterstützung für OpenTelemetry.

Am Ende dieses Codelabs haben Sie einen laufenden AlloyDB Omni-Container mit Beispiel-E-Commerce-Daten, einen MCP Toolbox-Server mit 31 vordefinierten AlloyDB Omni-Verwaltungs- und Abfragetools und einen konfigurierten Antigravity-CLI-Agenten (agy), der Schemas prüfen, SQL-Abfragen ausführen, Abfragepläne analysieren und den Datenbankzustand mithilfe von Prompts in natürlicher Sprache diagnostizieren kann.

Architekturdiagramm, das den End-to-End-Workflow vom Agenten über den MCP-Client (Antigravity CLI) und die MCP Toolbox bis hin zu AlloyDB Omni zeigt

Vorbereitung

Zugriff auf ein Google Cloud-Projekt und Cloud Shell über die Google Cloud Console oder eine Linux-Workstation.
Docker ist installiert und wird ausgeführt.
Der PostgreSQL-Client psql ist installiert.
curl und jq, um die Antigravity CLI und die MCP-Toolbox einzurichten.

Lerninhalte

Wie Sie einen AlloyDB Omni-Datenbankserver-Container mit Docker bereitstellen und ausführen.
Beispieltabellen, ‑daten und ‑indexe in AlloyDB Omni erstellen
Herunterladen, Konfigurieren und Starten der MCP Toolbox for Databases mit dem vordefinierten Toolset alloydb-omni
Konfiguration der Antigravity CLI als MCP-Client, um eine Verbindung zum MCP Toolbox-Server herzustellen
Wie Sie Prompts in natürlicher Sprache in der Antigravity CLI verwenden, um den Datenbankzustand zu prüfen, Schemas zu untersuchen, SQL-Abfragen auszuführen, Abfragepläne zu analysieren und Wartungsdiagnosen durchzuführen.

Voraussetzungen

Eine funktionierende Terminalumgebung mit Docker, psql, curl und jq. Sie können Google Cloud Shell verwenden, wo diese Tools bereits vorinstalliert sind.

2. Einrichtung und Anforderungen

Projekt einrichten

Google Cloud-Projekt erstellen

Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
Prüfen Sie, ob die Abrechnung für Ihr Google Cloud-Projekt aktiviert ist. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

Cloud Shell starten

Sie können AlloyDB Omni und die MCP Toolbox zwar lokal auf Ihrem Laptop ausführen, in diesem Codelab verwenden Sie jedoch die Google Cloud Shell, eine in der Cloud ausgeführte Befehlszeilenumgebung, in der Docker, psql, curl und jq bereits vorinstalliert sind.

Symbol zum Aktivieren von Cloud Shell

Öffnen Sie die Google Cloud Console und klicken Sie in der Symbolleiste rechts oben auf Cloud Shell aktivieren. Sie können Cloud Shell auch auf eine der folgenden Arten öffnen:
- Wenn Sie die Google Cloud Console verwenden, drücken Sie G und dann S.
- Öffnen Sie Cloud Shell direkt.

Die Bereitstellung und Verbindung mit der Umgebung dauert in der Regel einen kleinen Moment. Wenn dieser Vorgang abgeschlossen ist, wird in etwa Folgendes angezeigt:

Google Cloud Shell-Terminal, das anzeigt, dass die Umgebung verbunden ist

3. AlloyDB Omni-Datenbankserver vorbereiten und ausführen

In diesem Abschnitt rufen Sie den AlloyDB Omni-Docker-Container ab, führen ihn aus und füllen ihn zu Testzwecken mit E-Commerce-Beispieldaten.

AlloyDB Omni-Datenbankserver starten

Definieren Sie Umgebungsvariablen für den AlloyDB Omni-Host, den Port, die Datenbank, den Nutzer und ein generiertes Passwort:

export ALLOYDB_OMNI_HOST="127.0.0.1"
export ALLOYDB_OMNI_PORT="5432"
export ALLOYDB_OMNI_DATABASE="postgres"
export ALLOYDB_OMNI_USER="postgres"
export ALLOYDB_OMNI_PASSWORD="$(openssl rand -hex 8)@1aA"
echo "Your generated AlloyDB Omni postgres password is: $ALLOYDB_OMNI_PASSWORD"

Starten Sie den AlloyDB Omni-Container im getrennten Modus mit Docker:

docker run --name alloydbomni \
    -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \
    -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \
    -d google/alloydbomni:latest

Prüfen Sie, ob der Container ausgeführt wird und ob Sie mit psql eine Verbindung zum AlloyDB Omni-Server herstellen können:

docker ps -a
until docker exec alloydbomni pg_isready -U "$ALLOYDB_OMNI_USER" -d "$ALLOYDB_OMNI_DATABASE"; do sleep 2; done
PGPASSWORD=$ALLOYDB_OMNI_PASSWORD psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE -c "SELECT 1;"

Beispieldaten für Tests erstellen

Erstellen Sie die Beispieltabellen categories, products, customers und orders, fügen Sie Testdatensätze ein und erstellen Sie Indexe, damit Sie die Schemaprüfung, SQL-Abfragen und Abfrageausführungspläne über die MCP Toolbox testen können:

PGPASSWORD="$ALLOYDB_OMNI_PASSWORD" psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE << 'EOF'
CREATE TABLE IF NOT EXISTS categories (
    category_id SERIAL PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

CREATE TABLE IF NOT EXISTS products (
    product_id SERIAL PRIMARY KEY,
    product_name VARCHAR(100) UNIQUE NOT NULL,
    category VARCHAR(50) NOT NULL,
    price NUMERIC(10, 2) NOT NULL,
    stock INT DEFAULT 0
);

CREATE TABLE IF NOT EXISTS customers (
    customer_id SERIAL PRIMARY KEY,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INT REFERENCES customers(customer_id),
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    total_amount NUMERIC(10, 2)
);

-- Insert sample rows
INSERT INTO categories (name) VALUES
('Smartphones'),
('Laptops'),
('Audio')
ON CONFLICT DO NOTHING;

INSERT INTO products (product_name, category, price, stock) VALUES
('Pixel 9 Pro', 'Smartphones', 999.00, 50),
('MacBook Pro M3', 'Laptops', 1999.00, 20),
('ThinkPad X1 Carbon', 'Laptops', 1450.00, 35),
('Dell XPS 15', 'Laptops', 1700.00, 15),
('Bose QuietComfort', 'Audio', 349.00, 100)
ON CONFLICT DO NOTHING;

INSERT INTO customers (first_name, last_name, email) VALUES
('Ada', 'Lovelace', 'ada@example.com'),
('Alan', 'Turing', 'alan@example.com'),
('Grace', 'Hopper', 'grace@example.com')
ON CONFLICT DO NOTHING;

INSERT INTO orders (order_id, customer_id, total_amount, order_date) VALUES
(1, 1, 999.00, pg_catalog.now() - INTERVAL '7 months'),
(2, 2, 349.00, pg_catalog.now() - INTERVAL '1 month')
ON CONFLICT DO NOTHING;

CREATE INDEX IF NOT EXISTS idx_products_category ON products(category);
CREATE INDEX IF NOT EXISTS idx_orders_customer ON orders(customer_id);
EOF

4. MCP-Toolbox-Server starten

In diesem Abschnitt laden Sie die Binärdatei der MCP Toolbox herunter, konfigurieren die vordefinierten AlloyDB Omni-Tooldefinitionen und starten den MCP Toolbox-Server.

MCP Toolbox herunterladen

Erstellen Sie ein Verzeichnis für die MCP Toolbox und laden Sie die Binärdatei toolbox herunter:

mkdir -p ~/mcp/tools
cd ~/mcp
curl -L -O https://storage.googleapis.com/genai-toolbox/v0.31.0/linux/amd64/toolbox
chmod +x toolbox
./toolbox --version

MCP-Toolbox-Server konfigurieren und starten

Laden Sie die vordefinierte Toolkonfiguration alloydb-omni.yaml herunter und starten Sie den MCP Toolbox-Server an Port 5000 (mit den zuvor exportierten Umgebungsvariablen ALLOYDB_OMNI_*):
```
curl -sL --create-dirs -o "tools/alloydb-omni.yaml" "https://raw.githubusercontent.com/googleapis/mcp-toolbox/v0.31.0/internal/prebuiltconfigs/tools/alloydb-omni.yaml"
# Remove the trailing group definition block and YAML document separator for --config-folder compatibility
sed -i '/^kind: group/,$d' tools/alloydb-omni.yaml
sed -i '${/---/d;}' tools/alloydb-omni.yaml

./toolbox --config-folder ./tools/ --port 5000 --address 127.0.0.1
```
Die alloydb-omni.yaml-Konfiguration bietet 31 vordefinierte Tools, darunter die wichtigsten Tools, die in diesem Codelab vorgestellt werden:
- execute_sql
- get_query_plan
- database_overview
- list_active_queries
- list_tables, list_indexes, list_views, list_triggers
- list_top_bloated_tables, list_locks, list_autovacuum_configurations, list_invalid_indexes
Eine vollständige Liste der Tools finden Sie unter alloydb-omni.yaml auf GitHub.
Tipp: Lassen Sie den MCP Toolbox-Server in diesem Terminal-Tab laufen und öffnen Sie einen neuen Terminal-Tab (+ in Cloud Shell), um die verbleibenden Befehle in diesem Codelab auszuführen.

Prüfen Sie in einem neuen Terminal-Tab, ob der MCP Toolbox-Server ausgeführt wird und Ihre Tools über den JSON-RPC-Endpunkt /mcp verfügbar macht:

curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

5. MCP-Client (Antigravity CLI) konfigurieren

In diesem Abschnitt installieren Sie die Antigravity CLI (agy) und konfigurieren sie so, dass sie eine Verbindung zu Ihrem MCP Toolbox-Server herstellt.

Antigravity CLI installieren

Falls noch nicht geschehen, laden Sie das Antigravity CLI-Installationsprogramm (agy) herunter, führen Sie es aus und prüfen Sie die Version:

curl -fsSL https://antigravity.google/cli/install.sh -o /tmp/install.sh
bash /tmp/install.sh
rm -f /tmp/install.sh

# If prompted by the installer, add ~/.local/bin to your PATH:
export PATH="$HOME/.local/bin:$PATH"

# Verify the installation
agy --version

Antigravity-Befehlszeile konfigurieren

Fügen Sie den MCP Toolbox-Servereintrag zur MCP-Konfigurationsdatei Ihres Clients hinzu (z. B. ~/.gemini/config/mcp_config.json für die Antigravity CLI, .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json oder .mcp.json für Claude Code).

Führen Sie agy mcp add aus, um die Antigravity CLI mit dem laufenden MCP Toolbox-HTTP-Server an Port 5000 zu verbinden, und prüfen Sie den Eintrag mit agy mcp list:
```
export MCP_SERVER="127.0.0.1"
export MCP_PORT="5000"

agy mcp add alloydb-omni "http://${MCP_SERVER}:${MCP_PORT}/mcp"
agy mcp list
```
Dadurch wird die alloydb-omni-Serverkonfiguration in ~/.gemini/config/mcp_config.json geschrieben:
```
{
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}
```

Konfiguration prüfen

Starten Sie die Antigravity CLI:
```
agy
```
Wenn Sie agy zum ersten Mal starten, folgen Sie den Aufforderungen auf dem Bildschirm, um sich anzumelden (mit Google OAuth oder einem Google Cloud-Projekt). Wählen Sie Yes, I trust this folder (Ja, ich vertraue diesem Ordner) aus, wenn Sie gefragt werden, ob Sie dem aktuellen Verzeichnis vertrauen.

Geben Sie in der Antigravity CLI-Eingabeaufforderung /mcp ein, um den Bereich MCP-Server zu öffnen und zu prüfen, ob alloydb-omni verbunden ist:

/mcp

Die Ausgabe sieht in etwa so aus:

MCP Servers

Configured (~/.gemini/config/mcp_config.json)
>  ✓ alloydb-omni  Tools: database_overview, execute_sql, get_column_cardinality, get_query_plan, list_active_queries, +26 more

Keyboard: ↑/↓ Navigate  enter Actions

Drücken Sie Esc, um den Bereich MCP-Server zu schließen und zur Antigravity CLI-Eingabeaufforderung zurückzukehren.

6. Mit Abfragen für AlloyDB Omni testen

Nachdem die Antigravity CLI über die MCP Toolbox mit Ihrer AlloyDB Omni-Instanz verbunden ist, können Sie mit Ihrer Datenbank über Prompts in natürlicher Sprache interagieren.

Abfrage zur Datenbankübersicht ausführen

Fragen Sie in der Antigravity CLI nach einer Übersicht über die aktuelle Datenbank:

Give me an overview of the current database.

Wenn Sie aufgefordert werden, den Aufruf des Tools zuzulassen, wählen Sie Ja (oder Ja, und immer zulassen in dieser Unterhaltung) aus. Die Ausgabe sieht etwa so aus:

> Give me an overview of the current database.

● alloydb-omni/database_overview(Database overview check) (ctrl+o to expand)

  Here is an overview of the current AlloyDB Omni database instance:

  ### Database Overview
  • Instance / Engine: PostgreSQL 17.9 (AlloyDB Omni)
  • Role: Primary (is_replica: false)
  • Uptime: ~7 hours, 57 minutes
  • Connected Database: postgres
  • Connected User: postgres
  • Connections: 11 current / 100 max (1 active, 11% used)

  ### Databases in Instance
  • postgres
  • alloydbadmin (~15.74 MB)
  • alloydbmetadata (~14.82 MB)

Beispiele nach Kategorie testen

Geben Sie in der Antigravity CLI die folgenden Prompts in natürlicher Sprache ein. Der Agent ordnet jede Anfrage automatisch dem entsprechenden Tool in Ihrem AlloyDB Omni MCP-Toolset zu:

1. Datenbankübersicht und -status

Testziel	Prompt in natürlicher Sprache	Tool aufgerufen
Systemprüfung	`Give me an overview of the current database.`	`database_overview`
Aktive Verbindungen	`What queries are currently running on the database?`	`list_active_queries`
Installierte Erweiterungen	`What extensions are installed in this database?`	`list_installed_extensions`
Verfügbare Erweiterungen	`What extensions are available that I can install?`	`list_available_extensions`

2. Schema- und Katalog-Exploration

Testziel	Prompt in natürlicher Sprache	Tool aufgerufen
Tabellen auflisten	`Show me all the tables in the current database.`	`list_tables`
Indexe prüfen	`List all indexes in the database and which tables they belong to.`	`list_indexes`
Ansichten entdecken	`What views are available in the public schema?`	`list_views`
Tabellen-Trigger prüfen	`Show me the triggers defined on the orders table.`	`list_triggers`

3. Datenabfrage und -filterung (`execute_sql`)

Testziel	Prompt in natürlicher Sprache	Tool aufgerufen
Aggregierte Abfrage	`Show me the 3 most expensive products in the 'Laptops' category.`	`execute_sql`
Join-Abfrage	`Find all customers who have placed an order in the last 6 months.`	`execute_sql`
Nicht übereinstimmende Datensätze	`Which customers haven't placed any orders yet?`	`execute_sql`

4. Abfrageleistung und Erläuterungspläne (`get_query_plan`)

Testziel	Prompt in natürlicher Sprache	Tool aufgerufen
Plan erklären	`Explain the query plan for a query that finds all customers who have not placed an order in the last 6 months.`	`get_query_plan`
Indexüberprüfung	`Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.`	`get_query_plan`

5. Datenbankwartung und ‑diagnose

Testziel	Prompt in natürlicher Sprache	Tool aufgerufen
Tabellenaufblähung	`List the top five most bloated tables.`	`list_top_bloated_tables`
Sperrenkonflikt	`Show me if there are any active locks or blocked transactions.`	`list_locks`
Autovacuum-Einstellungen	`Show me the current autovacuum configuration.`	`list_autovacuum_configurations`
Ungültige Indexe	`Check for any invalid indexes in the database.`	`list_invalid_indexes`

7. Bereinigen

Nachdem Sie das Codelab abgeschlossen haben, bereinigen Sie den lokalen Container und die gestarteten Prozesse.

Beenden Sie die Antigravity CLI, indem Sie /quit eingeben oder zweimal Ctrl+D drücken.
Wechseln Sie zum Terminal-Tab, auf dem der MCP Toolbox-Server ausgeführt wird, und drücken Sie Ctrl+C, um ihn zu beenden.
Beenden und entfernen Sie den AlloyDB Omni-Docker-Container:
```
docker stop alloydbomni
docker rm alloydbomni
```

8. Glückwunsch

Glückwunsch zum Abschluss des Codelabs! Sie haben AlloyDB Omni erfolgreich in einem Container bereitgestellt, die MCP Toolbox for Databases mit dem vordefinierten AlloyDB Omni-Toolset konfiguriert und in die Antigravity CLI eingebunden, um Ihre Datenbank in natürlicher Sprache abzufragen und zu verwalten.

Behandelte Themen

AlloyDB Omni-Container mit Docker bereitstellen und prüfen
Beispieltabellen und ‑indizes zum Testen von KI-Agenten-Workflows füllen
Wie Sie die MCP Toolbox for Databases mit der vordefinierten alloydb-omni-Toolkonfiguration konfigurieren und ausführen.
Wie Sie die Antigravity CLI mit der MCP Toolbox verbinden und Prompts in natürlicher Sprache für die Schemaerkennung, SQL-Abfragen, die Analyse von Abfrageplänen und die Datenbankdiagnose ausführen.

Weitere Informationen finden Sie in den folgenden Ressourcen:

9. Umfrage

Wie möchten Sie diese Anleitung verwenden?

Nur durchgelesen

Durchgelesen und die Übungen gemacht