Разверните агент, поддерживающий корпоративное управление, с помощью MCP и Cloud Run.

1. Введение

Данный практический урок является частью двухсерийного цикла, посвященного созданию агента GenAI, учитывающего особенности управления ИИ.

(Вы можете прочитать первую часть этой серии, в которой рассказывается о том, как создать основу для работы с данными, применив аспекты Dataplex к таблицам BigQuery и протестировав правила локально через интерфейс командной строки Gemini. 👉 Читать часть 1 )

Однако тестирование в локальном интерфейсе командной строки — это только начало. Для внедрения этого решения во всей компании вам потребуется централизованная система безопасности, стандартизированные подключения к инструментам искусственного интеллекта и соответствующая прикладная среда для организации логики работы агента и предоставления привычного интерфейса чата.

Во второй части вы решите эти задачи и масштабируете систему до производственной среды. Вы развернете свои правила управления на центральном сервере MCP, размещенном на Cloud Run . Затем вы используете комплект разработки агентов Google (ADK) для создания самого приложения агента и подключения его к вашим инструментам MCP, включая профессиональный веб-интерфейс.

be15d5f41f0d716c.png

Предварительные требования

  • Проект Google Cloud с включенной функцией выставления счетов.
  • Базовое понимание Cloud Run, учетных записей служб IAM и Python.
  • Наборы данных BigQuery и аспекты Dataplex, созданные в Части 1. (Не беспокойтесь, если вы их удалили; ниже мы приводим быстрый скрипт для их восстановления!)

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

  • Как использовать протокол контекста модели (MCP) для стандартизации взаимодействия агентов ИИ с данными Google Cloud.
  • Как развернуть защищенный сервер MCP в Cloud Run.
  • Как создать агента искусственного интеллекта с помощью комплекта разработки агентов (ADK) и подключить его к бэкэнду MCP.
  • Как использовать встроенный в ADK пользовательский интерфейс разработчика для взаимодействия с управляемым агентом.

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

  • Доступ к Google Cloud Shell

Ключевые понятия

  • Протокол контекста модели (MCP): Представьте MCP как «универсальный USB-C кабель» для агентов ИИ. Вместо написания пользовательского кода интеграции API для каждой отдельной модели ИИ, MCP предоставляет стандартный способ безопасного подключения ИИ к вашим корпоративным инструментам обработки данных (таким как Dataplex и BigQuery).
  • Agent Development Kit (ADK): Гибкая платформа с открытым исходным кодом от Google, разработанная для упрощения сквозной разработки агентов ИИ. Она применяет принципы программной инженерии к созданию агентов, позволяя вам координировать сложные инструменты, управлять состоянием и легко запускать встроенный пользовательский интерфейс для разработчиков для тестирования и развертывания.

2. Настройка и требования

Запустить Cloud Shell

Хотя Google Cloud можно управлять удаленно с ноутбука, в этом практическом занятии вы будете использовать Google Cloud Shell — среду командной строки, работающую в облаке.

В консоли Google Cloud нажмите на значок Cloud Shell на панели инструментов в правом верхнем углу:

Активировать Cloud Shell

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

Скриншот терминала Google Cloud Shell, показывающий, что среда подключена.

Эта виртуальная машина содержит все необходимые инструменты разработки. Она предоставляет постоянный домашний каталог объемом 5 ГБ и работает в облаке Google, что значительно повышает производительность сети и аутентификацию. Вся работа в этом практическом задании может выполняться в браузере. Вам не нужно ничего устанавливать.

Инициализация среды

Откройте Cloud Shell и настройте переменные проекта, чтобы все команды были направлены на правильную инфраструктуру.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

Контрольная точка: Возобновить или перестроить?

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

Вариант А: Я только что закончил первую часть, и мои ресурсы все еще работают.

Отлично! Перейдите в рабочую директорию, и вы готовы продолжить.

cd ~/devrel-demos/data-analytics/governance-context

Вариант B: Я пропустил часть 1 ИЛИ Я удалил свои ресурсы (провел очистку).

