Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

1. Introdução

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

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

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

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

O que você vai criar

Gateway de Agente no modo de saída (agente para qualquer lugar)
Extensão de autorização do Identity-Aware Proxy (IAP)
Agente do ADK do Agent Runtime com identidade do agente
Agent Registry com endpoints da API do Google e do MCP
Conectividade de ferramentas MCP externas a conjuntos de dados públicos do Data Commons
Políticas de autorização com controle de acesso do IAM

Figura 1. Arquitetura do codelab

Conteúdo do laboratório

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

O que é necessário

Tenha um projeto do Google Cloud com o faturamento ativado.
Permissões do IAM para provisionar serviços de rede e recursos da Plataforma de Agentes
Um shell compatível com POSIX (bash ou zsh) com a CLI do Google Cloud (componentes gcloud e bq) instalada
Ferramentas de linha de comando: git, curl, jq (processador JSON), Python 3 e uv (gerenciador de pacotes Python)
Uma chave de API do Data Commons sem custo financeiro para acessar conjuntos de dados de teste de consultas

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 das políticas de acesso obrigatórias.

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

Comece no modo DRY_RUN:verifique se as solicitações do agente estão chegando ao gateway e passando por ele (modo somente auditoria).
Registre todos os serviços:registre todos os componentes agênticos no registro de agentes e confirme o acesso às ferramentas do agente.
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.
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.

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 Agent Platform:tráfego de saída direcionado a APIs do Cloud gerenciadas do Google Cloud, modelos de base, endpoints do MCP do Google (como o BigQuery) e serviços de governança da plataforma (registro de agentes e políticas da IAP).

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

O foco deste codelab é o tráfego de saída de um agente personalizado no Agent Runtime que tem como destino um endpoint de servidor MCP externo de terceiros acessível pela Internet.

Inspeção do protocolo MCP

A saída do Agent Gateway (agent-to-anywhere) pode analisar o conteúdo das solicitações do MCP e avaliar as políticas de acesso com base em atributos de protocolo refinados. As políticas de saída do servidor do agente para o MCP podem incluir condições, expressas na Common Expression Language (CEL), que são aplicadas no tempo de execução em todas as solicitações.

As chamadas da MCP geralmente usam o formato de protocolo de rede JSON-RPC e o transporte HTTP. Os detalhes do método MCP invocado (por exemplo, tools/call), o nome da ferramenta de destino e os argumentos estão contidos no payload JSON no corpo HTTP.

O atributo iap.googleapis.com/mcp.toolName é extraído pelo Agent Gateway ao analisar o corpo JSON para encontrar o identificador da ferramenta especificado na solicitação.

Atributos como iap.googleapis.com/mcp.tool.isReadOnly e mcp.tool.isDestructive geralmente não são enviados em cada corpo de solicitação. Em vez disso, são anotações (metadados) associadas à ferramenta. Assim, quando o Agent Gateway extrai o toolName do corpo, ele pesquisa a definição da ferramenta e as propriedades associadas no Agent Registry, onde o conteúdo toolspec.json foi registrado.

Figura 4. Inspeção do MCP do gateway do agente

As expressões CEL usadas nas condições do IAM do IAP usam o formato padrão api.getAttribute('iap.googleapis.com/ATTRIBUTE_NAME', 'DEFAULT_VALUE')== 'DESIRED_VALUE'.

Esta tabela descreve os atributos de governança de saída do gateway do agente que podem ser aplicados a solicitações do servidor MCP:

Atributo	Método / localização da MCP	Descrição
`mcp.toolName`	`tools/call` (corpo)	Identificador da ferramenta de destino solicitada no payload do RPC (por exemplo, `"delete_instance"`)
`mcp.tool.isReadOnly`	Agent Registry (`toolspec.json`)	Indica se a ferramenta é somente leitura (não modifica o ambiente)
`mcp.tool.isDestructive`	Agent Registry (`toolspec.json`)	Indica se a chamada da ferramenta pode resultar em modificações irreversíveis ou perda de dados.
`mcp.tool.isIdempotent`	Agent Registry (`toolspec.json`)	Indica se a execução repetida da ferramenta com argumentos idênticos produz o mesmo estado.
`mcp.tool.isOpenWorld`	Agent Registry (`toolspec.json`)	Indica se a ferramenta vai além dos sistemas internos limitados para a Internet pública sem limites.

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
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 preparo de implantação
Registros e auditoria	`roles/logging.viewer`	Inspecionar rastreamentos e registros de auditoria

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

Acessar seu projeto

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

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

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

Definir o ID do projeto

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Autenticar sessão

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Definir variáveis de ambiente shell

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

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-datacommons"
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_DISPLAY_NAME="api.datacommons.org"
export MCP_RESOURCE_NAME="${REGION}-datacommons-mcp"
export MCP_URL="https://api.datacommons.org/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_RESOURCE_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

