Управление рабочими нагрузками агентов с помощью Agent Gateway на платформе Gemini Enterprise Agent Platform.

1. Введение

Gemini Enterprise Agent Platform — это открытая платформа для создания, масштабирования, управления и оптимизации корпоративных агентов искусственного интеллекта, основанных на ваших данных.

Agent Runtime предоставляет управляемую среду выполнения для безопасного запуска агентов, например, созданных с использованием комплекта разработки агентов (ADK) с открытым исходным кодом, в Google Cloud.

В этом практическом занятии рассматривается, как использовать эти основные компоненты для управления агентом, запущенным пользователем в Gemini Enterprise, при его безопасном взаимодействии с внутренними инструментами.

О компании Agent Gateway

Agent Gateway — это сетевой компонент пакета Agent Governance платформы. Он выступает в качестве точки входа и выхода из сети для всех взаимодействий агентов, позволяя администраторам безопасности обеспечивать централизованное управление без необходимости для разработчиков управлять сложными сетевыми базовыми элементами.

Это обеспечивает два основных регулируемых пути доступа:

  • Взаимодействие между клиентом и агентом (входящий трафик): обеспечивает безопасность связи между внешними клиентами (такими как Cursor или Gemini CLI) и вашими агентами.
  • Agent-to-Anywhere (исходящий трафик): Обеспечивает безопасную связь между агентами, работающими в Google Cloud, и серверами, инструментами или API, работающими в любом месте.

В этом практическом занятии вы сосредоточитесь на режиме "Агент-в-любое место" (исходящий трафик) .

Контроль доступа с помощью Agent Gateway

Для обеспечения соблюдения политик безопасности Agent Gateway тесно интегрирован с остальной частью экосистемы:

  • Реестр агентов : Центральная библиотека утвержденных агентов и инструментов (включая серверы MCP сторонних производителей).
  • Идентификация агента : уникальная, отслеживаемая личность каждого агента, автоматически защищенная сквозным протоколом mTLS.
  • Identity-Aware Proxy (IAP) & IAM: Уровень принудительного исполнения по умолчанию, который проверяет личность агента на соответствие детальным разрешениям IAM, прежде чем разрешить вызовы определенных инструментов.
  • Model Armor : интегрированная через Service Extensions система защиты на основе искусственного интеллекта, предназначенная для очистки контента и защиты от атак с внедрением кода или утечки данных.

Режимы развертывания (публичная и частная сеть для Cloud Run)

Для обеспечения доступности данного практического занятия вы можете выбрать один из двух сетевых путей для ваших внутренних инструментов (серверов MCP), развернутых в Cloud Run:

  1. По умолчанию (публичный Ingress): Серверы MCP развернуты в Cloud Run с публичными именами хостов ( ingress=all ). Трафик от агента к инструментам направляется через стандартные URL-адреса *.run.app . Это не требует пользовательских DNS-доменов и является самым быстрым способом освоить концепции управления.
  2. Защищенная (частная сеть): опциональная, полностью приватная архитектура. Серверы MCP имеют ограниченный доступ ( ingress=internal-and-cloud-load-balancing ) и доступны через внутренний балансировщик нагрузки приложений с бессерверной архитектурой NEG. Для этого требуется наличие публичного DNS-домена для предоставления сертификата, управляемого Google.

При настройке Terraform вы выберете предпочтительный путь.

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

Что вы будете делать

  • Разверните основной стек инфраструктуры с помощью Terraform.
  • Создавайте и развертывайте внутренние инструменты в качестве серверов MCP на платформе Cloud Run.
  • Разверните агент ADK в Agent Runtime, используя исходящий трафик интерфейса PSC.
  • Настройте расширения службы Agent Gateway для доступа на основе идентификации (IAM) и проверки контента (Model Armor).
  • Отслеживание и проверка безопасного сквозного выполнения агента.

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

  • Веб-браузер, например Chrome.
  • Проект Google Cloud с включенной функцией выставления счетов и доступом владельца.
  • Разрешения IAM на уровне организации (в практическом задании предоставляются роли в рамках всей организации)
  • Домен, находящийся под вашим контролем и делегированный Cloud DNS (для управляемого публичного сертификата).
  • Знание Terraform, gcloud и основ работы с сетевыми ресурсами Google Cloud.

