Эта страница переведена с помощью Cloud Translation API.

База данных как инструмент: Agentic RAG с ADK, MCP Toolbox и Cloud SQL.

1. Введение

Полезность ИИ-агентов зависит от качества данных, к которым они имеют доступ. Большая часть реальных данных хранится в базах данных, а подключение агентов к базам данных обычно подразумевает написание кода для управления соединениями, логики запросов и встраивания конвейеров обработки данных в код агента. Каждый агент, которому необходим доступ к базе данных, повторяет эту работу, и каждое изменение запроса требует повторного развертывания агента.

В этом практическом занятии показан другой подход. Вы объявляете инструменты для работы с базой данных в файле YAML — стандартные SQL-запросы, поиск векторного сходства, даже автоматическое создание векторных представлений — а MCP Toolbox for Databases обрабатывает все операции с базой данных как MCP-сервер. Код вашего агента остается минимальным: загружаете инструменты, а Gemini решает, какой из них вызвать.

Что вы построите

Сервис «Ресторанный консьерж » для проекта «Находки для гурманов» — агент ADK на базе Gemini, который помогает посетителям просматривать меню ресторана, используя стандартные фильтры (категория, тип кухни), и находить блюда с помощью описаний на естественном языке, например: «Я хочу что-нибудь острое и вегетарианское». Агент считывает и записывает данные в базу данных Cloud SQL PostgreSQL полностью через MCP Toolbox for Databases, который обрабатывает весь доступ к базе данных, включая автоматическую генерацию векторных представлений для векторного поиска. В итоге и Toolbox, и агент работают на платформе Cloud Run.

Что вы узнаете

Как протокол MCP (Model Context Protocol) стандартизирует доступ к инструментам для агентов ИИ, и как MCP Toolbox for Databases применяет это к операциям с базами данных.
Настройте MCP Toolbox for Databases в качестве промежуточного программного обеспечения между агентом ADK и Cloud SQL PostgreSQL.
Инструменты базы данных определяются декларативно в файле tools.yaml — в вашем агенте не используется код базы данных.
Создайте агент ADK, который загружает инструменты с работающего сервера Toolbox, используя ToolboxToolset
Создавайте векторные представления данных с помощью встроенной функции embedding() Cloud SQL и включайте семантический поиск с помощью pgvector
Используйте функцию valueFromParam для автоматического приема вектора при операциях записи.
Разверните сервер Toolbox и агент ADK в Cloud Run.

Предварительные требования

Учетная запись Google Cloud с пробной платной учетной записью.
Базовые знания Python и SQL.
Опыт работы с облачными базами данных и ADK будет полезен.

2. Настройте свою среду.

На этом этапе подготавливается среда Cloud Shell, настраивается проект Google Cloud и клонируется репозиторий ссылок.

Открытая облачная оболочка

Откройте Cloud Shell в браузере. Cloud Shell предоставляет предварительно настроенную среду со всеми необходимыми инструментами для выполнения этого практического задания. При появлении запроса нажмите «Авторизовать».

Затем нажмите « Вид » -> « Терминал », чтобы открыть терминал. Ваш интерфейс должен выглядеть примерно так.

Это будет наш основной интерфейс: IDE сверху, терминал снизу.

Настройте рабочую директорию.

Создайте свою рабочую директорию. Весь код, написанный вами в этом практическом занятии, будет находиться здесь:

mkdir -p ~/build-agent-adk-toolbox-cloudsql
cloudshell workspace ~/build-agent-adk-toolbox-cloudsql && cd ~/build-agent-adk-toolbox-cloudsql

После этого подготовим несколько каталогов для управления такими вещами, как заполнение скриптов и логов.

mkdir -p ~/build-agent-adk-toolbox-cloudsql/scripts
mkdir -p ~/build-agent-adk-toolbox-cloudsql/logs

Настройте свой проект в Google Cloud.

Создайте файл .env с переменными location:

# For Vertex AI / Gemini API calls
echo "GOOGLE_CLOUD_LOCATION=global" > .env
# For Cloud SQL, Cloud Run, Artifact Registry
echo "REGION=us-central1" >> .env

