Saída do gateway de agente do Agent Runtime para o MCP do Google

1. Introdução

Este codelab explora a governança de saída do Gateway de agente para agentes de IA que acessam servidores remotos do Protocolo de Contexto de Modelo (MCP) do Google Cloud.

Os apps de IA, de chatbots independentes a sistemas autônomos com fluxos de trabalho multiagente, podem invocar ferramentas externas de forma dinâmica. Oferecer aos agentes acesso controlado para consultar bancos de dados, buscar conteúdo da Web e executar ações é essencial para agentes seguros e produtivos. No entanto, em ambientes empresariais, proteger a execução de ferramentas do agente é um desafio. Se um agente tiver acesso direto à rede, ataques de injeção de comandos ou alucinações do modelo poderão fazer com que ele exfiltre dados sensíveis ou execute comandos destrutivos.

Para gerenciar agentes autônomos em escala, o Agent Gateway oferece um ponto de aplicação centralizado de confiança zero integrado diretamente à arquitetura da Agent Platform. Em vez de depender de implementações personalizadas exclusivas para cada aplicativo ou código de agente, o Gateway de Agente oferece roteamento de rede, governança de agentes e segurança de tempo de execução aplicados no nível da plataforma.

Quando o gateway de agente opera no modo de saída (agent-to-anywhere), ele faz proxy de todas as solicitações de saída de agentes configurados para usar o gateway. Cada solicitação de carga de trabalho do agente é autenticada usando a identidade do agente exclusiva e autorizada com as políticas do Identity-Aware Proxy (IAP). As chamadas de ferramenta MCP são decodificadas e inspecionadas dinamicamente para aplicação de políticas. Os administradores de segurança podem aplicar permissões refinadas de maneira centralizada para garantir que os agentes só possam invocar endpoints e métodos aprovados.

O que você vai criar

• Gateway de Agente no modo de saída (agente para qualquer lugar)
• Extensão de autorização do Identity-Aware Proxy (IAP)
• Agente do ADK do Agent Runtime com identidade do agente
• Agent Registry com endpoints da API do Google e do MCP
• Políticas de autorização com controle de acesso do IAM
• Conjunto de dados do BigQuery para consultar usando o MCP

Figura 1. Arquitetura do codelab

Conteúdo do laboratório

• Como implantar o gateway de agente em uma sequência de configuração estruturada
• Como fazer a transição das políticas de autorização de um modo de simulação para um modo restrito
• Como registrar endpoints da API do Google e servidores MCP no Agent Registry
• Como auditar os registros do Gateway de Agente para validar a governança de saída

O que é necessário

• Tenha um projeto do Google Cloud com o faturamento ativado.
• Permissões do IAM para provisionar serviços de rede, conjuntos de dados do BigQuery e recursos da Agent Platform
• Um shell compatível com POSIX (bash ou zsh) com a CLI do Google Cloud (componentes gcloud e bq) instalada
• Ferramentas de linha de comando: git, curl, jq (processador JSON), Python 3 e uv (gerenciador de pacotes Python)

2. Conceitos

Sequência de implantação

Ao implantar o Gateway de Agente com controles de governança, é importante seguir uma sequência de configuração estruturada para que os agentes tenham acesso aos recursos necessários na inicialização e as solicitações de rede sejam bem-sucedidas.

Este codelab usa a seguinte sequência de implantação:

• Iniciar no modo de simulação:se um ambiente de execução do agente estiver configurado para encaminhar chamadas de saída ao gateway antes que ele seja totalmente provisionado, a inicialização da carga de trabalho vai falhar. Configurar primeiro a extensão de autorização do gateway no modo DRY_RUN garante que nenhuma solicitação seja descartada quando o tráfego do agente chegar ao gateway.
• Registre todos os serviços:todos os agentes, servidores MCP e endpoints que usam o gateway de agente precisam ser registrados no Agent Registry. As solicitações são negadas para origens ou destinos não registrados. Os agentes implantados no Agent Runtime e nos servidores MCP do Google são registrados automaticamente. Qualquer endpoint de API do Google ou servidor MCP personalizado precisa ser registrado manualmente.
• Aplicar políticas de autorização:as políticas de autorização são usadas para permitir que agentes registrados acessem componentes de agente. Para isso, conceda a função roles/iap.egressor ao principal de identidade do agente e vincule-o ao recurso de registro de destino. Avalie o comportamento do agente usando o modo de simulação e defina políticas para permitir o tráfego de saída escolhido pelo gateway. Depois que as políticas forem implementadas, mude para o modo ENFORCED para permitir que o gateway aplique ativamente as políticas de governança.

