Governar agentes com o Gateway de Agente

O Gateway de Agente permite que você controle o tráfego de saída dos agentes de IA que você cria e hospeda no Cloud Run. Ao rotear o tráfego de saída do serviço do Cloud Run por um Gateway de Agente autogerenciado que é executado no Secure Web Proxy, é possível aplicar políticas de acesso centralizadas, inspecionar payloads para garantir a segurança do conteúdo e coletar telemetria de observabilidade em todas as cargas de trabalho do agente.

Neste documento, descrevemos como configurar uma arquitetura centralizada para o Gateway de Agente no Cloud Run e abordamos como fazer o seguinte:

Arquitetura

Em uma implantação autogerenciada centralizada, o Secure Web Proxy atua como o ponto de aplicação de políticas e é executado na rede de nuvem privada virtual (VPC). O contêiner secundário de rede de ambiente intercepta o tráfego de saída do agente do Cloud Run e o encaminha pela saída de VPC direta para a instância do Secure Web Proxy. O Secure Web Proxy aplica regras de acesso e conteúdo de pontos de decisão de política, como o Identity-Aware Proxy (IAP) e o Model Armor.

Diagrama de arquitetura mostrando um serviço do Cloud Run com um contêiner de agente e um contêiner de proxy sidecar de ambiente roteando o tráfego pela saída de VPC direta para um Gateway de Agente autogerenciado apoiado pelo Secure Web Proxy dentro de uma rede VPC.
Figura 1. Arquitetura do Gateway de Agente autogerenciado para um agente do Cloud Run.

Para rotear e controlar o tráfego nessa arquitetura, configure os seguintes componentes:

  • Saída de VPC direta e rede de ambiente: o serviço do Cloud Run se conecta à rede VPC com --vpc-egress=all e --ambient-networking, que usa o escopo regional por padrão e encaminha todo o tráfego de saída para a rede VPC.
  • Gateway de Agente autogerenciado: um recurso lógico do Gateway de Agente no modo autogerenciado aponta para a instância do Secure Web Proxy na sua rede VPC.
  • Política de roteamento de saída: uma política EgressRouting da API Network Services direciona o tráfego de saída do serviço do Cloud Run para a instância do Secure Web Proxy.

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. Ative as APIs Cloud Run Admin, Network Services, Network Security, Service Extensions, Model Armor, Certificate Authority Service, Certificate Manager, Cloud Resource Manager, App Hub, Identity and Access Management, Identity-Aware Proxy, API Compute Engine, Traffic Director, Cloud DNS, API Network Connectivity e Agent Registry, se ainda não estiverem ativadas.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar as APIs

  13. Crie uma rede VPC e uma sub-rede com o Acesso privado do Google ativado na sub-rede.
  14. Configure o Agent Registry no seu projeto ou organização.
  15. Instale e inicialize a Google Cloud CLI.
  16. Atualize os componentes da CLI gcloud: 
    gcloud components update

Funções exigidas

Para receber as permissões necessárias para configurar o Gateway de Agente para o Cloud Run, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Se você configurar uma implantação entre projetos com a VPC compartilhada, peça ao administrador para conceder a você roles/compute.xpnAdmin no nível da organização ou da pasta.

Criar um Gateway de Agente autogerenciado

Antes de criar o recurso de Gateway de Agente, implante e configure uma instância do Secure Web Proxy na sua rede VPC, conforme descrito em Implantar o Secure Web Proxy como um Gateway de Agente:

  1. Configure a inspeção de TLS e crie uma política de segurança de gateway que anexe seu TlsInspectionPolicy. Não é necessário ter regras de política de segurança ou listas de URLs do Secure Web Proxy.
  2. Crie um recurso ServerTlsPolicy com allowOpen: false e mtlsPolicy.clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT. Não defina clientValidationTrustConfig.
  3. Implante uma instância do Secure Web Proxy no modo de roteamento de proxy explícito com addresses, ports, certificateUrls, gatewaySecurityPolicy e serverTlsPolicy configurados ao criar o gateway para que o Cloud Run transmita a identidade da carga de trabalho do agente para o Secure Web Proxy e o IAP por mTLS.

