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

Выход Agent Gateway из среды выполнения Agent Runtime на внешний MCP.

1. Введение

В этом практическом занятии рассматривается управление исходящим трафиком через Agent Gateway для агентов ИИ, обращающихся к внешним серверам протокола контекста модели (MCP), размещенным за пределами Google Cloud.

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

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

Когда Agent Gateway работает в режиме исходящего трафика ( агент — куда угодно ), он перенаправляет все исходящие запросы от агентов, настроенных на использование шлюза. Каждый запрос рабочей нагрузки агента аутентифицируется с использованием уникального идентификатора агента и авторизуется с помощью политик Identity-Aware Proxy (IAP) . Вызовы инструментов MCP динамически декодируются и проверяются на предмет применения политик. Администраторы безопасности могут централизованно устанавливать детальные разрешения, чтобы гарантировать, что агенты могут вызывать только утвержденные конечные точки и методы.

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

Шлюз агентов в режиме исходящего трафика ( агент — куда угодно ).
Расширение авторизации Identity-Aware Proxy (IAP)
Агент Agent Runtime ADK с идентификацией агента
Реестр агентов с использованием Google API и конечных точек MCP.
Внешнее подключение инструмента MCP к общедоступным наборам данных Data Commons.
Политики авторизации с контролем доступа IAM

рисунок1

Рис. 1. Архитектура Codelab

Чему вы научитесь

Как развернуть Agent Gateway в структурированной последовательности конфигурации
Как перевести политики авторизации из тестового режима в режим принудительного применения.
Как зарегистрировать конечные точки Google API и серверы MCP в реестре агентов.
Как использовать политики условной авторизации на основе атрибутов протокола MCP
Как проводить аудит журналов Agent Gateway для проверки управления исходящим трафиком.

Что вам нужно

Проект Google Cloud с включенной функцией выставления счетов.
Разрешения IAM для предоставления сетевых служб и ресурсов платформы агентов.
POSIX-совместимая оболочка ( bash или zsh ) с установленным Google Cloud CLI (компоненты gcloud и bq ).
Инструменты командной строки: git , curl , jq (процессор JSON), Python 3 и uv (менеджер пакетов Python).
Бесплатный ключ API Data Commons для доступа к тестовым наборам данных для запросов.

2. Понятия

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

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

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

Запуск в режиме DRY_RUN : Убедитесь, что запросы агента успешно поступают на шлюз и проходят через него (режим только аудита).
Зарегистрируйте все сервисы: зарегистрируйте все компоненты агента в реестре агентов и подтвердите доступ к инструментам агента.
Создание политик авторизации: Создайте и примените политики авторизации, разрешающие исходящий трафик от агентов к серверам и конечным точкам MCP.
Переключитесь в режим ENFORCED : обновите политику расширения авторизации, чтобы обеспечить соблюдение правил и заблокировать несанкционированный исходящий трафик.

рисунок 2

Рис. 2. Последовательность развертывания

Топология исходящей маршрутизации

Agent Gateway egress ( от агента к любому месту ) действует как централизованный прокси-сервер с нулевым доверием для исходящих запросов к агентским рабочим нагрузкам. Когда агент отправляет запрос к внешнему инструменту или API, исходящий запрос перехватывается Agent Gateway и оценивается на соответствие политикам управления, прежде чем быть направленным к месту назначения. В архитектуре Google Cloud Agent Platform Agent Gateway обеспечивает подключение к плоскости данных для:

Частные сети (VPC): исходящий трафик, ориентированный на внутренние корпоративные API, микросервисы, базы данных, размещенные в частных VPC, а также локальные или межоблачные сети, доступные через гибридное соединение.
Внешние сети (Интернет): Исходящий трафик, направленный на сторонние веб-сервисы, API SaaS или общедоступные конечные точки.
Сервисы ИИ и платформа агентов: исходящий трафик, ориентированный на управляемые API Google Cloud, базовые модели, конечные точки Google MCP (например, BigQuery) и сервисы управления платформой (реестр агентов и политики IAP).

рисунок3

Рис. 3. Топология маршрутизации исходящего трафика шлюза агента.

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

проверка протокола MCP

Исходящий трафик через Agent Gateway ( агент-в-любое место ) способен анализировать содержимое запросов MCP и оценивать политики доступа на основе детальных атрибутов протокола. Политики исходящего трафика от Agent к серверу MCP могут включать условия, выраженные на языке выражений Common Expression Language (CEL) , которые применяются во время выполнения к каждому запросу.