Нет проблем! Ниже мы привели блок команд "Ускоренного выполнения". Он автоматически перестроит озеро данных BigQuery и применит метаданные управления Dataplex точно так же, как мы это сделали в Части 1.

# 1. Clone the repo and navigate to the working directory
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

# 2. Rebuild the messy data lake with Terraform
cd terraform
terraform init
terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

# 3. Generate and apply Dataplex Aspects (Governance rules)
cd ..
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3. Масштабирование с помощью MCP: построение плоскости управления данными

На данный момент вы успешно протестировали свою логику управления с помощью Gemini CLI. Это отлично подходит для быстрого прототипирования, но запускается локально с использованием ваших личных учетных данных.

В реальной корпоративной среде необходима централизованная плоскость управления данными. Для её создания мы будем использовать GenAI Toolbox for Databases — официальный проект с открытым исходным кодом от Google. Этот инструментарий предоставляет предварительно настроенный MCP-сервер, специально разработанный для безопасного подключения агентов ИИ к базам данных Google Cloud и службам метаданных, таким как Dataplex.

Развернув этот набор инструментов в качестве нашего MCP-сервера в Cloud Run, мы достигаем следующих результатов:

  1. Централизованная идентификация: агент работает от имени ограниченной служебной учетной записи, а не от имени вашей личной учетной записи пользователя.
  2. Стандартизация: любой клиент (ADK, Gemini, пользовательские приложения) может «подключиться» к этому серверу, используя стандартный протокол MCP.
  3. Ограниченный доступ (минимальные привилегии): Мы не предоставляем студентам магистратуры неограниченный доступ к BigQuery. Мы заставляем их сначала пройтись по каталогу метаданных Dataplex.

Настройте определение инструмента ( tools.yaml ).

Для работы GenAI Toolbox требуется декларативный конфигурационный файл tools.yaml . Этот файл определяет sources (куда подключаться) и tools (что разрешено делать ИИ).

  1. Перейдите в каталог сервера и добавьте идентификатор вашего проекта в конфигурационный файл: 
cd ~/devrel-demos/data-analytics/governance-context/mcp_server
envsubst < tools.yaml > tools.tmp && mv tools.tmp tools.yaml
cat tools.yaml

Результат должен выглядеть идентично следующему фрагменту кода. Убедитесь, что поле «Проект» теперь соответствует вашему фактическому идентификатору проекта Google Cloud .

sources:
  dataplex:
    kind: dataplex
    project: YOUR-PROJECT-ID

tools:
  search_entries:
    kind: dataplex-search-entries
    source: dataplex
    description: Search for entries in Dataplex Catalog.

  lookup_entry:
    kind: dataplex-lookup-entry
    source: dataplex
    description: Retrieve a specific entry from Dataplex Catalog.

  search_aspect_types:
    kind: dataplex-search-aspect-types
    source: dataplex
    description: Find aspect types relevant to a query.

toolsets:
  dataplex-toolset:
    - search_entries
    - lookup_entry
    - search_aspect_types

Определив эти три инструмента, мы можем заставить ИИ работать в режиме «только для чтения» и ориентироваться в первую очередь на управление.

Защитите конфигурацию (Secret Manager)

В корпоративной архитектуре никогда не следует встраивать конфигурационные файлы непосредственно в образы контейнеров. Мы будем надежно хранить tools.yaml в Google Cloud Secret Manager .

gcloud services enable secretmanager.googleapis.com
gcloud secrets create dataplex-tools-config --data-file=tools.yaml

Внедрить принцип минимальных привилегий (IAM)

Далее мы создадим выделенную учетную запись службы для сервера GenAI Toolbox MCP. Эта учетная запись будет обладать только теми правами, которые необходимы для чтения каталога Dataplex и доступа к данным BigQuery.

export MCP_SA=mcp-sa
gcloud iam service-accounts create ${MCP_SA} \
    --display-name="Service Account for Dataplex MCP"
export MCP_SERVICE_ACCOUNT="${MCP_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

# Allow the server to read its own config from Secret Manager
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor"

# Allow the server to read Dataplex Metadata and BigQuery Data
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

