Como governar cargas de trabalho agênticas com o Agent Gateway na plataforma de agentes do Gemini Enterprise

1. Introdução

A plataforma de agentes do Gemini Enterprise é uma plataforma aberta para criar, escalonar, governar e otimizar agentes de IA de nível empresarial com base nos seus dados.

O Agent Runtime oferece o ambiente de execução gerenciado para executar agentes, como os criados com o Kit de Desenvolvimento de Agente (ADK) de código aberto, com segurança no Google Cloud.

Este codelab mostra como usar esses blocos de construção principais para governar um agente iniciado por um usuário no Gemini Enterprise enquanto ele entra em contato com ferramentas internas de forma segura.

Sobre o Agent Gateway

O Agent Gateway é o componente de rede do pacote de governança de agentes da plataforma. Ele atua como o ponto de entrada e saída da rede para todas as interações do agente, permitindo que os administradores de segurança apliquem a governança centralizada sem exigir que os desenvolvedores gerenciem primitivos de rede complexos.

Ele facilita dois caminhos principais de acesso controlado:

• Cliente para agente (entrada): protege as comunicações entre clientes externos (como o Cursor ou a CLI do Gemini) e seus agentes.
• Agente para qualquer lugar (saída): protege as comunicações entre agentes em execução no Google Cloud e servidores, ferramentas ou APIs em execução em qualquer lugar.

Neste codelab, você vai se concentrar no modo Agente para qualquer lugar (saída).

Para aplicar políticas de segurança, o Agent Gateway se integra perfeitamente ao restante do ecossistema:

• Registro de agentes:uma biblioteca central de agentes e ferramentas aprovados, incluindo servidores MCP de terceiros.
• Identidade do agente:uma persona exclusiva e rastreável para cada agente, protegida automaticamente com mTLS de ponta a ponta.
• Identity-Aware Proxy (IAP) e IAM:a camada de aplicação padrão que valida a identidade do agente com permissões refinadas do IAM antes de permitir chamadas para ferramentas específicas.
• Model Armor:um recurso de segurança de IA integrado por Service Extensions para higienizar conteúdo e proteger contra ataques de injeção de comando ou vazamento de dados.

Modos de implantação (rede pública x privada para o Cloud Run)

Para tornar este codelab acessível, você pode escolher entre dois caminhos de rede para suas ferramentas internas (servidores MCP) implantadas no Cloud Run:

1. Padrão (entrada pública): os servidores MCP são implantados no Cloud Run com nomes de host públicos (ingress=all). O tráfego é encaminhado do agente para as ferramentas usando URLs *.run.app padrão. Isso não exige domínios DNS personalizados e é a maneira mais rápida de aprender os conceitos de governança.
2. Segura (rede particular): uma arquitetura opcional e totalmente particular. Os servidores do MCP são restritos (ingress=internal-and-cloud-load-balancing) e expostos por um balanceador de carga de aplicativo interno com um NEG sem servidor. Para isso, você precisa ter um domínio DNS público para provisionar um certificado gerenciado pelo Google.

Você vai selecionar seu caminho preferido ao configurar o Terraform.

Para saber mais sobre a entrada de endpoints de rede para o Cloud Run, leia nossa documentação.

Atividades deste laboratório

• Provisionar a pilha de infraestrutura principal usando o Terraform
• Criar e implantar ferramentas internas como servidores MCP no Cloud Run
• Implantar um agente do ADK no Agent Runtime usando a saída da interface do PSC
• Configurar extensões de serviço do Agent Gateway para acesso com base em identidade (IAM) e triagem de conteúdo (Model Armor)
• Rastrear e validar a execução segura de ponta a ponta do agente

O que é necessário

• Um navegador da web, como o Chrome
• Um projeto na nuvem do Google Cloud com o faturamento ativado e acesso de proprietário
• Permissões do IAM no nível da organização (o codelab concede papéis no escopo da organização)
• Um domínio controlado por você delegado ao Cloud DNS (para o certificado público gerenciado)
• Familiaridade com o Terraform, gcloud e rede básica do Google Cloud

