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

Создайте помощника-ИИ для агента спортивного магазина с помощью ADK, MCP Toolbox и AlloyDB

1. Введение

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

В этой лабораторной работе вы узнаете, как создать помощника на основе искусственного интеллекта для Sports Shop Agent . Это приложение нового поколения на основе искусственного интеллекта, работающее на базе ADK , MCP Toolbox и AlloyDB , поможет пользователям решать различные задачи, включая:

Поиск товаров с использованием естественного языка.
Поиск ближайших магазинов для покупки рекомендуемых товаров.
Размещение новых заказов.
Проверка существующих статусов заказов.
Обновление заказов с указанием предпочтительных способов доставки.

Чему вы научитесь

Подготовка и заполнение базы данных AlloyDB для PostgreSQL.
Настройка MCP Toolbox for Databases с экземпляром AlloyDB для PostgreSQL.
Проектирование и разработка ИИ-агента с использованием комплекта разработки агентов (ADK) для помощи в обработке запросов в спортивных магазинах.
Тестирование вашего агента и MCP Toolbox для баз данных в облачной среде.
Использование расширенных возможностей запросов AlloyDB для ответов интеллектуальных агентов.

Что вам понадобится

Для выполнения этой лабораторной работы вам понадобится:

Веб-браузер Chrome.
Учетная запись Gmail.
Проект Google Cloud с включенным биллингом.

Эта лабораторная работа предназначена для разработчиков всех уровней, включая новичков.

2. Прежде чем начать

В этом разделе вы узнаете, как выполнить первоначальную настройку проекта Google Cloud, прежде чем приступить к созданию помощника на основе ИИ Sports Shop Agent.

Создать проект

В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud.
Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .
Активируйте Cloud Shell, перейдя по этой ссылке . Вы можете переключаться между Cloud Shell Terminal (для выполнения облачных команд) и Editor (для создания проектов), нажимая соответствующую кнопку в Cloud Shell.

После подключения к Cloud Shell вы проверяете, что вы уже прошли аутентификацию и что проекту присвоен ваш идентификатор проекта, с помощью следующей команды:

gcloud auth list

Выполните следующую команду в Cloud Shell, чтобы подтвердить, что команда gcloud знает о вашем проекте.

gcloud config list project

Установите переменную PROJECT_ID, для этого используйте следующую команду:

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

Включите следующие API, выполнив следующие команды:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com

3. Создайте экземпляр AlloyDB

В этом разделе вы настроите кластер и экземпляр базы данных AlloyDB, а также необходимые сетевые настройки и разрешения для вашего AI Agent.

Сначала выполните следующую команду в терминале Cloud Shell, чтобы создать кластер AlloyDB:

gcloud alloydb clusters create alloydb-cluster \
    --password=alloydb\
    --network=default \
    --region=us-central1 \
    --database-version=POSTGRES_16

AlloyDB использует частные IP-подключения для безопасного и высокопроизводительного доступа. Вам необходимо выделить диапазон частных IP-адресов в вашем VPC, который Google будет использовать для пирингового подключения к сетевой инфраструктуре сервисов, управляемой Google. Выполните следующую команду:

gcloud compute addresses create peering-range-for-alloydb \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --description="Automatically allocated IP range for service networking" \
    --network=default

Затем создайте пиринговое соединение VPC Service Peering. Это позволит вашей сети Google Cloud Virtual Private Cloud (VPC) безопасно и конфиденциально взаимодействовать с управляемыми сервисами Google, включая AlloyDB. Выполните следующую команду:

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=peering-range-for-alloydb \
--network=default

Теперь создайте основной экземпляр в кластере AlloyDB. Это конечная точка базы данных, к которой будут подключаться ваши приложения. Выполните следующую команду, чтобы создать экземпляр AlloyDB:

gcloud alloydb instances create alloydb-inst \
     --instance-type=PRIMARY \
     --cpu-count=2 \
     --region=us-central1 \
     --cluster=alloydb-cluster \
     --availability-type=ZONAL \
     --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

Примечание: Создание экземпляра может занять около 10 минут . Пожалуйста, дождитесь завершения этой операции, прежде чем продолжить.

Включить интеграцию Vertex AI

