Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Utilizza AlloyDB Omni con MCP Toolbox per l'integrazione degli agenti

1. Introduzione

Per fornire agli agenti AI, come l'Antigravity CLI, un accesso sicuro e strutturato al tuo database, puoi integrare AlloyDB Omni con MCP Toolbox for Databases.

AlloyDB Omni è una versione containerizzata scaricabile di AlloyDB per PostgreSQL progettata per essere eseguita ovunque (on-premise, su workstation per sviluppatori, a livello perimetrale o nel cloud), offrendo al contempo prestazioni e compatibilità PostgreSQL di livello enterprise.

MCP Toolbox for Databases è un server open source di Google che implementa il Model Context Protocol (MCP) per semplificare, velocizzare e rendere più sicura la creazione di strumenti di AI generativa che interagiscono con i database. Si trova tra il framework di orchestrazione dell'agente e il database e offre le seguenti funzionalità:

Sviluppo semplificato: strumenti di database predefiniti o personalizzati che si connettono all'agente con una configurazione minima e possono essere riutilizzati in più agenti o framework.
Prestazioni migliori: best practice integrate come il pooling delle connessioni e la gestione del ciclo di vita.
Sicurezza avanzata: gestione centralizzata delle credenziali e dell'autenticazione, in modo che gli agenti non richiedano credenziali del database non elaborate.
Osservabilità end-to-end: metriche e tracciamento pronti all'uso con supporto integrato per OpenTelemetry.

Al termine di questo codelab, avrai un container AlloyDB Omni in esecuzione compilato con dati di e-commerce di esempio, un server MCP Toolbox che espone 31 strumenti di amministrazione e query AlloyDB Omni predefiniti e un agente Antigravity CLI (agy) configurato in grado di ispezionare schemi, eseguire query SQL, analizzare piani di query e diagnosticare lo stato del database utilizzando prompt in linguaggio naturale.

Diagramma dell'architettura che mostra il workflow end-to-end dall'agente al client MCP (interfaccia a riga di comando Antigravity) a MCP Toolbox ad AlloyDB Omni

Prerequisiti

Accesso a un progetto cloud Google Cloud e a Cloud Shell dalla console Google Cloud o da una workstation Linux.
Docker installato e in esecuzione.
Il client PostgreSQL psql installato.
curl e jq installati per configurare Antigravity CLI e MCP Toolbox.

Obiettivi didattici

Come eseguire il deployment e l'esecuzione di un contenitore del server di database AlloyDB Omni utilizzando Docker.
Come creare tabelle, dati e indici di esempio in AlloyDB Omni.
Come scaricare, configurare e avviare MCP Toolbox for Databases con il set di strumenti alloydb-omni predefinito.
Come configurare l'interfaccia a riga di comando Antigravity come client MCP per connettersi al server MCP Toolbox.
Come utilizzare i prompt in linguaggio naturale nell'interfaccia a riga di comando di Antigravity per ispezionare l'integrità del database, esplorare gli schemi, eseguire query SQL, analizzare i piani di query ed eseguire la diagnostica di manutenzione.

Che cosa ti serve

Un ambiente terminale funzionante con Docker, psql, curl e jq. Puoi utilizzare Google Cloud Shell, in cui questi strumenti sono preinstallati.

2. Configurazione e requisiti

Configurazione del progetto

Crea un progetto Google Cloud

Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Avvia Cloud Shell

Sebbene tu possa eseguire AlloyDB Omni e MCP Toolbox localmente sul tuo laptop, in questo codelab puoi utilizzare Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud con Docker, psql, curl e jq preinstallati.

Icona per attivare Cloud Shell

Apri la console Google Cloud e fai clic su Attiva Cloud Shell nella barra degli strumenti in alto a destra.Puoi anche aprire Cloud Shell in uno dei seguenti modi:
- Se utilizzi la console Google Cloud, premi G, quindi S.
- Apri direttamente Cloud Shell.

In genere, bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine di questa operazione, viene visualizzato un messaggio simile al seguente:

Terminale Google Cloud Shell che mostra che l'ambiente è connesso