Topologia do codelab

Neste codelab, você vai implantar um agente de análise de crédito imobiliário completo que se comunica com segurança com três ferramentas internas.

Você vai começar provisionando a rede fundamental, incluindo uma VPC e um balanceador de carga de aplicativo interno configurado como seu gateway de agente. Em seguida, você vai implantar três servidores do Protocolo de Contexto de Modelo (MCP) no Cloud Run. Elas funcionam como suas ferramentas internas exclusivas:

• Gerenciamento de documentos (legacy-dms)
• E-mail corporativo (corporate-email)
• Comprovação de renda (income-verification)

Com as ferramentas instaladas, você vai implantar um assistente de hipoteca (mortgage-agent) criado com o ADK no Agent Runtime. Você vai configurar esse agente para usar uma interface do PSC para saída particular e ativar a descoberta de ferramentas de tempo de execução pelo registro de agentes.

Para proteger o fluxo, configure o gateway de agente com duas extensões de serviço. Primeiro, uma extensão REQUEST_AUTHZ verifica a identidade do agente em relação às políticas do IAM por ferramenta, garantindo que o agente acesse apenas ferramentas autorizadas. Em segundo lugar, uma extensão CONTENT_AUTHZ usando o Model Armor vai analisar os comandos e as respostas do agente.

Por fim, você vai registrar o agente no Gemini Enterprise, acionar uma tarefa de análise de crédito imobiliário como usuário final e verificar a execução segura e controlada usando o Cloud Trace.

Este codelab é destinado a engenheiros de plataforma e segurança de todos os níveis. O tempo estimado para concluir o curso é de 100 minutos.

2. Antes de começar

Criar um projeto e fazer a autenticação

Crie um novo projeto do GCP (ou reutilize um) com o faturamento ativado e autentique o Cloud Shell ou sua máquina local:

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

Ativar APIs de bootstrap

O módulo de fundação do Terraform ativa cerca de 30 APIs na primeira aplicação, mas um pequeno conjunto de bootstrap é necessário para terraform init e o bucket de estado do GCS:

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

Instale as ferramentas necessárias

Instale o conjunto de ferramentas. No Cloud Shell, a maioria deles já está presente. Em uma estação de trabalho:

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

Você também precisa do Terraform >= 1.12.2, do Python 3.12+ e do SDK do Google Cloud (gcloud).

Defina as variáveis de ambiente

O restante do codelab pressupõe que elas foram exportadas no seu shell.

Se você estiver seguindo o caminho opcional de rede segura, defina DOMAIN_NAME (por exemplo, agw.example.com). Caso contrário, ignore essa etapa.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com" 

Valide se todas as variáveis foram preenchidas corretamente. Três valores devem ser retornados.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

Se o ID da organização não for preenchido, encontre e defina manualmente.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. Clonar o repositório

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

Um tour rápido pelo conteúdo do diretório de demonstração:

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

4. Criar o bucket de estado do Terraform e a configuração de back-end

Crie um bucket do GCS para armazenar o estado remoto e copie o modelo de back-end:

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

Edite terraform/backend.conf com seus valores:

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

terraform/backend.conf é ignorado pelo Git. Cada usuário mantém a própria cópia.

5. (Opcional) Criar uma zona de DNS pública do Cloud DNS

Pule esta etapa se você estiver usando o caminho padrão. Se quiser usar a configuração mais simples com URLs públicos do Cloud Run, siga direto para a próxima etapa.

Por padrão, para este laboratório, o Cloud Run tem a configuração de entrada definida como all, e o Agent Registry registra cada servidor MCP no URL público *.run.app. Não é necessário DNS, certificados ou balanceador de carga adicionais. Se você quiser mudar para redes particulares (Cloud Run com ingress = internal-and-cloud-load-balancing atrás de um balanceador de carga de aplicativo interno), também vai precisar de uma zona de DNS pública do Cloud DNS para que o Certificate Manager possa validar o certificado do balanceador de carga.