Fig. 2. Sequência de implantação

Topologia de roteamento de saída

Os gateways geralmente gerenciam o tráfego de entrada (ingress) para serviços de back-end. O Gateway de Agente, que opera no modo de saída (agente para qualquer lugar), atua como um proxy de saída centralizado e de confiança zero para cargas de trabalho com agentes.

Quando um app de IA ou uma carga de trabalho agêntica tenta invocar uma ferramenta ou API externa, a solicitação de saída é interceptada pelo Gateway de Agente e avaliada de acordo com as políticas de governança antes de ser encaminhada para o destino:

• Redes privadas (VPC): tráfego de saída destinado a APIs empresariais internas, microsserviços, bancos de dados hospedados em VPCs privadas e redes locais ou entre nuvens acessíveis por conectividade híbrida.
• Redes externas (Internet): tráfego de saída direcionado a serviços da Web de terceiros, APIs SaaS ou endpoints públicos.
• Serviços de IA e Agent Platform:tráfego de saída direcionado a APIs do Cloud gerenciadas do Google Cloud, modelos de base, endpoints do MCP do Google (como o BigQuery) e serviços de governança da plataforma (registro de agentes e políticas da IAP).

Figura 3. Topologia de roteamento de saída do Gateway de Agente

O foco deste codelab é o tráfego de saída de um agente personalizado no Agent Runtime que tem como destino o endpoint remoto do servidor MCP do Google para o BigQuery.

3. Configuração

Papéis do IAM obrigatórios

As seguintes funções são necessárias para criar os recursos neste codelab:

Categoria	Papel do IAM obrigatório (ID)	Descrição
Gerenciamento de APIs	roles/serviceusage.serviceUsageAdmin	Ativar os serviços da API do Google Cloud
Rede e gateway	roles/networkservices.admin	Gateway de Agente de Provisionamento
Extensões de serviço	roles/serviceextensions.admin	Configurar extensões de roteamento
Segurança de rede	roles/networksecurity.admin	Implantar políticas de autorização
Registro de agentes	roles/agentregistry.admin	Hosts permitidos do catálogo
Vertex AI e agentes	roles/aiplatform.admin	Implantar cargas de trabalho do Agent Runtime
Políticas de saída	roles/iap.admin	Aplicar políticas do roles/iap.egressor
BigQuery	roles/bigquery.admin	Configurar esquemas e conjuntos de dados de teste
Cloud Storage	roles/storage.admin	Gerenciar buckets de preparo de implantação
Registros e auditoria	roles/logging.viewer	Inspecionar rastreamentos e registros de auditoria

Se preferir, use um papel básico amplo, como roles/admin, ou um papel legado, como roles/owner.

Acessar seu projeto

Este codelab usa um único projeto na nuvem do Google Cloud. As etapas de configuração usam a CLI gcloud e comandos do shell do Linux.

Comece acessando a linha de comando do projeto na nuvem do Google Cloud:

• Cloud Shell em shell.cloud.google.com ou
• Um terminal local com a CLI gcloud instalada

Definir o ID do projeto

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Autenticar sessão

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Definir variáveis de ambiente shell

# 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-dj"
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}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

Ativar serviços de 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 \
  discoveryengine.googleapis.com

OBSERVAÇÃO:alguns recursos podem usar comandos gcloud beta. Se não estiver instalado, execute gcloud components install beta para ativar.

Isso conclui a parte de configuração. Em seguida, vamos para a seção Gateway.

4. Gateway

Antes de aplicar os controles de acesso, implante o Gateway de Agente e configure a extensão de autorização no modo DRY_RUN. Isso permite que as chamadas de ferramentas de saída sejam bem-sucedidas e registra os resultados da avaliação para fins de auditoria.

Aqui, o Gateway de Agente usa um registro regional para oferecer suporte a recursos do Agent Runtime regionais.

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

Isso conclui a parte do gateway. Em seguida, vamos para a seção Autorização.

5. Autorização

A extensão de autorização do Gateway de Agente para o Identity-Aware Proxy (IAP) é um tipo de Service Extension usada para delegar decisões de autorização para todas as comunicações da Agent Platform.