топология Codelab

Комплексная архитектура: Gemini Enterprise, Agent Runtime, Agent Gateway и серверы MCP на платформе Cloud Run.

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

Начнём с настройки базовой сети, включая VPC и внутренний балансировщик нагрузки приложений, сконфигурированный в качестве шлюза агентов. Затем развернем три сервера протокола контекста модели (MCP) в Cloud Run. Они будут выступать в качестве ваших внутренних проприетарных инструментов:

  • Управление документами ( legacy-dms )
  • Корпоративная электронная почта ( corporate-email )
  • Проверка дохода ( income-verification )

Имея необходимые инструменты, вы развернете помощника по ипотеке ( mortgage-agent ), созданного с помощью ADK, в среде выполнения агентов. Вы настроите этого агента для использования интерфейса PSC для частного исходящего трафика и включите обнаружение инструментов среды выполнения через реестр агентов.

Для обеспечения безопасности потока вам потребуется настроить Agent Gateway с помощью двух расширений службы. Во-первых, расширение REQUEST_AUTHZ будет проверять идентификацию агента на соответствие политикам IAM для каждого инструмента, гарантируя, что агент получает доступ только к авторизованным инструментам. Во-вторых, расширение CONTENT_AUTHZ , использующее Model Armor, будет проверять запросы и ответы агента.

Наконец, вам нужно будет зарегистрировать агента в Gemini Enterprise, запустить задачу по андеррайтингу ипотеки от имени конечного пользователя и проверить безопасное, контролируемое выполнение с помощью Cloud Trace.

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

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

Создайте проект и пройдите аутентификацию.

Создайте новый проект GCP (или используйте уже существующий) с включенной оплатой, а затем выполните аутентификацию в Cloud Shell или на локальном компьютере:

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

Включить API начальной загрузки

Базовый модуль Terraform активирует около 30 API при первом применении, но для terraform init и хранилища состояний GCS требуется небольшой набор параметров начальной загрузки:

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

Установите необходимые инструменты

Установите набор инструментов. В Cloud Shell большинство из них уже установлены; на рабочей станции:

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

Вам также потребуется Terraform >= 1.12.2 , Python 3.12+ и Google Cloud SDK ( gcloud ).

Установите переменные среды

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

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com"

Убедитесь, что все ваши переменные заполнены правильно; вы должны получить три возвращаемых значения.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

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

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. Клонируйте репозиторий. 

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

Краткий обзор содержимого демонстрационной папки:

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

4. Создайте хранилище состояния Terraform и конфигурацию бэкэнда.

Создайте корзину GCS для хранения удаленного состояния, затем скопируйте шаблон бэкэнда:

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

Отредактируйте terraform/backend.conf , указав свои значения: 

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

5. (Необязательно) Создайте публичную зону Cloud DNS.

По умолчанию в этой лабораторной работе конфигурация входящего трафика Cloud Run установлена ​​на all , и реестр агентов регистрирует каждый сервер MCP по его общедоступному URL-адресу *.run.app — никаких дополнительных DNS-серверов, сертификатов или балансировщиков нагрузки не требуется. Если вы хотите переключиться на частную сеть (Cloud Run с ingress = internal-and-cloud-load-balancing за внутренним балансировщиком нагрузки приложений), вам также потребуется общедоступная зона Cloud DNS, чтобы Certificate Manager мог проверить сертификат балансировщика нагрузки.

Высокоуровневый поток частной сети

Высокоуровневый поток данных в рамках опции частной сети

Для использования подхода с частной сетью:

  1. Создайте общедоступную зону Cloud DNS — менеджер сертификатов проверит региональный управляемый сертификат, записав в него записи CNAME: 
gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

Соответствующая частная зона для mcp.${DOMAIN_NAME} (используемая внутренним балансировщиком нагрузки MCP и DNS-пирингом из среды выполнения агента) создается Terraform автоматически — вам не нужно создавать ее вручную. При отключенной частной сети ни публичная, ни частная зона не создаются.