3. Prepara ed esegui il server di database AlloyDB Omni

In questa sezione, eseguirai il pull e l'esecuzione del container Docker di AlloyDB Omni e lo compilerai con dati di e-commerce di esempio per i test.

Avvia il server di database AlloyDB Omni

Definisci le variabili di ambiente per l'host, la porta, il database, l'utente e una password generata di AlloyDB Omni:

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"

Avvia il container AlloyDB Omni in modalità scollegata utilizzando Docker:

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

Verifica che il container sia in esecuzione e che tu possa connetterti al server AlloyDB Omni utilizzando psql:

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;"

Crea dati di esempio per i test

Crea tabelle di esempio categories, products, customers e orders, inserisci record di test e crea indici per testare l'ispezione dello schema, le query SQL e i piani di esecuzione delle query tramite MCP Toolbox:

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. Avvia il server MCP Toolbox

In questa sezione, scaricherai il file binario di MCP Toolbox, configurerai le definizioni degli strumenti AlloyDB Omni predefiniti e avvierai il server MCP Toolbox.

Scarica MCP Toolbox

Crea una directory per MCP Toolbox e scarica il file binario toolbox:

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

Configura e avvia il server MCP Toolbox

Scarica la configurazione degli strumenti alloydb-omni.yaml predefinita e avvia il server MCP Toolbox sulla porta 5000 (utilizzando le variabili di ambiente ALLOYDB_OMNI_* esportate in precedenza):
```
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
```
La configurazione alloydb-omni.yaml fornisce 31 strumenti predefiniti, inclusi gli strumenti chiave mostrati in questo codelab:
- 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
Per l'elenco completo degli strumenti, consulta alloydb-omni.yaml su GitHub.
Suggerimento: tieni il server MCP Toolbox in esecuzione in questa scheda del terminale e apri una nuova scheda del terminale (+ in Cloud Shell) per eseguire i comandi rimanenti in questo codelab.

In una nuova scheda del terminale, verifica che il server MCP Toolbox sia in esecuzione ed esponga i tuoi strumenti tramite l'endpoint JSON-RPC /mcp:

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

5. Configura il client MCP (interfaccia a riga di comando Antigravity)

In questa sezione, installerai l'interfaccia a riga di comando Antigravity (agy) e la configurerai per connetterti al server MCP Toolbox.

Installa l'interfaccia a riga di comando Antigravity

Se non è già installata, scarica ed esegui il programma di installazione di Antigravity CLI (agy) e verifica la versione:

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

Configura l'interfaccia a riga di comando di Antigravity

