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

1. Introdução

Este codelab explora a governança de saída do Agent Gateway para agentes de IA que acessam endpoints remotos por uma rede VPC particular. O Agent Gateway que opera no modo de saída (agent-to-anywhere) oferece suporte à conectividade particular com uma rede VPC usando interfaces do Private Service Connect (PSC). Nesse cenário, o Agent Runtime usa o Agent Gateway para acessar um servidor HTTP MCP transmitível remoto hospedado no Cloud Run usando um endpoint do Private Service Connect (PSC) para APIs do Google na rede VPC.

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 Agent Gateway 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
  • Servidor HTTP transmissível do MCP do Cloud Run
  • Agent Registry com API do Google e endpoints personalizados do MCP
  • 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 do PSC para saída do gateway do agente
  • Regras de política de firewall do Cloud Next Generation Firewall (NGFW)

figure1

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 configurar o gateway de agente com conectividade de rede VPC privada
  • Como fazer a transição das políticas de autorização de um modo de teste para um modo aplicado
  • Como registrar endpoints da API do Google e servidores MCP no Agent Registry
  • Como auditar os registros do Agent Gateway para validar a governança de saída
  • Como validar o tráfego de saída do gateway do 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 Agent Platform
  • Um shell compatível com POSIX (bash ou zsh) com a Google Cloud CLI (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

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 da aplicação de políticas de acesso forçadas.

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. Registre todos os serviços:registre todos os componentes agênticos no registro de agentes e confirme o acesso às ferramentas do agente. Use o Cloud Logging e o painel de observabilidadedo gateway de agente para ver 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 de agentes para servidores e endpoints do MCP.
  4. Mude 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 a uma ferramenta ou API externa, a solicitação de saída é interceptada pelo gateway de agente e avaliada em relação às políticas de governança antes de ser encaminhada ao destino. Em uma arquitetura da plataforma de agentes do Google Cloud, o gateway de agentes oferece conectividade do plano de dados para:

  • 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 plataforma de agentes:tráfego de saída direcionado a APIs 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).

figure3

Figura 3. Topologia de roteamento de saída do gateway do agente

O foco deste codelab é o tráfego de saída de um agente personalizado no Agent Runtime segmentando um PSC para um endpoint de 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 saída do Agent Gateway.

Conectividade VPC

A saída do Agent Gateway (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 roteamento no Agent Gateway para enviar o tráfego que é resolvido para endereços IP particulares pelo anexo de rede do PSC na rede VPC.

figure4

Figura 4. Conectividade VPC do gateway do agente

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

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

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

Provisionar o gateway do 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

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

Cloud Storage

roles/storage.admin

Gerenciar buckets de pré-produção de implantação

Registros e auditoria

roles/logging.viewer

Inspecionar rastreamentos 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 e registros do Cloud DNS

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 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 do Google Cloud:

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)
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 do 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. Em seguida, vamos para a seção Rede.

4. Rede

A rede VPC é implantada usando o modo personalizado para criar sub-redes regulares que oferecem suporte ao anexo de rede do PSC para o gateway de agente e a saída direta de VPC 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

Crie uma rede VPC global.

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

Crie sub-redes para o anexo de rede PSC do gateway do agente e a saída direta da VPC 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

Crie uma política e uma regra de firewall para permitir todo o tráfego de saída com a geração de registros ativada. Isso será usado para monitorar o tráfego de saída do gateway do 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 produtores.

# 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 existente 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 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 o endpoint do PSC

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

Criar zona e registros DNS

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 o Cloud NAT

Crie um Cloud Router e o Cloud NAT para oferecer suporte à saída direta de VPC do Cloud Run para que o servidor MCP acesse dados climáticos 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 da rede. Em seguida, vamos para a seção Gateway.

5. Gateway

Antes de aplicar os controles de acesso, implante o Agent Gateway 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 registram os resultados da avaliação para fins de auditoria.