6. Настройка переменных Terraform

Скопируйте пример tfvars и отредактируйте его: 

cp terraform/example.tfvars terraform/terraform.tfvars

Существует два демонстрационных варианта, доступ к которым регулируется параметром enable_cloud_run_private_networking .

Путь по умолчанию: Cloud Run с публичным входом (ingress).

**Простейшая настройка.** Для пути по умолчанию вам нужно отредактировать всего три значения в файле terraform.tfvars . Для всех остальных переменных в файле уже есть подходящее для демонстрации значение по умолчанию. 

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:admin@example.com"]

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = "DRY_RUN"

Частная сеть (по желанию)

Установите параметр enable_cloud_run_private_networking = true и добавьте указанные ниже переменные для развертывания полного защищенного стека:

  • Внутреннее приложение LB
  • Сертификат, управляемый Google
  • Cloud Run с ingress = internal-and-cloud-load-balancing
  • DNS-пиринг Agent Gateway. 
enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

7. Развертывание инфраструктуры с помощью Terraform.

Инициализировать, проверить и применить: 

cd terraform
terraform init -backend-config=backend.conf
terraform plan
terraform apply

terraform apply выделяет около 40 ресурсов по пути по умолчанию и занимает 8–10 минут для нового проекта (примерно 60 ресурсов / 15–20 минут при enable_cloud_run_private_networking = true ). Она создает:

  • Основа проекта (API, идентификаторы сервисов, квоты)
  • VPC, подсети (основная, только прокси, PSC, интерфейс PSC, размещение Agent Gateway), Cloud NAT, правила брандмауэра.
  • Репозиторий Artifact Registry для образов Cloud Run
  • Три сервиса Cloud Run + SA для каждой службы (входящий трафик = all по умолчанию; internal-and-cloud-load-balancing при включенной частной сети)
  • Шаблон Model Armor + IAM
  • Agent Gateway, подключение к сети PSC-I, расширения IAP и Model Armor, обе политики авторизации, а также roles/iap.egressor .
  • Конечные точки реестра агентов (Vertex AI, IAP, Discovery Engine и т. д.) плюс три сервера MCP (по умолчанию зарегистрированы по адресу *.run.app/mcp ; по адресу . /mcp при включенной частной сети)

Только при enable_cloud_run_private_networking = true :

  • Внутренний региональный балансировщик нагрузки приложений с бессерверной архитектурой NEG (маршрутизация по маске URL) + частные DNS-записи A.
  • Частная DNS-зона MCP ( mcp. . прикреплены к VPC
  • Модуль публичной зоны DNS (авторизация DNS через диспетчер сертификатов) + региональный сертификат, управляемый Google.
  • Зона DNS интерфейса PSC (остаётся без разрешения, если нет частных имён хостов, поэтому она также ограничена флагом мастера).
  • Установление DNS-пиринга между Agent Gateway и mcp. . (с автоматическим добавлением)

8. Проверьте конечные точки реестра агентов.

Реестр агентов — это каталог сервисов для каждого проекта (API Google и ваши собственные серверы MCP), который агент обнаруживает во время выполнения. Ипотечный агент считывает его при запуске и динамически привязывает инструменты — URL-адреса MCP не встроены в код агента или его команду развертывания.

Конечные точки

Terraform выполнил от вашего имени следующие действия: для каждого API Google в agent_registry_google_apis он зарегистрировал пять вариантов (global, mTLS global, regional, regional mTLS, regional REP). Например, для aiplatform : 

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION}-rep \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Regional (REP)" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"

Серверы MCP

Terraform также регистрирует для вас 3 сервера MCP; для регистрации других серверов MCP вы можете следовать инструкциям в документации . 

gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC

Проверьте зарегистрированные конечные точки и серверы MCP. 

gcloud alpha agent-registry services list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

Источник: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl .

9. Проверьте конфигурацию шлюза агента.