Aggiungi la voce del server MCP Toolbox al file di configurazione MCP del tuo client (ad esempio ~/.gemini/config/mcp_config.json per l'Antigravity CLI, .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json o .mcp.json per Claude Code).

Per connettere l'interfaccia a riga di comando Antigravity al server HTTP MCP Toolbox in esecuzione sulla porta 5000, esegui agy mcp add e verifica la voce con 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
```
In questo modo, la configurazione del server alloydb-omni viene scritta in ~/.gemini/config/mcp_config.json:
```
{
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}
```

Verifica la configurazione

Avvia Antigravity CLI:
```
agy
```
Se è la prima volta che avvii agy, segui le istruzioni sullo schermo per accedere (con Google OAuth o un progetto Google Cloud) e seleziona Sì, considero attendibile questa cartella quando ti viene chiesto se considerare attendibile la directory corrente.

Al prompt della CLI di Antigravity, inserisci /mcp per aprire il riquadro Server MCP e verifica che alloydb-omni sia connesso:

/mcp

L'output è simile al seguente:

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

Premi Esc per chiudere il riquadro Server MCP e tornare al prompt di Antigravity CLI.

6. Esegui test utilizzando le query per AlloyDB Omni

Ora che l'interfaccia a riga di comando Antigravity è connessa alla tua istanza AlloyDB Omni tramite MCP Toolbox, puoi interagire con il tuo database utilizzando prompt in linguaggio naturale.

Esegui una query di panoramica del database

Al prompt di Antigravity CLI, chiedi una panoramica del database corrente:

Give me an overview of the current database.

Quando ti viene chiesto di consentire la chiamata dello strumento, seleziona Sì (o Sì, e consenti sempre in questa conversazione). L'output è simile al seguente:

> 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)

Esempi di test per categoria

Invia alla CLI Antigravity i seguenti prompt in linguaggio naturale. L'agente mappa automaticamente ogni richiesta allo strumento corrispondente nel set di strumenti MCP di AlloyDB Omni:

1. Panoramica e integrità del database

Obiettivo del test	Prompt di linguaggio naturale	Strumento richiamato
Controllo del sistema	`Give me an overview of the current database.`	`database_overview`
Connessioni attive	`What queries are currently running on the database?`	`list_active_queries`
Estensioni installate	`What extensions are installed in this database?`	`list_installed_extensions`
Estensioni disponibili	`What extensions are available that I can install?`	`list_available_extensions`

2. Esplorazione di schemi e cataloghi

Obiettivo del test	Prompt di linguaggio naturale	Strumento richiamato
Elenca tabelle	`Show me all the tables in the current database.`	`list_tables`
Ispeziona gli indici	`List all indexes in the database and which tables they belong to.`	`list_indexes`
Esplora le visualizzazioni	`What views are available in the public schema?`	`list_views`
Controlla i trigger della tabella	`Show me the triggers defined on the orders table.`	`list_triggers`

3. Query e filtri dei dati (`execute_sql`)

Obiettivo del test	Prompt di linguaggio naturale	Strumento richiamato
Query di aggregazione	`Show me the 3 most expensive products in the 'Laptops' category.`	`execute_sql`
Query JOIN	`Find all customers who have placed an order in the last 6 months.`	`execute_sql`
Record non corrispondenti	`Which customers haven't placed any orders yet?`	`execute_sql`

4. Prestazioni delle query e piani di spiegazione (`get_query_plan`)

Obiettivo del test	Prompt di linguaggio naturale	Strumento richiamato
Explain plan	`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`
Verifica dell'indice	`Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.`	`get_query_plan`

5. Manutenzione e diagnostica del database

Obiettivo del test	Prompt di linguaggio naturale	Strumento richiamato
Bloat della tabella	`List the top five most bloated tables.`	`list_top_bloated_tables`
Conflitto blocco	`Show me if there are any active locks or blocked transactions.`	`list_locks`
Impostazioni di autovacuum	`Show me the current autovacuum configuration.`	`list_autovacuum_configurations`
Indici non validi	`Check for any invalid indexes in the database.`	`list_invalid_indexes`

7. Esegui la pulizia

Al termine del codelab, esegui la pulizia del container locale e dei processi avviati.

Esci dall'interfaccia a riga di comando di Antigravity digitando /quit (o premendo Ctrl+D due volte).
Passa alla scheda del terminale in cui è in esecuzione il server MCP Toolbox e premi Ctrl+C per arrestarlo.
Arresta e rimuovi il container Docker di AlloyDB Omni:
```
docker stop alloydbomni
docker rm alloydbomni
```

8. Complimenti

Congratulazioni per aver completato il codelab. Hai eseguito il deployment di AlloyDB Omni in un container, configurato MCP Toolbox for Databases con il set di strumenti AlloyDB Omni predefinito e lo hai integrato con l'interfaccia a riga di comando Antigravity per eseguire query e gestire il tuo database utilizzando il linguaggio naturale.

Argomenti trattati

Come eseguire il deployment e verificare un container AlloyDB Omni utilizzando Docker.
Come compilare tabelle e indici di esempio per testare i workflow degli agenti.
Come configurare ed eseguire MCP Toolbox for Databases con la configurazione degli strumenti alloydb-omni predefinita.
Come connettere l'interfaccia a riga di comando Antigravity a MCP Toolbox ed eseguire prompt in linguaggio naturale per il rilevamento dello schema, le query SQL, l'analisi del piano di query e la diagnostica del database.

Per maggiori informazioni, consulta le seguenti risorse:

9. Sondaggio

Come utilizzerai questo tutorial?

L'ho solo letta

L'ho letta e ho completato gli esercizi