Depois que a instância do Secure Web Proxy estiver pronta, crie um recurso de Gateway de Agente autogerenciado que aponte para ela:

  1. Crie um arquivo de configuração YAML chamado my-agent-gateway.yaml:

    name: AGENT_GATEWAY_NAME
registries:
  - "//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION"
selfManaged:
  resourceUris:
    - "projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME"

    Substitua:

    • AGENT_GATEWAY_NAME: o nome que você quer atribuir ao recurso do Gateway de Agente.
    • PROJECT_ID: o ID do projeto que hospeda sua instância do Secure Web Proxy.
    • REGION: a região da instância do Secure Web Proxy, como us-central1.
    • SWP_NAME: o nome da instância do Secure Web Proxy.

  2. Importe a configuração do Gateway de Agente:

    gcloud beta network-services agent-gateways import AGENT_GATEWAY_NAME \
   --source="my-agent-gateway.yaml" \
   --location=REGION \
   --project=PROJECT_ID

  3. Verifique o recurso do Gateway de Agente:

    gcloud beta network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID

    Confirme se a saída mostra a configuração de selfManaged e o URI do recurso da instância do Secure Web Proxy antes de prosseguir para a próxima seção.

Configurar a rede de ambiente do Cloud Run para acessar a API Traffic Director

Quando você configura um serviço do Cloud Run com saída VPC direta e --vpc-egress=all, todas as conexões de saída da instância de contêiner são roteadas pela rede VPC. Isso inclui a conexão do sidecar do Envoy com o trafficdirector.REGION.rep.googleapis.com.

Para permitir que o arquivo secundário resolva e alcance a API Traffic Director, configure uma zona particular do Cloud DNS na sua rede VPC com base no uso do VPC Service Controls pelo ambiente:

Sem o VPC Service Controls

Se o projeto não usar o VPC Service Controls, crie uma zona de DNS particular do Cloud DNS que encaminhe solicitações de trafficdirector.REGION.rep.googleapis.com para o endereço IP do gateway do Secure Web Proxy para que o Secure Web Proxy permita o tráfego:

  1. Recupere o endereço IP interno do gateway do Secure Web Proxy:

    SWP_IP=$(gcloud network-services gateways describe SWP_NAME \
 --project="PROJECT_ID" \
 --location="REGION" \
 --format="value(addresses[0])")

    Substitua:

    • SWP_NAME: o nome da instância do Secure Web Proxy.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • REGION: a região da implantação.

  2. Crie uma zona gerenciada particular do Cloud DNS para a API Traffic Director:

    gcloud dns managed-zones create td-swp-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone routing control plane traffic to SWP" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

    Substitua VPC_NETWORK_NAME pelo nome da rede VPC.

  3. Adicione um registro A que aponte o domínio regional da API Traffic Director para o endereço IP do Secure Web Proxy:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-swp-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${SWP_IP}"

  4. Verifique se o conjunto de registros DNS está ativo na zona particular:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-swp-zone"

    Confirme se o registro A de trafficdirector.REGION.rep.googleapis.com. é resolvido para o endereço IP do Secure Web Proxy.

Com o VPC Service Controls

Para ambientes do VPC Service Controls, provisione um endpoint regional do Private Service Connect visando a API Traffic Director regional dentro da sub-rede VPC e mapeie o domínio usando uma zona particular do Cloud DNS:

  1. Crie um endpoint regional do Private Service Connect que tenha como destino a API Traffic Director regional:

    gcloud network-connectivity regional-endpoints create td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --network="projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME" \
 --subnetwork="projects/PROJECT_ID/regions/REGION/subnetworks/VPC_SUBNET_NAME" \
 --target-google-api="trafficdirector.REGION.rep.googleapis.com"

    Substitua:

    • PROJECT_ID: o ID do projeto Google Cloud .
    • REGION: a região da implantação.
    • VPC_NETWORK_NAME: o nome da sua rede VPC.
    • VPC_SUBNET_NAME: o nome da sub-rede VPC.

  2. Recupere o endereço IP interno do endpoint regional:

    TD_ENDPOINT_IP=$(gcloud network-connectivity regional-endpoints describe td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --format="value(address)")

  3. Crie uma zona gerenciada particular do Cloud DNS para a API Traffic Director:

    gcloud dns managed-zones create td-psc-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone for regional endpoint" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

  4. Adicione um registro A que resolva o domínio regional da API Traffic Director para o endereço IP do endpoint regional:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-psc-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${TD_ENDPOINT_IP}"

  5. Verifique o endpoint regional e o conjunto de registros DNS:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-psc-zone"

    Confirme se o registro A de trafficdirector.REGION.rep.googleapis.com. aponta para o endereço IP do endpoint regional.