ВАЖНО! Приведенные ниже шаги помогут быстро настроить проект Google Cloud, связанный с пробной учетной записью (строгая настройка) . Если вы предпочитаете использовать свой предыдущий проект, вы можете пропустить следующий шаг и выполнить следующий:

Добавьте название своего проекта в качестве переменной GOOGLE_CLOUD_PROJECT в файл .env
Активируйте свой проект в терминале с помощью gcloud config set project your-project-id

После этого вы можете сразу перейти к разделу активации API.

Если вы не уверены в этом, продолжите чтение раздела ниже.

Чтобы упростить настройку проекта в терминале, загрузите этот скрипт настройки проекта в свою рабочую директорию:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

Запустите скрипт. Он проверит вашу учетную запись для оплаты пробной версии, создаст новый проект (или проверит существующий), сохранит идентификатор вашего проекта в файл .env в текущем каталоге и установит активный проект в gcloud .

bash setup_verify_trial_project.sh && source .env

Сценарий будет:

Убедитесь, что у вас есть активный пробный аккаунт для оплаты.
Проверьте наличие существующего проекта в .env (если таковой имеется).
Создайте новый проект или используйте существующий.
Свяжите пробный аккаунт с вашим проектом.
Сохраните идентификатор проекта в файл .env
Установите этот проект в качестве активного проекта gcloud

Убедитесь, что проект настроен правильно, проверив желтый текст рядом с вашим рабочим каталогом в командной строке терминала Cloud Shell. Там должен отображаться идентификатор вашего проекта.

Активируйте необходимый API

Далее нам необходимо включить несколько API для продукта, с которым мы будем взаимодействовать:

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com

API Vertex AI ( aiplatform.googleapis.com ) — ваш агент использует модели Gemini, а Toolbox использует API встраивания для векторного поиска.
Cloud SQL Admin API ( sqladmin.googleapis.com ) — позволяет создавать и управлять экземпляром PostgreSQL.
API Compute Engine ( compute.googleapis.com ) — необходим для создания экземпляров Cloud SQL.
Cloud Run, Cloud Build, Artifact Registry — используются на этапе развертывания, который будет рассмотрен далее в этом практическом занятии.

3. Подготовка скриптов для инициализации базы данных

На этом этапе начинается создание экземпляра Cloud SQL и запускается автоматизированный скрипт настройки, который ожидает готовности экземпляра, затем создает базу данных, заполняет ее списками заданий и генерирует эмбеддинги — все за одну операцию.

Для начала добавим пароль к базе данных в ваш файл .env и перезагрузим её:

echo "DB_PASSWORD=restaurant-pwd" >> .env
echo "DB_INSTANCE=restaurant-instance" >> .env
echo "DB_NAME=restaurant_db" >> .env
source .env

Создание Bash-скрипта для создания экземпляра и базы данных.

Затем создайте скрипт scripts/setup_database.sh с помощью следующей команды.

mkdir -p ~/build-agent-adk-toolbox-cloudsql/scripts
cloudshell edit scripts/setup_database.sh

Затем скопируйте следующий код в файл scripts/setup_database.sh

#!/bin/bash
set -e
source .env

echo "================================================"
echo "Database Setup"
echo "================================================"
echo ""

# Step 1: Create Cloud SQL instance
echo "[1/5] Creating Cloud SQL instance..."

# Check if instance already exists
if gcloud sql instances describe "$DB_INSTANCE" --quiet >/dev/null 2>&1; then
    echo "      Instance already exists"
else
    echo "      Creating instance (takes 5-10 minutes)..."
    gcloud sql instances create "$DB_INSTANCE" \
        --database-version=POSTGRES_17 \
        --tier=db-custom-1-3840 \
        --edition=ENTERPRISE \
        --region="$REGION" \
        --root-password="$DB_PASSWORD" \
        --enable-google-ml-integration \
        --database-flags cloudsql.enable_google_ml_integration=on \
        --quiet
fi
echo "      ✓ Instance ready"
echo ""

# Step 2: Verify instance is ready
echo "[2/5] Verifying instance state..."

STATE=$(gcloud sql instances describe "$DB_INSTANCE" --format='value(state)')