Fluxo de alto nível da rede particular

Para usar a abordagem de rede particular:

1. Crie a zona de DNS pública do Cloud DNS. O Certificate Manager valida o certificado gerenciado regional gravando CNAMEs nela:

gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

A zona privada correspondente para mcp.${DOMAIN_NAME} (usada pelo balanceador de carga interno do MCP e pelo peering de DNS do Agent Runtime) é criada automaticamente pelo Terraform. Não é necessário criar manualmente. Com a rede particular desativada, nem a zona pública nem a particular são provisionadas.

Para um tutorial mais detalhado sobre o padrão de DNS de horizonte dividido público e privado usado nesta demonstração (configuração de zona gerenciada, peering de DNS entre VPCs, fluxo de validação de certificado), consulte o guia de configuração de DNS.

6. Configurar variáveis do Terraform

Copie o tfvars de exemplo e edite-o:

cp terraform/example.tfvars terraform/terraform.tfvars

Há dois caminhos de demonstração, controlados por enable_cloud_run_private_networking.

Caminho padrão: Cloud Run com entrada pública

**A configuração mais simples.**Para o caminho padrão, basta editar três valores em terraform.tfvars. Todas as outras variáveis no arquivo já têm um padrão adequado para demonstração.

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:[e-mail]"]

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

Vamos configurar a IAP no modo de simulação somente auditoria para testar a política de autorização da IAP sem aplicá-la. Depois de validar a implantação, vamos atualizar o modo de aplicação para "ENFORCED".

Rede privada (opcional)

Defina enable_cloud_run_private_networking = true e adicione as variáveis abaixo para provisionar a pilha segura completa:

• Balanceador de carga de aplicativo interno
• Certificado gerenciado pelo Google
• Cloud Run com ingress = internal-and-cloud-load-balancing
• Peering de DNS do gateway do agente.

enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

As imagens do Cloud Run acima apontam para um marcador de posição do Google. Isso é intencional. O Terraform cria os serviços do Cloud Run com lifecycle { ignore_changes = [template[0].containers[0].image] }, então as invocações skaffold run subsequentes substituem a imagem sem que o Terraform as rejeite.

agent_gateway_subnet_cidr precisa ser pelo menos /28, RFC 1918 e não pode se sobrepor a 10.0.0.0/24, 10.0.1.0/24 ou 10.0.2.0/24. Esses intervalos são reservados para saída do Agent Gateway.

O LB interno do MCP atende ao TLS para *.mcp.${DOMAIN_NAME} usando o mesmo certificado regional gerenciado pelo Google. Não defina mcp_internal_dns_zone.domain como um sufixo não roteável, como mcp-server.internal., enquanto enable_agent_gateway = true E enable_cloud_run_private_networking = true.

No momento, o gateway do agente não valida o certificado de substituição autoassinado. A configuração do Terraform impõe isso com um bloco check no momento do planejamento (ignorada quando a rede privada está desativada, já que não há um certificado do balanceador de carga para validar).

7. Implantar infraestrutura com o Terraform

Inicialize, revise e aplique:

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

O terraform apply provisiona cerca de 40 recursos no caminho padrão e leva de 8 a 10 minutos em um projeto novo (cerca de 60 recursos / 15 a 20 minutos quando enable_cloud_run_private_networking = true). Ele cria:

• Fundamentos do projeto (APIs, identidades de serviço, cotas)
• VPC, sub-redes (principal, somente proxy, PSC, interface do PSC, colocalização do gateway do agente), Cloud NAT, regras de firewall
• Repositório do Artifact Registry para imagens do Cloud Run
• Três serviços do Cloud Run + SAs de tempo de execução por serviço (ingress = all por padrão; internal-and-cloud-load-balancing quando o networking particular está ativado)
• Modelo do Model Armor + IAM
• Gateway de agente, anexo de rede PSC-I, extensões do IAP e do Model Armor, ambas as políticas de autorização e a concessão roles/iap.egressor para envolvidos no projeto
• Endpoints do Agent Registry (Vertex AI, IAP, Discovery Engine etc.) mais os três servidores MCP (registrados em *.run.app/mcp por padrão; em ./mcp quando a rede particular está ativada)

Somente quando enable_cloud_run_private_networking = true:

• LB de aplicativo interno regional com NEG sem servidor (roteamento de máscara de URL) + registros A de DNS particulares
• Zona de DNS particular do MCP (mcp..) anexada à VPC
• Módulo de zona de DNS pública (autorizações de DNS do Certificate Manager) + certificado regional gerenciado pelo Google
• Zona de DNS da interface do PSC (órfã quando não há nomes de host particulares para resolver, portanto, também é controlada pela flag principal)
• Peering de DNS do gateway do agente para mcp.. (pré-adicionado automaticamente)

8. Inspecionar os endpoints do registro de agentes

Apenas para referência. Os comandos nesta seção já foram executados para você pelo módulo agent-registry-endpoints do Terraform. Eles são mostrados para que você possa ver exatamente como é registrar um endpoint detectável pelo MCP.

O Agent Registry é um catálogo por projeto de serviços (APIs do Google e seus próprios servidores MCP) que um agente descobre durante a execução. O agente de crédito imobiliário lê isso na inicialização e vincula ferramentas dinamicamente. Nenhum URL do MCP é incorporado ao código do agente ou ao comando de implantação.

Endpoints

O que o Terraform executou em seu nome: para cada API do Google em agent_registry_google_apis, ele registrou cinco variantes (global, mTLS global, regional, mTLS regional, REP regional). Por exemplo, para aiplatform:

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION}-rep \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Regional (REP)" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"

Servidores MCP

O Terraform também registra os três servidores MCP para você. Para registrar outros servidores MCP, siga as etapas na documentação.

gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC

Verifique os endpoints e servidores MCP registrados.

gcloud alpha agent-registry services list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

Fonte: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl.

9. Analisar a configuração do gateway do agente

Apenas para referência. O Terraform já importou esse gateway de agente. O YAML abaixo é o equivalente literal de terraform/modules/agent-gateway/main.tf.

O gateway de agente é um plano de governança gerenciado pelo Google entre o ambiente de execução do agente e suas ferramentas. No modo AGENT_TO_ANYWHERE, ele é vinculado ao registro de agente do projeto e sai por uma interface PSC de propriedade do cliente para alcançar servidores MCP particulares na sua VPC.

Se você estivesse importando esse gateway manualmente, o YAML seria assim:

# agent-gateway.yaml — for reference only, Terraform already created this
name: agent-gateway
protocols: [MCP]
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJECT_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/agent-gateway-na
  dnsPeeringConfig:
    domains:
      - mcp.${DOMAIN_NAME}.
    targetProject: ${PROJECT_ID}
    targetNetwork: projects/${PROJECT_ID}/global/networks/gateway-vpc

gcloud alpha network-services agent-gateways import agent-gateway \
  --source=agent-gateway.yaml \
  --location=${REGION}

Verifique o gateway criado pelo Terraform:

gcloud alpha network-services agent-gateways describe agent-gateway \
  --location=${REGION}

O terraform-provider-google-beta atual ainda não expõe network_config.dns_peering_config. O Terraform o aplica usando um PATCH pós-aplicação em networkservices.googleapis.com/v1beta1. Você vai ver isso em terraform_data.dns_peering no módulo.

10. Examinar a autorização do IAP e do Model Armor

Apenas para referência. O Terraform já criou as duas extensões e as duas políticas. Os comandos abaixo vêm diretamente de terraform/modules/agent-gateway/main.tf.