Implantar ou atualizar um serviço do Cloud Run com rede ambiente e saída de VPC direta

Para conectar o agente do Cloud Run à instância do Secure Web Proxy na rede VPC, ative a saída de VPC direta e a rede ambiente regional e configure o serviço com uma identidade de agente. Quando você implanta com --functional-type=agent e --identity-type=agent-identity, o Cloud Run concede roles/run.agentDefaultAccess, que inclui as permissões roles/trafficdirector.client e roles/cloudtrace.agent:

  1. Implante um novo serviço de agente do Cloud Run ou atualize um serviço existente para ativar a rede regional de ambiente, a saída de VPC direta para todo o tráfego de saída e a identidade do agente:

    Novo serviço

    gcloud beta run deploy SERVICE_NAME \
 --image=IMAGE_URL \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Serviço atual

    gcloud beta run services update SERVICE_NAME \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --update-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Substitua:

    • SERVICE_NAME: o nome do serviço do agente do Cloud Run.
    • IMAGE_URL: uma referência à imagem do contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
    • VPC_NETWORK_NAME: o nome da rede VPC que hospeda sua instância do Secure Web Proxy. Para informações sobre como criar uma rede VPC e uma sub-rede, consulte Criar e gerenciar redes VPC.
    • VPC_SUBNET_NAME: o nome da sub-rede VPC em que sua instância do Secure Web Proxy pode ser acessada.
    • REGION: a região do serviço.
    • PROJECT_ID: o ID do projeto Google Cloud .

  2. Verifique se o serviço do Cloud Run usa rede de ambiente, saída de VPC direta e identidade do agente:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID

    Confirme se a saída mostra a sub-rede de saída de VPC direta, a saída all-traffic, a rede de ambiente regional e o principal de identidade do agente atribuído.

Configurar o agente do Cloud Run para confiar no Gateway de Agente

Para que o Secure Web Proxy inspecione payloads HTTPS e aplique políticas, ele precisa encerrar as sessões TLS de saída do agente. O contêiner do agente do Cloud Run precisa confiar no certificado da autoridade certificadora (CA) raiz ou subordinada associado à política de inspeção de TLS do Secure Web Proxy no CA Service ou na ICP da sua empresa particular:

  1. Exporte o certificado de CA codificado em PEM do pool do serviço de CA para sua instância do Secure Web Proxy:

    gcloud privateca pools get-ca-certs CA_POOL_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --output-file=agent-gateway-root.crt

    Substitua:

    • CA_POOL_NAME: o nome do pool de CAs associado à política de inspeção de TLS do Secure Web Proxy.
    • REGION: a região do pool de CAs.
    • PROJECT_ID: o ID do projeto Google Cloud .

  2. Atualize o serviço do Cloud Run para transmitir o conteúdo do certificado em uma variável de ambiente:

    gcloud beta run services update SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --update-env-vars="AGENT_GATEWAY_ROOT_CERT=$(cat agent-gateway-root.crt)"

    Substitua:

    • SERVICE_NAME: o nome do serviço do agente do Cloud Run.
    • REGION: a região do serviço.
    • PROJECT_ID: o ID do projeto Google Cloud .

    Por exemplo, o seguinte script de ponto de entrada de contêiner do Debian ou Ubuntu, entrypoint.sh, instala AGENT_GATEWAY_ROOT_CERT no repositório de confiança do sistema e exporta os caminhos do pacote de CA para clientes Python e gRPC antes de iniciar o aplicativo:

    #!/usr/bin/env bash
set -e
if [ -n "${AGENT_GATEWAY_ROOT_CERT}" ]; then
 printf '%s\n' "${AGENT_GATEWAY_ROOT_CERT}" > /usr/local/share/ca-certificates/agent-gateway.crt
 update-ca-certificates
 export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
 export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
fi
exec "$@"

  3. Verifique se o serviço define a variável de ambiente AGENT_GATEWAY_ROOT_CERT:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --format="yaml(spec.template.spec.containers[0].env)"