if [ "$STATE" != "RUNNABLE" ]; then
    echo "ERROR: Instance not ready (state: $STATE)"
    exit 1
fi
echo "      ✓ Instance is RUNNABLE"
echo ""

# Step 3: Grant IAM permissions
echo "[3/5] Granting Vertex AI permissions..."

SERVICE_ACCOUNT=$(gcloud sql instances describe "$DB_INSTANCE" \
    --format='value(serviceAccountEmailAddress)')

if [ -z "$SERVICE_ACCOUNT" ]; then
    echo "ERROR: Could not retrieve service account"
    exit 1
fi

gcloud projects add-iam-policy-binding "$GOOGLE_CLOUD_PROJECT" \
    --member="serviceAccount:$SERVICE_ACCOUNT" \
    --role="roles/aiplatform.user" \
    --quiet

echo "      ✓ Permissions granted"
echo ""

# Step 4: Create database
echo "[4/5] Creating database..."

# Check if database already exists
if gcloud sql databases describe "$DB_NAME" \
    --instance="$DB_INSTANCE" --quiet >/dev/null 2>&1; then
    echo "      Database already exists"
else
    gcloud sql databases create "$DB_NAME" \
        --instance="$DB_INSTANCE" \
        --quiet
fi

echo "      ✓ Database '$DB_NAME' ready"
echo ""

# Step 5: Seed database and generate embeddings
echo "[5/5] Seeding database and generating embeddings..."

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SETUP_SCRIPT="${SCRIPT_DIR}/setup_restaurant_db.py"

if [ ! -f "$SETUP_SCRIPT" ]; then
    echo "ERROR: Setup script not found: $SETUP_SCRIPT"
    exit 1
fi

uv run "$SETUP_SCRIPT"

echo ""
echo "================================================"
echo "Setup complete!"
echo "================================================"
echo ""

Создание скрипта на Python для заполнения начальных данных.

После этого создайте файл скрипта для заполнения базы данных scripts/setup_restaurant_db.py с помощью приведенной ниже команды.

cloudshell edit scripts/setup_restaurant_db.py

Затем скопируйте следующий код в файл scripts/setup_restaurant_db.py

import os
import sys
from pathlib import Path
from dotenv import load_dotenv
from google.cloud.sql.connector import Connector
import pg8000
import time

# Load environment variables from .env file
env_path = Path(__file__).parent.parent / '.env'
load_dotenv(env_path)
EMBEDDING_MODEL='gemini-embedding-001'

# Verify required environment variables
required_vars = ['GOOGLE_CLOUD_PROJECT', 'REGION', 'DB_PASSWORD']
missing_vars = [var for var in required_vars if not os.environ.get(var)]

if missing_vars:
    print(f"ERROR: Missing required environment variables: {', '.join(missing_vars)}", file=sys.stderr)
    print(f"", file=sys.stderr)
    print(f"Expected .env file location: {env_path}", file=sys.stderr)
    if not env_path.exists():
        print(f"✗ File not found at that location", file=sys.stderr)
    else:
        print(f"✓ File exists but is missing the variables above", file=sys.stderr)
    print(f"", file=sys.stderr)
    print(f"Make sure your .env file contains:", file=sys.stderr)
    for var in missing_vars:
        print(f"  {var}=<value>", file=sys.stderr)
    sys.exit(1)