Agent Gateway — это управляемая Google платформа управления между Agent Runtime и вашими инструментами. В режиме AGENT_TO_ANYWHERE она привязана к реестру агентов проекта и выходит через принадлежащий клиенту интерфейс PSC, чтобы иметь доступ к частным серверам MCP в вашей VPC.

Если бы вы импортировали этот шлюз вручную, файл YAML выглядел бы так: 

# agent-gateway.yaml — for reference only, Terraform already created this
name: agent-gateway
protocols: [MCP]
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJECT_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/agent-gateway-na
  dnsPeeringConfig:
    domains:
      - mcp.${DOMAIN_NAME}.
    targetProject: ${PROJECT_ID}
    targetNetwork: projects/${PROJECT_ID}/global/networks/gateway-vpc

gcloud alpha network-services agent-gateways import agent-gateway \
  --source=agent-gateway.yaml \
  --location=${REGION}

Проверьте шлюз, созданный Terraform: 

gcloud alpha network-services agent-gateways describe agent-gateway \
  --location=${REGION}

10. Изучите разрешения на использование IAP и Model Armor.

Agent Gateway делегирует полномочия по авторизации расширениям служб . Демонстрация включает два профиля политик:

  • REQUEST_AUTHZ — проверяется один раз для каждого запроса на этапе заголовков. Используется здесь для вызова IAP , который проверяет, имеет ли идентификатор вызывающего агента roles/iap.egressor на целевом сервере MCP.
  • CONTENT_AUTHZ — передает события тела запроса в расширение для очистки контента. Здесь используется для вызова Model Armor , который проверяет наличие внедрения запросов, взломов, нарушений RAI и (опционально) персональных данных через защиту конфиденциальных данных (SDP).

Расширение IAP REQUEST_AUTHZ 

cat > iap-authz-extension.yaml <<EOF
name: agent-gateway-iap-authz
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-iap-authz \
  --source=iap-authz-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

Привяжите его к шлюзу агентов с помощью политики REQUEST_AUTHZ : 

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-iap-policy" \
  -d '{
    "name": "agent-gateway-iap-policy",
    "policyProfile": "REQUEST_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-iap-authz"
        ]
      }
    }
  }'

Расширение Model Armor CONTENT_AUTHZ

В файле metadata.model_armor_settings расширения содержатся идентификаторы шаблонов запроса и ответа, которые Model Armor использует для оценки каждого вызова: 

cat > ma-extension.yaml <<EOF
name: agent-gateway-ma-authz
service: modelarmor.${REGION}.rep.googleapis.com
failOpen: true
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id":  "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-request-template",
      "response_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-response-template"
    }
  ]'
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-ma-authz \
  --source=ma-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-ma-policy" \
  -d '{
    "name": "agent-gateway-ma-policy",
    "policyProfile": "CONTENT_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-ma-authz"
        ]
      }
    }
  }'

Пользовательские шаблоны DLP

В Model Armor sdpSettings.basicConfig использует встроенный список типов информации. Для более точного управления (пользовательские типы информации, частичное маскирование, замена суррогатов, редактирование по вероятности) укажите Model Armor на ваши собственные шаблоны Cloud DLP для проверки и обезличивания данных с помощью sdpSettings.advancedConfig .

Создайте шаблон проверки, который помечает номера социального страхования США с вероятностью POSSIBLE или выше: 

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates" \
  -d '{
    "templateId": "agw-ssn-inspect-template",
    "inspectTemplate": {
      "displayName": "SSN Inspect Template",
      "inspectConfig": {
        "infoTypes": [
          { "name": "US_SOCIAL_SECURITY_NUMBER" }
        ],
        "minLikelihood": "POSSIBLE"
      }
    }
  }'

Создайте шаблон для обезличивания данных, который заменяет каждый обнаруженный факт токеном соответствующего информационного типа (например, [US_SOCIAL_SECURITY_NUMBER] ): 

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates" \
  -d '{
    "templateId": "agw-ssn-redaction-template",
    "deidentifyTemplate": {
      "displayName": "SSN Redaction Template",
      "deidentifyConfig": {
        "infoTypeTransformations": {
          "transformations": [{
            "primitiveTransformation": { "replaceWithInfoTypeConfig": {} }
          }]
        }
      }
    }
  }'

