Saída do gateway do agente do Agent Runtime para a rede VPC

1. Introdução

Este codelab aborda a governança de saída do Gateway de Agente para agentes de IA que acessam endpoints remotos por uma rede VPC privada. O Gateway de Agente que opera no modo de saída (agente para qualquer lugar) oferece conectividade particular com uma rede VPC usando interfaces do Private Service Connect (PSC). Nesse cenário, o Agent Runtime usa o Gateway de Agente para acessar um servidor MCP HTTP que pode ser transmitido remoto hospedado no Cloud Run usando um endpoint do Private Service Connect (PSC) para as APIs do Google na rede VPC.

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

Para gerenciar agentes autônomos em grande escala, o Gateway de Agente 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 ambiente de execução aplicadas no nível da plataforma.

Quando o Gateway de Agente opera no modo de saída (agent-to-anywhere), ele atua como proxy para 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 usando as políticas do Identity-Aware Proxy (IAP). As chamadas de ferramentas do MCP são decodificadas e inspecionadas dinamicamente para aplicação de políticas. Os administradores de segurança podem aplicar permissões detalhadas de forma 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 de agente
  • Servidor MCP HTTP transmissível do Cloud Run
  • Agent Registry com API do Google e endpoints de MCP personalizados
  • Políticas de autorização com controle de acesso do IAM
  • Recursos de rede VPC, zona do Cloud DNS e endpoint do PSC para APIs do Google
  • Anexo de rede PSC para saída do gateway de agente
  • Regras de política de firewall do Cloud Next Generation Firewall (NGFW)

figure1

Fig. 1. Arquitetura do codelab

Conteúdo do laboratório

  • Como implantar o Gateway de Agente em uma sequência de configuração estruturada
  • Como configurar o Gateway de Agente com conectividade de rede VPC privada
  • Como fazer a transição de políticas de autorização de um modo de teste para um modo restrito
  • Como registrar endpoints de 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
  • Como validar o tráfego de saída do Gateway de Agente usando os registros do Cloud NGFW

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 plataforma de agentes
  • 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 do Python)

2. Conceitos

Sequência de implantação

Este codelab segue uma sequência de configuração estruturada para que os agentes tenham acesso aos recursos necessários na inicialização e a conectividade possa ser confirmada antes de aplicar políticas de acesso aplicadas.

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

  1. Comece no modo DRY_RUN: verifique se as solicitações do agente estão chegando ao gateway e passando por ele (modo somente auditoria).
  2. Registrar todos os serviços: registre todos os componentes agênticos no Agent Registry e confirme o acesso à ferramenta do agente. Use o Cloud Logging e o painel de observabilidade do Gateway de Agente para conferir as consultas ao Agent Registry.
  3. Criar políticas de autorização: crie e aplique políticas de autorização para permitir o tráfego de saída dos agentes para os servidores MCP e endpoints.
  4. Mudar para o modo ENFORCED: atualize a política de extensão de autorização para aplicar políticas e bloquear o tráfego de saída não autorizado.

figure2

Fig 2. Sequência de implantação

Topologia de roteamento de saída

A saída do Gateway de Agente (agente para qualquer lugar) atua como um proxy de saída centralizado e de confiança zero para cargas de trabalho agênticas. Quando um agente faz uma solicitação para 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 roteada para o destino. Em uma arquitetura da plataforma de agentes do Google Cloud, o Gateway de Agente fornece conectividade do plano de dados para:

  • Redes privadas (VPC): tráfego de saída direcionado a APIs corporativas 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 de SaaS ou endpoints públicos.
  • Serviços de IA e plataforma de agentes: tráfego de saída direcionado a APIs gerenciadas do Google Cloud, modelos de fundação, endpoints do MCP do Google (como o BigQuery) e serviços de governança da plataforma (registro de agentes e políticas do IAP).

figure3

Fig. 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 um endpoint de API do PSC para APIs do Google implantado em uma rede VPC. Essa arquitetura permite o acesso privado ao servidor MCP hospedado no Cloud Run usando o anexo de rede do PSC para a saída do Gateway de Agente.