Atualizar o `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

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

4. Gateway

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

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

Criar gateway

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

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

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

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

5. Autorização

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

Fluxo de delegação:quando um agente tenta invocar um endpoint externo ou um servidor MCP, ele encaminha a solicitação para o Gateway de Agente. Em vez de avaliar o acesso localmente, o gateway usa a extensão de autorização para enviar um callout ao serviço de avaliação da IAP. O IAP avalia a identidade do agente (baseada em SPIFFE) em relação à política do IAM do recurso de destino no Agent Registry. O IAP retorna uma decisão ALLOW ou DENY para o gateway, que encaminha o tráfego ou o bloqueia com um código de status HTTP 403 Forbidden.
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.
Camada de vinculação:a extensão de serviço está conectada ao Gateway de Agente usando uma política de autorização configurada com o perfil REQUEST_AUTHZ.

Extensão de autorização

Criar extensão de autorização

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

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

# show authz extension details (verify extension state)
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

Política de autorização

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

Criar política de autorização

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

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

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

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

6. Base de código

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

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

Buscar artefatos remotos

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

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_emcp/codelabs/agw-cuj-arun-egress-emcp/agent-datacommons ./agent-datacommons
cp -r temp_agw_cuj_arun_egress_emcp/codelabs/agw-cuj-arun-egress-emcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_emcp

Criar bucket de preparo

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

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

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

7. Registro

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

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

Registrar endpoints

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

Verificar endpoints

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

Isso conclui a parte do registro. Em seguida, vamos para a seção Data Commons.

8. Data Commons

O Data Commons é uma iniciativa do Google para organizar conjuntos de dados públicos e disponibilizá-los para qualquer pessoa. É um serviço sem custo financeiro que pode ser acessado com uma chave de API depois de criar uma conta.

Criar chave de API

Depois de criar uma conta, siga estas etapas para gerar uma chave de API:

Faça login no portal de APIs do Data Commons.
Clique no botão Meus apps no canto superior direito.
Clique no botão + NOVO APP no canto superior direito, abaixo do seu nome de usuário.
Dê um nome ao app (por exemplo, "Codelab Agent MCP")
Clique no botão ATIVAR da API Data Commons. api.datacommons.org
Clique no botão SALVAR no canto inferior direito.

Isso cria uma chave de API e um secret. Clique no ícone "copiar" ao lado do valor da chave para Copiar chave de API. Cole o valor no comando do terminal para definir a variável de ambiente DC_API_KEY.

# set api key env var
 export DC_API_KEY="YOUR_API_KEY_HERE"

Criar servidor MCP `toolspec`

Ao registrar um servidor MCP manualmente, um arquivo de especificação de ferramenta precisa ser incluído durante o registro. O envio de um arquivo toolspec.json lista todas as ferramentas disponibilizadas pelo endpoint e permite que outros usuários as descubram.

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

# generate toolspec for registry ingestion
uv --directory agent-datacommons run python3 test_mcp.py --toolspec=include --token="${DC_API_KEY}"

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.

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

Registrar servidor MCP

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

# 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_RESOURCE_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_RESOURCE_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

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

9. Ambiente de execução

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

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

Implantar agente

# deploy agent runtime workload
uv --directory agent-datacommons 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 data commons stats" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --env-var="DC_API_KEY=${DC_API_KEY}"

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}

10. Políticas

As políticas de autorização de governança de agentes permitem o tráfego de um agente de IA pelo Agent Gateway até o destino (por exemplo, um endpoint de servidor MCP de terceiros para um aplicativo SaaS). 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.

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

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

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

A concessão de roles/iap.egressor à identidade do agente ou ao conjunto de principais do Agent Runtime no recurso de destino selecionado permite esse tráfego de saída. Neste codelab, 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.

Sobre a filtragem condicional do MCP

O servidor MCP do Data Commons tem duas ferramentas:

search_indicators: para consultas sobre como descobrir quais dados estão disponíveis, pesquisar variáveis ou entender a cobertura de dados
get_observations: para consultas que recuperam pontos de dados ou séries temporais específicos

Há algumas operações padrão do MCP que você precisa conhecer ao configurar políticas de governança condicional em servidores MCP. Antes que um cliente do MCP possa fazer um tools/call para search_indicators ou get_observations, ele precisa enviar solicitações de descoberta e handshake de protocolo:

initialize
notifications/initialized
tools/list

Para demonstrar a filtragem condicional de políticas, a política será configurada para estas condições:

Tabela. Avaliação de políticas para solicitações de MCP

Solicitação / Método	Valor de `mcp.toolName`	Avaliação de CEL	Resultado
`initialize`	`""`	`"" in ['search_indicators', '']`	✅ PERMITIDO (200)
`tools/list`	`""`	`"" in ['search_indicators', '']`	✅ PERMITIDO (200)
`search_indicators`	`"search_indicators"`	`"search_indicators" in [...]`	✅ PERMITIDO (200)
`get_observations`	`"get_observations"`	`"get_observations" in [...]`	❌ NEGADO (403)

Para permitir os handshakes de protocolo e a chamada de função search_indicators, a regra de política condicional inclui uma permissão para "search_indicators" ou "" (string vazia).

Configurar a política do IAM do servidor MCP do IAP do registro

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

OBSERVAÇÃO : etag: vai retornar o ACAB padrão porque nenhuma política foi definida ainda.

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

# create policy config file
cat > cfg/iap-policy-dc-agent-to-dc-mcp-tool-1.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ],
      "condition": {
        "title": "allow ${RE_AGENT_NAME} to use search_indicators tool for ${MCP_DISPLAY_NAME}",
        "expression": "api.getAttribute('iap.googleapis.com/mcp.toolName', '') in ['search_indicators', '']"
      }
    }
  ],
  "etag": "${IAP_ETAG}",
  "version": 3
}
EOF

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

# verify iap iam policy for mcp server
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.

11. Auditoria

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

Testar consultas do agente

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

Agent Platform → Agentes → Implantações → agent-datacommons
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 data do you have on water quality in Zimbabwe?
Compare the life expectancy, economic inequality, and GDP growth for BRICS nations

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.

# list unique urls with http status and iap authorization result
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=200 \
  --format="value(httpRequest.status, jsonPayload.authzPolicyInfo.result, httpRequest.requestUrl)" | sort -u

200     ALLOWED https://api.datacommons.org/mcp
200     ALLOWED https://cloudresourcemanager.googleapis.com:443/google.cloud.resourcemanager.v3.Projects/GetProject
200     ALLOWED https://telemetry.googleapis.com/v1/traces
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}/events
202     ALLOWED https://api.datacommons.org/mcp

Atualizar a política de IAM dos endpoints da IAP do registro

Conceder permissões de saída do agente para o endpoint de telemetria

# set var for endpoint display name
export ENDPOINT_1_DISPLAY_NAME="telemetry.googleapis.com"
echo ${ENDPOINT_1_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_1_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_1_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_1_REGISTRY_ID}

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

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

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

Conceder permissões de saída do agente para o endpoint aiplatform

# set var for endpoint display name
export ENDPOINT_2_DISPLAY_NAME="${REGION}-aiplatform.googleapis.com"
echo ${ENDPOINT_2_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_2_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_2_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_2_REGISTRY_ID}

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

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

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

Conceder permissões de saída do agente para o endpoint cloudresourcemanager

# set var for endpoint display name
export ENDPOINT_3_DISPLAY_NAME="cloudresourcemanager.googleapis.com"
echo ${ENDPOINT_3_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_3_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_3_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_3_REGISTRY_ID}

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

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

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

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

12. Aplicar

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

Atualizar extensão de autorização

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

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

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

Atualizar política de autorização

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

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

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

Verificar permissão condicional

Volte para o Playground do agente na interface do console.

Envie outra consulta de teste (tente invocar a ferramenta allowedsearch_indicators)...

What data topics do you have for Peru?

Observe que as solicitações do agente para o modelo de fundação do Gemini (${REGION}-aiplatform.googleapis.com/...), a API de telemetria (telemetry.googleapis.com/...) e o endpoint do servidor MCP do Data Commons (api.datacommons.org/mcp) são transmitidas com códigos de status HTTP 200 OK.

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

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

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

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

Verificar a negação condicional

Envie outra consulta de teste (tente invocar a ferramenta deniedget_observations)...

What are the diabetes levels in Peru compared to Slovakia?

O agente vai analisar search_indicators primeiro e tentar usar get_observations, mas não vai conseguir, e a resposta do agente vai ficar incompleta.

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

TIMESTAMP            STATUS  IAP_AUTHZ  MCP_METHOD                 TOOL_NAME          URL
YYYY-MM-DDTHH:MM:SS  403     DENIED     tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS          ALLOWED    tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  403     DENIED     tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  200     ALLOWED    tools/call                 search_indicators  https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  200     ALLOWED    tools/list                                    https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  202     ALLOWED    notifications/initialized                     https://api.datacommons.org/mcp

Isso valida que a política de governança está funcionando conforme o esperado.

A segunda linha, que indica um status em branco e ALLOWED, é um evento de registro de encerramento de conexão secundário emitido pelo Agent Gateway ao fechar o soquete após o envio da resposta 403. Como os eventos de fechamento de conexão não têm códigos de status de resposta, httpRequest.status fica em branco.

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

13. Limpeza

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

# next

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

# next

# clear policy on mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --mcp-server=${MCP_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 \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

# next

# clear policy on endpoint 1
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_1_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_1_REGISTRY_ID} \
  --region=${REGION}

# next

# clear policy on endpoint 2
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_2_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_2_REGISTRY_ID} \
  --region=${REGION}

# next

# clear policy on endpoint 3
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_3_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_3_REGISTRY_ID} \
  --region=${REGION}

# next

# remove manual registry entry
gcloud -q agent-registry services delete ${MCP_RESOURCE_NAME} --location=${REGION}

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

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

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

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

# next

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

# end

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

14. Conclusão

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

cosmopup

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

O que vem em seguida?

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

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

Valeu!