Вызовы MCP обычно используют формат протокола передачи данных JSON-RPC и транспорт HTTP. Подробная информация о вызываемом методе MCP (например, tools/call ), имя целевого инструмента и любые аргументы содержатся в полезной нагрузке JSON в теле HTTP-запроса.

Атрибут iap.googleapis.com/mcp.toolName извлекается Agent Gateway путем анализа тела JSON-запроса для поиска идентификатора инструмента, указанного в запросе.

Атрибуты типа iap.googleapis.com/mcp.tool.isReadOnly и mcp.tool.isDestructive обычно не передаются в теле каждого запроса. Вместо этого это аннотации (метаданные), связанные с инструментом. Поэтому, когда Agent Gateway извлекает toolName из тела запроса, он ищет определение инструмента и связанные с ним свойства в Agent Registry, где было зарегистрировано содержимое toolspec.json .

рисунок4

Рис. 4. Проверка MCP Agent Gateway.

Выражения CEL, используемые в условиях IAM в IAP, используют стандартный формат api.getAttribute('iap.googleapis.com/ATTRIBUTE_NAME', 'DEFAULT_VALUE')== 'DESIRED_VALUE' .

В этой таблице описаны атрибуты управления исходящим трафиком Agent Gateway, которые могут применяться к запросам к серверу MCP:

Атрибут	Метод/местоположение MCP	Описание
`mcp.toolName`	`tools/call` (Тело)	Идентификатор целевого инструмента, запрашиваемый в полезной нагрузке RPC (например, `"delete_instance"` )
`mcp.tool.isReadOnly`	Реестр агентов ( `toolspec.json` )	Указывает, является ли инструмент доступным только для чтения (не изменяет свою среду).
`mcp.tool.isDestructive`	Реестр агентов ( `toolspec.json` )	Указывает, может ли использование инструмента привести к необратимым изменениям или потере данных.
`mcp.tool.isIdempotent`	Реестр агентов ( `toolspec.json` )	Указывает, приводит ли повторное выполнение инструмента с одинаковыми аргументами к одному и тому же результату.
`mcp.tool.isOpenWorld`	Реестр агентов ( `toolspec.json` )	Указывает, распространяется ли действие инструмента за пределы ограниченных внутренних систем и охватывает ли он неограниченный общедоступный интернет.

На этом завершается раздел, посвященный концепциям... далее переходим к разделу «Настройка» .

3. Настройка

Необходимые роли IAM

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

Категория	Требуемая роль IAM (ID)	Описание
управление API	`roles/serviceusage.serviceUsageAdmin`	Включите сервисы Google Cloud API
Сетевые устройства и шлюзы	`roles/networkservices.admin`	Шлюз агента предоставления услуг
Расширения сервисов	`roles/serviceextensions.admin`	Настройка расширений маршрутизации
Сетевая безопасность	`roles/networksecurity.admin`	Разверните политики авторизации.
Реестр агентов	`roles/agentregistry.admin`	Каталог разрешенных хостов
Vertex AI и агенты	`roles/aiplatform.admin`	Развертывание рабочих нагрузок среды выполнения агента
Политика выхода	`roles/iap.admin`	Применить политики `roles/iap.egressor`
Облачное хранилище	`roles/storage.admin`	Управление тестовыми хранилищами для развертывания
Журналы и аудит	`roles/logging.viewer`	Проверьте трассировки и журналы аудита.

В качестве альтернативы можно использовать общую базовую роль, например, roles/admin или устаревшую роль roles/owner .

Получите доступ к своему проекту

В этом практическом занятии используется один проект Google Cloud. Шаги настройки выполняются с помощью командной строки gcloud и команд оболочки Linux.

Для начала откройте командную строку вашего проекта Google Cloud:

Cloud Shell доступен по адресу shell.cloud.google.com или
Локальный терминал с установленным интерфейсом командной строки gcloud

Укажите идентификатор вашего проекта.

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Аутентификация сессии

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Установка переменных среды оболочки

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-datacommons"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
export MCP_DISPLAY_NAME="api.datacommons.org"
export MCP_RESOURCE_NAME="${REGION}-datacommons-mcp"
export MCP_URL="https://api.datacommons.org/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_RESOURCE_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

Обновите интерфейс `gcloud cli` (рекомендуется).