Conectividade VPC

A saída do Gateway de Agente (agent-to-anywhere) pode se conectar a uma rede VPC especificando o networkConfig: egress: networkAttachment: [URI] no arquivo de configuração YAML de implantação. Essa configuração define regras de rota no Gateway de Agente para enviar o tráfego que se resolve em endereços IP privados pela anexo de rede do PSC para a rede VPC.

figure4

Fig. 4. Conectividade VPC do Gateway de Agente

O Gateway de Agente pode resolver nomes de host de DNS particulares usando o peering do Cloud DNS para um projeto de destino e uma rede VPC especificados. Todas as zonas particulares listadas na configuração dnsPeeringConfig: domains: [NAME] vão usar registros DNS do Cloud DNS no projeto de destino. Todas as outras consultas DNS vão usar o resolvedor público padrão do Cloud DNS da VPC.

Isso conclui a parte de conceitos. Agora, vamos para a seção Configuração.

3. Configuração

Papéis do IAM obrigatórios

Os seguintes papéis são necessários 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

Provisionar o Gateway de Agente

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

Agent Registry

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 de roles/iap.egressor

Cloud Storage

roles/storage.admin

Gerenciar buckets de preparo de implantação

Registros e auditoria

roles/logging.viewer

Inspecionar traces e registros de auditoria

Desenvolvedor do Cloud Run

roles/run.developer

Implante os serviços do Cloud Run

Leitor do Artifact Registry

roles/artifactregistry.reader

Extrair imagens de contêiner

Administrador de rede do Compute

roles/compute.networkAdmin

Gerenciar recursos de rede VPC

Administrador do DNS

roles/dns.admin

Gerenciar zonas de DNS e registros do Cloud DNS

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

Acessar o projeto

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

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

Defina 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

Defina 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)
export USER_IDENTITY=$(gcloud config get-value account)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}
# 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-weather"
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_NAME="mcp-weather"
export MCP_DISPLAY_NAME="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app"
export MCP_URL="https://${MCP_DISPLAY_NAME}/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_NAME}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_URL}
# create local dir for config files
mkdir -p cfg

Se você estiver executando uma instalação autogerenciada do SDK Google Cloud (ou seja, fora do Cloud Shell), atualize os componentes para a versão mais recente.

# update gcloud cli
gcloud components update

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
# enable google apis (all the rest)
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com

Isso conclui a parte de configuração. Agora, vamos para a seção Rede.

4. Rede

A rede VPC é implantada usando o modo personalizado para criar sub-redes regulares que dão suporte ao anexo de rede do PSC para o Gateway de Agente e a saída de VPC direta do Cloud Run.

O endpoint do PSC para APIs do Google é implantado usando um único /32endereço IPv4 interno global para oferecer suporte ao acesso interno privado ao Cloud Run. Esse endereço IP não é atribuído de nenhuma sub-rede regional.

criar redes

Criar uma rede VPC global.

# create vpc network
gcloud compute networks create vnet-${SLUG} --subnet-mode=custom

Crie sub-redes para o anexo de rede do PSC do Gateway de Agente e a saída de VPC direta do Cloud Run.

# create subnet for agent gateway psc na
gcloud compute networks subnets create subnet-${REGION}-agw \
  --network=vnet-${SLUG} \
  --range=192.168.10.0/28 \
  --region=${REGION} \
  --enable-private-ip-google-access

# create subnet for cloud run dvpc egress
gcloud compute networks subnets create subnet-${REGION}-crun \
  --network=vnet-${SLUG} \
  --range=10.10.10.0/24 \
  --region=${REGION} \
  --enable-private-ip-google-access

Crie regras de firewall

Criar uma política de firewall e uma regra para permitir todo o tráfego de saída com a geração de registros ativada. Ele será usado para monitorar o tráfego que sai do Gateway de Agente para a rede VPC.

# create fw policy
gcloud compute network-firewall-policies create fw-policy-${SLUG} --global
# create fw policy rule
gcloud compute network-firewall-policies rules create 1001 \
  --description="allow all out and log" \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --action=allow \
  --direction=EGRESS \
  --layer4-configs=all \
  --dest-ip-ranges=0.0.0.0/0 \
  --enable-logging