# Menu items data
MENU_ITEMS = [
    ("Truffle Mushroom Risotto", "Italian", "Main Course",
     "Arborio rice, truffle oil, porcini mushrooms, parmesan, white wine",
     "$28", "Vegetarian, Gluten-Free", True,
     "A creamy, luxurious risotto made with arborio rice slow-cooked in white wine and mushroom broth, finished with shaved black truffle and aged parmesan. The porcini mushrooms add a deep, earthy flavor that pairs beautifully with the delicate truffle oil drizzled on top."),
    ("Spicy Tuna Tartare", "Japanese", "Appetizer",
     "Ahi tuna, sriracha, sesame oil, avocado, crispy wonton",
     "$22", "Gluten-Free, Dairy-Free", True,
     "Fresh ahi tuna diced and tossed with sriracha aioli, toasted sesame oil, and lime juice, served atop creamy avocado slices with crispy wonton chips. A perfect balance of heat, richness, and crunch inspired by modern Japanese fusion cuisine."),
    ("Lamb Kofta Kebab", "Middle Eastern", "Main Course",
     "Ground lamb, cumin, coriander, yogurt sauce, flatbread",
     "$24", "Halal", True,
     "Hand-formed spiced lamb kebabs grilled over charcoal, seasoned with cumin, coriander, and sumac. Served with warm flatbread, tangy yogurt-cucumber sauce, and a fresh herb salad. A classic Middle Eastern street food elevated with premium ingredients."),
    ("Pad Thai", "Thai", "Main Course",
     "Rice noodles, shrimp, tamarind, peanuts, bean sprouts, lime",
     "$19", "Gluten-Free, Dairy-Free", True,
     "Stir-fried rice noodles with tiger shrimp, scrambled egg, and a sweet-sour tamarind sauce, topped with crushed peanuts, fresh bean sprouts, and a squeeze of lime. This classic Thai street food dish balances sweet, sour, salty, and umami in every bite."),
    ("Margherita Pizza", "Italian", "Main Course",
     "San Marzano tomatoes, fresh mozzarella, basil, olive oil",
     "$18", "Vegetarian", True,
     "A Neapolitan-style pizza with a thin, charred crust topped with crushed San Marzano tomatoes, creamy buffalo mozzarella, fresh basil leaves, and a drizzle of extra virgin olive oil. Simple, classic, and made with imported Italian ingredients."),
    ("Miso Glazed Black Cod", "Japanese", "Main Course",
     "Black cod, white miso, mirin, sake, pickled ginger",
     "$36", "Gluten-Free, Dairy-Free", True,
     "Buttery black cod marinated for 72 hours in a sweet white miso glaze with mirin and sake, then broiled until caramelized. Served with pickled ginger and steamed bok choy. A signature dish inspired by Nobu's iconic preparation."),
    ("Caesar Salad", "American", "Appetizer",
     "Romaine lettuce, parmesan, croutons, anchovy dressing",
     "$14", "Contains Gluten", True,
     "Crisp romaine hearts tossed with a house-made anchovy-garlic dressing, shaved parmesan, and golden sourdough croutons. A timeless salad that serves as the perfect light starter or side dish with grilled proteins."),
    ("Chicken Tikka Masala", "Indian", "Main Course",
     "Chicken thigh, tomato cream sauce, garam masala, basmati rice",
     "$21", "Gluten-Free", True,
     "Tender chunks of tandoori-marinated chicken simmered in a rich, creamy tomato sauce spiced with garam masala, cumin, and fenugreek. Served over fragrant basmati rice with warm garlic naan on the side."),
    ("Chocolate Lava Cake", "French", "Dessert",
     "Dark chocolate, butter, eggs, vanilla, powdered sugar",
     "$15", "Vegetarian", True,
     "A warm, individual-sized chocolate cake with a molten dark chocolate center that flows when you break through the delicate outer shell. Made with 70% Belgian dark chocolate and served with a scoop of vanilla bean ice cream."),
    ("Pho Bo", "Vietnamese", "Main Course",
     "Rice noodles, beef brisket, star anise, cinnamon, bean sprouts, Thai basil",
     "$17", "Gluten-Free, Dairy-Free", True,
     "A deeply aromatic beef broth simmered for 12 hours with star anise, cinnamon, and charred ginger, ladled over rice noodles and thinly sliced beef brisket. Served with fresh Thai basil, bean sprouts, jalapeño, and lime for the table to customize."),
    ("Lobster Bisque", "French", "Appetizer",
     "Lobster, heavy cream, cognac, tarragon, cayenne",
     "$19", "Gluten-Free", True,
     "A velvety smooth soup made from roasted lobster shells, finished with heavy cream, a splash of cognac, and fresh tarragon. Each bowl is garnished with tender lobster meat and a pinch of cayenne for subtle warmth."),
    ("Falafel Plate", "Middle Eastern", "Main Course",
     "Chickpeas, herbs, tahini, pickled vegetables, hummus",
     "$16", "Vegan, Gluten-Free", True,
     "Crispy-on-the-outside, fluffy-on-the-inside chickpea fritters seasoned with fresh parsley, cilantro, and cumin. Served with creamy tahini sauce, house-made hummus, pickled turnips, and warm pita bread."),
    ("Crème Brûlée", "French", "Dessert",
     "Heavy cream, vanilla bean, egg yolks, caramelized sugar",
     "$13", "Vegetarian, Gluten-Free", True,
     "A classic French custard made with Madagascar vanilla bean and farm-fresh egg yolks, topped with a perfectly torched layer of caramelized sugar that cracks with a satisfying snap. Rich, creamy, and elegantly simple."),
    ("Korean BBQ Short Ribs", "Korean", "Main Course",
     "Beef short ribs, soy sauce, sesame, garlic, pear marinade",
     "$32", "Dairy-Free", False,
     "Premium beef short ribs marinated overnight in a sweet and savory blend of soy sauce, Asian pear, garlic, and toasted sesame. Grilled tableside over charcoal and served with lettuce wraps, pickled daikon, and gochujang dipping sauce."),
    ("Tiramisu", "Italian", "Dessert",
     "Mascarpone, espresso, ladyfingers, cocoa, Marsala wine",
     "$14", "Vegetarian, Contains Gluten", True,
     "Layers of espresso-soaked ladyfingers and whipped mascarpone cream flavored with Marsala wine, dusted with premium Dutch cocoa powder. Made fresh daily and chilled for 24 hours to develop rich, complex flavors."),
]