1. Fluxo de delegação:quando um agente tenta invocar um endpoint externo ou um servidor MCP, ele encaminha a solicitação para o Gateway de Agente. Em vez de avaliar o acesso localmente, o gateway usa a extensão de autorização para enviar um callout ao serviço de avaliação da IAP. O IAP avalia a identidade do agente (baseada em SPIFFE) em relação à política do IAM do recurso de destino no Agent Registry. O IAP retorna uma decisão ALLOW ou DENY para o gateway, que encaminha o tráfego ou o bloqueia com um código de status HTTP 403 Forbidden.
2. Modos de aplicação:no modo DRY_RUN, o IAP avalia solicitações e registra decisões no Cloud Logging sem bloquear o tráfego. No modo ENFORCE, qualquer solicitação de um agente não autorizado ou para um destino não registrado é bloqueada imediatamente.
3. Camada de vinculação:a extensão de serviço está conectada ao Gateway de Agente usando uma política de autorização configurada com o perfil REQUEST_AUTHZ.

Extensão de autorização

Criar extensão de autorização

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

Política de autorização

Uma política de autorização vincula o provedor de segurança (IAP) ao recurso de gateway de destino e especifica o perfil de interceptação (REQUEST_AUTHZ).

Criar política de autorização

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

Isso conclui a parte de autorização. Em seguida, vamos para a seção Base de código.

6. Base de código

O código do agente, o conjunto de dados do BigQuery e o script de registro usados neste codelab são mantidos em um repositório remoto do Google Cloud no GitHub. As etapas a seguir vão clonar o repositório localmente, copiar os arquivos necessários para a estrutura do diretório de trabalho atual e limpar os arquivos temporários desnecessários.

Um bucket de armazenamento temporário é criado para o Agent Runtime fazer upload, criar e implantar o código do aplicativo do agente empacotado e os artefatos de dependência dele.

Buscar artefatos remotos

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

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

Criar conjunto de dados do BigQuery

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

Criar bucket de preparo

# 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)"

Isso conclui a parte da base de código. Em seguida, vamos para a seção Registro.

7. Registro

O Agent Registry é um inventário centralizado de todos os agentes, servidores MCP e endpoints (APIs) no ecossistema de IA. Ele também é um catálogo que pode ser usado para listar, pesquisar e descobrir outras ferramentas e serviços registrados para uso por aplicativos de IA. O modo de saída do Gateway de Agente (agent-to-anywhere) usa o modelo de dados do registro como a estrutura de governança para aplicar o controle de acesso de saída. As concessões de papéis do IAM para agentes de chamada principais são verificadas em relação à política vinculada ao recurso do registro.

Para inicializar o ambiente e oferecer suporte a agentes usando várias APIs e serviços do Google, um script é usado para registrar rapidamente um conjunto comum de endpoints de API usando nomes de host e locais de endpoints/googleapis.txt.

Registrar endpoints

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

Verificar endpoints

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

Isso conclui a parte do registro. Em seguida, vamos para a seção Tempo de execução.

8. Ambiente de execução

O agente do ADK agent-dj implantado no Agent Runtime é configurado com as seguintes configurações no script de implantação para integração com a Agent Platform:

• "identity_type": types.IdentityType.AGENT_IDENTITY para provisionar uma identidade principal exclusiva baseada em SPIFFE para o agente
• "agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } para direcionar todo o tráfego de saída iniciado pelo agente ao Agent Gateway para avaliação e aplicação de políticas.

Implantar agente

# deploy agent runtime workload
uv --directory agent-dj 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 dj contact info" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

Buscar sinais vitais de implantação

# 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 AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

Verificar entrada de registro

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

OBSERVAÇÃO:a implantação do agente no Agent Runtime cria automaticamente um link de registro (RuntimeReference), expõe o principal de identidade do agente usado para políticas de saída da IAP (RuntimeIdentity) e mostra a descoberta dinâmica de endpoints (protocols.interfaces).

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

Verificar a configuração do gateway

# verify agent gateway routing specification
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

VERIFIQUE:confira se agentGateway mostra o URI do recurso de gateway...
"agentGateway": "projects/PROJ_ID/locations/REGION/agentGateways/agw-SLUG-REGION-ata"

Conceder papéis do IAM do agente para recursos

As concessões de papéis do IAM para recursos permitem que o acesso à identidade principal do agente ao BigQuery, às ferramentas do MCP (para APIs do Google) e a outros serviços necessários da plataforma de IA. Essas políticas são aplicadas usando o IAM no nível do recurso.

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

Verificar os papéis do IAM do agente para recursos

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

Isso conclui a parte de tempo de execução. Em seguida, vamos para a seção Políticas.

9. Políticas

As políticas de autorização de governança de agentes permitem o tráfego de um agente de IA pelo Gateway de Agente até o destino (por exemplo, o endpoint do servidor MCP do Google Cloud para o BigQuery). Quando o tráfego chega ao destino, as permissões regulares do IAM autorizam o acesso aos dados (e foram ativadas na seção anterior).