# associate fw policy to vpc network
gcloud compute network-firewall-policies associations create \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --network=vnet-${SLUG} \
  --global-firewall-policy

Criar anexo de rede do PSC

Crie um anexo de rede do PSC configurado para aceitar automaticamente novas conexões de produtor.

# create psc network attachment
gcloud compute network-attachments create psc-na-${REGION}-agw \
  --region=${REGION} \
  --subnets=subnet-${REGION}-agw \
  --connection-preference=ACCEPT_AUTOMATIC

Verificar o anexo de rede do PSC

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}
# fetch psc na uri
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

Criar endpoint do PSC

Crie uma reserva de endereço IP para o endpoint global do PSC. O endereço usado aqui não pode vir de uma sub-rede atual nem se sobrepor a ela.

# set env var for psc ep ip address
export PSC_EP_IP="240.0.0.10"
echo ${PSC_EP_IP}
# reserve internal global ipv4 address
gcloud compute addresses create ip-psc2gapis \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=${PSC_EP_IP} \
  --network=vnet-${SLUG}

Crie um endpoint do PSC para as APIs do Google usando o pacote all-apis, que inclui o Cloud Run (run.app).

# create psc endpoint for google apis
gcloud compute forwarding-rules create psc2gapis \
  --global \
  --network=vnet-${SLUG} \
  --address=ip-psc2gapis \
  --target-google-apis-bundle=all-apis

Verificar endpoint do PSC

# show psc endpoint details
gcloud compute forwarding-rules describe psc2gapis --global

Criar zona de DNS e registros

Crie uma zona gerenciada particular do Cloud DNS para o domínio run.app.

# create private dns zone
gcloud dns managed-zones create priv-zone-run \
  --description="private zone for cloud run" \
  --dns-name="run.app." \
  --visibility=private \
  --networks=vnet-${SLUG}

Crie um registro DNS curinga A para *.run.app. apontando para o endereço IP do endpoint do PSC.

# create dns record
gcloud dns record-sets create *.run.app \
  --zone=priv-zone-run \
  --type=A \
  --ttl=300 \
  --rrdatas=${PSC_EP_IP}

Crie uma política do Cloud DNS para ativar a geração de registros de consultas DNS.

# create dns policy (logging)
gcloud dns policies create dns-policy-${SLUG} \
  --description="dns logging for vnet-${SLUG}" \
  --networks=vnet-${SLUG} \
  --enable-logging

Criar Cloud NAT

Crie um Cloud Router e um Cloud NAT para oferecer suporte à saída de VPC direta do Cloud Run, permitindo que o servidor MCP acesse dados meteorológicos externos pela rede VPC.

# create router for nat
gcloud compute routers create cr-nat-${SLUG}-${REGION} \
  --network=vnet-${SLUG} \
  --asn=16550 \
  --region=${REGION}
# create nat gateway
gcloud compute routers nats create nat-${SLUG}-${REGION} \
  --router=cr-nat-${SLUG}-${REGION} \
  --region=${REGION} \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges

Isso conclui a parte de rede. Agora, vamos para a seção Gateway.

5. 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, enquanto os resultados da avaliação são registrados para fins de auditoria.

Aqui, o Gateway de Agente usa um registro regional para oferecer suporte aos recursos regionais do Agent Runtime e especifica os campos networkConfig para o anexo de rede PSC da rede VPC e a configuração de peering de DNS.

Criar gateway

# create new agent gateway config file (with network settings)
cat > cfg/${AGW_NAME}-networkConfig.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domains:
      - run.app.
    targetProject: ${PROJ_ID}
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
EOF
# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}-networkConfig.yaml" \
  --location=${REGION}

Verificar gateway

# show agent gateway details
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}
# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

Verifique se há um endpoint de conexão aceito.