O Agent Gateway delega a autorização a extensões de serviço. Dois perfis de política abrangem a demonstração:

• REQUEST_AUTHZ: avaliado uma vez por solicitação na etapa de cabeçalhos. Usado aqui para chamar o IAP, que verifica se a identidade do agente de chamada tem roles/iap.egressor no servidor MCP de destino.
• CONTENT_AUTHZ: transmite eventos do corpo para a extensão para higienização de conteúdo. Usado aqui para chamar o Model Armor, que verifica injeção de comandos, jailbreaks, violações de RAI e (opcionalmente) PII pela Proteção de Dados Sensíveis (SDP).

Extensão IAP REQUEST_AUTHZ

cat > iap-authz-extension.yaml <<EOF
name: agent-gateway-iap-authz
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-iap-authz \
  --source=iap-authz-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

Vincule-o ao gateway de agente com uma política REQUEST_AUTHZ:

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-iap-policy" \
  -d '{
    "name": "agent-gateway-iap-policy",
    "policyProfile": "REQUEST_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-iap-authz"
        ]
      }
    }
  }'

Extensão CONTENT_AUTHZ do Model Armor

O metadata.model_armor_settings da extensão carrega os IDs de modelo de solicitação e resposta que o Model Armor usa para avaliar cada destaque:

cat > ma-extension.yaml <<EOF
name: agent-gateway-ma-authz
service: modelarmor.${REGION}.rep.googleapis.com
failOpen: true
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id":  "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-request-template",
      "response_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-response-template"
    }
  ]'
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-ma-authz \
  --source=ma-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-ma-policy" \
  -d '{
    "name": "agent-gateway-ma-policy",
    "policyProfile": "CONTENT_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-ma-authz"
        ]
      }
    }
  }'

Modelos personalizados do DLP

O sdpSettings.basicConfig do Model Armor usa uma lista integrada de infoTypes. Para um controle mais refinado (infoTypes personalizados, mascaramento parcial, substituição por substituto, edição por probabilidade), aponte o Model Armor para seus próprios modelos de inspeção e desidentificação do Cloud DLP via sdpSettings.advancedConfig.

Crie um modelo de inspeção que sinalize os números de CPF dos EUA com probabilidade POSSIBLE ou superior:

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates" \
  -d '{
    "templateId": "agw-ssn-inspect-template",
    "inspectTemplate": {
      "displayName": "SSN Inspect Template",
      "inspectConfig": {
        "infoTypes": [
          { "name": "US_SOCIAL_SECURITY_NUMBER" }
        ],
        "minLikelihood": "POSSIBLE"
      }
    }
  }'

Crie um modelo de desidentificação que substitua cada descoberta pelo token do infoType (por exemplo, [US_SOCIAL_SECURITY_NUMBER]):

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates" \
  -d '{
    "templateId": "agw-ssn-redaction-template",
    "deidentifyTemplate": {
      "displayName": "SSN Redaction Template",
      "deidentifyConfig": {
        "infoTypeTransformations": {
          "transformations": [{
            "primitiveTransformation": { "replaceWithInfoTypeConfig": {} }
          }]
        }
      }
    }
  }'

Em seguida, aponte uma configuração de resposta de modelo do Model Armor para o par usando sdpSettings.advancedConfig. É aqui que o módulo model_armor do Terraform define advanced_config se você o conectar:

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate":    "projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template",
        "deidentifyTemplate": "projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template"
      }
    }
  }
}

A extensão CONTENT_AUTHZ do Model Armor acima vai selecionar automaticamente esses modelos de configuração avançada na próxima vez que avaliar uma resposta. Não é necessário mudar a extensão. Verifique se o agente de serviço do Model Armor (service-${PROJECT_NUMBER}@gcp-sa-modelarmor.iam.gserviceaccount.com) tem roles/dlp.user e roles/dlp.reader no projeto. O módulo model-armor do Terraform já concede essas permissões.

IAM do egressor do IAP (somente por servidor MCP)