Если вы используете самостоятельную установку Google Cloud SDK (т.е. вне Cloud Shell), обновите компоненты до последней версии.

# update gcloud cli
gcloud components update

Включить API-сервисы

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

На этом завершается этап настройки... далее переходим к разделу «Шлюз» .

4. Шлюз

Перед применением контроля доступа разверните Agent Gateway и настройте его расширение авторизации в режиме DRY_RUN . Это позволит успешно выполнять исходящие вызовы инструментов, одновременно регистрируя результаты оценки для целей аудита.

Здесь Agent Gateway использует региональный реестр для поддержки региональных ресурсов среды выполнения агентов.

Создать шлюз

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}.yaml" \
  --location=${REGION}

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

На этом завершается раздел, посвященный шлюзу... далее переходим к разделу «Авторизация» .

5. Авторизация

Расширение авторизации Agent Gateway для Identity-Aware Proxy (IAP) — это тип расширения службы , используемый для делегирования решений по авторизации для всех коммуникаций Agent Platform .

Процесс делегирования: Когда агент пытается вызвать внешнюю конечную точку или сервер MCP, он перенаправляет запрос в Agent Gateway. Вместо локальной оценки доступа шлюз использует расширение авторизации для отправки вызова в службу оценки IAP. IAP оценивает идентификатор агента ( на основе SPIFFE ) в соответствии с политикой IAM целевого ресурса в реестре агентов. IAP возвращает шлюзу решение ALLOW или DENY , после чего шлюз либо перенаправляет трафик дальше, либо блокирует его с кодом состояния HTTP 403 Forbidden .
Режимы принудительного применения: В режиме DRY_RUN IAP оценивает запросы и регистрирует решения в Cloud Logging, не блокируя трафик. В режиме ENFORCE любой запрос от неавторизованного агента или к незарегистрированному целевому объекту немедленно блокируется.
Уровень привязки: Расширение сервиса подключается к Agent Gateway с помощью политики авторизации , настроенной с использованием профиля REQUEST_AUTHZ .

Расширение авторизации

Создать расширение авторизации

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

# show authz extension details (verify extension state)
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

Политика авторизации

Политика авторизации привязывает поставщика безопасности (IAP) к целевому ресурсу шлюза и определяет профиль перехвата ( REQUEST_AUTHZ ).

Создать политику авторизации

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

# show authz policy details (verify dry run mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

На этом завершается раздел, посвященный авторизации... далее переходим к разделу «Кодовая база» .

6. Кодовая база

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

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

Получение удаленных артефактов

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_emcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_emcp/codelabs/agw-cuj-arun-egress-emcp/agent-datacommons ./agent-datacommons
cp -r temp_agw_cuj_arun_egress_emcp/codelabs/agw-cuj-arun-egress-emcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_emcp

Создать временный контейнер

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

На этом завершается раздел, посвященный коду... далее переходим к разделу «Реестр» .

7. Реестр

Реестр агентов представляет собой централизованный каталог всех агентов, серверов MCP и конечных точек (API) в экосистеме ИИ. Он также является каталогом, который можно использовать для перечисления, поиска и обнаружения других зарегистрированных инструментов и сервисов для использования приложениями ИИ. Режим исходящего трафика Agent Gateway ( агент-в-любое место ) использует модель данных реестра в качестве основы управления для обеспечения контроля доступа к исходящему трафику. Предоставление ролей IAM для вызывающих агентов проверяется на соответствие политике, привязанной к ресурсу реестра.

Для инициализации среды и поддержки агентов, использующих различные API и сервисы Google , используется скрипт, позволяющий быстро зарегистрировать общий набор конечных точек API, используя имена хостов и местоположения из endpoints/googleapis.txt .

Регистрация конечных точек

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

Проверьте конечные точки

# list registry regional endpoints (verify registration)
gcloud agent-registry endpoints list --location=${REGION} \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces[0].url:label=URL)"

На этом завершается раздел, посвященный реестру... далее переходим к разделу «Общие ресурсы данных» .

8. Центры обработки данных

Data Commons — это инициатива Google по организации общедоступных наборов данных и предоставлению к ним доступа любому желающему. Это бесплатный сервис, доступ к которому можно получить с помощью ключа API после создания учетной записи .

Создать ключ API

После создания учетной записи выполните следующие шаги, чтобы получить ключ API:

Войдите в портал API Data Commons.
Нажмите кнопку « Мои приложения » в правом верхнем углу.
Нажмите кнопку " + НОВОЕ ПРИЛОЖЕНИЕ " в правом верхнем углу под вашим именем пользователя.
Дайте своему приложению имя (например, "Codelab Agent MCP")
Нажмите кнопку « ВКЛЮЧИТЬ » для доступа к API Data Commons api.datacommons.org
Нажмите кнопку « СОХРАНИТЬ » в правом нижнем углу.

Это создаст ключ и секрет API. Нажмите значок «копировать» рядом со значением ключа, чтобы « Скопировать ключ API ». Вставьте значение в командную строку терминала, чтобы установить переменную среды DC_API_KEY .

# set api key env var
 export DC_API_KEY="YOUR_API_KEY_HERE"

Создать `toolspec` сервера MCP

При ручной регистрации сервера MCP необходимо включить файл спецификации инструментов. Загрузка файла toolspec.json позволяет перечислить все инструменты, доступные через конечную точку, и дает другим пользователям возможность их обнаружить.

Скрипт test_mcp.py , входящий в состав кода agent-datacommons/ , генерирует файл toolspec.json , подключаясь к целевому MCP-серверу (через SSE или HTTP), и вызывает list_tools() для получения всех доступных инструментов, предоставляемых сервером.

# generate toolspec for registry ingestion
uv --directory agent-datacommons run python3 test_mcp.py --toolspec=include --token="${DC_API_KEY}"

Анализ сгенерированного toolspec показывает, какие атрибуты MCP может использовать Agent Gateway для оценки и применения политик исходящего трафика.

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' agent-datacommons/toolspec.json

Зарегистрировать сервер MCP

# register mcp server
gcloud agent-registry services create ${MCP_RESOURCE_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for data commons" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=agent-datacommons/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_RESOURCE_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_RESOURCE_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

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

9. Среда выполнения

Агент agent-datacommons ADK, развернутый в Agent Runtime, настроен в скрипте развертывания со следующими параметрами для интеграции с Agent Platform:

"identity_type": types.IdentityType.AGENT_IDENTITY для предоставления уникального основного идентификатора на основе SPIFFE для агента
"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } для направления всего исходящего трафика, инициированного агентом, на Agent Gateway для оценки и применения политик.

Развернуть агент

# deploy agent runtime workload
uv --directory agent-datacommons run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for data commons stats" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --env-var="DC_API_KEY=${DC_API_KEY}"

Получение основных параметров развертывания

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET \
  "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

Проверьте запись в реестре.

# show agent resource registry details
gcloud agent-registry agents describe ${RE_AGENT_REGISTRY_ID} --location=${REGION}

10. Политика

Политики авторизации управления агентом разрешают трафик от ИИ-агента через Agent Gateway и далее к месту назначения (например, к конечной точке стороннего MCP-сервера для SaaS-приложения). После того, как трафик достигнет места назначения, доступ к данным предоставляется на основе стандартных разрешений на уровне сервиса или приложения.

Предоставление ролей IAM для исходящего трафика Agent Gateway включает политики доступа, которые позволяют субъекту-агенту получать доступ к зарегистрированным целевым ресурсам через Agent Gateway. Политики применяются на уровне Agent Gateway и проверяются с помощью политик IAM Identity-Aware Proxy (IAP).

Предоставьте агенту роли IAM для исходящего трафика через Agent Gateway.

Agent Gateway проверяет входящие запросы, чтобы убедиться, что у вызывающего агента есть разрешение iap.webServiceVersions.egressViaIAP (предоставляемое ролью roles/iap.egressor ) на целевой ресурс.

Предоставление roles/iap.egressor идентификатору агента или набору субъектов среды выполнения агента для выбранного целевого ресурса разрешает исходящий трафик. В этом практическом задании роль применяется к основному агенту , предоставляя разрешение конкретному идентификатору агента среды выполнения агента.

Политики IAM привязаны к целевым ресурсам, определенным в модели данных Agent Registry. Ресурс iap_web/agentRegistry представляет собой уровень в иерархии IAM , охватывающий весь реестр . agentRegistry служит родительским ресурсом для отдельных дочерних ресурсов для agents , mcpServers и endpoints . В этом практическом задании политика IAM привязана к уровням mcpServer и конечных точек , которые применяют разрешения к конкретным дочерним ресурсам.

О фильтрации условного MCP

Сервер Data Commons MCP содержит два инструмента:

search_indicators : для запросов, касающихся определения доступных данных, поиска переменных или оценки охвата данных.
get_observations : используется для запросов на получение конкретных точек данных или временных рядов.

При настройке условных политик управления на серверах MCP следует учитывать некоторые стандартные операции MCP. Прежде чем клиент MCP сможет выполнить tools/call для search_indicators или get_observations , он должен сначала отправить запросы на установление соединения и обнаружение протокола:

initialize
notifications/initialized
tools/list

Для демонстрации фильтрации по условиям политики, политика будет настроена на следующие условия:

Таблица. Оценка политики обработки запросов MCP.

Запрос / Метод	Значение `mcp.toolName`	Оценка CEL	Результат
`initialize`	`""`	`"" in ['search_indicators', '']`	✅ РАЗРЕШЕНО (200)
`tools/list`	`""`	`"" in ['search_indicators', '']`	✅ РАЗРЕШЕНО (200)
`search_indicators`	`"search_indicators"`	`"search_indicators" in [...]`	✅ РАЗРЕШЕНО (200)
`get_observations`	`"get_observations"`	`"get_observations" in [...]`	❌ ОТКАЗАНО (403)

Чтобы разрешить установление протокольных соединений и вызов инструмента search_indicators , правило условной политики включает в себя разрешение для "search_indicators" или "" (пустая строка).

Настройка политики IAM сервера IAP MCP в реестре

# show iap iam policy for mcp server
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

ПРИМЕЧАНИЕ: etag: должен возвращать ACAB по умолчанию, поскольку политики еще не определены.

# fetch active etag on policy for mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy \
  --resource-type=agent-registry --region=${REGION} \
  --mcp-server=${MCP_REGISTRY_ID} --format="value(etag)")