Aqui, o Agent Gateway usa um registro regional para oferecer suporte a recursos do Agent Runtime regionais 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. Em seguida, vamos para a seção Autorização.

6. Autorização

A extensão de autorização do gateway de agentes 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 Agent Gateway. 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 do 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 Agent Gateway.

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. Em seguida, 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 de endpoint usados neste codelab são mantidos em um repositório remoto do GitHub do Google Cloud. 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 armazenamento temporário é criado para o ambiente de execução do agente 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_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. Em seguida, 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 Agent Gateway usa o modelo de dados do registro como framework 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 ao agente usando várias APIs e serviços do Google, crie um único serviço de endpoint de registro que agrupe as interfaces principais da API necessárias para este laboratório. Isso vai facilitar o gerenciamento das políticas de governança para conjuntos comuns de ferramentas que a maioria dos agentes usa.

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. Em seguida, 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 oferecer suporte à implantação de serviços do Cloud Run com base no 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 o 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 a invocação da 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 do 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 representação de conta de serviço à conta de serviço padrão do Compute. Isso permite que o agente, executado com as credenciais padrão do aplicativo (ADC, na sigla em inglês), gere tokens de ID OIDC assinados pelo Google em nome da conta de serviço do invocador personalizado para autenticar chamadas ao 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 conectando-se ao servidor MCP de destino (por SSE ou HTTP) e chamando 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 Agent Gateway pode usar para avaliação e aplicação da política de saída.

Verificar MCP toolspec

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

Atualizar 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 apenas que recursos internos 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. Em seguida, 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 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 baseada em SPIFFE exclusiva 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.

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 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 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 de 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 do invocador do IAM do Cloud Run integrada só confia e pode verificar tokens de ID OIDC padrão assinados pelo principal emissor do Google OIDC (accounts.google.com).

Assim, 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 representação da conta de serviço no tempo 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 execução

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

Crie as vinculações de função necessárias para a identidade do agente.

Vincular políticas para acesso do agente

# 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 governança de agentes permitem que o tráfego seja encaminhado de um agente de IA pelo Agent Gateway 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 a saída do Agent Gateway permite políticas de acesso que permitem o acesso da identidade principal do agente aos recursos de destino registrados pelo Agent Gateway. As políticas são aplicadas no nível do Agent Gateway e validadas usando políticas do IAM do Identity-Aware Proxy (IAP).

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

O Agent Gateway 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, a função é aplicada ao principal agente, 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 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 aos níveis mcpServer e endpoint, o que aplica a permissão aos recursos filhos específicos.

Configurar o agente para a política do servidor MCP

Criar uma 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: vai retornar o ACAB padrão porque 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 do 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. Em seguida, vamos para a seção Auditoria.

12. Auditoria

A extensão de autorização do Agent Gateway 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 confirma quais políticas precisam ser configuradas para permitir o tráfego pretendido.

Testar consultas do agente

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

  • Agent Platform → Agentes → Implantações → agent-weather
  • 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...

  • 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

Veja os registros e inspecione 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), basta uma única política para conceder permissões de saída do agente para acesso ao endpoint.

Criar uma política de 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 do 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 da auditoria. Em seguida, 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 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, faça a transição da extensão de autorização do IAP do Agent Gateway 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 a aplicaçã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.

Envie outra consulta de teste...

  • What is the current temperature in Los Angeles?

Observe que as solicitações do agente para o modelo de base 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 do 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 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 Agent Gateway 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 do firewall

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

# 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 faz chamadas para APIs de clima 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 DNS

Consulte os registros de consultas DNS para solicitações resolvidas pela zona 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
  )"

As pesquisas de DNS para o serviço do Cloud Run (mcp-weather...run.app) têm origem na rede VPC usando peering de DNS e são resolvidas com êxito para o endpoint PSC interno das 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. Em seguida, 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. Em seguida, vamos para a Conclusão.

15. Conclusão

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

cosmopup

O Cosmopup acha que os codelabs são incríveis!

O que vem em seguida?

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

Valeu!