Разверните сервер MCP в Cloud Run.

Теперь развернем GenAI Toolbox. Мы используем предварительно собранный образ контейнера от Google ( database-toolbox/toolbox ) и монтируем нашу конфигурацию из Secret Manager ( --set-secrets ) во время выполнения.

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

gcloud run deploy governance-mcp \
    --image=$IMAGE \
    --service-account $MCP_SERVICE_ACCOUNT \
    --region=$REGION \
    --no-allow-unauthenticated \
    --set-secrets="/app/tools.yaml=dataplex-tools-config:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080"

Теперь вы создали управляемый API! Вместо того чтобы предоставлять вашему интерфейсу GenAI прямой доступ к базе данных, он будет подключаться к этому URL-адресу Cloud Run. Агент сможет видеть только то, что ему разрешает этот Toolbox.

4. Создайте бэкэнд агента с помощью ADK.

Вы создали защищенную, управляемую плоскость управления данными (MCP), работающую в Cloud Run. Теперь вашему ИИ-агенту необходима платформа для организации его логики, такой как обработка пользовательского ввода, определение момента обращения к серверу MCP и форматирование выходных данных.

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

Изучите логику работы агента (agent.py)

Прежде чем настраивать инфраструктуру, давайте рассмотрим ядро ​​этого приложения.

Перейдите в указанную директорию и выведите содержимое файла agent.py. Этот файл является «мозгом» вашей системы развертывания ADK.

cd ~/devrel-demos/data-analytics/governance-context/mcp_server
cat agent.py

Посмотрите на структуру кода. Он выполняет три важнейшие функции с минимальным количеством шаблонного кода:

  1. Интеграция с MCPToolset: Вместо написания собственных HTTP-клиентов для взаимодействия с инструментами Dataplex, ADK использует MCPToolset(server_url=mcp_url) . Это позволяет динамически получать определение tools.yaml с развернутого сервера MCP и преобразовывать его в вызовы собственных функций для LLM.
  2. Системные инструкции: Параметр instructions содержит строгие правила управления (та же логика, что и в файле CLI GEMINI.md ). Он явно указывает модели выполнить цикл обработки данных от Фазы 1 (поиск метаданных) до Фазы 2 (запрос данных).
  3. Оркестрация агентов: Класс Agent(...) связывает модель Gemini, системную подсказку и инструменты MCP. При развертывании ADK автоматически преобразует этот объект в масштабируемую конечную точку FastAPI.

Разделение обязанностей: Настройка идентификации внешнего интерфейса.

Для безопасного выполнения этого кода необходимо указать агенту местоположение вашего MCP-сервера. Мы сформируем URL-адрес динамически и сохраним его в файл .env , который ADK будет считывать во время выполнения.

Мы также создадим отдельный идентификатор ( dataplex-agent-sa ) для этого приложения, ориентированного на пользователя. Такое разделение обязанностей гарантирует, что у фронтенд-агента будут другие права доступа, чем у бэкенд-сервера управления.

Выполните следующие команды для настройки среды и идентификации: 

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export MCP_SERVER_URL=https://governance-mcp-${PROJECT_NUMBER}.${REGION}.run.app/mcp

export AGENT_SA=dataplex-agent-sa
export AGENT_SERVICE_ACCOUNT="${AGENT_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create ${AGENT_SA} \
    --display-name="Service Account for Dataplex Agent "

Настройка переменных времени выполнения

Фреймворк ADK использует переменные окружения для понимания своего контекста. Нам необходимо явно указать идентификатор проекта, регион и включить использование Vertex AI. Мы добавляем эти данные в тот же файл .env . 

echo MCP_SERVER_URL=$MCP_SERVER_URL > .env
echo GOOGLE_GENAI_USE_VERTEXAI=1 >> .env
echo GOOGLE_CLOUD_PROJECT=$PROJECT_ID >> .env
echo GOOGLE_CLOUD_LOCATION=$REGION >> .env

Предоставление разрешений

