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

1. Введение

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

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

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

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

.

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

8912d1983c34ee8e.png

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

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

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

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

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

  • Протокол контекста модели (MCP): Представьте MCP как «универсальный USB-C кабель» для агентов ИИ. Вместо написания пользовательского кода интеграции API для каждой отдельной модели ИИ, MCP предоставляет стандартный способ безопасного подключения ИИ к вашим корпоративным инструментам работы с данными (таким как Knowledge Catalog и BigQuery).
  • Agent Development Kit (ADK): Гибкая платформа с открытым исходным кодом от Google, разработанная для упрощения сквозной разработки агентов ИИ. Она применяет принципы программной инженерии к созданию агентов, позволяя вам координировать сложные инструменты, управлять состоянием и легко запускать встроенный пользовательский интерфейс для разработчиков для тестирования и развертывания.
  • Gemini Enterprise Agent Platform (GEAP) : среда корпоративного уровня для размещения и оркестрации агентов искусственного интеллекта в облаке 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"

Включите необходимые API.

Включите минимальный набор API Google Cloud, необходимый для управления вашей базой данных, запуска моделей Vertex AI и размещения агента ADK на Cloud Run.

gcloud services enable \
    dataplex.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

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

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

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

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

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

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

Нет проблем! Ниже мы привели блок команд "Ускоренного выполнения". Он автоматически перестроит озеро данных BigQuery, зарегистрирует тип аспекта и применит метаданные управления точно так же, как мы это делали в Части 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 BigQuery datasets and tables
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

# 3. Register the Knowledge Catalog aspect type
gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --metadata-template-file-name="aspect_template.json"

# 4. Generate and apply aspects (governance rules)
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3. Централизованная плоскость управления данными (управляемая MCP)

В реальной корпоративной среде необходима безопасная централизованная плоскость управления данными. Вместо того чтобы создавать и развертывать собственный контейнер сервера MCP в Cloud Run, мы подключим наш агент напрямую к управляемому Google серверу MCP Knowledge Catalog .

Используя эту управляемую конечную точку, мы достигаем следующих результатов:

  1. Отсутствие необходимости в обслуживании: нет необходимости управлять контейнерами, масштабированием или устанавливать обновления для сервера MCP.
  2. Стандартизация: Агент подключается к стандартной, защищенной конечной точке Google API, используя протокол контекста модели (транспорт SSE).
  3. Контролируемая область действия: сервер MCP предоставляет доступ только к необходимым инструментам работы с метаданными ( search_entries , lookup_context , lookup_entry ), обеспечивая цикл рассуждений, ориентированный на управление и доступ только для чтения.

Сервер Knowledge Catalog MCP, управляемый Google, доступен по следующему защищенному URL-адресу:

https://dataplex.googleapis.com/mcp

Поскольку это API от Google, агент должен аутентифицироваться с помощью стандартного токена доступа Google Cloud OAuth2, а не токена идентификации. Мы будем обрабатывать эту аутентификацию автоматически в коде нашего приложения.

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

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

Мы будем использовать Google Agent Development Kit (ADK) . ADK — это фреймворк, ориентированный на код, который автоматически интегрирует логику вашего агента в бэкэнд FastAPI и предоставляет встроенный веб-интерфейс для мгновенного тестирования.

Откройте код агента в редакторе Cloud Shell.

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

Выполните указанную ниже команду в терминале и посмотрите структуру кода в редакторе. Приложение создано с использованием комплекта разработки агентов Google (ADK) :

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

# Copy the governance skill directory inside the application bundle so it packages during Cloud Run deployment
mkdir -p skills
cp -r ../.agents/skills/knowledge-catalog-governance skills/

cloudshell edit agent.py

(Примечание: agent.py содержит стандартный код в начале, предназначенный для обработки аутентификации Google Cloud OAuth2 и обновления токенов, что обеспечивает безопасное взаимодействие агента с API каталога знаний, управляемым Google).

1. Загрузка встроенных навыков