As concessões de papéis do IAM para saída do Gateway de Agente permitem políticas de acesso que concedem à identidade principal do agente acesso a recursos de destino registrados pelo Gateway de Agente. As políticas são aplicadas no nível do Gateway de Agente e validadas usando políticas do IAM do Identity-Aware Proxy (IAP).

Conceder papéis do IAM do agente para saída do gateway de agente

O Gateway de Agente verifica as solicitações recebidas para validar se a identidade do agente de chamada tem a permissão iap.webServiceVersions.egressViaIAP (concedida pela função roles/iap.egressor) no recurso de destino.

A concessão de roles/iap.egressor à identidade do agente ou ao conjunto de principais do Agent Runtime no recurso de destino selecionado permite esse tráfego de saída. Neste codelab, o papel é aplicado ao principal set, que concede permissão a todas as identidades de agente do Agent Runtime no projeto.

As políticas do IAM são vinculadas aos recursos de destino, conforme definido no modelo de dados do registro de agentes. O recurso iap_web/agentRegistry representa um nível "em todo o registro" na hierarquia do IAM. Em que agentRegistry serve como pai dos recursos filhos individuais para agents, mcpServers e endpoints. Neste codelab, a política do IAM está vinculada ao nível do registro, que aplica a permissão a todos os recursos filhos.

NOTE: em uma implantação de produção, é possível implementar políticas mais granulares para restringir a saída de agentes específicos para endpoints específicos. Controles refinados e políticas de permissão condicionais serão abordados em codelabs futuros.

Configurar a política do IAM do registro regional do IAP

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

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

# create policy config file
cat > cfg/iap-policy-re-agent-set-to-registry-${REGION}.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_ID_SET}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

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

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

Isso conclui a parte das políticas. Em seguida, vamos para a seção Auditoria.

10. Auditoria

A extensão de autorização do Gateway de Agente está operando no modo DRY_RUN. As solicitações de saída são observadas e registradas, mas não bloqueadas.

Testar consultas do agente

Abra uma janela do navegador na interface do console do Google Cloud e acesse:

• Agent Platform → Agentes → Implantações → agent-dj
• Selecione a guia Playground.

Ou execute este comando no terminal e clique no link para acessar o playground do agente:

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

Envie algumas consultas de teste...

• How many DJs do we have on file?
• What is the phone number of DJ Cosmopup?

Verifique se as consultas retornam respostas válidas (por exemplo, "Há 12 DJs no arquivo").

Analisar registros de auditoria

Veja os registros e inspecione as avaliações de políticas de simulação.

# query gateway logs for dry run
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
  )"

VERIFIQUE:confira se o resultado IAP_AUTHZ mostra ALLOWED.

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

Isso conclui a parte da auditoria. Em seguida, vamos para a seção Aplicar.

11. Aplicar

O agente conseguiu fazer solicitações bem-sucedidas pelo gateway no modo DRY_RUN. Faça a transição da extensão de autorização do IAP do Gateway de Agente para o modo ENFORCE atualizando a política de autorização.

Atualizar extensão de autorização

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

Atualizar política de autorização

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

Verificar a aplicação

Volte para o Playground do agente na interface do console.

Envie outra consulta de teste...

• What DJ Fishfry's credit card number?

Observe que as solicitações do agente para o modelo de fundação do Gemini (${REGION}-aiplatform.googleapis.com/...) e o endpoint do servidor MCP (bigquery.googleapis.com/mcp) são transmitidas com códigos de status 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)"

Verifique se não há solicitações bloqueadas. Procure tentativas de saída negadas com códigos de status HTTP 403 Forbidden nos registros de auditoria do gateway.

# 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
  )"

Isso conclui a parte de aplicação. Em seguida, vamos para a seção Limpeza.

12. Limpeza

# 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

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

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

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

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

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

# next

# 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 network-services agent-gateways delete ${AGW_NAME} --location=${REGION}

# next

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

# end

Isso conclui a parte de revisão dos dados. Em seguida, vamos para a Conclusão.

13. Conclusão

Parabéns! Você implantou e controlou com sucesso as comunicações de saída de um agente que acessa ferramentas usando o Gateway de Agente!

O Cosmopup acha que os codelabs são demais!

O que vem em seguida?

• Confira a documentação da Gemini Enterprise Agent Platform para conhecer recursos e tutoriais avançados.
• Configure medidas de segurança do Model Armor no Gateway de Agente para aumentar a segurança da IA
• Conheça as Políticas de Governança Semântica para aplicar regras de negócios e conformidade a consultas em linguagem natural

Envie comentários, dúvidas ou correções usando este formulário de feedback.

Agradecemos pela atenção!