def get_connection():
    """Create a connection to Cloud SQL using the connector."""
    project = os.environ['GOOGLE_CLOUD_PROJECT']
    region = os.environ['REGION']
    password = os.environ['DB_PASSWORD']
    instance = os.environ['DB_INSTANCE']
    database = os.environ['DB_NAME']

    connector = Connector()
    conn = connector.connect(
        f"{project}:{region}:{instance}",
        "pg8000",
        user="postgres",
        password=password,
        db=database
    )
    return conn, connector


def create_schema(cursor):
    """Create extensions and menu_items table."""
    cursor.execute("CREATE EXTENSION IF NOT EXISTS google_ml_integration")
    cursor.execute("CREATE EXTENSION IF NOT EXISTS vector")
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS menu_items (
            id SERIAL PRIMARY KEY,
            name VARCHAR NOT NULL,
            cuisine_type VARCHAR NOT NULL,
            category VARCHAR NOT NULL,
            ingredients VARCHAR NOT NULL,
            price VARCHAR NOT NULL,
            dietary_tags VARCHAR NOT NULL,
            available BOOLEAN NOT NULL DEFAULT TRUE,
            description TEXT NOT NULL,
            description_embedding vector(3072)
        )
    """)


def seed_menu_items(cursor, conn):
    """Insert menu items."""
    cursor.execute("SELECT COUNT(*) FROM menu_items")
    existing_count = cursor.fetchone()[0]

    if existing_count > 0:
        print(f"      {existing_count} menu items already exist, skipping seed")
        return 0

    cursor.executemany("""
        INSERT INTO menu_items (name, cuisine_type, category, ingredients, price, dietary_tags, available, description)
        VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
    """, MENU_ITEMS)
    conn.commit()
    return len(MENU_ITEMS)


def generate_embeddings(cursor, conn):
    """Generate embeddings using Cloud SQL's embedding() function."""
    cursor.execute("SELECT COUNT(*) FROM menu_items WHERE description_embedding IS NULL")
    null_count = cursor.fetchone()[0]

    if null_count == 0:
        print("      All menu items already have embeddings")
        return 0

    cursor.execute(f"""
        UPDATE menu_items
        SET description_embedding = embedding('{EMBEDDING_MODEL}', description)::vector
        WHERE description_embedding IS NULL
    """)
    rows_updated = cursor.rowcount
    conn.commit()
    return rows_updated