echo ${IAP_ETAG}

# create policy config file
cat > cfg/iap-policy-dc-agent-to-dc-mcp-tool-1.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ],
      "condition": {
        "title": "allow ${RE_AGENT_NAME} to use search_indicators tool for ${MCP_DISPLAY_NAME}",
        "expression": "api.getAttribute('iap.googleapis.com/mcp.toolName', '') in ['search_indicators', '']"
      }
    }
  ],
  "etag": "${IAP_ETAG}",
  "version": 3
}
EOF

# import policy file (bind iam policy)
gcloud beta iap web set-iam-policy cfg/iap-policy-dc-agent-to-dc-mcp-tool-1.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

# verify iap iam policy for mcp server
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

На этом завершается раздел, посвященный политике компании... далее переходим к разделу «Аудит» .

11. Аудит

Расширение авторизации Agent Gateway работает в режиме DRY_RUN . Исходящие запросы отслеживаются и регистрируются, но не блокируются.

Запросы тестового агента

Откройте окно браузера с пользовательским интерфейсом консоли Google Cloud и перейдите по следующей ссылке:

Платформа агентов → Агенты → Развертывания → agent-datacommons
Выберите вкладку «Игровая площадка» .

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

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

Отправьте несколько тестовых запросов...

What data do you have on water quality in Zimbabwe?
Compare the life expectancy, economic inequality, and GDP growth for BRICS nations

Убедитесь, что запросы возвращают корректные ответы.

Анализ журналов аудита

Просмотрите журналы и изучите результаты оценки политики в ходе пробного запуска.

# list unique urls with http status and iap authorization result
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=200 \
  --format="value(httpRequest.status, jsonPayload.authzPolicyInfo.result, httpRequest.requestUrl)" | sort -u

200     ALLOWED https://api.datacommons.org/mcp
200     ALLOWED https://cloudresourcemanager.googleapis.com:443/google.cloud.resourcemanager.v3.Projects/GetProject
200     ALLOWED https://telemetry.googleapis.com/v1/traces
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}/events
202     ALLOWED https://api.datacommons.org/mcp

Обновление реестра, конечных точек IAP, политики IAM.

Предоставьте агенту права на исходящий трафик для конечной точки телеметрии.

# set var for endpoint display name
export ENDPOINT_1_DISPLAY_NAME="telemetry.googleapis.com"
echo ${ENDPOINT_1_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_1_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_1_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_1_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-re-agent-to-ep-1.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-re-agent-to-ep-1.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_1_REGISTRY_ID} \
  --region=${REGION}

# verify iap iam policy for telemetry endpoint
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_1_REGISTRY_ID}