Для создания высокооптимизированного агента мы загружаем инструкции по управлению из внешнего каталога навыков агента, используя встроенную функцию ADK load_skill_from_dir . Такой подход обеспечивает поэтапное раскрытие информации :

  • Метаданные уровня L1: Агент загружает только название и описание навыка при запуске. Этот минимальный контекст позволяет LLM определить, когда следует использовать навык, без предварительного расхода большого количества токенов.
  • Инструкции уровня L2: Полный набор инструкций, содержащийся в SKILL.md , динамически загружается во время выполнения только тогда, когда модель определяет, что это необходимо. 
base_dir = Path(__file__).parent
governance_skill = load_skill_from_dir(
    base_dir / "skills" / "knowledge-catalog-governance"
)

# Bundle the skill and MCP tools together into a SkillToolset
governance_skill_toolset = skill_toolset.SkillToolset(
    skills=[governance_skill],
    additional_tools=[tools]
)

2. Организация работы агентов

ADK позволяет управлять сложным поведением агентов, объединяя несколько агентов в цепочку. Мы определяем рабочий процесс SequentialAgent , состоящий из двух специализированных агентов:

  • governance_researcher: Оснащен инструментами governance_skill_toolset и tools MCP каталога знаний. Проверяет, попадает ли запрос в область действия каталога данных и соответствия требованиям, а затем запрашивает данные из каталога знаний, используя переменные среды, внедренные в его системные инструкции.
  • compliance_formatter: Отвечает за преобразование необработанных результатов поиска метаданных в формате JSON в корректный ответ или за корректное объяснение границ области действия запроса, если запрос выходит за её пределы. 
# 1. Researcher Agent (has access to the encapsulated SkillToolset)
governance_researcher = LlmAgent(
    name="governance_researcher",
    model=model_name,
    description="Dynamically interprets metadata schema (Booleans/Enums) and searches for assets using strict syntax.",
    instruction=f"""
    You are a governance researcher. Your job is to verify Knowledge Catalog metadata rules and find compliant assets for the user's query.
    
    YOUR ACTIVE ENVIRONMENT CONTEXT:
    - Google Cloud Project ID: {project_id}
    - Location (Region): {location}

    YOUR WORKFLOW:
    1. First, check if the user query is related to data analytics assets, database tables, or data compliance.
       - If YES: Call `load_skill` with `name="knowledge-catalog-governance"` to load the rules, then use search/lookup tools to locate a certified compliant table.
       - If NO (e.g., general chit-chat, unrelated tasks): Skip skill loading and output a JSON object indicating it is out of scope:
         {"error": "out_of_scope", "message": "The query does not pertain to data catalog search or governance compliance."}
    2. Populate the required projectId and location parameters in tool calls with the active environment parameters.
    3. Return the verified table's metadata in JSON format as your final research output.
    """,
    tools=[governance_skill_toolset, tools],
    output_key="research_data"
)

# 2. Formatter Agent (formats the output or explains out-of-scope errors)
compliance_formatter = LlmAgent(
    name="compliance_formatter",
    model=model_name,
    description="Formats the JSON research data into a helpful response for the user.",
    instruction="""
    You are the **Intelligent Data Governance Specialist**.
    Your job is to explain the findings of the governance research clearly to the user.

    **YOUR GOAL:**
    1. If the researcher found a matching table (valid JSON with table metadata):
       - Explain the logical connection between the User's Request, the Governance Schema (translated criteria), and the Recommended Table.
       - Use the following RESPONSE TEMPLATE:
         - **Analysis:** "I analyzed the metadata schema and translated your request into the following technical criteria:..."
         - **Recommendation:** "Based on this, I recommend the following table:"
           - **Table:** [Insert Table Name]
           - **Description:** [Insert Table Description]
         - **Verification:** "This asset is a verified match because: [Explain the verification details]."
    2. If the researcher returned an 'out_of_scope' error or no matching tables were found:
       - Apologize politely and explain that no data asset currently matches the strict governance criteria defined in `official-data-product-spec`.
       - Clearly state what domain of questions this agent is certified to answer (e.g., Data Catalog Search and Data Governance compliance).
    """
)