connectionEndpoints:
- ipAddress: 192.168.10.2
  projectIdOrNum: '[AGW_PROJECT_NO]'
  status: ACCEPTED
  subnetwork: https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/regions/${REGION}/subnetworks/subnet-${REGION}-agw

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

6. Autorização

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

  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 uma chamada ao serviço de avaliação do 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 ao 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 as solicitações e registra as 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 é conectada ao Gateway de Agente usando uma política de autorização configurada com o perfil REQUEST_AUTHZ.

Extensão de autorização

Uma extensão de autorização especifica o serviço do provedor de segurança com configurações de conectividade e outros parâmetros que definem como o serviço vai operar e se integrar ao Gateway de Agente.

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

Importar extensão de autorização

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

Verificar a extensão de autorização

# show authz extension details
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

Vincular política de autorização

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

Verificar a política de autorização

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

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

7. Base de código

O agente, o servidor MCP e o código de registro do endpoint 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.

Um bucket de preparo de armazenamento é criado para que o Agent Runtime faça upload, crie e implante 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_vpc
# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/agent-weather ./agent-weather
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/mcp-weather ./mcp-weather
# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_vpc

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. Agora, vamos para a seção Registro.

8. 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 Gateway de Agente usa o modelo de dados do registro como o framework de governança para aplicar o controle de acesso de saída. As concessões de papéis do IAM para os agentes de chamada principais são verificadas em relação à política vinculada ao recurso de registro.

Para inicializar o ambiente e dar suporte ao agente usando várias APIs e serviços do Google, crie um único serviço de endpoint de registro que agrupe as principais interfaces de API necessárias para este laboratório. Isso vai facilitar o gerenciamento de políticas de governança para conjuntos comuns de ferramentas que a maioria dos agentes vai usar.

Registrar endpoints

# create endpoint service (with multiple entries)
gcloud agent-registry services create core-gapi-services \
  --location=${REGION} \
  --display-name="gapi.core.services" \
  --description="core apis and services" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://cloudresourcemanager.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.googleapis.com

Verificar o registro do endpoint

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

Isso conclui a parte do registro. Agora, vamos para a seção Servidor MCP.

9. Servidor MCP

Conceder permissões do IAM para implantação

Conceda permissões à conta de serviço padrão do Compute para permitir a implantação de serviços do Cloud Run usando o código-fonte.

# grant cloud run builder role to default compute sa
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

Verificar permissões do IAM

# show iam policy on project for default compute sa
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members=serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Implantar servidor MCP

# deploy cloud run service
gcloud -q run deploy ${MCP_NAME} \
  --source=mcp-weather/server \
  --region=${REGION} \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --network=vnet-${SLUG} \
  --subnet=subnet-${REGION}-crun \
  --vpc-egress=all-traffic \
  --startup-probe=httpGet.path=/warmup

Conceder permissões do IAM para entrada

Vincular política para acesso do usuário

Conceda permissões à conta de usuário (própria) para invocar o servidor MCP hospedado no Cloud Run. Isso é necessário para executar o script de geração toolspec.

# grant run invoker role to user account on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --region=${REGION} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

Verificar permissões do IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Criar uma SA personalizada para invocação do MCP

Crie uma conta de serviço personalizada para invocar o servidor MCP hospedado no Cloud Run. Essa conta de serviço será usada pelo agente para buscar um token de ID OIDC válido assinado pelo Google para acessar o Cloud Run.

# create custom sa for mcp server invocation
gcloud iam service-accounts create sa-${MCP_NAME}-invoker \
  --display-name="custom sa to invoke ${MCP_NAME}"
# set env var for service account identity
export MCP_INVOKER_SA="sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com"
echo ${MCP_INVOKER_SA}

Vincular política para conta de serviço

# grant run invoker role to custom sa on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --role="roles/run.invoker" \
  --member="serviceAccount:${MCP_INVOKER_SA}" \
  --region=${REGION}

Verificar permissões do IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Conceder permissões do IAM para autenticação

Conceda papéis de identidade temporária de conta de serviço à conta de serviço padrão do Compute. Isso vai permitir que o agente, em execução com o Application Default Credentials (ADC), gere tokens de ID do OIDC assinados pelo Google em nome da conta de serviço do invocador personalizado para autenticar chamadas para o Cloud Run.