Чтобы разрешить вашему экземпляру AlloyDB выполнять векторные поисковые запросы (которые необходимы для таких функций ИИ, как семантический поиск) и вызывать модели, развернутые в Vertex AI, вам необходимо предоставить разрешения Vertex AI агенту службы AlloyDB.

Сначала получите номер вашего проекта Google Cloud, так как он необходим для привязки IAM.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Затем предоставьте разрешение Vertex AI сервисному агенту AlloyDB:

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

Включить публичный IP

В рамках подготовки к следующим шагам мы включим возможность подключения по публичному IP-адресу в нашем экземпляре AlloyDB.

В консоли перейдите в поле поиска в верхней центральной части экрана и введите «alloydb», затем отредактируйте и перейдите в раздел «Подключение по публичному IP». Установите флажок «Включить публичный IP» и введите IP-адрес вашей машины Cloud Shell.

Чтобы узнать IP-адрес вашей машины Cloud Shell, перейдите в терминал Cloud Shell и введите команду ifconfig | grep -A 1 eth0. В результате замените последние две цифры на 0.0 с размером маски «/16». Например, это будет выглядеть так: «XX.XX.0.0/16», где XX — цифры.

Вставьте этот IP-адрес в текстовое поле «Сети» раздела «Разрешенные внешние сети» на странице редактирования экземпляра.

Примечание: операция обновления может занять до 3 минут.

4. Загрузите базу данных

Создать базу данных магазина

Теперь пришло время создать базу данных и загрузить начальные данные для вашего спортивного магазина.

Чтобы psql мог подключиться к вашему частному экземпляру AlloyDB из Cloud Shell, используйте прокси-сервер аутентификации AlloyDB. Эта утилита обеспечивает безопасное туннелирование вашего соединения с базой данных. (См. раздел «Прокси-сервер аутентификации AlloyDB» ).

Загрузите AlloyDB Auth Proxy с помощью следующей команды:

wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.3/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

Сделайте его исполняемым:

chmod +x alloydb-auth-proxy

Выполните эту команду в первом окне терминала Cloud Shell. Прокси-сервер будет работать в фоновом режиме и перенаправлять соединения.

./alloydb-auth-proxy "projects/$PROJECT_ID/locations/us-central1/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip

Важно: оставьте это окно терминала открытым и запустите прокси-сервер. Не закрывайте его.

Откройте новое окно терминала в Cloud Shell (щелкните значок + рядом с вкладкой «Терминал Cloud Shell» в верхней части).

Подключитесь к экземпляру AlloyDB с помощью psql:

psql -h 127.0.0.1 -U postgres

Примечание: при появлении запроса введите пароль, который вы установили для пользователя postgres при создании кластера (если вы следуете непосредственно документации, пароль — alloydb ).

И создадим базу данных магазина для нашего приложения (выполняйте команды одну за другой):

CREATE DATABASE store;
\c store
exit

Исходный код

Теперь клонируйте репозиторий исходного кода codelab. Перед клонированием убедитесь, что вы находитесь в домашнем каталоге или в подходящем месте, и выполните следующую команду:

git clone https://github.com/mtoscano84/sports-agent-adk-mcp-alloydb.git

Заполнить базу данных

Перейдите в папку data клонированного проекта, чтобы получить доступ к файлу дампа базы данных.

cd sports-agent-adk-mcp-alloydb/data

Затем импортируйте образец набора данных в базу данных вашего store , используя файл store_backup.sql из репозитория.

psql -h 127.0.0.1 -U postgres -d store -f store_backup.sql

Примечание: во время импорта вы можете увидеть несколько предупреждений и сообщений об ошибках, которые можно игнорировать в рамках этой лабораторной работы. Они часто связаны с разрешениями или объектами, которые уже существуют, если дамп содержит полную схему. Вы увидите несколько предупреждений и сообщений об ошибках, которые можно игнорировать.

5. Настройка службы авторизации

В этом разделе вы настроите службу авторизации для вашего приложения. Эта служба критически важна для обеспечения безопасности доступа и защиты от уязвимостей, связанных с мгновенными инъекциями, в вашем ИИ-агенте.