Rotear o tráfego de saída para o Gateway de Agente

Depois de configurar o serviço do Cloud Run e o Gateway de Agente, crie uma política EgressRouting da API Network Services para direcionar o tráfego de saída do serviço do Cloud Run para o gateway do Secure Web Proxy:

  1. Criar o recurso EgressRouting:

    gcloud alpha network-services egress-routings create my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME"

    Substitua:

    • REGION: a região do serviço e do gateway do Cloud Run.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • SWP_NAME: o nome do recurso subjacente do Secure Web Proxy Gateway, não o recurso AgentGateway.
    • SERVICE_NAME: o nome do serviço do agente do Cloud Run. Para rotear todos os serviços do Cloud Run no projeto pelo gateway com uma única política, defina workloadUri como //run.googleapis.com/projects/PROJECT_ID ou //run.googleapis.com/projects/PROJECT_NUMBER.

    Depois que EgressRouting entrar em vigor, todo o tráfego de saída do serviço do Cloud Run será roteado pelo Secure Web Proxy. Configure as políticas na próxima seção para permitir e controlar as solicitações de saída.

  2. Verifique se o recurso EgressRouting está ativo:

    gcloud alpha network-services egress-routings describe my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID

    Confirme se sources lista o URI da carga de trabalho do Cloud Run e se gateway faz referência ao recurso de gateway do Secure Web Proxy.

Configurar políticas no Gateway de Agente

Depois de rotear o tráfego de saída pelo Gateway de Agente, controle as solicitações de saída do agente anexando políticas de autorização e vinculações de extensão de extensões de serviço ao recurso do Gateway de Agente:

  • Tráfego de referência e filtragem de ferramentas do MCP: permita endpoints de modelo e métodos e ferramentas aprovados do Protocolo de Contexto de Modelo (MCP) usando políticas de autorização ALLOW.
  • Controle de acesso baseado em identidade: vincule o IAP a um ExtensionBinding recurso e configure uma Política de acesso unificado do IAM para controlar quais agentes podem chamar servidores MCP, ferramentas ou endpoints específicos.
  • Segurança de conteúdo: vincule o Model Armor a um recurso ExtensionBinding para inspecionar e higienizar comandos e respostas em busca de injeção de comandos, vazamento de dados sensíveis ou violações de políticas.

Todas as políticas de autorização ou regras de política de segurança de gateway anexadas ao recurso Gateway do Secure Web Proxy são ignoradas. Depois de criar ou atualizar um recurso ExtensionBinding, as mudanças podem levar até cinco minutos para serem propagadas para o gateway. Para ver a sequência de avaliação de regras em regras de rede, inspeção de TLS, vinculações de extensão e regras HTTP, consulte Ordem de avaliação para regras de autorização.

Permitir tráfego de saída de referência e MCP

O Secure Web Proxy nega todo o tráfego de saída com erros 403 Forbidden por padrão até que um ALLOW AuthzPolicy no recurso do Gateway de Agente permita.

Como o serviço do Cloud Run usa --vpc-egress=all, todo o tráfego de saída do contêiner, incluindo chamadas de ferramenta do MCP e solicitações de LLM, é roteado pelo gateway. Anexe políticas de autorização ALLOW ao recurso do Gateway de Agente para os dois tipos de tráfego:

Configurar políticas de saída do IAP

O Gateway de Agente usa o IAP como mecanismo de decisão de política para avaliar as Políticas de Acesso Unificadas do IAM. Para aplicar políticas de identidade de agente, defina suas regras de acesso em uma política de acesso unificada do IAM e vincule o IAP ao gateway:

  1. Crie uma política de acesso unificado do IAM usando o principal Identidade do agente do serviço do Cloud Run, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME, e vincule a política ao projeto ou gateway seguindo Criar políticas de acesso do IAM e Vincular uma política de acesso unificado a um projeto.
  2. Vincule o IAP, iap.googleapis.com, ao Gateway de Agente com um ExtensionBinding seguindo as instruções em Vincular o IAP ao Gateway de Agente.

