O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Entrada do Gateway de Agente para o Agent Runtime com o Model Armor

1. Introdução

Este Codelab explora a governança de entrada do Gateway de Agente para agentes de IA hospedados no Agent Runtime.

O Agent Gateway operando no modo de entrada (cliente-agente) oferece suporte à governança de comunicações entre clientes (usuários finais humanos, agentes de desktop, IDEs de programação, agentes semelhantes etc.) e agentes hospedados do Agent Runtime. Esse modo é usado para proteger os agentes contra ataques de injeção de comando de entrada ou conteúdo nocivo enviado por clientes. Todo o tráfego de entrada é processado usando extensões de autorização e o Model Armor para proteger o ponto de entrada da rede em todas as interações do agente.

O que você vai criar

Gateway de Agente no modo de entrada (cliente para agente)
Extensão de autorização do Model Armor
Agente do ADK do Agent Runtime com identidade do agente
Dados de arquivos do Cloud Storage consultados pelo agente usando o MCP
Modelos do Model Armor para analisar comandos e respostas de LLMs
Modelos da Proteção de Dados Sensíveis para desidentificar dados

Figura 1. Arquitetura do codelab

Conteúdo do laboratório

Como implantar o Gateway de Agente para filtrar o tráfego de entrada para um agente
Como configurar extensões de autorização e delegação do Model Armor
Como criar e implantar modelos personalizados do Model Armor
Como criar e implantar modelos personalizados da Proteção de Dados Sensíveis
Como testar e validar políticas de triagem de LLM

O que é necessário

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

2. Conceitos

Direção do tráfego e funções do gateway

O Gateway de Agente funciona como um proxy de rede compatível com agentes, mas a função operacional muda dependendo da direção do tráfego:

Modo agente para qualquer lugar (saída):funciona como um proxy de saída. Quando um agente chama ferramentas de banco de dados externos, servidores MCP de terceiros ou APIs, o gateway de saída gerencia a descoberta de serviços, o roteamento, o TLS mútuo (mTLS), a injeção dinâmica de credenciais OAuth e o controle de acesso aos endpoints.
Modo cliente-agente (entrada):funciona como um gateway de segurança de front-end. O objetivo principal é proteger a entrada do ambiente de execução do agente interceptando e higienizando os comandos de linguagem natural recebidos antes que eles cheguem ao código agêntico ou aos modelos de IA.

Caminho de entrada para o Agent Runtime

As solicitações do cliente destinadas a um agente hospedado no Agent Runtime são direcionadas ao endpoint de API aiplatform.googleapis.com.

POST https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query

Esse fluxo de comunicação de entrada para o endpoint de API representa o caminho de entrada cliente-agente.

Para proteger esse caminho de entrada gerenciado pelo Google, o Gateway de Agente se integra diretamente ao Google Front End (GFE) na camada de infraestrutura de serviço de API. Ao implantar um agente gerenciado no Agent Runtime, o Google vincula nativamente a política de autorização do gateway de entrada às solicitações de clientes recebidas na borda da rede.

Fig. 2. Governança de entrada com o Gateway de Agente para o Agent Runtime

Como a inspeção ocorre na camada de front-end antes que as solicitações entrem no Agent Runtime, essa arquitetura não introduz sobrecarga de rede ou latência de salto interno adicional. O escalonamento é processado automaticamente pela infraestrutura de front-end, eliminando a necessidade de gerenciar intervalos de IP internos, balanceadores de carga ou rotas DNS personalizadas.

Higienização inline de ameaças com o Model Armor

A avaliação das credenciais do autor da chamada e a aplicação do controle de acesso do IAM (roles/aiplatform.user) são processadas de forma nativa pelo nível de hospedagem da API aiplatform. O gateway de entrada em si não realiza autorização de identidade, mas se concentra na segurança de conteúdo usando extensões de autorização configuradas com um perfil CONTENT_AUTHZ. O gateway atua como um ponto de aplicação de políticas inline, interceptando os comandos de linguagem natural em trânsito antes que eles cheguem ao loop de raciocínio do agente de IA ou ao LLM subjacente.

