Управление рабочими нагрузками агентов с помощью 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 тесно интегрирован с остальной частью экосистемы:

• Реестр агентов : Центральная библиотека утвержденных агентов и инструментов (включая серверы 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

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

Начнём с настройки базовой сети, включая 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 ).

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

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

Если вы используете необязательный защищенный сетевой путь, укажите DOMAIN_NAME (например, agw.example.com); в противном случае можете его проигнорировать.

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"

terraform/backend.conf игнорируется Git. Каждый пользователь поддерживает свою собственную копию.

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

Пропустите этот шаг, если используете путь по умолчанию. Если вы хотите использовать простейшую настройку с общедоступными URL-адресами Cloud Run, перейдите непосредственно к следующему шагу.

По умолчанию в этой лабораторной работе конфигурация входящего трафика 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 автоматически — вам не нужно создавать ее вручную. При отключенной частной сети ни публичная, ни частная зона не создаются.

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

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:[e-mail]"]

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

Мы настроим IAP в режиме только аудита, чтобы проверить политику авторизации IAP без её принудительного применения. После проверки работоспособности развертывания мы изменим режим принудительного применения на null , чтобы обеспечить соблюдение политик.

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

Установите параметр 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"

Приведённые выше образы Cloud Run указывают на заглушку от Google. Это сделано намеренно — Terraform создаёт сервисы Cloud Run с lifecycle { ignore_changes = [template[0].containers[0].image] } , поэтому последующие вызовы skaffold run заменяют образ, не вызывая возражений со стороны Terraform.

Внутренний балансировщик нагрузки MCP предоставляет TLS для *.mcp.${DOMAIN_NAME} , используя тот же региональный сертификат, управляемый Google. Не устанавливайте mcp_internal_dns_zone.domain на немаршрутизируемый суффикс, например mcp-server.internal. при условии, что enable_agent_gateway = true И enable_cloud_run_private_networking = true .

В настоящее время Agent Gateway не проверяет самоподписанный резервный сертификат. Конфигурация Terraform обеспечивает это с помощью блока check во время планирования (пропускается, когда частная сеть отключена, поскольку нет сертификата балансировщика нагрузки для проверки).

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

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

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

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. . (с автоматическим добавлением)

Если у вас возникли проблемы с существующим бакетом Cloud Build, например Error 409: The requested bucket name is not available. The bucket namespace is shared by all users of the system вы можете импортировать этот существующий бакет в состояние Terraform, выполнив следующую команду: terraform import google_storage_bucket.cloudbuild ${PROJECT_ID}_cloudbuild

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

Только для справки. Команды в этом разделе уже были выполнены для вас модулем agent-registry-endpoints из Terraform. Они показаны, чтобы вы могли точно увидеть, как выглядит регистрация конечной точки, обнаруживаемой MCP.

Реестр агентов — это каталог сервисов для каждого проекта (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. Проверьте конфигурацию шлюза агента.

Только для справки. Terraform уже импортировал этот Agent Gateway. Приведенный ниже YAML-файл является точным эквивалентом файла terraform/modules/agent-gateway/main.tf .

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}

В текущей версии terraform-provider-google-beta файл network_config.dns_peering_config пока недоступен. Terraform применяет его через PATCH -запрос после применения изменений на networkservices.googleapis.com/v1beta1 . Вы увидите это в terraform_data.dns_peering в модуле.

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

Только для справки. Terraform уже создал оба расширения и обе политики. Приведенные ниже команды взяты непосредственно из terraform/modules/agent-gateway/main.tf .

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"
      }
    }
  }
}

Расширение Model Armor CONTENT_AUTHZ, указанное выше, автоматически подхватит эти расширенные шаблоны конфигурации при следующей оценке ответа — никаких изменений в расширении не требуется. Убедитесь, что агент службы Model Armor ( service-${PROJECT_NUMBER}@gcp-sa-modelarmor.iam.gserviceaccount.com ) имеет права доступа к roles/dlp.user и roles/dlp.reader в проекте (модуль model-armor от Terraform уже предоставляет эти права).

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

Вернитесь в корневой каталог демонстрационной версии:

cd ..

Подставьте значения шаблона:

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. Разверните ипотечного агента в среде выполнения агентов.

Предоставьте всем агентам роль IAP Egressor на всех конечных точках, зарегистрированных в реестре. Агенту необходим доступ к этим конечным точкам, поскольку при развертывании ему нужно получить доступ к github.com для загрузки пакетов, а затем к различным API Google, необходимым для развертывания.