Como o --vpc-egress=all envia chamadas de modelo, como REGION-aiplatform.googleapis.com, pelo gateway, defina o escopo de matchConditions no ExtensionBinding do IAP como prefix: "urn:mcp" para que as chamadas de modelo ignorem a avaliação do IAP. Para também controlar o tráfego de agente para agente, adicione prefix: "urn:agent". Se a vinculação de extensão corresponder a outros hosts, adicione uma regra de permissão para cada host na política de acesso unificado do IAM, como destination.unregistered.host == 'REGION-aiplatform.googleapis.com'. Por exemplo, consulte Criar uma política de agente para endpoint não registrado.

Configurar políticas do Model Armor

Para inspecionar e limpar comandos e respostas que passam pelo Gateway de Agente, crie modelos do Model Armor e vincule-os ao gateway:

  1. Crie modelos regionais de solicitação e resposta do Model Armor e conceda os papéis necessários ao agente de serviço das Extensões de Serviço seguindo as instruções em Configurar o Model Armor em um gateway.
  2. Anexe seus modelos ao Gateway de Agente com um ExtensionBinding seguindo as instruções em Vincular o Model Armor para higienização de comandos e respostas.

Configurar uma implantação centralizada entre projetos com VPC compartilhada

Em uma organização com vários projetos, é possível implantar os agentes do Cloud Run em um ou mais projetos de serviço enquanto hospeda um Gateway de Agente, uma instância do Secure Web Proxy e um Registro de Agente em um projeto host de rede dedicado usando a VPC compartilhada:

  • Projeto A, projeto de serviço do agente: hospeda o serviço do agente do Cloud Run e a política local EgressRouting.
  • Projeto B, projeto host de gateway e rede: atua como o projeto host da VPC compartilhada e precisa hospedar o Gateway de Agente, a instância do Secure Web Proxy, o Agent Registry, os recursos ExtensionBinding e as vinculações de política do IAM.
Diagrama de arquitetura entre projetos mostrando o Projeto A hospedando um serviço do Cloud Run e uma política de roteamento de saída, conectado por uma rede VPC compartilhada ao Projeto B, que hospeda o Gateway de Agente, o Secure Web Proxy e o Agent Registry.
Figura 2. Implantação do Gateway de Agente entre projetos usando a VPC compartilhada.

Antes de iniciar essas etapas, ative run.googleapis.com, compute.googleapis.com, networkservices.googleapis.com e trafficdirector.googleapis.com no Projeto A, além de aiplatform.googleapis.com se o agente chamar a Vertex AI. No Projeto B, implante a instância do Secure Web Proxy e o recurso do Gateway de Agente na rede VPC compartilhada, conforme descrito em Criar um Gateway de Agente autogerenciado, e configure o roteamento de DNS ou do Private Service Connect, conforme descrito em Configurar a rede de ambiente do Cloud Run para acessar a API Traffic Director, para que os sidecars de ambiente no Projeto A possam acessar a API Traffic Director.

