1. Введение
В этой лабораторной работе вы создадите агента с помощью Agent Development Kit (ADK) , который использует MCP Toolbox for Databases .
В ходе выполнения лабораторной работы вы будете применять следующий пошаговый подход:
- Подготовьте базу данных Cloud SQL для PostgreSQL, в которой будут храниться база данных отелей и образцы данных.
- Настройте MCP Toolbox for Databases, который обеспечивает доступ к данным.
- Спроектируйте и разработайте агента с помощью Agent Development Kit (ADK), который будет использовать MCP Toolbox для ответа на запросы пользователя.
- Изучите варианты тестирования Agent и MCP Toolbox for Databases локально и в Google Cloud с помощью сервиса Cloud Run.
Что ты будешь делать?
- Разработайте, создайте и разверните агента, который будет отвечать на запросы пользователей о гостиницах в определенном месте или искать гостиницы по названию.
Чему вы научитесь
- Подготовка и заполнение базы данных Cloud SQL для PostgreSQL образцами данных.
- Настройте MCP Toolbox for Databases для экземпляра базы данных Cloud SQL for PostgreSQL.
- Спроектируйте и разработайте агента с использованием Agent Development Kit (ADK) для ответа на запросы пользователей.
- Протестируйте Agent и MCP Toolbox для баз данных в локальной среде.
- (Необязательно) Разверните Agent и 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 для PostgreSQL для хранения данных о наших отелях. Cloud SQL для 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, такую как ИМЯ, ВЕРСИЯ_БАЗЫ_ДАННЫХ, РАСПОЛОЖЕНИЕ и т. д.
4. Подготовьте базу данных отелей
Теперь нашей задачей будет создание образца данных для нашего гостиничного агента.
Откройте страницу Cloud SQL в консоли Cloud. Вы увидите готовый и созданный hoteldb-instance . Щёлкните по имени экземпляра ( hoteldb-instance ), как показано ниже:
В левом меню Cloud SQL выберите пункт меню Cloud SQL Studio , как показано ниже:
Вам будет предложено войти в Cloud SQL Studio, через которую мы будем выполнять несколько SQL-команд. Выберите postgres для параметра «База данных», а для параметров «Пользователь» и «Пароль» используйте значение postgres . Нажмите кнопку AUTHENTICATE .
Сначала создадим таблицу отелей по схеме, приведённой ниже. В одной из панелей редактора 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
);
Теперь заполним таблицу отелей образцами данных. Выполните следующий 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');
Давайте проверим данные, выполнив SELECT SQL, как показано ниже:
SELECT * FROM hotels;
Вы должны увидеть ряд записей в таблице отелей, как показано ниже:
Мы завершили настройку экземпляра Cloud SQL и создали демонстрационные данные. В следующем разделе мы настроим MCP Toolbox for Databases.
5. Настройка MCP Toolbox для баз данных
MCP Toolbox for Databases — это MCP-сервер с открытым исходным кодом для баз данных. Он разработан с учётом требований корпоративного уровня и качества для производства. Он позволяет разрабатывать инструменты проще, быстрее и безопаснее, решая такие сложные задачи, как организация пула соединений, аутентификация и многое другое.
Toolbox помогает создавать инструменты Gen AI, которые позволят вашим агентам получать доступ к данным в вашей базе данных. Toolbox предоставляет:
- Упрощенная разработка: интегрируйте инструменты в свой агент менее чем в 10 строк кода, повторно используйте инструменты между несколькими агентами или фреймворками и с легкостью развертывайте новые версии инструментов.
- Лучшая производительность: лучшие практики, такие как пул соединений, аутентификация и многое другое.
- Повышенная безопасность: интегрированная аутентификация для более безопасного доступа к вашим данным
- Сквозное наблюдение: готовые метрики и трассировка со встроенной поддержкой OpenTelemetry.
Toolbox располагается между фреймворком оркестровки вашего приложения и базой данных, предоставляя плоскость управления для изменения, распространения и вызова инструментов. Он упрощает управление инструментами, предоставляя централизованное хранилище для их хранения и обновления, позволяя агентам и приложениям совместно использовать инструменты и обновлять их без необходимости повторного развертывания приложения.
Вы видите, что одной из баз данных, поддерживаемых MCP Toolbox for Databases, является Cloud SQL, и мы подготовили ее в предыдущем разделе.
Установка набора инструментов
Откройте Cloud Shell Terminal и создайте папку с именем 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
Теперь у нас есть готовая к использованию двоичная версия инструментария. Следующий шаг — настроить инструментарий с использованием наших источников данных и других конфигураций.
Настройка 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как карту в разделе источников файла tools.yaml. Как правило, конфигурация источника содержит всю информацию, необходимую для подключения к базе данных и взаимодействия с ней. В нашем случае мы настроили один источник, указывающий на наш экземпляр Cloud SQL для PostgreSQL с учётными данными. Подробнее см. в справочнике по источникам . -
Toolsопределяют действия, которые может выполнять агент, например, чтение и запись в источник. Инструмент представляет собой действие, которое может выполнять ваш агент, например, выполнение SQL-оператора. Вы можете определитьToolsкак карту в разделе инструментов файла tools.yaml. Как правило, инструменту требуется источник для работы. В нашем случае мы определяем два инструмента:search-hotels-by-nameиsearch-hotels-by-location, а также указываем источник, с которым он работает, а также SQL-запрос и параметры. Подробнее см. в справочнике по инструментам . - Наконец, у нас есть
Toolset, позволяющий определять группы инструментов, которые вы хотите загружать вместе. Это может быть полезно для определения различных групп в зависимости от агента или приложения. В нашем случае у нас есть один набор инструментовmy_first_toolset, содержащий два определенных нами инструмента.
Запустите MCP Toolbox для сервера баз данных
Выполните следующую команду (из папки mcp-toolbox ), чтобы запустить сервер:
./toolbox --tools-file "tools.yaml"
В идеале вы должны увидеть вывод, подтверждающий, что сервер смог подключиться к нашим источникам данных и загрузил набор инструментов. Пример вывода приведён ниже:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z 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-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 for Databases
Toolbox предоставляет визуальный интерфейс ( Toolbox UI ) для непосредственного взаимодействия с инструментами путем изменения параметров, управления заголовками и выполнения вызовов — все это в простом веб-интерфейсе.
Если вы хотите это проверить, вы можете запустить предыдущую команду, которую мы использовали для запуска Toolbox Server, с опцией --ui .
Для этого завершите работу предыдущего экземпляра MCP Toolbox for Databases Server, который, возможно, был запущен, и введите следующую команду:
./toolbox --tools-file "tools.yaml" --ui
В идеале вы должны увидеть сообщение о том, что сервер смог подключиться к нашим источникам данных и загрузил набор инструментов. Пример сообщения приведён ниже. Обратите внимание, что в нём упоминается, что пользовательский интерфейс Toolbox запущен и работает.
2025-09-08T02:44:11.561572538Z INFO "Initialized 1 sources."
2025-09-08T02:44:11.561966395Z INFO "Initialized 0 authServices."
2025-09-08T02:44:11.562060934Z INFO "Initialized 2 tools."
2025-09-08T02:44:11.562105678Z INFO "Initialized 2 toolsets."
2025-09-08T02:44:11.568209923Z INFO "Server ready to serve!"
2025-09-08T02:44:11.568259411Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui"
Нажмите на URL-адрес пользовательского интерфейса и убедитесь, что в конце URL-адреса есть /ui . Отобразится интерфейс, как показано ниже:
Нажмите на опцию «Инструменты» слева, чтобы просмотреть настроенные инструменты. В нашем случае их должно быть два, а именно: search-hotels-by-name и search-hotels-by-location , как показано ниже:
Просто нажмите на один из инструментов ( search-hotels-by-location ), и откроется страница, на которой вы сможете протестировать инструмент, указав необходимые значения параметров, а затем нажмите « Запустить инструмент», чтобы увидеть результат. Пример запуска показан ниже:
В MCP Toolkit for Databases также описан Python-способ проверки и тестирования инструментов, который описан здесь . Мы пропустим это и перейдём сразу к Agent Development Kit (ADK) в следующем разделе, где мы рассмотрим использование этих инструментов.
6. Написание нашего агента с помощью 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:
--version Show the version and exit.
--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 для создания каркаса для нашего приложения 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
Обратите внимание на папку, в которой были созданы шаблон по умолчанию и необходимые файлы для Агента.
Первым идёт файл .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, обычно именуемый просто агентом, использует большие языковые модели (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 , чтобы завершить диалог.
7. Подключение нашего агента к инструментам
Теперь, когда мы знаем, как написать агента и протестировать его локально, мы подключим его к инструментам. В контексте 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 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"
В идеале вы должны увидеть вывод, подтверждающий, что сервер смог подключиться к нашим источникам данных и загрузил набор инструментов. Пример вывода приведён ниже:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
После успешного запуска сервера MCP запустите агента в другом терминале, как мы это делали ранее, с помощью команды adk run (из папки my-agents ), показанной ниже. Также можно использовать команду adk web .
$ adk run hotel-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 hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
Обратите внимание, что теперь агент использует два инструмента, которые мы настроили в MCP Toolbox for Databases ( search-hotels-by-name и search-hotels-by-location ), и предоставляет нам правильные параметры. После этого он может без проблем извлечь данные из базы данных экземпляра PostgreSQL и соответствующим образом отформатировать ответ.
На этом завершается локальная разработка и тестирование нашего гостиничного агента, который мы создали с помощью Agent Development Kit (ADK) и который работал на основе инструментов, которые мы настроили в MCP Toolbox for Databases.
8. (Необязательно) Развертывание MCP Toolbox для баз данных и агента в облаке
В предыдущем разделе мы использовали терминал 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 Server с настроенным файлом 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")
Протестируйте приложение Agent с помощью 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-адреса службы, к которому вы затем сможете получить доступ в браузере, чтобы просмотреть то же веб-приложение, которое позволило вам общаться с агентом отеля, как мы видели ранее при локальной настройке.
9. Уборка
Чтобы избежать списания средств с вашего аккаунта 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
10. Поздравления
Поздравляем, вы успешно создали агента с помощью Agent Development Kit (ADK), который использует MCP Toolbox for Databases.