Несмотря на то, что агент делегирует проверки управления серверу MCP, ему все равно необходимы базовые разрешения для работы. Мы предоставляем ровно две роли:

  1. Пользователь Vertex AI: Запустить модель Gemini для генерации ответов на естественном языке.
  2. Cloud Run Invoker: Для безопасного вызова API вашего MCP-сервера. Он не получает прямого доступа к BigQuery или Dataplex! 
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

gcloud run services add-iam-policy-binding governance-mcp \
  --region=$REGION \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

Развертывание в облаке. Запуск.

Наконец, мы развертываем весь стек в Cloud Run.

Мы используем uvx для запуска инструмента ADK без ручной установки зависимостей. Приведенная ниже команда упаковывает логику вашего agent.py, создает образ контейнера, внедряет вашу учетную запись службы и запускает сервер FastAPI. Добавив флаг --with_ui , она также включает веб-среду ADK для отладки.

Эта команда создает и развертывает контейнер. Выполнение может занять от 1 до 3 минут. 

uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service_name=dataplex-agent \
  --with_ui \
  . \
  -- \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated

После завершения выполнения этой команды будет выведен URL-адрес сервиса ( eg, https://dataplex-agent-xyz.run.app ). Щелкните по этой ссылке, чтобы открыть полностью управляемый интерфейс чата GenAI.

12a5fa4c2aaf381f.png

Комплексный архитектурный процесс

Вы завершили настройку системы. При взаимодействии пользователя с пользовательским интерфейсом ADK происходит следующая последовательность действий:

  1. Пользователь отправляет запрос в ADK Agent (пользовательский интерфейс разработчика) .
  2. Агент ADK (agent.py) обрабатывает входные данные и вызывает модель Gemini .
  3. Gemini определяет, что ему необходим контекст, и запрашивает у сервера MCP выполнение инструментов Dataplex.
  4. Сервер MCP обеспечивает соблюдение правил управления Dataplex и возвращает метаданные.
  5. Gemini формирует достоверный ответ на основе метаданных и возвращает его пользователю.

5. Протестируйте корпоративный агент.

Теперь, когда ваш агент запущен, давайте вернемся к сценариям управления, протестированным ранее с помощью CLI. Логика остается той же, но теперь вы взаимодействуете с развернутой веб-платформой ADK Web Playground, которая визуализирует внутреннее состояние и выполнение инструментов.

  1. Оркестрация: Агент ADK (работающий в Cloud Run) получает ваш текст.
  2. Маршрутизация инструментов: Gemini распознает, что ваш вопрос требует контекстных данных, и перенаправляет запрос на сервер MCP .
  3. Проверка управления: Сервер MCP (работающий на отдельном экземпляре Cloud Run) запрашивает у Dataplex информацию о конкретных типах аспектов.
  4. Синтез: Соответствующие метаданные возвращаются в Gemini для генерации окончательного ответа.

Проверьте логику управления.

Откройте в браузере URL-адрес сервиса, сгенерированный на предыдущем шаге ( eg, https://dataplex-agent-xyz.run.app ). Вставьте следующую строку: 

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

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

  1. Распознавание намерений: Агент анализирует слова «прямо сейчас» и «не могу ждать ночи».
  2. Поиск метаданных: вызывает инструмент MCP search_aspect_types . Он ищет данные, у которых параметр update_frequency установлен на REALTIME или STREAMING, а не на DAILY или MONTHLY.
  3. Выборка: Она показывает, что таблица mkt_realtime_campaign_performance соответствует этим критериям, в то время как fin_monthly_closing_internal (несмотря на высокое качество) слишком медленная для вашего запроса.
  4. Ответ: Агент рекомендует расписание в режиме реального времени.

e0da615724199e.png

Почему это важно:

Без этих метаданных управления, магистр права, скорее всего, рекомендовал бы таблицу fin_monthly_closing_internal просто потому, что в ней есть столбец с именем "ad_spend", игнорируя тот факт, что данные устарели на 24 часа. Ваш контекст метаданных предотвратил бизнес-ошибку.

Вы также можете протестировать запрос "Заседание совета директоров", чтобы увидеть, как агент переключается между различными таблицами в зависимости от уровня данных: 

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

6. Уборка

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

Уничтожьте Озеро Дантейк (Терраформирование)

Используйте Terraform для удаления таблиц BigQuery, наборов данных и определений аспектов Dataplex. 

cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

Удалить службы Cloud Run

Отключите вычислительные ресурсы, чтобы прекратить активную оплату за запущенные контейнеры. 

gcloud run services delete governance-mcp --region=$REGION --quiet
gcloud run services delete dataplex-agent --region=$REGION --quiet

Очистка артефактов сборки и промежуточного хранилища.

При развертывании агента ADK с использованием uvx система автоматически создавала образ контейнера и загружала ваш исходный код во временное хранилище Cloud Storage. Эти артефакты сохраняются даже после удаления службы Cloud Run и будут влечь за собой постоянные расходы на хранение.

Удалите репозиторий Artifact Registry и промежуточный сегмент Cloud Storage: 

# Delete the repository used for the agent build
gcloud artifacts repositories delete cloud-run-source-deploy \
    --location=$REGION \
    --quiet

# Delete the staging bucket created by Cloud Run source deploy
gcloud storage rm --recursive gs://run-sources-${PROJECT_ID}-${REGION}

Удалить личные данные, права доступа и секреты.

Сначала удалите привязки политик IAM, чтобы предотвратить сохранение "записей-сирот" (бесхозных записей) на странице IAM вашего проекта. Затем удалите учетные записи служб и секреты конфигурации. 

# Remove IAM roles granted to the MCP Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

# Remove IAM roles granted to the Agent Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" --quiet

# Delete the Service Accounts
gcloud iam service-accounts delete $MCP_SERVICE_ACCOUNT --quiet
gcloud iam service-accounts delete $AGENT_SERVICE_ACCOUNT --quiet

# Delete the Secret Manager entry
gcloud secrets delete dataplex-tools-config --quiet

Удалить локальную конфигурацию

Наконец, очистите локальные конфигурационные файлы и переменные среды в Cloud Shell. 

# Uninstall the Gemini CLI extension (installed in Part 1)
gemini extensions uninstall dataplex

# Remove local repository files and unset variables
cd ~
rm -rf ~/devrel-demos
unset MCP_SERVER_URL
unset MCP_SERVICE_ACCOUNT
unset AGENT_SERVICE_ACCOUNT

7. Поздравляем!

Вы успешно развернули комплексный агент GenAI, учитывающий принципы управления.

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

Основные выводы

  • Детерминированный ИИ на основе метаданных: вместо того, чтобы полагаться на модель LLM для определения правильной таблицы на основе имен столбцов, вы внедрили строгий цикл рассуждений, используя GenAI Toolbox for Databases. Явно предоставив доступ только к трем инструментам Dataplex ( search_aspect_types , search_entries , lookup_entry ), вы заставили модель проверять сертификаты данных перед синтезом ответов.
  • Архитектура с разделением ресурсов (MCP): Развернув сервер протокола контекста модели (MCP) на Cloud Run, вы абстрагировали правила управления данными в централизованный стандартизированный API. Фронтенд-агент не должен содержать логику работы с базой данных; ему нужно только взаимодействовать через стандарт MCP. Это означает, что вы можете подключить любую будущую модель ИИ или клиент к той же управляемой бэкэнд-системе.
  • Разделение обязанностей: Вы применили принцип минимальных привилегий, изолировав идентификаторы IAM. Агент ADK, ориентированный на пользователя, работает с правами доступа, ограниченными вызовом модели и маршрутизацией API, в то время как сервер MCP обеспечивает безопасную обработку запросов к каталогу Dataplex и извлечение данных из BigQuery.
  • Оркестрация агентов с использованием подхода Code First: Вы использовали Google Agent Development Kit (ADK), чтобы мгновенно интегрировать логику вашего агента на Python в масштабируемый бэкэнд FastAPI, используя встроенный пользовательский интерфейс разработчика для визуализации и отладки выполнения внутренних инструментов агента.

Что дальше?