Quando um comando do usuário chega ao serviço de front-end, o gateway inicia um destaque de ext_proc (processamento externo) para o serviço de extensão de autorização regional do Model Armor, que transmite a chamada para o plano de dados do Model Armor. O Model Armor funciona como um firewall de linguagem natural, avaliando o texto em relação a modelos ativos para verificar riscos de segurança:

Tentativas de jailbreak e injeções indiretas de comando
URLs maliciosos, linguagem tóxica ou conteúdo não seguro
Vazamento de informações de identificação pessoal (PII) e dados sensíveis

Se o modelo incluir filtros da Proteção de Dados Sensíveis (SDP), o Model Armor fará uma chamada gRPC adicional ao serviço de SDP do Cloud. O Cloud SDP inspeciona o payload usando o modelo especificado, realiza a desidentificação ou o encobrimento solicitado e retorna o resultado higienizado de volta à cadeia para ser encaminhado com segurança.

Se uma violação da política ou uma correspondência de dados sensíveis não editados for detectada, o gateway vai bloquear ou editar o payload na borda antes de entrar no tempo de execução. Como resultado, o aplicativo do agente de IA em execução permanece protegido e nunca processa payloads maliciosos ou não editados.

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`	Gateway de Agente de Provisionamento
Extensões de serviço	`roles/serviceextensions.admin`	Configurar extensões de roteamento
Segurança de rede	`roles/networksecurity.admin`	Implantar políticas de autorização
Proteção de dados sensíveis	`roles/dlp.admin`	Gerenciar modelos de inspeção e desidentificação do SDP
Model Armor	`roles/modelarmor.admin`	Criar e gerenciar modelos de segurança
Agent Platform	`roles/aiplatform.admin`	Implantar cargas de trabalho do Agent Runtime
Cloud Storage	`roles/storage.admin`	Gerenciar implantação e buckets de dados do cliente
Administração do IAM	`roles/resourcemanager.projectIamAdmin`	Vincular permissões para envolvidos no projeto para a identidade do agente
Registros e auditoria	`roles/logging.viewer`	Inspecionar rastreamentos e registros de auditoria

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

Acessar seu projeto

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

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

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

Definir o ID do projeto

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Autenticar sessão

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Definir variáveis de ambiente shell

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

# 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}-cta"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-crm"
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 DATA_BUCKET="customer-data-${PROJ_NO}"
export MCP_URL="https://storage.mtls.googleapis.com/storage/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${DATA_BUCKET}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

Atualizar `gcloud cli` (recomendado)

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 \
  dlp.googleapis.com

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

4. Gateway

Implante um gateway de agente gerenciado pelo Google que opere no modo cliente-agente (CLIENT_TO_AGENT). Ao contrário dos gateways de saída, que exigem associações de registro de agente para encaminhar chamadas de saída, o gateway de entrada se vincula diretamente na camada de front-end para servir como ponto de aplicação inline para solicitações recebidas destinadas ao Agent Runtime.

Embora as políticas de saída geralmente comecem no modo DRY_RUN na camada de gateway, a governança de conteúdo de entrada (CONTENT_AUTHZ) é implantada diretamente no modo restrito. O registro granular somente de auditoria ou o bloqueio ativo são controlados upstream nos modelos individuais do Model Armor.

Criar gateway

# create agent gateway config file
cat > cfg/${AGW_NAME}.yaml <<EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: CLIENT_TO_AGENT
EOF

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

Verificar gateway

# list agent gateways (in region)
gcloud network-services agent-gateways list --location=${REGION}

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

Isso conclui a parte do gateway... agora vamos para a seção Model Armor.

5. Model Armor

Modelos de SDP

Crie um modelo de inspeção e desidentificação da Proteção de Dados Sensíveis (SDP) para ser usado no modelo de resposta do Model Armor. Essa configuração sinaliza números de Seguro Social dos EUA (SSNs) para redação.

Criar modelo de inspeção

O modelo de inspeção identifica informações sensíveis (US_SOCIAL_SECURITY_NUMBER) nos dados.

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

Criar modelo de desidentificação

O modelo de desidentificação especifica a transformação a ser aplicada aos CPF encontrados pelo modelo de inspeção. Nesse caso, a transformação é substituir o CPF pelo infoType.

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

Verificar modelos de SDP

# get (describe) inspect template
curl -fsS -X GET "https://dlp.googleapis.com/v2/projects/${PROJ_ID}/locations/${REGION}/inspectTemplates" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" -H "x-goog-user-project: ${PROJ_ID}" | jq

# get (describe) de-identify template
curl -fsS -X GET "https://dlp.googleapis.com/v2/projects/${PROJ_ID}/locations/${REGION}/deidentifyTemplates" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" -H "x-goog-user-project: ${PROJ_ID}" | jq

Modelos do Model Armor

O endpoint padrão da API Model Armor é global (modelarmor.googleapis.com). No entanto, os recursos do Model Armor para modelos e mecanismos de avaliação são localizados em regiões geográficas específicas. O proxy de endpoint regional do Google Cloud (REP), ou endpoint de API regional, do Model Armor é https://modelarmor.${LOCATION}.rep.googleapis.com/.

Por padrão, ao executar gcloud model-armor ..., a CLI tenta enviar solicitações de API ao endpoint global padrão (https://modelarmor.googleapis.com/). Uma substituição de endpoint de API é usada para redirecionar todas as solicitações HTTP do SDK/CLI para o Model Armor diretamente ao nível regional da API rep.googleapis.com, onde esses modelos vinculados a locais são criados, armazenados e consultados.

Definir substituição de API

# set api endpoint override per location
gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.${REGION}.rep.googleapis.com/"

Verificar substituição de API

# view api overrides on active gcloud config
gcloud config list api_endpoint_overrides/

Criar modelo de filtro de solicitação

Crie um modelo de filtro de solicitação para bloquear discurso de ódio, assédio, conteúdo sexualmente explícito e ataques de injeção de URI. O registro em log será ativado para capturar informações detalhadas sobre a aplicação da política. Códigos e mensagens de erro personalizados também são configurados para quando uma solicitação é bloqueada.

# create model armor template (request)
gcloud beta model-armor templates create ${AGW_NAME}-modar-req-template \
  --project=${PROJ_ID} \
  --location=${REGION} \
  --rai-settings-filters='[
    { "filterType": "HATE_SPEECH", "confidenceLevel": "MEDIUM_AND_ABOVE" },
    { "filterType": "HARASSMENT", "confidenceLevel": "MEDIUM_AND_ABOVE" },
    { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "MEDIUM_AND_ABOVE" }
  ]' \
  --pi-and-jailbreak-filter-settings-enforcement=enabled \
  --pi-and-jailbreak-filter-settings-confidence-level=medium-and-above \
  --template-metadata-enforcement-type=INSPECT_AND_BLOCK \
  --malicious-uri-filter-settings-enforcement=enabled \
  --template-metadata-custom-llm-response-safety-error-code=798 \
  --template-metadata-custom-llm-response-safety-error-message="ahoy! model response blocked by content filter :(" \
  --template-metadata-custom-prompt-safety-error-code=799 \
  --template-metadata-custom-prompt-safety-error-message="ahoy! the request was blocked by ye content filter... so rephrase the prompt and try again!" \
  --template-metadata-ignore-partial-invocation-failures \
  --template-metadata-log-operations \
  --template-metadata-log-sanitize-operations

Criar modelo de filtro de resposta

Crie um modelo de filtro de resposta para bloquear o mesmo conteúdo que o modelo de filtro de solicitação. A DLP é configurada na parte da resposta para remover a identificação de SSNs em mensagens que retornam do agente para o cliente.

# create model armor template (response)
gcloud beta model-armor templates create ${AGW_NAME}-modar-resp-template \
  --project=${PROJ_ID} \
  --location=${REGION} \
  --rai-settings-filters='[
      { "filterType": "HATE_SPEECH", "confidenceLevel": "MEDIUM_AND_ABOVE" },
      { "filterType": "HARASSMENT", "confidenceLevel": "MEDIUM_AND_ABOVE" },
      { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "MEDIUM_AND_ABOVE" }
  ]' \
  --malicious-uri-filter-settings-enforcement=enabled \
  --advanced-config-inspect-template=projects/${PROJ_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template \
  --advanced-config-deidentify-template=projects/${PROJ_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template \
  --template-metadata-enforcement-type=INSPECT_AND_BLOCK \
  --template-metadata-custom-llm-response-safety-error-code=798 \
  --template-metadata-custom-llm-response-safety-error-message="ahoy! model response blocked by content filter :(" \
  --template-metadata-custom-prompt-safety-error-code=799 \
  --template-metadata-custom-prompt-safety-error-message="ahoy! the request was blocked by ye content filter... so rephrase the prompt and try again!" \
  --template-metadata-ignore-partial-invocation-failures \
  --template-metadata-log-operations \
  --template-metadata-log-sanitize-operations

Verificar modelos do Model Armor

# list model armor templates
gcloud model-armor templates list --location=${REGION}

# show request filter template details
gcloud model-armor templates describe ${AGW_NAME}-modar-req-template --location=${REGION}

# show response filter template details
gcloud model-armor templates describe ${AGW_NAME}-modar-resp-template --location=${REGION}

Permissões do IAM

O Model Armor faz chamadas de API para invocar o serviço de Proteção de Dados Sensíveis (SDP). Conceda à identidade de serviço do Model Armor permissões do IAM para usar modelos de inspeção e desidentificação da SDP.

Vincular a política do IAM para a Proteção de Dados Sensíveis

# grant dlp (sdp) user role to the model armor service identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-modelarmor.iam.gserviceaccount.com" \
  --role="roles/dlp.user"

Verificar permissões do IAM

# show iam policy for all dlp (sdp) roles on project
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.role:roles/dlp" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

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

6. Autorização

Permissões do IAM

Para inspecionar o tráfego inline usando o Model Armor, o agente de serviço das extensões de serviço (DEP) exige vinculações explícitas do IAM, mesmo entre recursos no mesmo projeto:

roles/modelarmor.calloutUser e roles/serviceusage.serviceUsageConsumer:concedidas no projeto do gateway para permitir callouts de inspeção inline.
roles/modelarmor.user:concedida no projeto de modelo para permitir o acesso e a avaliação dos modelos do Model Armor.

Vincular política do IAM para o Model Armor

# grant model armor callout user role to dep (service extension) service agent
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/modelarmor.calloutUser"

# grant service usage consumer role to dep (service extension) service agent
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

# grant model armor user role to dep (service extension) service agent
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/modelarmor.user"

Verificar permissões do IAM

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

Extensão de autorização

A configuração da extensão de autorização para o Gateway de Agente define as configurações de integração que serão aplicadas ao tráfego de payload de entrada e saída. A configuração define o serviço de processamento externo (service), que faz referência à API regional do Model Armor e se vincula aos modelos de solicitação e resposta específicos usando o campo de metadados model_armor_settings.

Criar extensão de autorização

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-modar.yaml <<EOF
name: ${AGW_NAME}-svc-ext-authz-modar
service: modelarmor.${REGION}.rep.googleapis.com
metadata:
  model_armor_settings: '[
    {
      "request_template_id": "projects/${PROJ_ID}/locations/${REGION}/templates/${AGW_NAME}-modar-req-template",
      "response_template_id": "projects/${PROJ_ID}/locations/${REGION}/templates/${AGW_NAME}-modar-resp-template"
    }
  ]'
failOpen: true
timeout: 5s
EOF

Importar extensão de autorização

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

Verificar a extensão de autorização

# list authz extensions
gcloud service-extensions authz-extensions list --location=${REGION}

# show authz extension details
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-modar \
  --location=${REGION}

Política de autorização

As políticas de autorização usam perfis de política para determinar o tipo de avaliação realizada. Enquanto os perfis baseados em solicitação (REQUEST_AUTHZ) avaliam cabeçalhos HTTP, essa configuração usa um perfil de autorização baseado em conteúdo (CONTENT_AUTHZ) para vincular a extensão Model Armor ao gateway para inspeção detalhada de payload.

Criar política de autorização

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

Importar política de autorização

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

Verificar a política de autorização

# list authz policies
gcloud beta network-security authz-policies list --location=${REGION}

# show authz policy details
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-modar \
  --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 código do agente e os dados de arquivo 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.

Buscar artefatos remotos

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

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_ingress_modar/codelabs/agw-cuj-arun-ingress-modar/agent-crm ./agent-crm

# remove temporary directory
rm -rf temp_agw_cuj_arun_ingress_modar

Um bucket de armazenamento para preparação é usado pelo Agent Runtime para fazer upload, criar e implantar o código do aplicativo do agente empacotado e os artefatos de dependência dele.

Criar bucket de armazenamento para preparo

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

Verificar o bucket de armazenamento

# list storage buckets
gcloud storage buckets list --format="value(storage_url)"

Isso conclui a parte do codebase. Em seguida, vamos para a seção Dados do cliente do GCS.

Dados do cliente

Crie um bucket do Cloud Storage para armazenar dados de clientes. O agente vai ler diretamente usando a biblioteca de cliente padrão do Google Cloud, que chama o endpoint MCP do Cloud Storage.

Criar um bucket de armazenamento para dados do cliente

# create storage bucket
gcloud storage buckets create gs://${DATA_BUCKET} --location=${REGION}

Verificar o bucket de armazenamento

# list storage buckets
gcloud storage buckets list --format="value(storage_url)"

Fazer o upload dos dados dos clientes

# copy local data to bucket
gcloud storage cp -r ./agent-crm/data/* gs://${DATA_BUCKET}/

Verificar os dados do cliente

# list bucket objects
gcloud storage ls gs://${DATA_BUCKET}/ --long

Isso conclui a parte sobre dados do cliente do GCS. Em seguida, vamos para a seção do agente do ADK.

8. Agente do ADK

O agente do ADK agent-crm 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
"client_to_agent_config": {"agent_gateway": "${AGW_URI}"} para direcionar todo o tráfego de entrada do agente ao caminho de avaliação e aplicação da política do gateway do agente.

O agente também recebe o URL do servidor mTLS MCP para o servidor MCP do Cloud Storage e o nome do bucket de dados para invocar a ferramenta MCP do GCS em uma conexão segura.

Implantar agente

# deploy agent
uv --directory agent-crm 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 customer data" \
  --mcp-server-url="${MCP_URL}" \
  --data-bucket=${DATA_BUCKET} \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-ingress=${AGW_URI} \
  --allow-token-sharing

Verificar implantação

Buscar sinais vitais de implantação

# fetch agent runtime (reasoning engine) resource 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 \
  --project=${PROJ_ID} --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

Verificar a configuração do gateway

# show agent runtime 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}'

Permissões do IAM

Vincular políticas do IAM à identidade do agente

# grant mcp tool user role to agent set (all agent runtime agents in project)
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_ID_SET}" \
  --role="roles/mcp.toolUser"

# grant storage object viewer role to agent identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/storage.objectViewer"

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

# grant cloudtrace agent role to agent identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/cloudtrace.agent"

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

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

# grant telemetry writer role to agent identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/telemetry.writer"

# grant service usage consumer role to agent identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/serviceusage.serviceUsageConsumer"

# grant browser role to agent identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

Verificar permissões do IAM

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

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

Isso conclui a parte do agente do ADK. Em seguida, vamos para a seção Teste.

9. Teste

Enviar consultas da CLI

Testar um comando seguro

# post query to agent streamQuery
curl --no-buffer -s -X POST "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" -H "X-Goog-User-Project: ${PROJ_ID}" \
  -d @- <<EOF | jq -r --unbuffered 'if type == "array" then .[] else . end | select(.content.parts != null) | .content.parts[].text // empty'
{
  "input": {
    "message": "what are the names of our west customers?",
    "user_id": "test-user"
  }
}
EOF

Você vai receber uma resposta como... "Nossos clientes da região oeste são: Bob Johnson e Alice Brown"

Testar um gatilho de redação

# post query to agent streamQuery
curl --no-buffer -s -X POST "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" -H "X-Goog-User-Project: ${PROJ_ID}" \
  -d @- <<EOF | jq -r --unbuffered 'if type == "array" then .[] else . end | select(.content.parts != null) | .content.parts[].text // empty'
{
  "input": {
    "message": "what are ssn's for bob johnson and alice brown?",
    "user_id": "test-user"
  }
}
EOF

Testar outro comando seguro

# post query to agent streamQuery
curl --no-buffer -s -X POST "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" -H "X-Goog-User-Project: ${PROJ_ID}" \
  -d @- <<EOF | jq -r --unbuffered 'if type == "array" then .[] else . end | select(.content.parts != null) | .content.parts[].text // empty'
{
  "input": {
    "message": "what are bob johnson's and alice brown's email addresses?",
    "user_id": "test-user"
  }
}
EOF

Registros de auditoria

Ver os registros de rastreamento

Quando a telemetria está ativada, o ambiente de execução do agente transmite eventos estruturados que representam consultas do usuário, parâmetros de ferramentas, fluxos de execução e saídas de escolha de modelo.

# show agent runtime (reasoning engine) telemetry and trace logs
gcloud logging read \
  "logName:\"projects/${PROJ_ID}/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout\" AND labels.managed-by=\"reasoning-engine\"" \
  --project=${PROJ_ID} \
  --limit=15 \
  --format="table(
    timestamp.date(format=\"%I:%M:%S %p\", tz=LOCAL):label=TIME,
    trace.basename().sub('^(.{8}).*$', '\\1'):label=TRACE_ID,
    labels.\"event.name\".scope(-1):label=EVENT,
    jsonPayload.content.role:label=ROLE,
    jsonPayload.content.parts[0].text:label=TEXT_CONTENT,
    jsonPayload.content.parts[0].function_call.name:label=TOOL_CALL
  )"

O TRACE_ID agrupa a consulta do usuário, as chamadas de ferramentas intermediárias e as decisões do modelo em uma única linha do tempo:

TIME         TRACE_ID  EVENT                  ROLE   TEXT_CONTENT                                     TOOL_CALL
HH:MM:SS PM  3070a1fd  gen_ai.choice          model  Bob Johnson's SSN is 219-45-7895.
                                                     Alice Brown's SSN is 219-45-7896.
HH:MM:SS PM  3070a1fd  gen_ai.user.message    user
HH:MM:SS PM  3070a1fd  gen_ai.user.message    model                                                   read_customer_file
HH:MM:SS PM  3070a1fd  gen_ai.user.message    user
HH:MM:SS PM  3070a1fd  gen_ai.user.message    model                                                   read_customer_file
HH:MM:SS PM  3070a1fd  gen_ai.user.message    user
HH:MM:SS PM  3070a1fd  gen_ai.user.message    model                                                   list_customer_files
HH:MM:SS PM  3070a1fd  gen_ai.user.message    user   what are ssn's for bob johnson and alice brown?
HH:MM:SS PM  3070a1fd  gen_ai.system.message
HH:MM:SS PM  3070a1fd  gen_ai.choice          model                                                   read_customer_file

Conferir os registros de higienização do Model Armor

Esses registros mostram a ameaça e a limpeza bidirecionais em tempo real realizadas pelo Model Armor à medida que o tráfego flui pelo gateway de agentes.

# show model armor logs
gcloud logging read \
  "logName:\"projects/${PROJ_ID}/logs/modelarmor.googleapis.com%2Fsanitize_operations\"" \
  --project=${PROJ_ID} \
  --limit=50 \
  --format="table(
    timestamp.date(format=\"%I:%M:%S %p\", tz=LOCAL):label=TIME,
    jsonPayload.sanitizationResult.sanitizationVerdict:label=VERDICT,
    jsonPayload.sanitizationInput.byteItem.byteData.decode(base64).decode(utf-8).sub('\n', ' \\\\\\\\n ').trailoff(123):label=INPUT_DATA
  )"

Observe a entrada de registro da solicitação higienizada e bloqueada.

TIME         VERDICT                                 INPUT_DATA
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_ALLOW  Bob Johnson's email address is bob.j@example.com. \n Alice Brown's email address is alice.b...
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_ALLOW  what are bob johnson's and alice brown's email addresses?
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_BLOCK  6��
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_ALLOW  what are ssn's for bob johnson and alice brown?
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_ALLOW  Our west customers are: Bob Johnson and Alice Brown.
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_ALLOW  what are the names of our west customers?

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

10. Limpeza

# remove agent iam bindings
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/storage.objectViewer"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/aiplatform.user"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/cloudtrace.agent"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/monitoring.metricWriter"

# next

# remove more agent and agent set iam bindings
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/logging.logWriter"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/telemetry.writer"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/serviceusage.serviceUsageConsumer"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/browser"

# next

# remove rest of iam bindings
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_ID_SET}" --role="roles/mcp.toolUser"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="serviceAccount:service-${PROJ_NO}@gcp-sa-modelarmor.iam.gserviceaccount.com" --role="roles/dlp.user"

# next

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

# next

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

# next

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

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

# next

# remove dep (service extensions) service agent iam bindings
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/modelarmor.calloutUser"

gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/modelarmor.user"

# next

# delete model armor templates
gcloud -q model-armor templates delete ${AGW_NAME}-modar-resp-template --location=${REGION}
gcloud -q model-armor templates delete ${AGW_NAME}-modar-req-template --location=${REGION}

# unset model armor api endpoint override
gcloud config unset api_endpoint_overrides/modelarmor

# next

# delete sdp (dlp) templates
curl -fsS -X DELETE "https://dlp.googleapis.com/v2/projects/${PROJ_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJ_ID}"

curl -fsS -X DELETE "https://dlp.googleapis.com/v2/projects/${PROJ_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJ_ID}"

# next

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

# end

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

11. Conclusão

Parabéns! Você implantou o gateway de agente e governou o tráfego de entrada para um agente de IA.

cosmopup

O Cosmopup acha que os codelabs são muito legais!

O que vem em seguida?

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

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

Valeu!

Entrada do Gateway de Agente para o Agent Runtime com o Model Armor

1. Introdução

O que você vai criar

Conteúdo do laboratório

O que é necessário

2. Conceitos

Direção do tráfego e funções do gateway

Caminho de entrada para o Agent Runtime

Higienização inline de ameaças com o Model Armor

3. Configuração

Papéis do IAM obrigatórios

Acessar seu projeto

Definir o ID do projeto

Autenticar sessão

Definir variáveis de ambiente shell

Atualizar gcloud cli (recomendado)

Ativar serviços de API

4. Gateway

Criar gateway

Verificar gateway

5. Model Armor

Modelos de SDP

Criar modelo de inspeção

Criar modelo de desidentificação

Verificar modelos de SDP

Modelos do Model Armor

Definir substituição de API

Verificar substituição de API

Criar modelo de filtro de solicitação

Criar modelo de filtro de resposta

Verificar modelos do Model Armor

Permissões do IAM

Vincular a política do IAM para a Proteção de Dados Sensíveis

Verificar permissões do IAM

6. Autorização

Permissões do IAM

Vincular política do IAM para o Model Armor

Verificar permissões do IAM

Extensão de autorização

Criar extensão de autorização

Importar extensão de autorização

Verificar a extensão de autorização

Política de autorização

Criar política de autorização

Importar política de autorização

Verificar a política de autorização

7. Base de código

Buscar artefatos remotos

Criar bucket de armazenamento para preparo

Verificar o bucket de armazenamento

Dados do cliente

Criar um bucket de armazenamento para dados do cliente

Verificar o bucket de armazenamento

Fazer o upload dos dados dos clientes

Verificar os dados do cliente

8. Agente do ADK

Implantar agente

Verificar implantação

Buscar sinais vitais de implantação

Verificar a configuração do gateway

Permissões do IAM

Vincular políticas do IAM à identidade do agente

Verificar permissões do IAM

9. Teste

Enviar consultas da CLI

Testar um comando seguro

Testar um gatilho de redação

Testar outro comando seguro

Registros de auditoria

Ver os registros de rastreamento

Conferir os registros de higienização do Model Armor

10. Limpeza

11. Conclusão

O que vem em seguida?

Atualizar `gcloud cli` (recomendado)