Para configurar uma implantação entre projetos, siga estas etapas:

  1. Configure o Projeto B como um projeto host de VPC compartilhada, anexe o Projeto A como um projeto de serviço e compartilhe a sub-rede que hospeda sua instância do Secure Web Proxy. Para ativar a VPC compartilhada e anexar projetos de serviço, é necessário ter roles/compute.xpnAdmin no nível da organização ou da pasta. Para instruções, consulte Enviar tráfego para uma rede VPC compartilhada com saída de VPC direta e Provisionar VPC compartilhada.

  2. No Projeto B, conceda roles/compute.networkUser na sub-rede compartilhada ao agente de serviço do Cloud Run do Projeto A:

    gcloud compute networks subnets add-iam-policy-binding SHARED_SUBNET_NAME \
   --project=PROJECT_B_ID \
   --region=REGION \
   --member="serviceAccount:service-PROJECT_A_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
   --role="roles/compute.networkUser"

    Substitua:

    • SHARED_SUBNET_NAME: o nome da sub-rede compartilhada no Projeto B.
    • PROJECT_B_ID: o ID do projeto B, o gateway e o projeto host da VPC compartilhada.
    • REGION: a região da sub-rede compartilhada.
    • PROJECT_A_NUMBER: o número do Projeto A, o projeto de serviço do agente.

  3. Implante o serviço do agente do Cloud Run no Projeto A apontando para a sub-rede compartilhada no Projeto B:

    gcloud beta run deploy SERVICE_NAME \
   --project=PROJECT_A_ID \
   --image=IMAGE_URL \
   --subnet=projects/PROJECT_B_ID/regions/REGION/subnetworks/SHARED_SUBNET_NAME \
   --vpc-egress=all \
   --functional-type=agent \
   --identity-type=agent-identity \
   --ambient-networking \
   --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
   --region=REGION

    Substitua:

    • SERVICE_NAME: o nome do serviço de agente do Cloud Run no Projeto A.
    • PROJECT_A_ID: o ID do Projeto A, o projeto de serviço do agente.
    • IMAGE_URL: uma referência à imagem do contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

    Depois de implantar o serviço, configure o agente no Projeto A para confiar no certificado de CA raiz da instância do Secure Web Proxy no Projeto B seguindo as etapas em Configurar o agente do Cloud Run para confiar no Gateway de Agente.

  4. Crie uma política EgressRouting no Projeto A que faça referência ao gateway do Secure Web Proxy no Projeto B. Você precisa ter roles/networkservices.admin no Projeto A:

    gcloud alpha network-services egress-routings create my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_B_ID/locations/REGION/gateways/CENTRAL_SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_A_ID/locations/REGION/services/SERVICE_NAME"

    Substitua CENTRAL_SWP_NAME pelo nome do gateway do Secure Web Proxy no Projeto B. Para rotear todos os serviços do Cloud Run no Projeto A pelo gateway do Projeto B, defina workloadUri como //run.googleapis.com/projects/PROJECT_A_ID ou //run.googleapis.com/projects/PROJECT_A_NUMBER.

  5. Confirme se o recurso EgressRouting entre projetos está ativo no Projeto A:

    gcloud alpha network-services egress-routings describe my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID

  6. Configure as políticas centralizadas de referência, IAP e Model Armor no recurso Gateway de Agente no Projeto B, conforme descrito em Configurar políticas no Gateway de Agente:

    • Permita o tráfego de modelo e MCP de referência no recurso de Gateway de Agente no Projeto B seguindo Permitir tráfego de saída e MCP de referência.
    • Para autorizar o agente no Projeto A a chamar servidores MCP registrados no Projeto B, crie uma política de acesso unificado do IAM no Projeto B com uma lista principals que faça referência ao número do Projeto A, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_A_NUMBER/locations/REGION/services/SERVICE_NAME, vincule a política ao Projeto B ou ao recurso do Gateway de Agente e anexe o ExtensionBinding do IAP no Projeto B.
    • Para aplicar as proteções centralizadas do Model Armor no Projeto B, crie seus modelos regionais do Model Armor, conceda os papéis necessários ao agente de serviço das Extensões de Serviço do Projeto B e anexe o ExtensionBinding do Model Armor ao recurso do Gateway de Agente no Projeto B.

Ver registros e traces

As interações de agentes de saída roteadas pelo Gateway de Agente geram registros e traces distribuídos para que você possa monitorar decisões baseadas em política e depurar o comportamento do agente:

Se as solicitações de saída falharem ou ignorarem o gateway, consulte Resolver problemas do Gateway de Agente.

Regiões compatíveis

É possível usar o Gateway de Agente no Cloud Run nas seguintes regiões:

  • europe-west1
  • us-central1

Limitações

Além das limitações de rede ambiente e das considerações sobre o Secure Web Proxy em Implantar o Secure Web Proxy como um Gateway de Agente, as seguintes limitações se aplicam ao usar o Gateway de Agente com o Cloud Run:

  • As solicitações de agente de saída roteadas por uma instância do Secure Web Proxy com inspeção de TLS para os endpoints *.mtls.googleapis.com e *.mtls.run.app falham com erros 503 porque o Secure Web Proxy encerra e reinicia as sessões de TLS sem encaminhar o certificado do cliente.
  • Cada Gateway de Agente regional autogerenciado aceita no máximo um Registro de Agente regional na lista registries.
  • Por padrão, cada projeto é compatível com até 10 recursos regionais AgentGateway e 10 recursos regionais EgressRouting por região. Os novos projetos podem começar com um limite de 2 por região. Para solicitar um aumento de cota, entre em contato com a equipe de conta.
  • É preciso exportar o certificado raiz ou subordinado do pool do CA Service ou da ICP empresarial particular e configurar o contêiner do agente para confiar nele.

A seguir