Vincular política para autenticação

# grant oidc token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

# grant service account token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

Verificar permissões do IAM

# show iam policy for the custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Criar MCP toolspec

Ao registrar um servidor MCP manualmente, é necessário incluir um arquivo de especificação de ferramenta. Um arquivo toolspec.json lista todas as ferramentas disponibilizadas pelo servidor MCP e permite que outros usuários as descubram depois de registradas.

O script test_mcp.py, incluído na base de código mcp-weather/, gera um arquivo toolspec.json ao se conectar ao servidor MCP de destino (por SSE ou HTTP) e chamar list_tools() para recuperar todas as ferramentas disponíveis expostas pelo servidor.

# fetch oidc token for cloud run authentication
export OIDC_TOKEN=$(gcloud auth print-identity-token)
# generate toolspec for registry ingestion
uv --directory mcp-weather run test_mcp.py --toolspec=include --token="${OIDC_TOKEN}"

Uma análise da saída toolspec gerada mostra os atributos do MCP que o Gateway de Agente pode usar para avaliar e aplicar políticas de saída.

Verificar o MCP toolspec

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

Atualizar a entrada do Cloud Run

Mude a configuração de entrada do serviço do Cloud Run para que ele aceite apenas solicitações recebidas da rede VPC. Isso impede o acesso público direto ao endpoint do MCP e permite que apenas recursos internos o acessem. O tráfego destinado ao endpoint do PSC para APIs do Google na rede VPC será considerado entrada interna e permitido.

# update cloud run service config
gcloud run services update ${MCP_NAME} \
  --region=${REGION} \
  --ingress=internal

Verificar a entrada do Cloud Run

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION} | grep -iE 'ingress|egress'

Registrar servidor MCP

Agora, com o toolspec em mãos, registre o servidor MCP no Agent Registry regional.

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

Verificar o registro do MCP

# 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_NAME} --location=${REGION}
# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

Isso conclui a seção do servidor MCP. Agora, vamos para a seção do agente do ADK.

10. Agente do ADK

O agente do ADK agent-weather implantado no Agent Runtime é configurado com as seguintes definiçõ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 para o Gateway de Agente para avaliação e aplicação de políticas

O agente também é configurado para usar o servidor MCP transmitindo o URL e a conta de serviço para buscar o token de ID do OIDC.

Implantar agente

# deploy agent runtime workload
uv --directory agent-weather 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 weather info" \
  --mcp-server-url="${MCP_URL}" \
  --mcp-invoker-sa="${MCP_INVOKER_SA}" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

Verificar implantação

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

Verificar entrada do registro

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

Verificar a configuração do gateway

# show agent config details (gateway config)
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}'

Conceder permissões do IAM para autenticação

Quando um agente é configurado para usar a Identidade do Agente, ele recebe um token (formato JWT-SVID) do Security Token Service (STS) federado, que é assinado por sts.googleapis.com (o provedor de identidade SPIFFE).

No entanto, a verificação integrada do invocador do IAM do Cloud Run só confia e pode verificar tokens de ID do OIDC padrão assinados pelo emissor principal do OIDC do Google (accounts.google.com).

Portanto, uma conta de serviço personalizada é usada para trocar o token STS federado (JWT-SVID) obtido pela identidade do agente por um token padrão do Google (OIDC) obtido usando a identidade temporária da conta de serviço no ambiente de execução.

Crie as vinculações de papéis necessárias para a conta de serviço personalizada.

Vincular política para autenticação (falsificação de identidade)

# grant service account token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

# grant service account openid token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

Verificar permissões do IAM

# show iam policy for custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Conceder permissões do IAM para o ambiente de execução

Conceder permissões do IAM para o ambiente de execução permite que o agente acesse os serviços da plataforma de IA e outras APIs e serviços principais do Google usando a identidade do agente principal baseada em SPIFFE. Essas políticas são aplicadas usando o IAM no nível do recurso.

