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

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

1. Введение

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

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

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

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

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

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

Для выполнения этого практического задания вам потребуется:

Веб-браузер Chrome.
Аккаунт Gmail.
Проект в Google Cloud с включенной функцией выставления счетов.

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

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

В этом разделе описаны этапы первоначальной настройки вашего проекта Google Cloud, необходимые перед началом создания ИИ-помощника для спортивных магазинов.

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

В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud.
Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .
Активируйте Cloud Shell, перейдя по этой ссылке . Вы можете переключаться между терминалом Cloud Shell (для выполнения облачных команд) и редактором (для сборки проектов), нажав соответствующую кнопку в 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, а также сконфигурируете необходимые сетевые параметры и права доступа для вашего агента ИИ.

Сначала выполните следующую команду в терминале 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. Это позволит вашей сети виртуальной частной сети (VPC) Google Cloud безопасно и конфиденциально взаимодействовать с управляемыми сервисами 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, необходимо предоставить агенту службы AlloyDB разрешения Vertex AI.

Для начала получите номер своего проекта 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". В результате замените последние 2 цифры на 0.0 с маской '/16'. Например, это будет выглядеть так: "XX.XX.0.0/16", где XX — числа.

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

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

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

Создайте базу данных магазина.

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

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

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

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

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

chmod +x alloydb-auth-proxy

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

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

Подключитесь к экземпляру 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"
База данных: "хранилище"
Пароль: "alloydb"

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

Важный:

Оставьте значение LOCATION таким, как в примере.
Используйте тот же адрес электронной почты, который вы используете для регистрации в консоли Google Cloud.

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»:

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

Название приложения: "Искусственный интеллект для организации покупок спортивных товаров"
Адрес электронной почты службы поддержки пользователей: "ВАШ_EMAIL"
Целевая аудитория: "Внешняя"
Контактная информация: "ВАШ_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-[НОМЕР_ВАШЕГО_ПРОЕКТА].us-central1.run.app — это ожидаемый URL-адрес развертывания вашего фронтенд-приложения, который будет настроен позже в этом практическом занятии. Убедитесь, что вы заменили [НОМЕР_ВАШЕГО_ПРОЕКТА] на фактический номер, который вы скопировали.

Важно: После создания во всплывающем окне отобразится ваш идентификатор клиента 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.16.0

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

chmod +x toolbox

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

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

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

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

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

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

Для получения более подробной информации о настройке файла tools.yaml обратитесь к этой документации .

Давайте запустим MCP Toolbox для серверов баз данных.

Для запуска сервера выполните следующую команду (из папки 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 доступным в качестве общедоступной конечной точки, которую можно интегрировать с другими приложениями и вашим агентом ИИ, вам необходимо развернуть его в Cloud Run. Подробные инструкции по размещению Toolbox в Cloud Run приведены здесь .

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

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 с настроенным файлом 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.

В этом разделе вы развернете своего агента ИИ, созданного с использованием комплекта разработки агентов (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=$(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 для баз данных.

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

Разверните наш агент в Cloud Run.

Наконец, вы развернете настроенный агент ИИ в 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 в Artifact Registry для образов вашего фронтенда.

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.
Изменить способ доставки на экспресс-доставку для моего заказа [НОМЕР_ВАШЕГО_ЗАКАЗА]
Проверить статус моих заказов
Спасибо, Финн!

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

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

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

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

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

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

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

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

Векторный поиск

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

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

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

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

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

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

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

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

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

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

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

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

Имя пользователя: "postgres"
База данных: "хранилище"
Пароль: "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';

В файле "tools.yaml" нашего агента вы найдете инструмент под названием "check-inventory-by-store-brand-category". Этот инструмент использует преобразование естественного языка AlloyDB в SQL:

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

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

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

Чтобы увидеть фактический SQL-запрос, сгенерированный искусственным интеллектом AlloyDB на основе ваших данных на естественном языке, вернитесь в 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 для баз данных и AlloyDB для PostgreSQL.

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