Предоставить агенту разрешения на исходящий трафик для конечной точки AIplatform.

# set var for endpoint display name
export ENDPOINT_2_DISPLAY_NAME="${REGION}-aiplatform.googleapis.com"
echo ${ENDPOINT_2_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_2_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_2_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_2_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-re-agent-to-ep-2.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-re-agent-to-ep-2.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_2_REGISTRY_ID} \
  --region=${REGION}

# verify iap iam policy for aiplatform endpoint
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_2_REGISTRY_ID}

Предоставьте агенту права на исходящий трафик для конечной точки cloudresourcemanager.

# set var for endpoint display name
export ENDPOINT_3_DISPLAY_NAME="cloudresourcemanager.googleapis.com"
echo ${ENDPOINT_3_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_3_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_3_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_3_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-re-agent-to-ep-3.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-re-agent-to-ep-3.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_3_REGISTRY_ID} \
  --region=${REGION}

# verify iap iam policy for cloudresourcemanager endpoint
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_3_REGISTRY_ID}

На этом завершается раздел аудита... далее переходим к разделу «Принудительное исполнение» .

12. Принудить к исполнению

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

Обновить расширение авторизации

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

Обновить политику авторизации

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Проверить условное разрешение

Вернитесь в среду разработки агентов в консольном интерфейсе.

Отправьте дополнительный тестовый запрос (попытайтесь вызвать разрешенный инструмент search_indicators )...

What data topics do you have for Peru?

Обратите внимание, что запросы агента к модели фонда Gemini ( ${REGION}-aiplatform.googleapis.com/... ), API телеметрии ( telemetry.googleapis.com/... ) и конечной точке сервера Data Commons MCP ( api.datacommons.org/mcp ) передаются со статусом HTTP 200 OK .

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

Убедитесь, что никакие запросы не блокируются. Найдите в журналах аудита шлюза любые отклоненные исходящие попытки с кодом состояния HTTP 403 Forbidden .

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

Проверить условный отказ

Отправьте дополнительный тестовый запрос (попытайтесь вызвать запрещенный инструмент get_observations )...

What are the diabetes levels in Peru compared to Slovakia?

Агент сначала проверит search_indicators затем попытается использовать get_observations , но потерпит неудачу, и ответ агента останется неполным.

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

TIMESTAMP            STATUS  IAP_AUTHZ  MCP_METHOD                 TOOL_NAME          URL
YYYY-MM-DDTHH:MM:SS  403     DENIED     tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS          ALLOWED    tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  403     DENIED     tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  200     ALLOWED    tools/call                 search_indicators  https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  200     ALLOWED    tools/list                                    https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  202     ALLOWED    notifications/initialized                     https://api.datacommons.org/mcp

Это подтверждает, что политика управления работает должным образом!

Обратите внимание, что вторая строка, указывающая на пустой статус и ALLOWED представляет собой вторичное событие разрыва соединения, генерируемое Agent Gateway при закрытии сокета после отправки ответа 403 (поскольку события закрытия соединения не имеют кодов состояния ответа, httpRequest.status пуст).

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

13. Уборка

# delete agent
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# delete storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# next

# clear policy on mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --mcp-server=${MCP_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

# next

# clear policy on endpoint 1
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_1_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_1_REGISTRY_ID} \
  --region=${REGION}

# next

# clear policy on endpoint 2
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_2_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_2_REGISTRY_ID} \
  --region=${REGION}

# next

# clear policy on endpoint 3
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_3_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_3_REGISTRY_ID} \
  --region=${REGION}

# next

# remove manual registry entry
gcloud -q agent-registry services delete ${MCP_RESOURCE_NAME} --location=${REGION}

# delete gateway resources
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-enforced --location=${REGION}

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-datacommons endpoints

# end

На этом завершается этап очистки... далее переходим к заключению !

14. Заключение

Поздравляем! Вы успешно развернули и настроили исходящие коммуникации для агента, получающего доступ к инструментам через Agent Gateway!

космопап

Cosmopup считает, что Codelabs — это просто супер!

Что дальше?

Ознакомьтесь с документацией Gemini Enterprise Agent Platform для получения информации о расширенных функциях и обучающих материалах.
Настройте защитные механизмы Model Armor на Agent Gateway для повышения безопасности ИИ.
Изучите политики семантического управления для обеспечения соблюдения бизнес-правил и соответствия требованиям при обработке запросов на естественном языке.

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

Спасибо!