Crie as vinculações de papéis necessárias para a identidade do agente.

Vincular políticas para acesso de agentes

# 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 permissões do IAM

# show iam policy on project for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Isso conclui a parte do agente do ADK. Agora, vamos para a seção Políticas.

11. Políticas

As políticas de autorização de Agent Governance permitem que o tráfego seja roteado de um agente de IA pelo Gateway de Agente até o destino final do recurso (por exemplo, um endpoint de servidor MCP particular para recuperação de dados). Quando o tráfego chega ao destino, as permissões regulares no nível do serviço ou do aplicativo autorizam o acesso aos dados.

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

Conceder papéis do IAM para saída do Gateway de Agente

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

Conceder 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 agent, que concede permissão à identidade específica do agente do Agent Runtime.

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

Configurar a política de agente para servidor MCP

Criar política para o agente no servidor MCP

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

OBSERVAÇÃO : etag: precisa retornar o ACAB padrão, já que nenhuma política foi definida ainda.

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

Vincular política para o agente ao servidor MCP

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

Verificar permissões do IAM

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

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

12. 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. Analisar os registros antes de mudar para o modo ENFORCED vai confirmar quais políticas precisam ser configuradas para permitir o tráfego pretendido.

Consultas do agente de teste

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

  • Plataforma de Agentes → Agentes → Implantações → agent-weather
  • Selecione a guia Playground.

Ou use este comando de 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...

  • What is the weather like in London?
  • How warm is it in New York?

Verifique se as consultas retornam respostas válidas.

Analisar registros de auditoria

Acessar registros e inspecionar as avaliações de políticas de simulação.

# show gateway logs for endpoints and authz status (duplicates removed)
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=50 \
  --freshness=24h \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    httpRequest.requestUrl.sub('(https?://[^/:]+).*', '\1'):label=ENDPOINT \
  )" | awk 'NR==1 {print; next} ! seen[$2,$3,$4]++'
TIMESTAMP            STATUS  AUTHZ    ENDPOINT
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://cloudresourcemanager.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://${REGION}-aiplatform.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://iamcredentials.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://telemetry.googleapis.com
YYYY-MM-DDTHH:MM:SS  202     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app

Configurar a política de agente para endpoints

Como as APIs principais do Google para agent-weather foram registradas em um serviço de endpoint coletivo no registro (gapi.core.services), é necessária apenas uma política para conceder permissões de saída do agente para acesso ao endpoint.

Criar política para agente para endpoint

# set var for endpoint display name
export ENDPOINT_DISPLAY_NAME="gapi.core.services"
echo ${ENDPOINT_DISPLAY_NAME}
# fetch endpoint registry id
export ENDPOINT_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_REGISTRY_ID}
# create policy config file
cat > cfg/iap-policy-agent-to-ep.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

Vincular política para agente ao endpoint

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

Verificar permissões do IAM

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

Isso conclui a parte de auditoria. Agora, vamos para a seção Aplicar.

13. Aplicar

O agente conseguiu fazer solicitações pelo gateway no modo DRY_RUN. Os registros de acesso e os endpoints foram analisados para criar um conjunto de políticas de governança que permitem o tráfego de saída necessário do agente. Agora, mude a 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

Criar 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

Importar extensão de autorização

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

Verificar a extensão de autorização

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

Atualizar política de autorização

Criar 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

Vincular política de autorização

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

Verificar a política de autorização

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

Verificar restrição

Volte para o Playground do agente na interface do console.

  • Clique no botão + Nova sessão para criar uma nova sessão de chat.

Enviar outra consulta de teste…

  • What is the current temperature in Los Angeles?

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 (mcp-weather-${PROJ_NO}.${REGION}.run.app/mcp) são transmitidas com códigos de status HTTP 200 OK.

Analisar registros de gateway

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

Confira os registros do MCP do Gateway de Agente e observe como o payload do aplicativo MCP (JSON-RPC) é inspecionado para expor os metadados do protocolo, incluindo quais ferramentas estão sendo executadas.

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

Analisar registros de firewall