Сначала вы добавите пользователя-пример в таблицу users в базе данных вашего store . Этот пользователь будет использоваться для аутентификации в вашем приложении.

Перейдите в консоль и перейдите в AlloyDB, выберите основной экземпляр, а затем AlloyDB Studio:

При появлении запроса войдите в AlloyDB Studio, используя учетные данные , созданные при настройке кластера:

Имя пользователя: "postgres"
База данных: "store"
Пароль: "alloydb"

В редакторе SQL выполните оператор INSERT, чтобы добавить пользователя в базу данных. Измените имя, фамилию и адрес электронной почты.

Важный:

Сохраните МЕСТОПОЛОЖЕНИЕ, как в примере.
Используйте тот же адрес электронной почты, который вы использовали для регистрации в Google Cloud Console.

INSERT INTO users (user_id, first_name, last_name, Address, city, postal_code, location, email)
VALUES (10,'John', 'Doe', 'Carrer Muntaner 39', 'Barcelona', '08019', '0101000020E61000008AAE0B3F38B144401FBB0B9414780140', 'john.doe@example.com');

Далее вам необходимо настроить экран согласия OAuth для вашего проекта. Этот экран отображается пользователям, когда ваше приложение запрашивает доступ к их аккаунту Google, и определяет бренд вашего приложения.

В консоли перейдите в раздел «API и службы», «Согласие Google OAuth»:

Для создания бренда вашего приложения предоставьте следующую информацию:

Название приложения: «ИИ-агент спортивных покупок»
Электронная почта службы поддержки пользователей: «YOUR_EMAIL»
Аудитория: «Внешняя»
Контактная информация: «ВАШ_ЭМЕЙЛ»

Теперь вам нужно создать идентификатор клиента OAuth, который ваше внешнее приложение будет использовать для проверки личности пользователя в Google.

Для начала убедитесь, что у вас есть номер проекта Google Cloud. Это необходимо для корректной настройки URI перенаправления. Выполните следующую команду в терминале Cloud Shell:

Если переменная PROJECT_ID не установлена в этом окне терминала Cloud Shell, выполните:

export PROJECT_ID=[YOUR_PROJECT_ID]

Затем получите PROJECT_NUMBER с помощью следующей команды:

gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Затем перейдите в раздел «API и службы» -> «Учетные данные» -> «Создать учетные данные» -> «Идентификатор клиента OAuth».

Для создания учетных данных используйте следующую информацию:

Тип приложения: «Веб-приложение»
Название: «Приложение для спортивного шоппинг-агента на базе искусственного интеллекта»

Разрешенные источники JavaScript:

URL1: https://finn-frontend-[НОМЕР_ВАШЕГО_ПРОЕКТА].us-central1.run.app

Разрешенные URI перенаправления:

URL1: https://finn-frontend-[НОМЕР_ВАШЕГО_ПРОЕКТА].us-central1.run.app

Примечание: URL-адрес https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app — ожидаемый URL-адрес развёртывания вашего фронтенд-приложения, который будет настроен далее в этой практической работе. Замените [YOUR_PROJECT_NUMBER] на фактически скопированный вами номер.

Важно: после создания во всплывающем окне отобразится ваш идентификатор клиента OAuth , а иногда и секретный ключ клиента. Сохраните свой идентификатор клиента OAuth в надёжном месте , так как он понадобится вам позже при настройке вашего интерфейса.

6. MCP ToolBox для настройки баз данных

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

Поскольку одной из баз данных, поддерживаемых MCP Toolbox for Databases, является AlloyDB, и мы уже подготовили ее в предыдущем разделе, давайте продолжим и настроим Toolbox.

Сначала вам необходимо локально настроить сервер MCP Toolbox в среде Cloud Shell, чтобы проверить его работоспособность.

В терминале Cloud Shell перейдите в папку toolbox , расположенную в репозитории клонированного проекта:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Выполните следующие команды, чтобы загрузить двоичный файл Toolbox и предоставить ему разрешения на выполнение:

# see releases page for other versions
export VERSION=0.7.0

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox

chmod +x toolbox

Примечание: здесь указана версия 0.7.0. Для производственных сред всегда проверяйте и используйте последнюю стабильную версию со страницы релизов Toolbox .

