1. Введение
В этом практическом занятии вы создадите агента, используя комплект разработки агентов (ADK) , который задействует MCP Toolbox for Databases .
В ходе выполнения практического задания вы будете использовать следующий пошаговый подход:
- Создайте базу данных Cloud SQL для PostgreSQL, которая будет содержать базу данных отелей и примеры данных.
- Настройте MCP Toolbox для баз данных, который обеспечит доступ к данным.
- Разработайте и создайте агента с использованием комплекта разработки агентов (ADK), который будет использовать MCP Toolbox для ответа на запросы пользователя.
- Изучите возможности тестирования Agent и MCP Toolbox for Databases локально и в Google Cloud с помощью сервиса Cloud Run.
Что вы будете делать
- Разработайте, создайте и разверните агента, который будет отвечать на запросы пользователей о гостиницах в определенном регионе или осуществлять поиск гостиниц по названию.
Что вы узнаете
- Подготовка и заполнение базы данных Cloud SQL для PostgreSQL тестовыми данными.
- Настройка MCP Toolbox для баз данных для экземпляра базы данных Cloud SQL for PostgreSQL.
- Разработайте и создайте агента с использованием комплекта разработки агентов (ADK) для ответа на запросы пользователей.
- Протестируйте агент и MCP Toolbox для баз данных в локальной среде.
- (При желании) Разверните агент и MCP Toolbox для баз данных в Google Cloud.
Что вам понадобится
- Веб-браузер Chrome
- Аккаунт Gmail
- Облачный проект с включенной функцией выставления счетов.
Этот практический урок, предназначенный для разработчиков всех уровней (включая начинающих), использует Python в качестве примера приложения. Однако знание 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>
- Включите необходимые API с помощью команды, указанной ниже. Это может занять несколько минут, поэтому, пожалуйста, наберитесь терпения.
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
После успешного выполнения команды вы должны увидеть сообщение, похожее на показанное ниже:
Operation "operations/..." finished successfully.
Альтернативой команде gcloud является поиск каждого продукта в консоли или использование этой ссылки .
Если какой-либо API отсутствует, вы всегда можете включить его в процессе реализации.
Для получения информации о командах gcloud и их использовании обратитесь к документации .
3. Создайте экземпляр Cloud SQL.
Для хранения данных о наших отелях мы будем использовать экземпляр Google Cloud SQL for PostgreSQL . Cloud SQL for PostgreSQL — это полностью управляемый сервис баз данных, который помогает настраивать, поддерживать, управлять и администрировать ваши реляционные базы данных PostgreSQL на платформе Google Cloud Platform.
Для создания экземпляра выполните следующую команду в Cloud Shell:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Выполнение этой команды занимает примерно 3-5 минут. После успешного выполнения команды вы увидите сообщение о завершении работы, а также информацию о вашем экземпляре Cloud SQL, такую как NAME, DATABASE_VERSION, LOCATION и т. д.
4. Подготовьте базу данных отелей.
Теперь наша задача — создать несколько примеров данных для нашего гостиничного агента.
Перейдите на страницу Cloud SQL в консоли Cloud. Вы должны увидеть, что hoteldb-instance готов и создан. Щелкните по имени экземпляра ( hoteldb-instance ), как показано ниже:
В левом меню Cloud SQL выберите пункт меню Cloud SQL Studio , как показано ниже:
Вам будет предложено войти в Cloud SQL Studio, через которую мы выполним несколько SQL-команд. Выберите postgres в качестве параметра базы данных, а в полях «Пользователь» и «Пароль» укажите значение postgres . Нажмите кнопку AUTHENTICATE .
Для начала создадим таблицу hotel в соответствии со схемой, приведенной ниже. В одной из панелей редактора Cloud SQL Studio выполните следующий SQL-запрос:
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
);
Теперь давайте заполним таблицу hotels примерами данных. Выполните следующий SQL-запрос:
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');
Давайте проверим данные, выполнив SQL-запрос SELECT, как показано ниже:
SELECT * FROM hotels;
В таблице отелей вы должны увидеть несколько записей, как показано ниже:
Мы завершили процесс настройки экземпляра Cloud SQL и создали наши тестовые данные. В следующем разделе мы займемся настройкой MCP Toolbox для баз данных.
5. Настройка MCP Toolbox для баз данных.
MCP Toolbox for Databases — это MCP-сервер с открытым исходным кодом для работы с базами данных. Он разработан с учетом требований корпоративного и производственного уровня. Он позволяет разрабатывать инструменты проще, быстрее и безопаснее, обрабатывая такие сложные процессы, как пулы соединений, аутентификация и многое другое.
Toolbox помогает создавать инструменты Gen AI, позволяющие вашим агентам получать доступ к данным в вашей базе данных. Toolbox предоставляет:
- Упрощенная разработка: интегрируйте инструменты в свой агент менее чем за 10 строк кода, используйте инструменты повторно в нескольких агентах или фреймворках и упростите развертывание новых версий инструментов.
- Повышение производительности: лучшие практики, такие как объединение соединений, аутентификация и многое другое.
- Повышенная безопасность: интегрированная аутентификация для более безопасного доступа к вашим данным.
- Сквозная мониторинговая возможность: готовые метрики и трассировка со встроенной поддержкой OpenTelemetry.
Toolbox выступает посредником между системой оркестрации вашего приложения и базой данных, предоставляя плоскость управления, используемую для изменения, распространения или вызова инструментов. Он упрощает управление инструментами, предоставляя централизованное место для хранения и обновления инструментов, позволяя обмениваться инструментами между агентами и приложениями и обновлять эти инструменты без необходимости повторного развертывания приложения.
Как видите, одной из баз данных, поддерживаемых MCP Toolbox for Databases, является Cloud SQL, и мы настроили её в предыдущем разделе.
Установка панели инструментов
Откройте терминал Cloud Shell и создайте папку с именем mcp-toolbox .
mkdir mcp-toolbox
Перейдите в папку mcp-toolbox с помощью команды, показанной ниже:
cd mcp-toolbox
Установите бинарную версию MCP Toolbox for Databases с помощью приведенного ниже скрипта. Приведенная ниже команда предназначена для Linux, но если вы используете Mac или Windows, убедитесь, что загружаете правильный бинарный файл. Проверьте страницу релизов для вашей операционной системы и архитектуры и загрузите правильный бинарный файл.
export VERSION=0.23.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Теперь у нас есть готовая к использованию бинарная версия инструментария. Давайте убедимся, что мы правильно настроили бинарный файл инструментария и он показывает правильную версию.
Для определения версии панели инструментов введите следующую команду:
./toolbox -v
В результате должно появиться сообщение, аналогичное следующему:
toolbox version 0.23.0+binary.linux.amd64.466aef0
Следующий шаг — настройка панели инструментов с учетом наших источников данных и других параметров.
Настройка файла tools.yaml
Основной способ настройки Toolbox — через файл tools.yaml . Создайте файл с именем tools.yaml в той же папке, например, mcp-toolbox , содержимое которого показано ниже.
Вы можете использовать редактор nano, доступный в Cloud Shell. Команда nano выглядит следующим образом: " nano tools.yaml ".
Не забудьте заменить значение YOUR_PROJECT_ID на идентификатор вашего проекта в Google Cloud.
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
Давайте кратко разберем содержимое файла:
-
Sourcesпредставляют собой различные источники данных, с которыми может взаимодействовать инструмент. Источник — это источник данных, с которым может взаимодействовать инструмент. Вы можете определитьSourcesв виде карты в разделе sources файла tools.yaml. Как правило, конфигурация источника содержит всю информацию, необходимую для подключения к базе данных и взаимодействия с ней. В нашем случае мы настроили один источник, указывающий на наш экземпляр Cloud SQL for PostgreSQL с учетными данными. Для получения дополнительной информации обратитесь к справочнику по источникам . -
Toolsопределяют действия, которые может выполнять агент, например, чтение и запись в источник. Инструмент представляет собой действие, которое может выполнить ваш агент, например, выполнение SQL-запроса. Вы можете определитьToolsв виде карты в разделе tools вашего файла tools.yaml. Как правило, инструменту требуется источник, с которым он будет взаимодействовать. В нашем случае мы определяем два инструмента:search-hotels-by-nameиsearch-hotels-by-locationи указываем источник, с которым он взаимодействует, а также SQL-запрос и параметры. Для получения дополнительной информации обратитесь к справочнику по инструментам . - Наконец, у нас есть
Toolset), который позволяет определять группы инструментов, которые вы хотите загружать вместе. Это может быть полезно для определения различных групп в зависимости от агента или приложения. В нашем случае у нас есть один набор инструментов под названиемmy_first_toolset, который содержит два определенных нами инструмента.
Сохраните файл tools.yaml в редакторе nano, выполнив следующие шаги:
- Нажмите
Ctrl + O(команда "Выписать на бумагу"). - Вам будет предложено подтвердить «Имя файла для записи». Просто нажмите
Enter. - Теперь нажмите
Ctrl + X, чтобы выйти.
Запустите MCP Toolbox для сервера баз данных.
Для запуска сервера выполните следующую команду (из папки mcp-toolbox ):
./toolbox --tools-file "tools.yaml"
В идеале вы должны увидеть сообщение о том, что сервер смог подключиться к нашим источникам данных и загрузил набор инструментов. Пример выходных данных приведен ниже:
2025-12-17T04:02:19.18028278Z INFO "Initialized 1 sources: my-cloud-sql-source"
2025-12-17T04:02:19.1804012Z INFO "Initialized 0 authServices: "
2025-12-17T04:02:19.180466127Z INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2025-12-17T04:02:19.180520492Z INFO "Initialized 2 toolsets: my_first_toolset, default"
2025-12-17T04:02:19.180534152Z INFO "Initialized 0 prompts: "
2025-12-17T04:02:19.180554658Z INFO "Initialized 1 promptsets: default"
2025-12-17T04:02:19.18058529Z WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag to prevent DNS rebinding attacks"
2025-12-17T04:02:19.185746495Z 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-адреса в браузере добавьте следующее:
/api/toolset
Это должно отобразить инструменты, которые в данный момент настроены. Пример вывода показан ниже:
{
"serverVersion": "0.23.0+binary.linux.amd64.466aef0",
"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": []
}
}
}
Протестируйте инструменты через MCP Toolbox для пользовательского интерфейса баз данных.
Панель инструментов предоставляет визуальный интерфейс ( пользовательский интерфейс панели инструментов ) для непосредственного взаимодействия с инструментами путем изменения параметров, управления заголовками и выполнения вызовов — все это в рамках простого веб-интерфейса.
Если вы хотите это проверить, вы можете запустить предыдущую команду, которую мы использовали для запуска сервера Toolbox, с опцией --ui .
Для этого завершите работу предыдущего запущенного экземпляра MCP Toolbox for Databases Server и выполните следующую команду:
./toolbox --tools-file "tools.yaml" --ui
В идеале вы должны увидеть сообщение о том, что сервер смог подключиться к нашим источникам данных и загрузил набор инструментов и сами инструменты. Пример сообщения приведен ниже, и вы заметите, что в нем указано, что пользовательский интерфейс панели инструментов запущен и работает.
2025-12-17T04:03:56.582589201Z INFO "Initialized 1 sources: my-cloud-sql-source"
2025-12-17T04:03:56.582724914Z INFO "Initialized 0 authServices: "
2025-12-17T04:03:56.582772914Z INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2025-12-17T04:03:56.582803723Z INFO "Initialized 2 toolsets: default, my_first_toolset"
2025-12-17T04:03:56.582815576Z INFO "Initialized 0 prompts: "
2025-12-17T04:03:56.582832887Z INFO "Initialized 1 promptsets: default"
2025-12-17T04:03:56.582870495Z WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag to prevent DNS rebinding attacks"
2025-12-17T04:03:56.588485105Z INFO "Server ready to serve!"
2025-12-17T04:03:56.588520956Z INFO "Toolbox UI is up and running at: http://127.0.0.1:5000/ui"
Щелкните по URL-адресу пользовательского интерфейса и убедитесь, что у вас есть...
/ui
в конце URL-адреса (если вы запускаете это в Cloud Shell, перенаправление браузера приведет к тому, что /ui не будет отображаться в конце). Это отобразит пользовательский интерфейс, как показано ниже:
Чтобы просмотреть настроенные инструменты, нажмите на опцию «Инструменты» слева. В нашем случае их должно быть два: search-hotels-by-name и search-hotels-by-location », как показано ниже:
Просто нажмите на один из инструментов (например, search-hotels-by-location »), и откроется страница, где вы сможете протестировать инструмент, указав необходимые значения параметров, а затем нажать « Запустить инструмент» , чтобы увидеть результат. Пример запуска показан ниже:
В MCP Toolkit for Databases также описан способ проверки и тестирования инструментов с использованием Python, описание которого можно найти здесь .
Если мы вернемся к ранее представленной схеме (как показано ниже), то увидим, что мы завершили настройку базы данных и сервера MCP, и перед нами открываются два пути:
- Чтобы понять, как настроить сервер MCP в качестве терминала/IDE с поддержкой ИИ, перейдите к шагу 6. В нем будет описано, как интегрировать наш сервер MCP Toolbox в
Gemini CLI. - Чтобы понять, как использовать
Agent Development Kit (ADK) using Pythonдля написания собственных агентов, которые могут использовать MCP Server Toolbox в качестве инструмента для ответа на вопросы, связанные с набором данных, перейдите к шагам 7 и 8.
6. Интеграция MCP Toolbox в Gemini CLI
Gemini CLI — это агент искусственного интеллекта с открытым исходным кодом, который переносит возможности Gemini непосредственно в ваш терминал. Вы можете использовать его как для задач, связанных с программированием, так и для задач, не связанных с программированием. Он интегрирован с различными инструментами, а также поддерживает серверы MCP.
Поскольку у нас есть работающий сервер MCP, наша цель в этом разделе — настроить MCP Toolbox for Databases Server в Gemini CLI, а затем использовать Gemini CLI для взаимодействия с нашими данными.
Первым делом проверим, запущен ли у вас Toolbox в одном из терминалов Cloud Shell. Предполагая, что вы используете стандартный порт 5000 , интерфейс MCP Server доступен по следующему адресу: http://localhost:5000/mcp .
Откройте новое окно терминала и создайте папку с именем my-gemini-cli-project следующим образом. Также перейдите в папку my-gemini-cli-project .
mkdir my-gemini-cli-project
cd my-gemini-cli-project
Выполните следующую команду, чтобы добавить MCP-сервер в список MCP-серверов, настроенных в Gemini CLI.
gemini mcp add --scope="project" --transport="http" "MCPToolbox" "http://localhost:5000/mcp"
Проверить текущий список настроенных серверов MCP в Gemini CLI можно с помощью следующей команды:
gemini mcp list
В идеале вы должны увидеть настроенный нами MCPToolbox с зеленой галочкой рядом, что означает, что Gemini CLI удалось подключиться к серверу MCP.
Configured MCP servers:
✓ MCPToolbox: http://localhost:5000/mcp (http) - Connected
В том же терминале убедитесь, что вы находитесь в папке my-gemini-cli-project . Запустите Gemini CLI с помощью команды gemini .
Это откроет интерфейс командной строки Gemini, и вы увидите, что теперь настроен 1 сервер MCP. Вы можете использовать команду /mcp list , чтобы увидеть список серверов MCP и инструментов. Например, вот пример вывода:
Теперь вы можете задать любой из вопросов:
-
Which hotels are there in Basel? -
Tell me more about the Hyatt Regency?
Вы увидите, что в результате выполнения указанных выше запросов Gemini CLI выберет соответствующий инструмент из MCPToolbox. Он запросит у вас разрешение на выполнение инструмента. Предоставьте необходимые разрешения, и вы увидите, что результаты будут возвращены из базы данных.
7. Разработка нашего агента с использованием комплекта разработки агентов (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:
--version Show the version and exit.
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
conformance Conformance testing tools for ADK.
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.
eval_set Manage Eval Sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Создание нашего первого приложения для агентов.
Теперь мы воспользуемся adk для создания шаблона для нашего приложения Hotel Agent с помощью команды adk create указав имя приложения ** (hotel_agent_app) **, как показано ниже.
adk create hotel_agent_app
Выполните указанные шаги и выберите следующее:
- Модель Gemini для выбора модели для корневого агента.
- Выберите Vertex AI для бэкэнда.
- Отобразится ваш идентификатор проекта Google по умолчанию и регион. Выберите сам регион по умолчанию.
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
Обратите внимание на папку, в которой созданы шаблон по умолчанию и необходимые файлы для агента. Вы можете увидеть эти файлы с помощью команды ls -al в терминале в каталоге ` <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app .
Первым делом рассмотрим файл .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.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Это самый простой агент, который можно написать с помощью ADK. Согласно документации ADK, агент — это автономный исполнительный блок, предназначенный для автономной работы и достижения конкретных целей. Агенты могут выполнять задачи, взаимодействовать с пользователями, использовать внешние инструменты и координировать свои действия с другими агентами.
В частности, LLMAgent, обычно называемый просто Agent, использует большие языковые модели (LLM) в качестве основного механизма для понимания естественного языка, рассуждений, планирования, генерации ответов и динамического принятия решений о дальнейших действиях или используемых инструментах, что делает их идеальными для гибких, ориентированных на язык задач. Подробнее о LLM-агентах можно узнать здесь .
Давайте изменим код файла agent.py следующим образом:
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 локально.
В существующем окне терминала выполните следующую команду. Убедитесь, что вы находитесь в родительской папке (my-agents) содержащей папку hotel_agent_app .
adk web
Пример выполнения показан ниже:
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)
Нажмите на последнюю ссылку, и откроется веб-консоль для тестирования агента. В браузере должно отобразиться следующее, как показано ниже:
Обратите внимание, что в верхнем левом углу отображается приложение hotel_agent_app . Теперь вы можете начать общение с агентом. Задайте несколько вопросов о городах. Пример диалога показан ниже:
Вы можете завершить запущенный процесс в терминале Cloud Shell (Ctrl-C).
Альтернативный способ тестирования агента — использование команды adk run , приведенной ниже, из папки my-agents .
adk run hotel_agent_app
Попробуйте выполнить команду, и вы сможете общаться с агентом через командную строку (терминал). Введите exit , чтобы закрыть диалог.
8. Подключение нашего агента к инструментам
Теперь, когда мы знаем, как написать агента и протестировать его локально, мы собираемся подключить этого агента к инструментам. В контексте ADK инструмент представляет собой определенную возможность, предоставляемую агенту ИИ, позволяющую ему выполнять действия и взаимодействовать с миром за пределами его основных способностей к генерации текста и рассуждениям.
В нашем случае мы собираемся оснастить нашего агента инструментами, которые мы настроили в панели инструментов MCP для баз данных.
Измените файл agent.py , добавив следующий код. Обратите внимание, что в коде используется порт по умолчанию 5000, но если вы используете другой номер порта, пожалуйста, используйте его.
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,
)
Теперь мы можем протестировать агента, который будет получать реальные данные из нашей базы данных PostgreSQL, настроенной с помощью MCP Toolbox for Databases.
Для этого выполните следующие действия:
В одном из терминалов Cloud Shell запустите MCP Toolbox for Databases. Возможно, он уже запущен локально на порту 5000, как мы тестировали ранее. Если нет, выполните следующую команду (из папки mcp-toolbox ), чтобы запустить сервер:
./toolbox --tools_file "tools.yaml"
В идеале вы должны увидеть сообщение о том, что сервер смог подключиться к нашим источникам данных и загрузил набор инструментов и сами инструменты.
После успешного запуска сервера MCP в другом терминале запустите агент, как мы делали ранее, с помощью команды adk run (из папки my-agents ), показанной ниже. При желании вы также можете использовать adk web .
$ adk run hotel_agent_app/
...
Running agent hotel_agent, type exit to exit.
[user]: what can you do for me ?
[hotel_agent]: I can help you find hotels by location or by name.
[user]: I would like to search for hotels?
[hotel_agent]: Great! Do you want to search by location or by hotel name?
[user]: I'd like to search in Basel
[hotel_agent]: Here are some hotels in Basel:
* Holiday Inn Basel (Upper Midscale)
* Hyatt Regency Basel (Upper Upscale)
* Hilton Basel (Luxury)
[user]:
Обратите внимание, что агент теперь использует два инструмента, которые мы настроили в MCP Toolbox for Databases ( search-hotels-by-name и search-hotels-by-location ), и предоставляет нам правильные параметры. После этого он может беспрепятственно получать данные из базы данных экземпляра PostgreSQL и соответствующим образом форматировать ответ.
На этом завершается локальная разработка и тестирование нашего агента для отелей, который мы создали с использованием комплекта разработки агентов (ADK) и который работал на инструментах, настроенных нами в MCP Toolbox for Databases.
9. (Необязательно) Развертывание MCP Toolbox для баз данных и агента в Cloud Run
В предыдущем разделе мы использовали терминал Cloud Shell для запуска сервера MCP Toolbox и протестировали инструменты с помощью агента. Тестирование проводилось локально в среде Cloud Shell.
У вас есть возможность развернуть как сервер MCP Toolbox, так и агент в сервисах Google Cloud, которые смогут разместить эти приложения для нас.
Размещен сервер MCP Toolbox на платформе Cloud Run.
Для начала мы можем разместить сервер MCP Toolbox на платформе Cloud Run. Это даст нам общедоступную конечную точку, которую мы сможем интегрировать с любыми другими приложениями и/или приложениями агентов. Инструкции по размещению на Cloud Run приведены здесь . Теперь рассмотрим основные шаги.
Запустите новый терминал Cloud Shell или используйте существующий. Перейдите в папку mcp-toolbox , где находятся исполняемый файл toolbox и tools.yaml .
Выполните следующие команды (для каждой команды приведено пояснение):
Установите переменную PROJECT_ID так, чтобы она указывала на идентификатор вашего проекта в Google Cloud.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Далее убедитесь, что в проекте включены следующие сервисы Google Cloud.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Давайте создадим отдельную учетную запись службы, которая будет выступать в качестве идентификатора для службы Toolbox, которую мы будем развертывать в Google Cloud Run. Мы также убедимся, что эта учетная запись службы имеет необходимые роли, то есть возможность доступа к Secret Manager и взаимодействия с Cloud SQL.
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
Мы загрузим файл tools.yaml в качестве секретного файла, и поскольку нам нужно установить Toolbox в Cloud Run, мы будем использовать последний образ контейнера для Toolbox и зададим его в переменной IMAGE.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
Последний шаг в знакомой команде развертывания в 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
Это запустит процесс развертывания сервера Toolbox с настроенным tools.yaml в Cloud Run. После успешного развертывания вы должны увидеть сообщение, похожее на следующее:
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
Теперь вы можете перейти по указанному выше Service URL в браузере. Должно отобразиться сообщение "Hello World", которое мы видели ранее. Кроме того, вы можете перейти по следующему URL-адресу, чтобы ознакомиться с доступными инструментами:
SERVICE URL/api/toolset
Вы также можете получить доступ к Cloud Run из консоли Google Cloud, и там вы увидите сервис Toolbox в списке сервисов Cloud Run.
Примечание: Если вы хотите по-прежнему запускать Hotel Agent локально и при этом подключаться к недавно развернутой службе Cloud Run, вам нужно всего лишь внести одно изменение в файл my-agents/hotel_agent_app/agent.py .
Вместо следующего:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Измените его на URL-адрес службы Cloud Run, как показано ниже:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
Протестируйте приложение агента, используя adk run или adk web , как мы видели ранее.
Развертывание приложения Hotel Agent в Cloud Run
Первый шаг — убедиться, что вы внесли изменения в файл my-agents/hotel_agent_app/agent.py как указано выше, чтобы указать URL-адрес службы Toolbox, работающей в Cloud Run, а не на локальном хосте.
В новом терминале Cloud Shell или в существующей сессии терминала убедитесь, что вы находитесь в правильной виртуальной среде Python, которую мы настроили ранее.
Для начала создадим файл requirements.txt в папке my-agents/hotel_agent_app , как показано ниже:
google-adk
toolbox-core
Перейдите в папку my-agents и сначала настроим следующие переменные среды:
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
Наконец, давайте развернем приложение-агент в Cloud Run с помощью команды adk deploy cloud_run, как показано ниже. Если вас попросят разрешить неаутентифицированные вызовы к службе, укажите пока значение "y".
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
Это запустит процесс развертывания приложения Hotel Agent в Cloud Run. Будут загружены исходные файлы, они будут упакованы в контейнер Docker, отправлены в реестр артефактов, а затем развернута служба в Cloud Run. Это может занять несколько минут, поэтому, пожалуйста, наберитесь терпения.
Вы должны увидеть сообщение, похожее на приведенное ниже:
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
После успешного развертывания вам будет предоставлено значение для URL-адреса службы, к которому вы сможете получить доступ в браузере, чтобы просмотреть то же веб-приложение, которое позволяло вам общаться с агентом отеля, как мы видели ранее при локальной настройке.
10. Уборка
Чтобы избежать постоянных списаний средств с вашего аккаунта Google Cloud, важно удалить ресурсы, созданные нами во время этого семинара. Мы удалим экземпляр Cloud SQL, а также, при необходимости, если вы развернули Toolbox и приложение Hotels в Cloud Run, то удалим и эти сервисы.
Убедитесь, что следующие переменные среды установлены правильно в соответствии с вашим проектом и регионом:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
Следующие две команды удаляют развернутые нами службы Cloud Run:
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
Следующая команда удаляет экземпляр Cloud SQL:
gcloud sql instances delete hoteldb-instance
11. Поздравляем!
Поздравляем, вы успешно создали агента с помощью комплекта разработки агентов (ADK), использующего MCP Toolbox для баз данных.