Veja os registros da prioridade de regra de política de firewall de rede 1001.

# show firewall logs for rule 1001
gcloud logging read \
  "jsonPayload.rule_details.priority=1001" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.disposition:label=ACTION,
    jsonPayload.connection.src_ip:label=SRC_IP,
    jsonPayload.connection.dest_ip:label=DEST_IP,
    jsonPayload.connection.dest_port:label=DEST_PORT,
    jsonPayload.vpc.subnetwork_name:label=SUBNET
  )"

Observe a visualização no nível da rede dos diferentes caminhos de tráfego:

  • Gateway de Agente se comunicando com recursos internos da rede VPC usando subnet-${REGION}-agw
  • O servidor MCP hospedado no Cloud Run fazendo chamadas para APIs Weather externas usando subnet-${REGION}-crun.
TIMESTAMP            ACTION   SRC_IP        DEST_IP        DEST_PORT  SUBNET
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw

Analisar registros de DNS

Veja os registros de consulta DNS para solicitações resolvidas pela zona de DNS particular (priv-zone-run).

gcloud logging read \
  "resource.type=\"dns_query\" AND resource.labels.target_name=\"priv-zone-run\"" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.queryName:label=QUERY_NAME,
    jsonPayload.queryType:label=TYPE,
    jsonPayload.rdata:label=RESPONSE_RDATA,
    jsonPayload.sourceNetwork:label=NETWORK,
    resource.labels.source_type:label=SRC_TYPE
  )"

Observe que as buscas DNS para o serviço do Cloud Run (mcp-weather...run.app) se originam da rede VPC usando o peering de DNS e são resolvidas com sucesso para o endpoint interno do PSC para as APIs do Google (240.0.0.10).

TIMESTAMP            QUERY_NAME                                     TYPE  RESPONSE_RDATA                                                     NETWORK   SRC_TYPE
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone

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

14. Limpeza

# delete agent runtime
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 agent resources
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

for ROLE in \
  "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 mcp (cloud run) resources
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

gcloud -q run services delete ${MCP_NAME} --region=${REGION}

gcloud -q artifacts repositories delete cloud-run-source-deploy --location=${REGION}

gcloud -q iam service-accounts delete sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com

gcloud -q agent-registry services delete ${MCP_NAME} --location=${REGION}

# next
# delete gateway resources (policy binding must be deleted synchronously first)
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} --async

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

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

# next
# remove policies
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_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_REGISTRY_ID} \
  --region=${REGION}

# next
# delete dns resources
gcloud -q dns record-sets delete *.run.app --type=A --zone=priv-zone-run

gcloud -q dns managed-zones delete priv-zone-run

gcloud -q dns policies update dns-policy-${SLUG} --networks=""

gcloud -q dns policies delete dns-policy-${SLUG}

# next
# delete router (includes nat) and psc resources
gcloud -q compute routers delete cr-nat-${SLUG}-${REGION} --region=${REGION}

gcloud -q compute forwarding-rules delete psc2gapis --global

gcloud -q compute addresses delete ip-psc2gapis --global

# next
# delete firewall resources
gcloud -q compute network-firewall-policies associations delete --name=fw-policy-bind-${SLUG} --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies rules delete 1001 --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} --global

# next
# delete network resources
gcloud -q compute networks subnets delete subnet-${REGION}-agw --region=${REGION}

gcloud -q compute networks subnets delete subnet-${REGION}-crun --region=${REGION}

gcloud -q compute network-attachments delete psc-na-${REGION}-agw --region=${REGION}

gcloud -q compute networks delete vnet-${SLUG}

# next
# clean up local working directories and generated configs
rm -rf cfg agent-weather mcp-weather

# end

Isso conclui a parte de limpeza. Agora, vamos para a Conclusão.

15. Conclusão

Parabéns! Você implantou o Gateway de Agente e controlou o tráfego de saída do agente de IA.

cosmopup

O Cosmopup acha que os codelabs são o máximo!

O que vem em seguida?

Fique à vontade para enviar comentários, perguntas ou correções usando este formulário de feedback.

Valeu!