Перейдите в редактор Cloud Shell (переключиться можно из терминала, щелкнув значок редактора).

В том же каталоге sports-agent-adk-mcp-alloydb/src/toolbox вы найдёте файл tools.yaml . Откройте его и обновите поля, указав идентификатор клиента OAuth и идентификатор проекта Google Cloud, полученные на предыдущих этапах.

Давайте разберемся с tools.yaml

Источники представляют собой различные источники данных, с которыми может взаимодействовать инструмент. Источник представляет собой источник данных, с которым может взаимодействовать инструмент. Вы можете определить источники как карту в разделе источников файла tools.yaml. Как правило, конфигурация источника содержит всю информацию, необходимую для подключения к базе данных и взаимодействия с ней.

Инструменты определяют действия, которые может выполнять агент, например, чтение и запись в источник. Инструмент представляет собой действие, которое может выполнить ваш агент, например, выполнение SQL-оператора. Вы можете определить инструменты как карту в разделе инструментов файла tools.yaml. Как правило, для работы с инструментом требуется источник.

Более подробную информацию о настройке tools.yaml см. в этой документации .

Давайте запустим MCP Toolbox for Databases Server.

Выполните следующую команду (из папки mcp-toolbox), чтобы запустить сервер:

./toolbox --tools-file "tools.yaml"

Теперь, если вы откроете сервер в режиме веб-просмотра в облаке, вы сможете увидеть работающий сервер Toolbox со всеми инструментами нашего приложения.

Сервер MCP Toolbox по умолчанию работает на порту 5000. Давайте воспользуемся Cloud Shell для проверки.

Нажмите «Веб-просмотр» в Cloud Shell, как показано ниже:

Нажмите «Изменить порт» и установите порт 5000, как показано ниже, затем нажмите «Изменить и просмотреть».

Это должно дать следующий результат:

В MCP Toolkit for Databases описан Python SDK для проверки и тестирования инструментов, документация по которому доступна здесь . Мы пропустим это и перейдём сразу к Agent Development Kit (ADK) в следующем разделе, где мы рассмотрим использование этих инструментов.

Давайте развернем наш Toolbox в Cloud Run

Чтобы сделать ваш сервер Toolbox доступным как публичная конечная точка, интегрируемая с другими приложениями и вашим AI-агентом, разверните его в Cloud Run. Подробные инструкции по размещению Toolbox в Cloud Run приведены здесь .

Вернитесь в терминал Cloud Shell и перейдите в папку инструментов:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Убедитесь, что переменная среды PROJECT_ID соответствует идентификатору вашего проекта Google Cloud.

export PROJECT_ID=$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 и возможность взаимодействия с AlloyDB.

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/alloydb.client'


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/serviceusage.serviceUsageConsumer'

Затем вы загрузите файл 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

Наконец, разверните свой сервер Toolbox в 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 [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00002-dn2] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app

Теперь вы можете перейти по указанному выше URL-адресу сервиса в браузере. Должно появиться сообщение «Hello World», которое мы видели ранее. Кроме того, вы можете перейти по следующему URL-адресу, чтобы ознакомиться с доступными инструментами:

https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/api/toolset

Вы также можете зайти в Cloud Run из консоли Google Cloud и увидеть службу Toolbox, доступную в списке служб в Cloud Run.

7. Агент, созданный на основе ADK

В этом разделе вы развернете свой ИИ-агент, созданный с использованием Agent Development Kit (ADK), в Cloud Run.

Сначала включите в своем проекте необходимые API для сборки и развертывания агента в Cloud Run, а также для взаимодействия с реестром артефактов и облачным хранилищем. Выполните следующую команду в терминале Cloud Shell:

gcloud services enable artifactregistry.googleapis.com \
                       cloudbuild.googleapis.com \
                       run.googleapis.com \
                       storage.googleapis.com

Затем мы назначим необходимые разрешения учётной записи службы вычислений по умолчанию в нашем проекте. Сначала выполните следующую команду в терминале Cloud Shell, чтобы получить PROJECT_NUMBER:

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

Назначьте разрешения учетной записи службы вычислений по умолчанию:

# Grant Cloud Run service account access to GCS
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role="roles/artifactregistry.repoAdmin"

# Grant Vertex AI User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"

# Grant Vertex AI Model User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.modelUser"

Подключите нашего агента к инструментам

Мы подключим нашего агента к инструментам. В контексте ADK инструмент представляет собой определённую возможность, предоставляемую ИИ-агенту, позволяющую ему выполнять действия и взаимодействовать с миром, выходящие за рамки его основных возможностей по генерации текста и рассуждению.

В нашем случае мы собираемся оснастить нашего агента инструментами, которые мы настроили в MCP Toolbox for Databases.

Используя редактор Cloud Shell, перейдите в каталог sports-agent-adk-mcp-alloydb/src/backend/ и отредактируйте файл finn_agent.py, используя следующий код. Обратите внимание, что мы используем URL-адрес службы Cloud Run с сервера MCP ToolBox, развёрнутого на предыдущем шаге:

Разверните нашего агента в облаке Run

Наконец, вы развернете настроенный вами AI Agent в Cloud Run, сделав его доступным через конечную точку HTTP.

Сначала создайте Docker-репозиторий в Artifact Registry для хранения образов контейнеров вашего агента. Выполните следующую команду в Cloud Shell:

gcloud artifacts repositories create finn-agent-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-agent images"

Затем соберите образ Docker для вашего агента с помощью Cloud Build. Выполните эту команду из корневого каталога клонированного проекта ( sports-agent-adk-mcp-alloydb/ ):

gcloud builds submit src/backend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent

Теперь разверните службу Agent. Эта команда создаст службу Cloud Run, извлечет образ из реестра артефактов и настроит переменные среды.

gcloud run deploy finn-agent \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=TRUE"

Примечание: мы динамически устанавливаем переменные среды, включая GOOGLE_CLOUD_PROJECT (используя переменную оболочки $PROJECT_ID ).

Вы должны получить аналогичный вывод, указывающий на успешное развертывание вашего агента:

Deploying container to Cloud Run service [finn-agent] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-agent] revision [finn-agent-00005-476] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-agent-359225437509.us-central1.run.app

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

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}' \
  https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app/chat

Вы получите примерно такой вывод:

«Здравствуйте! Меня зовут Финн, я ваш помощник по покупкам в спортивных магазинах с искусственным интеллектом. Я могу помочь вам найти спортивные товары, экипировку и оборудование. Чем я могу вам помочь?»

На этом этапе вы успешно проверили развертывание AlloyDB, MCP Toolbox и вашего агента, созданного с использованием ADK.

8. Развертывание фронтенда

В этом разделе вы развернёте диалоговый пользовательский интерфейс для вашего ИИ-помощника в Cloud Run. Этот интерфейс создан с использованием React и JavaScript.

Перед развертыванием вам необходимо обновить исходный код интерфейса, указав URL-адреса развернутого агента и идентификатор клиента OAuth.

Используя редактор Cloud Shell, перейдите по адресу sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ и откройте файл Home.jsx . Вам потребуется обновить URL-адрес службы Cloud Run вашего агента. Затем замените его URL-адресом службы Cloud Run вашего агента из предыдущего шага (например, https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app ).

Теперь перейдите в sports-agent-adk-mcp-alloydb/src/frontend/src/components/ и откройте файл GoogleSignInButton.jsx . В этом файле вам нужно указать идентификатор клиента OAuth, полученный в разделе «Настройка службы авторизации».

Разверните интерфейс в Cloud Run

Теперь, когда ваше внешнее приложение настроено, вы готовы развернуть его в Cloud Run.

Выполните следующую команду в терминале Cloud Shell из корневого каталога ( sports-agent-adk-mcp-alloydb/ ), чтобы создать репозиторий Docker в реестре артефактов для ваших образов интерфейса.

gcloud artifacts repositories create finn-frontend-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-frontend images"

Затем соберите образ Docker для вашего фронтенд-приложения с помощью Cloud Build. Выполните эту команду из корневого каталога вашего проекта:

gcloud builds submit src/frontend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend

Наконец, мы развернем интерфейс в Cloud Run с помощью следующей команды:

gcloud run deploy finn-frontend \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID

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