# 3. Orchestrated Workflow (Exported as root_agent)
root_agent = SequentialAgent(
    name="governance_workflow",
    description="Workflow to learn metadata rules, search with strict syntax, and recommend assets.",
    sub_agents=[
        governance_researcher,
        compliance_formatter,
    ]
)

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

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

Выполните следующую команду для генерации файла .env . Обратите внимание, что MCP_SERVER_URL указывает непосредственно на конечную точку API каталога знаний, управляемого Google:

export MCP_SERVER_URL="https://dataplex.googleapis.com/mcp"

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

5. Запустите и протестируйте агент локально.

Перед развертыванием агента в облаке следует запустить его локально в Cloud Shell, чтобы проверить его работу. Поскольку агент зависит от нескольких пакетов Python (включая библиотеки Google Cloud Logging и ADK), мы настроим локальную виртуальную среду для установки этих зависимостей.

При локальном запуске в Cloud Shell агент автоматически использует ваши активные учетные данные пользователя Google Cloud, поэтому у него уже есть необходимые разрешения для доступа к Vertex AI и Knowledge Catalog.

  1. Перейдите в каталог mcp_server , создайте виртуальное окружение и установите зависимости: 
cd ~/devrel-demos/data-analytics/governance-context/mcp_server

# Create a virtual environment using uv
uv venv
source .venv/bin/activate

# Install the dependencies listed in requirements.txt
uv pip install -r requirements.txt
  1. Начните интерактивный чат в терминале: 
adk run .
  1. После начала сессии вы увидите приглашение. Введите запрос для проверки логики управления агента: 
I need the Q1 revenue summary for our internal board meeting.

Агент обработает ваш запрос, выполнит запрос к Каталогу знаний через управляемый сервер MCP и выведет свои рекомендации и обоснование непосредственно в терминал.

  1. Чтобы выйти из интерактивной сессии, введите exit или quit (или нажмите Ctrl+C ). После выхода вы можете деактивировать виртуальную среду: 
deactivate

6. Разверните агент в производственной среде.

Теперь, когда вы проверили агента локально, вы готовы развернуть его в Google Cloud для использования в производственной среде.

Создайте учетную запись службы

В целях безопасности развернутый агент не должен работать с использованием ваших личных учетных данных. Мы создадим для агента отдельную учетную запись ( knowledge-catalog-agent-sa ), придерживаясь принципа минимальных привилегий.

Для создания учетной записи службы выполните следующие команды: 

export AGENT_SA=knowledge-catalog-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 Knowledge Catalog Agent"

Предоставить разрешения

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

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogAdmin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/viewer"

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

Наконец, мы развертываем агента в Cloud Run. Следующая команда создает образ контейнера, используя Dockerfile из текущего каталога, загружает его в Artifact Registry и развертывает в Cloud Run. Выполнение может занять от 1 до 3 минут. 

gcloud run deploy knowledge-catalog-agent \
  --source . \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated \
  --clear-base-image \
  --labels created-by=adk

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

12a5fa4c2aaf381f.png

7. Проверьте работу оператора в режиме реального времени.

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

Откройте в браузере URL-адрес сервиса, сгенерированный на предыдущем шаге (например, https://knowledge-catalog-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_entries с запросом: [PROJECT_ID].us-central1.official-data-product-spec.update_frequency=REALTIME_STREAMING
  3. Выборка: Она указывает, что таблица mkt_realtime_campaign_performance соответствует этим критериям.
  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?"

8. Уборка

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

Уничтожьте озеро данных.

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

cd ~/devrel-demos/data-analytics/governance-context
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

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

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

gcloud run services delete knowledge-catalog-agent --region=$REGION --quiet

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

При развертывании агента ADK система автоматически создавала образ контейнера и загружала ваш исходный код во временное хранилище Cloud Storage.

Удалите репозиторий 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, а затем удалите учетные записи служб. 

# 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

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

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

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

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

# Uninstall the AGY CLI plugin
agy plugin uninstall dataplex

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

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

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

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

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

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

Что дальше?