./scripts/grant_agent_mcp_egress.sh --bind-all-agents --endpoints

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

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 \
  --mcp-invoker-sa=$(terraform -chdir=../../terraform output -raw agent_mcp_invoker_email) \
  --model-endpoint-location=global

Агент обнаруживает инструменты MCP во время выполнения , перечисляя mcpServers в реестре агентов по адресу projects/${PROJECT_ID}/locations/${REGION} .

После завершения выполнения скрипта скопируйте распечатанный reasoningEngines/ в вашу оболочку (например, 4262292559201566720):

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 || api.getAttribute('iap.googleapis.com/mcp.toolName', '') == ''" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

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

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

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

Если для каких-либо конечных точек нет политик, запустите скрипт со следующей конфигурацией: ./scripts/grant_agent_mcp_egress.sh --agent-id $AGENT_ID --endpoints

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

Безусловный доступ ко всем серверам 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 [e-mail]

Агент сможет успешно отправить электронное письмо , поскольку условная политика не применяется из-за того, что расширение IAP находится в режиме пробного запуска.

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

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

В Playground полностью обходится аутентификация Gemini Enterprise, что делает его самым быстрым местом для подтверждения корректного предоставления доступа к вызовам инструментов расширением IAP REQUEST_AUTHZ. Если инструмент возвращает ошибку 403, повторно запустите scripts/grant_agent_mcp_egress.sh перед дальнейшим отладочным анализом.

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 [e-mail]

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

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 [e-mail]

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

Если у вас настроена защита Model Armor для Gemini Enterprise, вам может потребоваться изменить конфигурацию базовой защиты конфиденциальных данных, поскольку шаблон Gemini Enterprise по умолчанию блокирует информационные типы типа FINANCIAL_ACCOUNT_NUMBER . Более подробную информацию можно найти в документации.

17. Панель мониторинга наблюдаемости

Панель мониторинга отладки авторизации предоставляет единое представление об исходящем трафике агентов среды выполнения.

На панели управления отображается следующее:

• Агент ➔ Конечная точка (ошибки 403)
• Агент ➔ Сервер MCP (ошибки 403)
• Агент ➔ Агент (Ошибка 403)
• Незарегистрированные исходящие блоки
• Обзор трафика и режим принудительного включения встроенных покупок
• Отказы в доступе к API IAM через GCP

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

• Блокировка незарегистрированных исходящих запросов — этот виджет специально изолирует трафик, заблокированный шлюзом агента, поскольку имя хоста назначения отсутствует в реестре агентов. Поскольку прокси-сервер шлюза блокирует эти запросы до того, как они достигнут IAP, для этих записей отсутствуют записи в журналах аудита IAP.
• Обзор трафика и режим принудительного применения IAP — Этот виджет предоставляет таблицу, отображающую все типы трафика. Что особенно важно, он включает в себя статус пробного запуска IAP, позволяя пользователям увидеть, блокируют ли политики IAP трафик или просто наблюдают за ним.
• Отказы в предоставлении доступа к API IAM через GCP — Этот виджет выполняет поиск в стандартных журналах аудита Cloud ( cloudaudit.googleapis.com ) для выявления ошибок предоставления доступа к API Google Cloud для агентов.

Эта панель мониторинга находится на вкладке «Наблюдаемость» в разделе «Шлюз агентов»: Agent Platform > Agents > Gateways > Specific Instance > Observability

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

Отладка с помощью ИИ и Gemini CLI

В Gemini CLI можно использовать навык agent-platform-debugger для устранения неполадок. Этот навык содержит специализированные знания для отладки с помощью ИИ. Поскольку Gemini CLI рассматривает .agents/skills/ как первоклассный псевдоним для .gemini/skills/ в рамках рабочей области, вы можете использовать навыки напрямую. Чтобы использовать этот навык из репозитория Codelab:

Перейдите в каталог репозитория и запустите Gemini CLI:

cd /path/to/cloud-networking-solutions/demos/agent-gateway
gemini

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

/skills list

В списке должен быть agent-platform-debugger . Если он отсутствует, перезагрузите навыки:

/skills reload

Советы по устранению неполадок

• 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 .

19. Уборка

Механизм логического вывода не управляется 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

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

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

Что вы узнали

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

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

• Обзор политик управления агентами
• Документация по Agent Gateway
• Документация, подтверждающая личность агента
• Обзор платформы Gemini Enterprise Agent