O Terraform não cria uma vinculação roles/iap.egressor em todo o projeto no registro implícito de agentes da IAP. A vinculação que o IAP REQUEST_AUTHZ avalia é por servidor MCP e por mecanismo de inferência, concedida depois que o agente é implantado e você sabe o ID dele. A etapa "Conceder saída do agente por servidor MCP" executa scripts/grant_agent_mcp_egress.sh para isso.

11. Criar e implantar os servidores MCP no Cloud Run

Os arquivos cloudrun/*.yaml.tmpl e skaffold.yaml.tmpl fazem referência a ${PROJECT_ID}, ${REGION} e ${MCP_INGRESS} (a anotação de entrada do Cloud Run). Origine MCP_INGRESS de uma saída do Terraform para que os manifestos renderizados permaneçam sincronizados com enable_cloud_run_private_networking e renderize com envsubst:

Exporte a configuração de entrada do Cloud Run.

• all
• internal-and-cloud-load-balancing (ao usar a abordagem de rede particular)

export MCP_INGRESS=all

envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
  envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done

Cada serviço do Cloud Run é executado como uma conta de serviço de ambiente de execução por serviço criada pelo Terraform (por exemplo, mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). Para implantar como essas contas de serviço, você precisa de roles/iam.serviceAccountUser:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountUser"

Crie com o Cloud Build e implante com o Skaffold:

skaffold run

O Skaffold cria três imagens (legacy-dms, corporate-email, income-verification-api) no seu repositório do Artifact Registry e atualiza cada serviço do Cloud Run para apontar para o novo resumo.

Verificar:

gcloud run services list --region=${REGION}

Os três serviços vão aparecer com o status ACTIVE.

12. Implantar o agente de hipotecas no Agent Runtime

Instale as dependências do agente e faça a implantação:

cd src/mortgage-agent
uv sync

uv run python deploy_agent.py \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --enable-agent-identity \
  --agent-name=mortgage-agent \
  --agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
  --model-endpoint-location=global

O agente descobre ferramentas do MCP no tempo de execução listando mcpServers no Agent Registry em projects/${PROJECT_ID}/locations/${REGION}.

Quando o script for concluído, copie o reasoningEngines/ impresso no shell:

export AGENT_ID=<numeric-id-from-output>
cd ../..

13. Conceder saída por agente e por servidor MCP

A extensão IAP REQUEST_AUTHZ autoriza cada chamada de ferramenta verificando o roles/iap.egressor do agente no servidor MCP específico ou endpoint que ele está chamando. Consulte Criar uma política de saída de um servidor de agente para MCP.

O script (scripts/grant_agent_mcp_egress.sh) enumera os servidores MCP no registro de agentes em projects/${PROJECT_ID}/locations/${REGION} e mescla uma vinculação roles/iap.egressor para o principal do agente na política do IAM de cada servidor (espelhando a semântica gcloud add-iam-policy-binding).

Caso de uso 1: concessão incondicional no escopo de servidores MCP específicos

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "legacy-dms income-verification"

Caso de uso 2: concessão condicional (CEL) no escopo de um servidor MCP específico

Para restringir o agente a um subconjunto de ferramentas em um único servidor MCP, anexe uma condição do IAM. O Agent Gateway publica atributos por ferramenta que o IAP REQUEST_AUTHZ expõe à CEL, incluindo:

• iap.googleapis.com/mcp.toolName
• iap.googleapis.com/mcp.tool.isReadOnly
• iap.googleapis.com/request.auth.type.

Restrinja o agente a ferramentas somente leitura em corporate-email:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "corporate-email" \
  --condition-expression "api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Depois disso, as ferramentas de escrita em corporate-email vão retornar 403 PermissionDenied de IAP REQUEST_AUTHZ. As ferramentas somente leitura continuam funcionando.

Verificar as vinculações

Acesse a guia "Políticas" para ver a lista de políticas criadas para os endpoints e servidores Mcp.

Outros casos de uso:

Concessão incondicional em todos os servidores MCP, com escopo para um agente

Execute isso após cada nova implantação do agente. Sem filtro e sem condição, o agente nomeado recebe roles/iap.egressor em todos os servidores MCP no registro:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID}

14. Testar o agente no console da Plataforma de Agentes

O console da Agent Platform vem com um Playground que permite conversar diretamente com o agente implantado. É a maneira mais rápida de fazer um teste rápido de chamadas de função e inspecionar rastreamentos antes de conectar o agente ao Gemini Enterprise.

1. Abra a página Implantações da plataforma do agente no console do Google Cloud.
2. Use o campo Filtro se precisar restringir a lista de ambientes de execução e clique no seu ambiente mortgage-agent.
3. Abra a guia Playground.
4. Digite um comando para conversar com o agente:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Isso vai retornar uma resposta das ferramentas de gerenciamento de documentos e de comprovação de renda. Os números de CPF também serão ocultados nessa resposta. 5. Digite uma pergunta complementar:

Can you send a summary of this to my email [e-mail]

O agente precisa identificar que não tem acesso à ferramenta send_email e responder de acordo.

Como o agente foi implantado com a instrumentação do OpenTelemetry, o Playground expõe quatro visualizações do painel lateral que você pode alternar enquanto o agente responde:

• Trace: traces completos da conversa, incluindo o gateway de agente, IAP REQUEST_AUTHZ e Model Armor CONTENT_AUTHZ
• Evento: um gráfico das ferramentas invocadas e detalhes do evento para a vez atual
• Estado: o estado da sessão do agente e as entradas/saídas de ferramentas
• Sessões: todas as sessões iniciadas com esse tempo de execução.

O Playground ignora completamente a autenticação do Gemini Enterprise, o que o torna o lugar mais rápido para confirmar se a extensão IAP REQUEST_AUTHZ está concedendo chamadas de função corretamente. Se uma ferramenta retornar 403 aqui, execute scripts/grant_agent_mcp_egress.sh novamente antes de fazer uma depuração mais detalhada.

15. Aplicar a autorização do IAP

Agora que validamos a implantação, podemos atualizar o modo de aplicação do IAP para null e aplicar as políticas. Abra terraform.tfvars e atualize o modo de DRY_RUN para null.

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

Aplique a alteração.

terraform apply

Volte para o Playground e tente a conversa de novo.

1. Abra a página Implantações da plataforma do agente no console do Google Cloud.
2. Use o campo Filtro se precisar restringir a lista de ambientes de execução e clique no seu ambiente mortgage-agent.
3. Abra a guia Playground.
4. Digite um comando para conversar com o agente:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Isso vai retornar uma resposta das ferramentas de gerenciamento de documentos e de comprovação de renda. Os números de CPF também serão ocultados nessa resposta. 5. Digite uma pergunta complementar:

Can you send a summary of this to my email [e-mail]

Se tudo estiver configurado corretamente, o agente vai responder que não pode enviar o e-mail devido à política de autorização.

16. Configuração e teste do Gemini Enterprise

Configurar o Gemini Enterprise

Siga o guia de introdução ao Gemini Enterprise.

Registrar nosso agente do ADK no Gemini Enterprise

Siga as etapas para registrar nosso agente no Gemini Enterprise neste link.

1. No console do Google Cloud, acesse a página Gemini Enterprise.
2. Selecione o app Gemini Enterprise em que o agente está registrado.
3. Abra o URL mostrado na seção Seu web app do Gemini Enterprise está pronto.
4. Selecione a guia Agente no menu à esquerda para abrir a Galeria de agentes.
5. Selecione Agente do Assistente de hipoteca e comece a conversar.

Teste os mesmos comandos no playground do Agent Runtime:

Comando inicial:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Pergunta complementar:

Can you send a summary of this to my email [e-mail]

Se você voltar à seção "Implantação do agente" no console do Google Cloud, selecionar nossa implantação e acessar a guia "Rastreamentos", vai ver o agente do Gemini Assistant no período que mostra a chamada originada do Gemini Enterprise.

17. Solução de problemas e correções comuns

• terraform apply falha no gateway do agente com "o recurso está sendo criado e, portanto, não pode ser atualizado". O projeto de locatário do gateway leva cerca de 30 segundos para ser concluído antes que as políticas de autorização possam ser anexadas. O time_sleep.wait_for_gateway do módulo processa isso. Basta executar terraform apply novamente.
• O agente informa "nenhum servidor MCP encontrado" ou inicializa apenas com ferramentas de utilidade: confirme enable_agent_registry_endpoints = true em terraform.tfvars e faça o seguinte:

  gcloud alpha agent-registry mcp-servers list \
    --project=${PROJECT_ID} --location=${REGION}
  

  Você vai encontrar três entradas, uma para cada serviço do MCP do Cloud Run. Se a lista estiver vazia, verifique se os serviços do MCP podem ser acessados de dentro da VPC e se o gateway do agente preencheu o registro (isso é feito de forma lenta na primeira lista de ferramentas proxy).
• As chamadas de ferramenta retornam 403 PermissionDenied: execute scripts/grant_agent_mcp_egress.sh novamente. O motivo mais comum é esquecer de conceder novamente após a nova implantação do agente (o reasoningEngines/ muda a cada implantação).
• skaffold run falha com "permissão negada na conta de serviço": você não tem roles/iam.serviceAccountUser. Execute novamente a concessão automática na etapa anterior.
• Erros de peering de DNS do Agent Gateway para o MCP LB: verifique se agent_gateway_dns_peering_config.target_network corresponde exatamente a projects/${PROJECT_ID}/global/networks/${VPC_NAME} e se cada entrada domains termina com um ponto final.
• terraform plan continua querendo atualizar as tags de imagem do Cloud Run. Isso não deve acontecer devido à regra lifecycle { ignore_changes }. Se for o caso, confirme que você não editou mcp_services[*].image em terraform.tfvars depois de skaffold run.

18. Limpar

O mecanismo de raciocínio não é gerenciado pelo Terraform (o SDK do ADK o cria). Exclua manualmente:

gcloud beta ai reasoning-engines delete ${AGENT_ID} \
  --region=${REGION} --project=${PROJECT_ID}

Desfaça tudo o que o Terraform criou:

cd terraform
terraform destroy
cd ..

Se você criou a zona de DNS pública apenas para este codelab:

gcloud dns managed-zones delete agw-example-com

Por fim, exclua o bucket de estado do Terraform:

gcloud storage rm -r gs://${PROJECT_ID}-tfstate

19. Parabéns

Parabéns! Você implementou com sucesso a governança abrangente de um agente do ADK com várias ferramentas usando o Agent Gateway. Ao atuar como o plano de controle de rede centralizado, o Agent Gateway permitiu estabelecer um caminho de saída seguro para ferramentas particulares, aplicar políticas do IAM refinadas com base na identidade pelo Identity-Aware Proxy e limpar interações de conteúdo usando proteções integradas do Model Armor.

O que você aprendeu

• Como implantar e configurar o gateway de agente como a camada de governança central para o tráfego de saída do agente para qualquer lugar.
• Como integrar o Agent Registry para descoberta de ferramentas de tempo de execução dinâmicas e governadas.
• Como escrever e aplicar políticas do IAM por ferramenta e com base em condições para controlar estritamente os caminhos de execução do agente.
• Como usar extensões de serviço do Agent Gateway para aplicar políticas do Model Armor, interceptando e encobrindo automaticamente o tráfego sensível do agente.

Documentos de referência

• Visão geral das políticas de governança de agentes
• Documentação do gateway de agente
• Documentação de identidade do agente
• Visão geral da plataforma de agentes do Gemini Enterprise