Deploying container to Cloud Run service [finn-frontend] in project [sport-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-frontend] revision [finn-frontend-00002-mwc] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-frontend-535807247199.us-central1.run.app

Откройте веб-браузер и используйте URL-адрес службы из предыдущего шага, чтобы открыть недавно развернутое приложение, работающее на базе вашего ИИ-агента!

9. Запустите нашего агента

Ваш помощник-ИИ-агент спортивного магазина Финн теперь полностью готов помочь вам с покупками!

Откройте веб-браузер и перейдите по URL-адресу сервиса вашего фронтенд-приложения из предыдущего шага. URL имеет следующий формат: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

После загрузки интерфейса нажмите кнопку в правом верхнем углу (обычно с надписью «Войти» или аналогичной), чтобы пройти аутентификацию, используя ваши учётные данные Google. Это действие будет использовать ранее настроенную вами конфигурацию OAuth.

После успешной аутентификации вы готовы к общению с Финном! Нажмите кнопку «Купить сейчас», чтобы начать диалог с шопингом.

Используйте следующий скрипт для тестирования различных функций вашего ИИ-агента. Скопируйте и вставьте эти подсказки в интерфейс чата по одной:

Привет, Финн!
Я ищу кроссовки для ультратрейла.
Расскажите мне подробнее об Ultra Glide
Добавить Ultra Glide, размер 40, цвет красный/серый в мой список покупок
Показать мой список покупок
Найти магазины рядом со мной
Пожалуйста, оформите заказ, используя мой список покупок для магазина Sports Diagonal Mar
Проверить статус моих заказов
Пожалуйста, перечислите способы доставки для магазина Sports Diagonal Mar
Обновите способ доставки моего заказа [YOUR_ORDER_NUMBER] на «Экспресс-доставка»
Проверить статус моих заказов
Спасибо, Финн!

Для наглядной демонстрации развернутого Finn Agent и его возможностей посмотрите видео ниже:

Демонстрация ИИ-помощника спортивного агента на базе AlloyDB

10. Результаты

Выполнив предыдущий скрипт, вы успешно проверили полную интеграцию вашего агента ADK, его подключение к AlloyDB и использование им MCP Toolbox. В этом разделе описаны основные реализованные вами возможности.

Служба авторизации

MCP Toolbox for Databases предоставляет возможность интеграции сервиса авторизации (в частности, Google Sign-In в этой лабораторной работе) для аутентификации пользователей в вашем приложении. В MCP Toolbox ваш OAuth Client ID используется для проверки личности пользователя при вызове инструмента.

Этот надёжный механизм аутентификации предлагает превосходное решение для защиты вашего агентского приложения от «инъекции подсказок» (prompt injection) — типа атаки, при которой вредоносный ввод пытается обойти или манипулировать предполагаемым поведением агента. Подробнее см. в статье Википедии о «инъекции подсказок».

В данном приложении этот метод используется, когда пользователь запрашивает «проверить статус наших заказов» или «показать мой список покупок». Агент предназначен для отображения только заказов, принадлежащих аутентифицированному пользователю , что предотвращает несанкционированный доступ к информации о заказах.

Поиск векторов

Ваше агентское приложение использует AlloyDB для PostgreSQL для предоставления расширенных возможностей запросов, в частности, векторного поиска. AlloyDB поддерживает онлайн-генерацию встраиваемых данных непосредственно в базу данных с помощью SQL-функций.

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

В своей заявке вы сталкиваетесь с этой техникой, когда спрашиваете Финна: «Я ищу кроссовки для ультратрейлового забега».

Геопространственные возможности (PostGis)

AlloyDB для PostgreSQL обеспечивает полную совместимость со стандартными функциями PostgreSQL. В этом приложении мы используем популярное расширение PostgreSQL — PostGIS — для предоставления агенту возможностей геолокации.

Когда вы задаете агенту вопрос: «Найти магазины рядом со мной», агент запускает инструмент, который использует индексы PostGIS в базе данных для эффективного поиска магазинов, ближайших к указанному или предполагаемому местоположению пользователя.

11. (Необязательно) Тестирование преобразования естественного языка AlloyDB AI в SQL