def main():
    conn, connector = get_connection()
    cursor = conn.cursor()

    try:
        create_schema(cursor)
        conn.commit()

        seeded = seed_menu_items(cursor, conn)
        if seeded > 0:
            print(f"      ✓ Inserted {seeded} menu items")

        # Waiting for vertex role propagation
        time.sleep(60)
        embedded = generate_embeddings(cursor, conn)
        if embedded > 0:
            print(f"      ✓ Generated {embedded} embeddings")

    except Exception as e:
        print(f"ERROR: {e}", file=sys.stderr)
        sys.exit(1)
    finally:
        cursor.close()
        conn.close()
        connector.close()


if __name__ == "__main__":
    main()

Теперь перейдём к следующему шагу.

4. Создайте и инициализируйте базу данных.

Теперь наши скрипты готовы к выполнению. Для выполнения подготовленного скрипта нам понадобится Python, поэтому давайте сначала подготовим его.

Настройте проект Python.

uv — это быстрый менеджер пакетов и проектов для Python, написанный на Rust ( документация uv ). В этом практическом занятии он используется для повышения скорости и упрощения поддержки проекта на Python.

Инициализируйте проект Python и добавьте необходимые зависимости:

uv init
uv add cloud-sql-python-connector --extra pg8000
uv add python-dotenv

Обратите внимание, что здесь мы используем Python SDK cloud-sql-python-connector для инициализации защищенного соединения с нашим экземпляром базы данных, аутентификация которого осуществляется с помощью учетных данных приложения по умолчанию.

Запустите скрипт установки.

Теперь мы можем запустить скрипт настройки в фоновом режиме и просмотреть вывод консоли, который будет записан в файл logs/atabase_setup.log используя следующую команду. Вы можете перейти к следующему разделу, пока этот процесс не завершится.

mkdir -p ~/build-agent-adk-toolbox-cloudsql/logs
bash scripts/setup_database.sh > logs/database_setup.log 2>&1 &

Загрузите исполняемый файл Toolbox.

В этом руководстве мы будем использовать MCP Toolbox, к счастью, он поставляется с предварительно собранным бинарным файлом, готовым к использованию в среде Linux. Теперь давайте загрузим его в фоновом режиме, так как это займет довольно много времени. Выполните следующую команду, чтобы загрузить бинарный файл, и просмотрите вывод в logs/toolbox_dl.log . Вы можете перейти к следующему разделу, пока процесс не завершится.

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.1.0/linux/amd64/toolbox > logs/toolbox_dl.log 2>&1 &

Понимание скрипта установки `scripts/setup_database.sh`

Теперь давайте попробуем разобраться в скрипте настройки, который мы ранее сконфигурировали. Он выполняет следующий процесс.

Первая команда, которую мы там выполняем, — это команда gcloud sql instances create со следующим флагом.

db-custom-1-3840 — это самый маленький выделенный уровень Cloud SQL (1 vCPU, 3,75 ГБ ОЗУ) в версии ENTERPRISE . Подробнее можно прочитать здесь . Для интеграции Vertex AI ML требуется выделенное ядро — уровни с общим ядром ( db-f1-micro , db-g1-small ) его не поддерживают.
--root-password устанавливает пароль для пользователя postgres по умолчанию.
--enable-google-ml-integration включает встроенную интеграцию Cloud SQL с Vertex AI, которая позволяет вызывать модели встраивания непосредственно из SQL с помощью функции embedding() .

Проверьте, находится ли экземпляр уже в состоянии RUNNABLE
Предоставьте учетной записи службы экземпляра Cloud SQL разрешение на вызов Vertex AI с помощью команды gcloud projects add-iam-policy-binding . Это необходимо для встроенной функции embedding() , которую мы будем использовать при заполнении базы данных данными.
Создание базы данных
Выполнение скрипта setup_restaurant_db.py для заполнения базы данных.

Понимание скрипта инициализации `scripts/setup_restaurant_db.py`

Теперь перейдём к скрипту инициализации. Этот скрипт выполняет следующие действия:

Инициализируйте соединение с экземпляром базы данных.
Устанавливает два расширения PostgreSQL:

google_ml_integration — предоставляет функцию SQL embedding() , которая вызывает модели встраивания Vertex AI непосредственно из SQL. Это расширение на уровне базы данных, которое делает функции машинного обучения доступными внутри restaurant_db . Флаг уровня экземпляра ( --enable-google-ml-integration ), который вы устанавливаете при создании экземпляра, позволяет виртуальной машине Cloud SQL обращаться к Vertex AI — расширение делает функции SQL доступными в этой конкретной базе данных.
vector ( pgvector ) — добавляет vector тип данных и операторы расстояния для хранения и запроса векторных представлений.

Создайте таблицу, обратите внимание, что столбец description_embedding имеет vector(3072) — это столбец pgvector , который хранит 3072-мерные векторы.
Заполните начальные данные пунктов меню.
Сгенерируйте данные для встраивания из поля description и заполните поле description_embedding , используя встроенную интеграцию вершин через функцию embedding()

embedding('gemini-embedding-001', description) — вызывает модель встраивания Gemini от Vertex AI напрямую из SQL, передавая текст description каждого задания. Это расширение google_ml_integration которое вы установили в скрипте инициализации.
::vector — преобразует возвращаемый массив чисел с плавающей запятой в vector тип pgvector, чтобы его можно было хранить и запрашивать с помощью операторов расстояния.
UPDATE применяется ко всем 15 строкам, генерируя одно 3072-мерное векторное представление для каждого описания вакансии.

Это позволит подготовить исходные данные, к которым будет иметь доступ наш агент.

5. Настройка MCP Toolbox для баз данных.

На этом шаге представлен MCP Toolbox for Databases, настроено подключение к вашему экземпляру Cloud SQL и определены два стандартных инструмента для выполнения SQL-запросов.

Что такое MCP и зачем использовать Toolbox?

MCP (Model Context Protocol) — это открытый протокол, стандартизирующий способы обнаружения внешних инструментов и взаимодействия с ними у агентов искусственного интеллекта. Он определяет модель «клиент-сервер»: агент размещает MCP-клиент, а инструменты предоставляются MCP-серверами. Любой MCP-совместимый клиент может использовать любой MCP-совместимый сервер — агенту не требуется собственный код интеграции для каждого инструмента.

MCP Toolbox for Databases — это сервер MCP с открытым исходным кодом, созданный специально для доступа к базам данных. Без него вам пришлось бы писать функции на Python, которые открывают соединения с базами данных, управляют пулами соединений, формируют параметризованные запросы для предотвращения SQL-инъекций, обрабатывают ошибки и встраивают весь этот код в ваш агент. Каждый агент, которому необходим доступ к базе данных, повторяет эту работу. Изменение запроса означает повторное развертывание агента.

С помощью Toolbox вы пишете YAML-файл. Каждый инструмент соответствует параметризованному SQL-запросу. Toolbox обрабатывает пулы соединений, параметризованные запросы, аутентификацию и мониторинг. Инструменты независимы от агента — обновить запрос можно, отредактировав tools.yaml и перезапустив Toolbox, без изменения кода агента. Те же инструменты работают с ADK, LangGraph, LlamaIndex или любой совместимой с MCP платформой.

Напишите конфигурацию инструментов

Теперь нам нужно создать файл tools.yaml в редакторе Cloud Shell, чтобы настроить конфигурацию наших инструментов.

cloudshell edit tools.yaml

Файл использует многодокументный YAML — каждый блок, разделённый символами --- представляет собой отдельный ресурс. Каждый ресурс имеет kind , который определяет его назначение ( sources для подключений к базам данных, tools для действий, вызываемых агентом), и type , указывающий на бэкэнд ( cloud-sql-postgres для источника, postgres-sql для инструментов на основе SQL). Инструмент ссылается на свой источник по name , благодаря чему Toolbox знает, к какому пулу подключений следует обращаться. Переменные среды используют синтаксис ${VAR_NAME} и разрешаются при запуске.

Теперь давайте сначала скопируем следующие скрипты в файл tools.yaml

# tools.yaml

# --- Data Source ---
kind: source
name: restaurant-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: ${DB_INSTANCE}
database: ${DB_NAME}
user: postgres
password: ${DB_PASSWORD}

---