Затем укажите конфигурацию ответа шаблона Model Armor на эту пару через sdpSettings.advancedConfig (именно здесь модуль model_armor Terraform устанавливал бы advanced_config если бы вы его подключили): 

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate":    "projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template",
        "deidentifyTemplate": "projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template"
      }
    }
  }
}

IAM для выхода из IAP (только для каждого MCP-сервера)

Terraform не создает общепроектную привязку roles/iap.egressor к неявному реестру агентов IAP. Фактическая привязка IAP REQUEST_AUTHZ предназначена для каждого MCP-сервера и каждого механизма рассуждений и предоставляется после развертывания агента и при условии, что известен идентификатор агента. Шаг "Предоставить агенту исходящий трафик для каждого MCP-сервера" запускает scripts/grant_agent_mcp_egress.sh для этого.

11. Создайте и разверните серверы MCP в Cloud Run.

Файлы cloudrun/*.yaml.tmpl и skaffold.yaml.tmpl ссылаются на ${PROJECT_ID} , ${REGION} и ${MCP_INGRESS} (аннотация входящего трафика Cloud Run). Используйте MCP_INGRESS из выходных данных Terraform, чтобы сгенерированные манифесты оставались синхронизированными с enable_cloud_run_private_networking , затем выполните рендеринг с помощью envsubst :

Экспортируйте конфигурацию входящего трафика Cloud Run.

  • all
  • internal-and-cloud-load-balancing (при использовании подхода частной сети) 
export MCP_INGRESS=all

envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
  envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done

Каждая служба Cloud Run запускается от имени созданного Terraform сервиса среды выполнения (например, mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com ). Для развертывания от имени этих сервисов вам потребуется добавить в свою учетную запись roles/iam.serviceAccountUser : 

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountUser"

Сборка осуществляется с помощью Cloud Build, а развертывание — с помощью Skaffold: 

skaffold run

Skaffold создает три образа ( legacy-dms , corporate-email , income-verification-api ) в вашем репозитории Artifact Registry и обновляет каждую службу Cloud Run, чтобы она указывала на новый дайджест.

Проверять: 

gcloud run services list --region=${REGION}

Все три сервиса должны отображаться со статусом ACTIVE .

12. Разверните ипотечного агента в среде выполнения агентов.

Установите зависимости агента и выполните развертывание: 

cd src/mortgage-agent
uv sync

uv run python deploy_agent.py \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --enable-agent-identity \
  --agent-name=mortgage-agent \
  --agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
  --model-endpoint-location=global

После завершения выполнения скрипта скопируйте распечатанный reasoningEngines/ в свою скорлупу: 

export AGENT_ID=<numeric-id-from-output>
cd ../..

13. Предоставьте агенту исходящий доступ к каждому MCP-серверу.

Расширение IAP REQUEST_AUTHZ авторизует каждый вызов инструмента, проверяя roles/iap.egressor на конкретном сервере MCP или конечной точке, к которой он обращается. См. раздел «Создание политики исходящего трафика от агента к серверу MCP» .

Скрипт ( scripts/grant_agent_mcp_egress.sh ) перечисляет серверы MCP в реестре агентов в projects/${PROJECT_ID}/locations/${REGION} и объединяет привязку roles/iap.egressor для основного агента с политикой IAM каждого сервера (зеркально отображая семантику gcloud add-iam-policy-binding ).

Вариант использования 1 — Безусловный доступ, ограниченный определенными серверами MCP. 

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "legacy-dms income-verification"

Вариант использования 2 — Условное предоставление прав (CEL), ограниченное конкретным сервером MCP.

Чтобы ограничить доступ агента к определенному набору инструментов на одном сервере MCP, добавьте условие IAM. Шлюз агента публикует атрибуты для каждого инструмента, которые IAP REQUEST_AUTHZ предоставляет CEL, включая:

  • iap.googleapis.com/mcp.toolName
  • iap.googleapis.com/mcp.tool.isReadOnly
  • iap.googleapis.com/request.auth.type .

Ограничьте доступ агента к инструментам только для чтения в corporate-email : 

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "corporate-email" \
  --condition-expression "api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

После выполнения этой команды инструменты для записи на corporate-email возвращают ошибку 403 PermissionDenied от IAP REQUEST_AUTHZ; инструменты только для чтения продолжают работать.

Проверьте привязки.

Перейдите на вкладку «Политики» , и вы увидите список политик, созданных для конечных точек и серверов MCP.

Дополнительные варианты использования:

Безусловный доступ ко всем серверам MCP, ограниченный одним агентом.

Выполняйте это после каждого переразвертывания агента. Без фильтра и без условий именованный агент получает roles/iap.egressor на каждом сервере MCP в реестре: 

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID}

14. Протестируйте агента в консоли платформы агента.

Консоль Agent Platform поставляется с Playground, который позволяет напрямую общаться с развернутым агентом. Это самый быстрый способ провести тестирование инструментов и проверить трассировку перед подключением агента к Gemini Enterprise.

  1. Откройте страницу «Развертывание платформы агентов» в консоли Google Cloud.
  2. Используйте поле «Фильтр» , если вам нужно сузить список доступных временных интервалов, затем выберите временной интервал вашего mortgage-agent .
  3. Откройте вкладку «Игровая площадка» .
  4. Введите команду, чтобы пообщаться с оператором в чате: 
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

В результате должны появиться ответы от инструмента управления документами и инструмента проверки доходов; номера социального страхования также должны быть скрыты в этом ответе. 5. Введите дополнительный запрос: 

Can you send a summary of this to my email jane@example.com

Агент должен указать, что у него нет доступа к инструменту send_email, и дать соответствующий ответ.

Поскольку агент был развернут с использованием инструментария OpenTelemetry, в Playground отображаются четыре боковых панели, между которыми можно переключаться по мере ответа агента:

  • Трассировка — полная трассировка разговора, включая диапазоны Agent Gateway, IAP REQUEST_AUTHZ и Model Armor CONTENT_AUTHZ.
  • Событие — граф задействованных инструментов и подробная информация о событии для текущего хода.
  • Состояние — состояние сессии агента и входные/выходные данные инструмента.
  • Сессии — все сессии, которые вы запустили в рамках этой среды выполнения.

15. Обеспечить авторизацию IAP.

Теперь, когда мы проверили развертывание, мы можем изменить режим принудительного применения IAP на null , чтобы обеспечить соблюдение политик. Откройте файл terraform.tfvars и измените режим с DRY_RUN на null 

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = null

Внесите изменения.

terraform apply

Вернитесь на игровую площадку и попробуйте продолжить разговор.

  1. Откройте страницу «Развертывание платформы агентов» в консоли Google Cloud.
  2. Используйте поле «Фильтр» , если вам нужно сузить список доступных временных интервалов, затем выберите временной интервал вашего mortgage-agent .
  3. Откройте вкладку «Игровая площадка» .
  4. Введите команду, чтобы пообщаться с оператором в чате: 
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

В результате должны появиться ответы от инструмента управления документами и инструмента проверки доходов; номера социального страхования также должны быть скрыты в этом ответе. 5. Введите дополнительный запрос: 

Can you send a summary of this to my email jane@example.com

Если все настроено правильно, агент должен ответить, что не может отправить электронное письмо из-за политики авторизации.

16. Настройка и тестирование Gemini Enterprise

Настройка Gemini Enterprise

Следуйте инструкциям в руководстве по началу работы с Gemini Enterprise .

Зарегистрируйте нашего агента ADK в Gemini Enterprise.

Чтобы зарегистрировать нашего агента в Gemini Enterprise, выполните следующие шаги (инструкции можно найти здесь) .

  1. В консоли Google Cloud перейдите на страницу Gemini Enterprise .
  2. Выберите приложение Gemini Enterprise, в котором зарегистрирован агент.
  3. Откройте URL-адрес, указанный в разделе «Ваше веб-приложение Gemini Enterprise готово» .
  4. Чтобы открыть галерею агентов , выберите вкладку «Агент» в меню слева.
  5. Выберите «Помощник ипотечного агента» и начните чат.

Попробуйте выполнить те же действия, что и в среде выполнения Agent Runtime Playground:

Первоначальный запрос: 

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Дополнительная подсказка: 

Can you send a summary of this to my email jane@example.com

Если вы вернетесь в раздел «Развертывание агентов» в консоли, выберете наше развертывание агентов и перейдете на вкладку «Трассировки» , вы увидите агента Gemini Assistant в трассировке, показывающей, что вызов был инициирован из Gemini Enterprise.

17. Поиск и устранение неисправностей и распространенные способы их исправления.

  • terraform apply завершается с ошибкой на Agent Gateway: «Ресурс находится в процессе создания и поэтому не может быть обновлен» — для завершения работы над проектом клиента шлюза требуется около 30 секунд, прежде чем можно будет подключить политики аутентификации. Модуль ` time_sleep.wait_for_gateway решает эту проблему; просто перезапустите terraform apply .
  • Агент сообщает об отсутствии серверов MCP или загружается только с помощью утилит — подтвердите, enable_agent_registry_endpoints = true в terraform.tfvars , после чего:
    gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION}
    Вы должны увидеть три записи (по одной на каждую службу Cloud Run MCP). Если список пуст, проверьте, доступны ли службы MCP изнутри VPC и заполнил ли Agent Gateway реестр (он делает это отложенно при первом списке инструментов, подключенных через прокси).
  • Вызовы инструментов возвращают ошибку 403 PermissionDenied — повторно запустите scripts/grant_agent_mcp_egress.sh . Наиболее распространенная причина — забыть повторно предоставить права доступа после повторного развертывания агента ( reasoningEngines/ (изменяется при каждом развертывании).
  • skaffold run завершается с ошибкой «отказано в доступе к учетной записи службы» — отсутствует roles/iam.serviceAccountUser . Повторно выполните предоставление прав доступа, описанное на предыдущем шаге.
  • Ошибки DNS-пиринга от Agent Gateway к MCP LB — убедитесь, что agent_gateway_dns_peering_config.target_network точно соответствует projects/${PROJECT_ID}/global/networks/${VPC_NAME} , и что каждая запись domains заканчивается точкой.
  • terraform plan постоянно пытается обновить теги образа Cloud Run — этого не должно происходить из-за правила lifecycle { ignore_changes } . Если это всё же происходит, убедитесь, что вы не редактировали mcp_services[*].image в файле terraform.tfvars после skaffold run .

18. Уборка

Механизм логического вывода не управляется Terraform (он создается SDK ADK). Удалите его вручную: 

gcloud beta ai reasoning-engines delete ${AGENT_ID} \
  --region=${REGION} --project=${PROJECT_ID}

Удалите всё, что создала Terraform: 

cd terraform
terraform destroy
cd ..

Если вы создали публичную DNS-зону специально для этого практического занятия: 

gcloud dns managed-zones delete agw-example-com

Наконец, удалите хранилище состояния Terraform: 

gcloud storage rm -r gs://${PROJECT_ID}-tfstate

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

Поздравляем! Вы успешно внедрили комплексное управление агентами для многофункционального ADK-агента с помощью Agent Gateway. Выступая в качестве централизованной плоскости управления сетью, Agent Gateway позволил вам установить безопасный исходящий канал связи с частными инструментами, обеспечить соблюдение детальных политик IAM на основе идентификации через Identity-Aware Proxy и очистить взаимодействие с контентом с помощью интегрированных механизмов защиты Model Armor.

Что вы узнали

  • Как развернуть и настроить Agent Gateway в качестве центрального уровня управления исходящим трафиком от агента к любому серверу.
  • Как интегрировать реестр агентов для управляемого, динамического обнаружения инструментов во время выполнения.
  • Как создавать и применять политики IAM для каждого инструмента и на основе условий, чтобы строго контролировать пути выполнения агентов.
  • Как использовать расширения службы Agent Gateway для применения политик Model Armor, автоматически перехватывая и редактируя конфиденциальный трафик агентов.

Справочная документация