1. Введение
В этой лабораторной работе вы будете использовать MCP Toolbox for Databases, чтобы сделать доступными ваши наборы данных BigQuery.
В ходе выполнения лабораторной работы вы будете применять следующий пошаговый подход:
- Определите конкретный набор данных BigQuery («Заметки о выпуске Google Cloud») из общедоступной программы наборов данных BigQuery.
- Настройте MCP Toolbox for Databases, который подключается к набору данных BigQuery.
- Разработайте агента с помощью Agent Development Kit (ADK), который будет использовать MCP Toolbox для ответа на вопросы пользователя о заметках о выпуске Google Cloud.
Что ты будешь делать?
- Настройте MCP Toolbox for Databases, чтобы предоставить примечания к выпуску Google Cloud, общедоступный набор данных BigQuery, в качестве интерфейса MCP для других клиентов MCP (IDE, инструментов и т. д.).
Чему вы научитесь
- Изучите общедоступные наборы данных BigQuery и выберите нужный.
- Настройте MCP Toolbox for Databases для общедоступного набора данных BigQuery, который мы хотим сделать доступным для клиентов MCP.
- Спроектируйте и разработайте агента с использованием Agent Development Kit (ADK) для ответа на запросы пользователей.
- Протестируйте Agent и MCP Toolbox для баз данных в локальной среде.
Что вам понадобится
- Веб-браузер Chrome.
- Локальная среда разработки Python.
2. Прежде чем начать
Создать проект
- В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud.
- Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .
- Вы будете использовать Cloud Shell — среду командной строки, работающую в Google Cloud и предустановленную вместе с bq. Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud.
- После подключения к Cloud Shell вы проверяете, что вы уже прошли аутентификацию и что проекту присвоен ваш идентификатор проекта, с помощью следующей команды:
gcloud auth list
- Выполните следующую команду в Cloud Shell, чтобы подтвердить, что команда gcloud знает о вашем проекте.
gcloud config list project
- Если ваш проект не настроен, используйте следующую команду для его настройки:
gcloud config set project <YOUR_PROJECT_ID>
Информацию о командах и использовании gcloud см. в документации .
3. Набор данных Google Release Notes и клиенты MCP
Сначала давайте взглянем на заметки о выпуске Google Cloud, которые регулярно обновляются на официальной веб-странице заметок о выпуске Google Cloud , снимок экрана которой представлен ниже:
Вы можете подписаться на URL-адрес ленты, но что, если мы сможем просто спросить об этих заметках о выпуске в нашем чате с агентами? Например, с помощью простого запроса типа «Обновите для меня информацию о заметках о выпуске Google Cloud».
4. Набор инструментов MCP для баз данных
MCP Toolbox for Databases — это MCP-сервер с открытым исходным кодом для баз данных. Он разработан с учётом требований корпоративного уровня и качества для производства. Он позволяет разрабатывать инструменты проще, быстрее и безопаснее, решая такие сложные задачи, как организация пула соединений, аутентификация и многое другое.
Toolbox помогает создавать инструменты Gen AI, которые позволят вашим агентам получать доступ к данным в вашей базе данных. Toolbox предоставляет:
- Упрощенная разработка: интегрируйте инструменты в свой агент менее чем в 10 строк кода, повторно используйте инструменты между несколькими агентами или фреймворками и с легкостью развертывайте новые версии инструментов.
- Лучшая производительность: лучшие практики, такие как пул соединений, аутентификация и многое другое.
- Повышенная безопасность: интегрированная аутентификация для более безопасного доступа к вашим данным
- Сквозное наблюдение: готовые метрики и трассировка со встроенной поддержкой OpenTelemetry.
- Toolbox упрощает подключение баз данных к любым помощникам на основе искусственного интеллекта с поддержкой MCP, даже к тем, которые находятся в вашей IDE.
Toolbox располагается между фреймворком оркестровки вашего приложения и базой данных, предоставляя плоскость управления для изменения, распространения и вызова инструментов. Он упрощает управление инструментами, предоставляя централизованное хранилище для их хранения и обновления, позволяя агентам и приложениям совместно использовать инструменты и обновлять их без необходимости повторного развертывания приложения.
Подведем итог простыми словами:
- MCP Toolbox доступен в виде двоичного образа контейнера, или вы можете собрать его из исходного кода.
- Он предоставляет набор инструментов, которые настраиваются через файл tools.yaml. Эти инструменты можно рассматривать как подключаемые к вашим источникам данных. Вы можете видеть различные поддерживаемые источники данных: AlloyDB, BigQuery и т. д.
- Поскольку этот набор инструментов теперь поддерживает MCP, вы автоматически получаете конечную точку сервера MCP, которую затем могут использовать агенты (IDE), или вы можете использовать их при разработке своих приложений агентов с использованием различных фреймворков, таких как Agent Development Kit (ADK).
В этой записи блога мы сосредоточимся на областях, выделенных ниже:
Итак, мы создадим конфигурацию в MCP Toolbox for Databases, которая умеет подключаться к нашему набору данных BigQuery. Затем мы разработаем агента с помощью Agent Development Kit (ADK), который будет интегрироваться с конечной точкой MCP Toolbox и позволит нам отправлять естественные запросы о нашем наборе данных. Представьте, что вы разрабатываете агентское приложение, которое умеет взаимодействовать с вашим набором данных BigQuery и выполняет некоторые запросы.
5. Заметки о выпуске набора данных BigQuery для Google Cloud
Программа Google Cloud Public Dataset Program предоставляет доступ к различным наборам данных для ваших приложений. Одним из таких наборов данных является база данных Google Cloud Release Notes. Этот набор данных содержит ту же информацию, что и официальная веб-страница Google Cloud Release Notes , и доступен для публичного запроса.
В качестве теста я просто проверяю набор данных, выполнив простой запрос, показанный ниже:
SELECT
product_name,description,published_at
FROM
`bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
WHERE
DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY product_name,description,published_at
ORDER BY published_at DESC
Это дает мне список записей из набора данных Release Notes, которые были опубликованы за последние 7 дней.
Замените его любым другим набором данных по вашему выбору, а также соответствующими запросами и параметрами. Теперь нам осталось только настроить его как источник данных и инструмент в MCP Toolbox for Databases. Давайте посмотрим, как это сделать.
6. Установка MCP Toolbox для баз данных
Откройте терминал на локальном компьютере и создайте папку с именем mcp-toolbox .
mkdir mcp-toolbox
Перейдите в папку mcp-toolbox с помощью команды, показанной ниже:
cd mcp-toolbox
Установите двоичную версию MCP Toolbox for Databases с помощью скрипта, приведённого ниже. Приведённая ниже команда предназначена для Linux, но если вы используете Mac или Windows, убедитесь, что вы загружаете правильный двоичный файл. Ознакомьтесь со страницей релизов для вашей операционной системы и архитектуры и загрузите правильный двоичный файл.
export VERSION=0.13.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Теперь у нас есть готовая к использованию двоичная версия инструментария. Следующий шаг — настроить инструментарий с использованием наших источников данных и других конфигураций.
7. Настройка MCP Toolbox для баз данных
Теперь нам нужно определить наш набор данных BigQuery и инструменты в файле tools.yaml , необходимом для MCP Toolbox for Database. Файл tools.yaml — это основной способ настройки Toolbox.
Создайте файл с именем tools.yaml в той же папке, т. е. mcp-toolbox , содержимое которого показано ниже.
Вы можете использовать редактор nano, доступный в Cloud Shell. Команда nano выглядит следующим образом: « nano tools.yaml ».
Не забудьте заменить значение YOUR_PROJECT_ID на идентификатор вашего проекта Google Cloud.
sources:
my-bq-source:
kind: bigquery
project: YOUR_PROJECT_ID
tools:
search_release_notes_bq:
kind: bigquery-sql
source: my-bq-source
statement: |
SELECT
product_name,description,published_at
FROM
`bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
WHERE
DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY product_name,description,published_at
ORDER BY published_at DESC
description: |
Use this tool to get information on Google Cloud Release Notes.
toolsets:
my_bq_toolset:
- search_release_notes_bq
Давайте вкратце разберем суть файла:
- Источники представляют собой различные источники данных, с которыми может взаимодействовать инструмент. Источник представляет собой источник данных, с которым может взаимодействовать инструмент. Вы можете определить источники как карту в разделе источников файла tools.yaml. Как правило, конфигурация источника содержит всю информацию, необходимую для подключения к базе данных и взаимодействия с ней. В нашем случае мы определили источник BigQuery
my-bq-source, и вам необходимо указать идентификатор вашего проекта Google Cloud. Подробнее см. в справочнике по источникам . - Инструменты определяют действия, которые может выполнять агент, например, чтение и запись в источник. Инструмент представляет собой действие, которое может выполнять ваш агент, например, выполнение оператора SQL. Вы можете определить Инструменты как карту в разделе инструментов файла tools.yaml. Как правило, инструменту требуется источник для выполнения действий. В нашем случае мы определяем один инструмент
search_release_notes_bq. Он ссылается на источник BigQuerymy-bq-source, который мы определили на первом этапе. Он также содержит оператор и инструкцию, которые будут использоваться клиентами AI Agent. Подробнее см. в справочнике по инструментам . - Наконец, у нас есть набор инструментов, позволяющий определять группы инструментов, которые вы хотите загружать вместе. Это может быть полезно для определения различных групп в зависимости от агента или приложения. В нашем случае у нас есть определение набора инструментов, в котором на данный момент определён только один существующий инструмент
search_release_notes_bq. Вы можете создать несколько наборов инструментов, включающих в себя комбинации различных инструментов.
Итак, на данный момент мы определили только один инструмент, который получает информацию о выпуске за последние 7 дней по запросу. Но вы также можете использовать различные комбинации параметров.
Дополнительные сведения о конфигурации ( Источник , Инструменты ) см. в конфигурации источника данных BigQuery в MCP Toolbox for Databases.
8. Тестирование MCP Toolbox для баз данных
Мы скачали и настроили Toolbox с помощью файла tools.yaml в папке mcp-toolbox . Давайте сначала запустим его локально.
Выполните следующую команду:
./toolbox --tools-file="tools.yaml"
При успешном выполнении вы должны увидеть запуск сервера с примером вывода, аналогичным приведенному ниже:
2025-09-08T03:56:45.772489914Z INFO "Initialized 1 sources."
2025-09-08T03:56:45.772682659Z INFO "Initialized 0 authServices."
2025-09-08T03:56:45.772735103Z INFO "Initialized 1 tools."
2025-09-08T03:56:45.772774639Z INFO "Initialized 2 toolsets."
2025-09-08T03:56:45.777711644Z INFO "Server ready to serve!"
Сервер MCP Toolbox по умолчанию работает на порту 5000 Если порт 5000 уже занят, используйте другой порт (например, 7000 ), как показано в команде ниже. В последующих командах используйте порт 7000 вместо порта 5000 .
./toolbox --tools-file "tools.yaml" --port 7000
Давайте воспользуемся Cloud Shell, чтобы проверить это.
Нажмите «Веб-просмотр» в Cloud Shell, как показано ниже:
Нажмите «Изменить порт» и установите порт 5000, как показано ниже, затем нажмите «Изменить и просмотреть».
Это должно дать следующий результат:
В URL-адресе браузера добавьте в конец URL-адреса следующее:
/api/toolset
Это должно открыть список текущих настроенных инструментов. Пример вывода показан ниже:
{
"serverVersion": "0.13.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
"tools": {
"search_release_notes_bq": {
"description": "Use this tool to get information on Google Cloud Release Notes.\n",
"parameters": [],
"authRequired": []
}
}
}
Тестирование инструментов через интерфейс MCP Toolbox for Databases
Toolbox предоставляет визуальный интерфейс ( Toolbox UI ) для непосредственного взаимодействия с инструментами путем изменения параметров, управления заголовками и выполнения вызовов — все это в простом веб-интерфейсе.
Если вы хотите это проверить, вы можете запустить предыдущую команду, которую мы использовали для запуска Toolbox Server, с опцией --ui .
Для этого завершите работу предыдущего экземпляра MCP Toolbox for Databases Server, который, возможно, был запущен, и введите следующую команду:
./toolbox --tools-file "tools.yaml" --ui
В идеале вы должны увидеть сообщение о том, что сервер смог подключиться к нашим источникам данных и загрузил набор инструментов. Пример сообщения приведён ниже. Обратите внимание, что в нём упоминается, что пользовательский интерфейс Toolbox запущен и работает.
2025-09-08T03:59:34.856476253Z INFO "Initialized 1 sources."
2025-09-08T03:59:34.856546526Z INFO "Initialized 0 authServices."
2025-09-08T03:59:34.856577586Z INFO "Initialized 1 tools."
2025-09-08T03:59:34.856641568Z INFO "Initialized 2 toolsets."
2025-09-08T03:59:34.86133344Z INFO "Server ready to serve!"
2025-09-08T03:59:34.861366205Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui"
Нажмите на URL-адрес пользовательского интерфейса и убедитесь, что в конце URL-адреса есть /ui . Отобразится интерфейс, как показано ниже:
Нажмите на опцию «Инструменты» слева, чтобы просмотреть настроенные инструменты. В нашем случае это должен быть только один, то есть search_release_notes_bq , как показано ниже:
Просто нажмите на кнопку «Инструменты» ( search_release_notes_bq ), и откроется страница для тестирования инструмента. Поскольку параметры не требуются, вы можете просто нажать кнопку «Запустить инструмент», чтобы увидеть результат. Пример запуска показан ниже:
В MCP Toolkit for Databases также описан Python-способ проверки и тестирования инструментов, который описан здесь . Мы пропустим это и перейдём сразу к Agent Development Kit (ADK) в следующем разделе, где мы рассмотрим использование этих инструментов.
9. Написание нашего агента с помощью Agent Development Kit (ADK)
Установить комплект разработки агентов (ADK)
Откройте новую вкладку терминала в Cloud Shell и создайте папку с именем my-agents как показано ниже. Перейдите в папку my-agents .
mkdir my-agents
cd my-agents
Теперь давайте создадим виртуальную среду Python с помощью venv следующим образом:
python -m venv .venv
Активируйте виртуальную среду следующим образом:
source .venv/bin/activate
Установите пакеты ADK и MCP Toolbox for Databases вместе с зависимостью langchain следующим образом:
pip install google-adk toolbox-core
Теперь вы сможете вызвать утилиту adk следующим образом.
adk
Он покажет вам список команд.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Создание нашего первого приложения-агента
Теперь мы собираемся использовать adk для создания каркаса для приложения Google Cloud Release Notes Agent Application с помощью команды adk create с именем приложения ** (gcp-releasenotes-agent-app) **, как указано ниже.
adk create gcp-releasenotes-agent-app
Следуйте инструкциям и выберите следующее:
- Модель Gemini для выбора модели корневого агента.
- Выберите Vertex AI для бэкэнда.
- Будут отображены идентификатор и регион вашего проекта Google по умолчанию. Выберите регион по умолчанию.
Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_GOOGLE_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in ../my-agents/gcp-releasenotes-agent-app:
- .env
- __init__.py
- agent.py
Обратите внимание на папку, в которой были созданы шаблон по умолчанию и необходимые файлы для Агента.
Первым идёт файл .env . Его содержимое показано ниже:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Значения указывают на то, что мы будем использовать Gemini через Vertex AI вместе с соответствующими значениями идентификатора и местоположения проекта Google Cloud.
Затем у нас есть файл __init__.py , который отмечает папку как модуль и содержит единственный оператор, который импортирует агента из файла agent.py .
from . import agent
Наконец, давайте взглянем на файл agent.py . Его содержимое показано ниже:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Это простейший агент, который можно написать с помощью ADK. Согласно документации ADK, агент — это самостоятельный исполнительный модуль, предназначенный для автономной работы и достижения определённых целей. Агенты могут выполнять задачи, взаимодействовать с пользователями, использовать внешние инструменты и координировать работу с другими агентами.
В частности, агент LLMAgent, обычно именуемый просто агентом, использует большие языковые модели (LLM) в качестве своего основного механизма для понимания естественного языка, рассуждений, планирования, генерации ответов и динамического принятия решений о дальнейших действиях или используемых инструментах, что делает его идеальным решением для гибких задач, ориентированных на язык. Узнайте больше об агентах LLM здесь .
На этом мы завершаем подготовку к созданию базового агента с помощью Agent Development Kit (ADK). Теперь нам нужно подключить агента к MCP Toolbox, чтобы он мог использовать этот инструмент для ответа на запросы пользователя (в данном случае это будут заметки о выпуске Google Cloud).
10. Подключение нашего агента к инструментам
Сейчас мы подключим этого агента к инструментам. В контексте ADK инструмент представляет собой определённую возможность, предоставляемую ИИ-агенту, позволяющую ему выполнять действия и взаимодействовать с миром, выходящие за рамки его основных возможностей по генерации текста и рассуждению.
В нашем случае мы собираемся оснастить нашего агента инструментами, которые мы настроили в MCP Toolbox for Databases.
Измените файл agent.py , добавив следующий код. Обратите внимание, что в коде используется порт по умолчанию 5000, но если вы используете другой порт, используйте его.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load all the tools
tools = toolbox.load_toolset('my_bq_toolset')
root_agent = Agent(
name="gcp_releasenotes_agent",
model="gemini-2.0-flash",
description=(
"Agent to answer questions about Google Cloud Release notes."
),
instruction=(
"You are a helpful agent who can answer user questions about the Google Cloud Release notes. Use the tools to answer the question"
),
tools=tools,
)
Теперь мы можем протестировать агента, который будет извлекать реальные данные из нашего набора данных BigQuery, настроенного с помощью MCP Toolbox for Databases.
Для этого выполните следующую последовательность:
В одном из терминалов Cloud Shell запустите MCP Toolbox for Databases. Возможно, он уже запущен локально на порту 5000, как мы тестировали ранее. Если нет, выполните следующую команду (из папки mcp-toolbox ), чтобы запустить сервер:
./toolbox --tools_file "tools.yaml"
В идеале вы должны увидеть вывод, подтверждающий, что сервер смог подключиться к нашим источникам данных и загрузил набор инструментов. Пример вывода приведён ниже:
./toolbox --tools-file "tools.yaml"
2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources."
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices."
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools."
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets."
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!"
После успешного запуска сервера MCP запустите агента в другом терминале с помощью команды adk run (из папки my-agents ), показанной ниже. Также можно использовать команду adk web .
$ adk run gcp-releasenotes-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 gcp_releasenotes_agent, type exit to exit.
[user]: get me the google cloud release notes
[gcp_releasenotes_agent]: Here are the Google Cloud Release Notes.
Google SecOps SOAR: Release 6.3.49 is being rolled out to the first phase of regions. This release contains internal and customer bug fixes. Published: 2025-06-14
Compute Engine: Dynamic NICs let you add or remove network interfaces to or from an instance without having to restart or recreate the instance. You can also use Dynamic NICs when you need more network interfaces. The maximum number of vNICs for most machine types in Google Cloud is 10; however, you can configure up to 16 total interfaces by using Dynamic NICs. Published: 2025-06-13
Compute Engine: General purpose C4D machine types, powered by the fifth generation AMD EPYC processors (Turin) and Google Titanium, are generally available. Published: 2025-06-13
Google Agentspace: Google Agentspace Enterprise: App-level feature management. As an Agentspace administrator, you can choose to turn the following features on or off for your end users in the web app: Agents gallery, Prompt gallery, No-code agent, NotebookLM Enterprise. Published: 2025-06-13
Cloud Load Balancing: Cloud Load Balancing supports load balancing to multi-NIC instances that use Dynamic NICs. This capability is in Preview. Published: 2025-06-13
Virtual Private Cloud: Dynamic Network Interfaces (NICs) are available in Preview. Dynamic NICs let you update an instance to add or remove network interfaces without having to restart or recreate the instance. Published: 2025-06-13
Security Command Center: The following Event Threat Detection detectors for Vertex AI have been released to Preview:
- `Persistence: New Geography for AI Service`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Admin Activity`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Data Access`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Admin Activity`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Data Access`
- `Privilege Escalation: Anomalous Impersonation of Service Account for AI Admin Activity`
- `Persistence: New AI API Method`
......
......
Обратите внимание, что агент использует инструмент, который мы настроили в MCP Toolbox для баз данных ( search_release_notes_bq ), и извлекает данные из набора данных BigQuery и соответствующим образом форматирует ответ.
11. Поздравления
Поздравляем, вы успешно настроили MCP Toolbox для баз данных и настроили набор данных BigQuery для доступа из клиентов MCP.