В этом разделе представлена расширенная функция AlloyDB для PostgreSQL, доступная до появления GA : преобразование естественного языка в SQL . Эта функция позволяет генерировать SQL-запросы непосредственно из подсказок на естественном языке, используя возможности искусственного интеллекта в вашей базе данных.

Важно: поскольку это функция Pre-GA, для ее использования вам потребуется зарегистрироваться и получить доступ к вашему проекту Google Cloud, кластеру AlloyDB и базе данных.

Зарегистрируйтесь для получения доступа: пожалуйста, заполните эту форму , чтобы запросить доступ для вашего проекта.
Документация: Подробнее об использовании AlloyDB AI Natural Language to SQL можно узнать в официальной документации.

После регистрации и подтверждения доступа к вашему проекту выполните следующие шаги в AlloyDB Studio.

Войдите в AlloyDB, используя учетные данные, созданные при создании кластера:

Имя пользователя: "postgres"
База данных: "store"
Пароль: "alloydb"

1. Создайте расширение alloydb_ai_nl. Это расширение предоставляет необходимые функции для работы с естественным языком в AlloyDB AI.

CREATE EXTENSION alloydb_ai_nl cascade;

2. Создайте конфигурацию для вашего приложения. Конфигурация определяет контекст схемы, который модель ИИ будет использовать для анализа вашей базы данных.

SELECT
 alloydb_ai_nl.g_create_configuration(
   'finn_app_config'        -- configuration_id
 );

3. Зарегистрируйте схему/таблицы в конфигурации. Добавьте в конфигурацию конкретные таблицы и схемы, с которыми будет взаимодействовать агент вашего приложения.

SELECT alloydb_ai_nl.g_manage_configuration(
   operation => 'register_table_view',
   configuration_id_in => 'finn_app_config',
   table_views_in=>'{public.products, public.products_variants, public.orders, public.orders_items, public.users, public.inventory, public.stores}'
);

4. Генерация контекста для схемы/таблиц. На этом этапе зарегистрированные таблицы обрабатываются для генерации необходимого контекста для модели ИИ. Этот процесс может занять около 2–3 минут .

SELECT alloydb_ai_nl.generate_schema_context(
 'finn_app_config',
 TRUE
);

5. Проверьте автоматически сгенерированный контекст для конкретных таблиц и столбцов (необязательно). Вы можете изучить сгенерированный контекст, чтобы понять, как модель ИИ интерпретирует вашу схему.

SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.inventory';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.name';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.popularity_score';

Инструмент под названием «check-inventory-by-store-brand-category» находится в файле «tools.yaml» нашего агента. Этот инструмент использует AlloyDB Natural Language для SQL:

Откройте веб-браузер и используйте URL-адрес сервиса для открытия приложения: «https://finn-frontend-[НОМЕР_ВАШЕГО_ПРОЕКТА].us-central1.run.app»

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

Привет, Финн!
Какое общее количество товаров категории Бег бренда Salomon есть в наличии в магазине «Sports Diagonal Mar»?

Чтобы увидеть реальный SQL-запрос, сгенерированный AlloyDB AI на основе введенных вами данных на естественном языке, вернитесь в AlloyDB Studio и выполните следующий запрос:

SELECT
   alloydb_ai_nl.get_sql(
       'finn_app_config',
       'What is the total quantity of category Running products of Salomon in stock at the "Sports Diagonal Mar" store?'
   ) ->> 'sql';

Будет отображен оператор SQL, сгенерированный AlloyDB AI.

12. Уборка

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, используемые в этой лабораторной работе, выполните следующие действия:

В консоли Google Cloud перейдите на страницу Управление ресурсами .
В списке проектов выберите проект, который вы хотите удалить, и нажмите Удалить.
В диалоговом окне введите идентификатор проекта, а затем нажмите кнопку «Завершить», чтобы удалить проект.

13. Поздравления

Поздравляем! Вы успешно создали приложение на основе агентного ИИ, управляемого данными, с использованием ADK, MCP Toolbox for Databases и AlloyDB для PostgreSQL.

Для получения дополнительной информации обратитесь к документации по продукту: Agent Development Kit , MCP Toolbox for Databases и AlloyDB for PostgreSQL.