Rotear o tráfego do Agent Runtime pelo gateway do agente

Nesta página, descrevemos como rotear o tráfego do Agent Runtime pelo Gateway de Agente. O Gateway de Agente é um componente central de rede e segurança do ecossistema da Gemini Enterprise Agent Platform. Ele oferece conectividade segura e governada para todas as interações agênticas, sejam elas entre usuários e agentes, agentes e ferramentas ou entre os próprios agentes.

Antes de começar

• Saiba como implantar agentes no Agent Runtime.

• Saiba mais sobre o Agent Gateway. É possível usar o Gateway de Agente no modo Agent-to-Anywhere (saída) para proteger e controlar todas as comunicações de saída com tráfego de saída para ferramentas, modelos, APIs e outros agentes. Use o gateway no modo cliente para agente (entrada) para controlar quais clientes podem acessar seus agentes. O gateway permite escolher quais políticas do IAP e modelos do Model Armor precisam ser aplicados a essas interações.

  Uma única instância do Runtime pode se vincular a um gateway de agente para qualquer lugar (saída) e a um gateway de cliente para agente (entrada) simultaneamente.

• Analise as limitações associadas às implantações de ambiente de execução associadas ao Gateway de Agente.

Rotear o tráfego do Agent Runtime pelo Gateway de Agente

Para rotear o tráfego do Agent Runtime pelo Gateway de Agente, siga estas etapas:

1. Criar o Gateway de Agente

   Crie um recurso de Gateway de Agente e anexe as políticas de autorização necessárias. É possível criar um gateway no modo agente para qualquer lugar (saída) ou cliente para agente (entrada).

   • Para o modo cliente para agente (entrada), o agente e o gateway precisam ser criados no mesmo projeto e região.
   • No modo agente para qualquer lugar (saída), o gateway pode ser criado em um projeto diferente do agente, mas precisa ser criado na mesma região. Todos os registros associados do Registro de Agente e as vinculações de política do IAM precisam ser criados no mesmo projeto que o Gateway de Agente.

   Para instruções, consulte Configurar o Gateway de Agente.

   Verifique se o gateway está configurado para atender às necessidades da implantação. Por exemplo, se o agente exigir acesso ao LLM, configure o gateway para permitir esse acesso e evitar possíveis falhas de implantação do Agent Runtime.

2. Opcional: configurar o acesso ao gateway de saída entre projetos

   Se o gateway de agente para qualquer lugar (saída) estiver em um projeto diferente do agente do ambiente de execução, siga estas etapas para conceder ao agente de serviço do ambiente de execução acesso ao projeto do gateway de saída:

   gcloud

   1. Crie um papel personalizado do IAM no projeto do Gateway de Agente:

   gcloud iam roles create ar_agw_cross_project_sa \
       --project=AGENT_GATEWAY_PROJECT_ID \
       --title="Runtime Agent Gateway Cross-Project SA" \
       --description="Custom role for the cross-project service agent to access Agent Gateway" \
       --permissions="networkservices.agentGateways.get,networkservices.operations.get"

   Substitua AGENT_GATEWAY_PROJECT_ID pelo ID do projeto em que o Gateway de Agente está implantado.

   1. Atribua o papel personalizado no projeto de gateway ao agente de serviço do Agent Runtime do projeto de agente:

   gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
       --member="serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
       --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

   Substitua AGENT_RUNTIME_PROJECT_NUMBER pelo número do projeto em que o agente do ambiente de execução está implantado.

   Terraform

   Para conceder acesso entre projetos de vários projetos de carga de trabalho do Runtime a um projeto central do Gateway de Agente de forma declarativa, crie o papel personalizado do IAM no projeto central do gateway e conceda-o ao agente de serviço do Runtime de cada projeto de carga de trabalho:

   variable "runtime_project_numbers" {
     type        = set(string)
     description = "Project numbers hosting cross-project Agent Runtime workloads"
     default     = ["AGENT_RUNTIME_PROJECT_NUMBER"]
   }
   
   resource "google_project_iam_custom_role" "ar_agw_cross_project_sa" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     role_id     = "ar_agw_cross_project_sa"
     title       = "Runtime Agent Gateway Cross-Project SA"
     description = "Custom role for cross-project service agents to access Agent Gateway"
     permissions = [
       "networkservices.agentGateways.get",
       "networkservices.operations.get",
     ]
   }
   
   resource "google_project_iam_member" "ar_agw_cross_project_binding" {
     for_each = var.runtime_project_numbers
   
     project = "AGENT_GATEWAY_PROJECT_ID"
     role    = google_project_iam_custom_role.ar_agw_cross_project_sa.name
     member  = "serviceAccount:service-${each.value}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com"
   }
   

3. Configurar o agente para rotear o tráfego pelo Gateway de Agente

   Dependendo se você está implantando um novo agente ou configurando um agente atual, escolha uma das seguintes opções:

   • Para novos agentes que usam o SDK do Python

     Especifique o recurso de gateway ao implantar o agente. Por exemplo, para implantar o agente no Agent Runtime, use client.runtimes.create para transmitir o objeto local_agent com as configurações opcionais.

     Se você quiser usar recursos de plataforma mediados por gateway, como Model Armor ou Políticas de governança semântica com esse agente, defina agent_gateway_config e identity_type=AGENT_IDENTITY na chamada de criação, como mostrado neste exemplo. O back-end aplica identity_type = "AGENT_IDENTITY" no nível da API sempre que agent_gateway_config é especificado, fazendo com que a validação da implantação falhe se a identidade da instância do ambiente de execução for omitida ou configurada incorretamente.

     Do agente para qualquer lugar

     remote_agent = client.runtimes.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "agent_to_anywhere_config": {"agent_gateway": projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME}
           },
           "identity_type": types.IdentityType.AGENT_IDENTITY,
           # Other optional configuration ...
           # "requirements": requirements,
           # "gcs_dir_name": gcs_dir_name,
           # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
           "env_vars": {
             "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
           }
       },
     )

     Substitua:

     • AGENT_GATEWAY_PROJECT_ID: o ID do projeto em que o Gateway de Agente está implantado.
     • REGION: a região em que o agente e o gateway estão implantados
     • AGENT_GATEWAY_TO_ANYWHERE_NAME: o nome do Gateway de Agente que você criou no modo Agente para Qualquer Lugar (saída)

     Do cliente para o agente

     remote_agent = client.runtimes.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "client_to_agent_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME}
           },
           "identity_type": types.IdentityType.AGENT_IDENTITY,
           # Other optional configuration ...
           # "requirements": requirements,
           # "gcs_dir_name": gcs_dir_name,
           # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
           "env_vars": {
             "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
           }
       },
     )

     Substitua:

     • PROJECT_ID: o ID do projeto em que o agente e o gateway estão implantados
     • REGION: a região em que o agente e o gateway estão implantados
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: o nome do Gateway de Agente que você criou no modo de cliente para agente (entrada)

   • Para novos agentes que usam o Terraform

     Ao provisionar o agente com o Terraform, use o provedor google-beta e configure o bloco agent_gateway_config dentro do recurso google_vertex_ai_reasoning_engine. Para detalhes sobre a configuração do Terraform, consulte Provisionar agentes com o Terraform.

     Do agente para qualquer lugar

     Use a configuração do Terraform a seguir para associar um agente a um gateway de agente para qualquer lugar para saída.

     resource "google_vertex_ai_reasoning_engine" "agent" {
     provider = google-beta
     
     project      = "AGENT_RUNTIME_PROJECT_ID"
     region       = "REGION"
     display_name = "AGENT_DISPLAY_NAME"
     description  = "AGENT_DESCRIPTION"
     
     spec {
       identity_type = "AGENT_IDENTITY"
     
       container_spec {
         image_uri = "REGION-docker.pkg.dev/AGENT_RUNTIME_PROJECT_ID/REPOSITORY/IMAGE:TAG"
       }
     
       deployment_spec {
         agent_gateway_config {
           agent_to_anywhere_config {
             agent_gateway = "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
           }
         }
       }
     }
     }

     Substitua:

     • AGENT_RUNTIME_PROJECT_ID: o ID do projeto em que o agente está implantado
     • REGION: a região em que o agente e o gateway estão implantados.
     • AGENT_DISPLAY_NAME: o nome de exibição do agente.
     • AGENT_DESCRIPTION: uma descrição do agente
     • REPOSITORY: o repositório do Artifact Registry que contém a imagem do contêiner
     • IMAGE: o nome da imagem do contêiner
     • TAG: a tag da imagem do contêiner
     • AGENT_GATEWAY_PROJECT_ID: o ID do projeto em que o Gateway de Agente está implantado
     • AGENT_GATEWAY_TO_ANYWHERE_NAME: o nome do Gateway de Agente que você criou no modo Agente para Qualquer Lugar (saída)

     Do cliente para o agente

     Use a configuração do Terraform a seguir para associar um agente a um gateway de cliente para agente para entrada.

     resource "google_vertex_ai_reasoning_engine" "agent" {
     provider = google-beta
     
     project      = "PROJECT_ID"
     region       = "REGION"
     display_name = "AGENT_DISPLAY_NAME"
     description  = "AGENT_DESCRIPTION"
     
     spec {
       identity_type = "AGENT_IDENTITY"
     
       container_spec {
         image_uri = "REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG"
       }
     
       deployment_spec {
         agent_gateway_config {
           client_to_agent_config {
             agent_gateway = "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
           }
         }
       }
     }
     }

     Substitua:

     • PROJECT_ID: o ID do projeto em que o agente e o gateway são implantados
     • REGION: a região em que o agente e o gateway estão implantados.
     • AGENT_DISPLAY_NAME: o nome de exibição do agente.
     • AGENT_DESCRIPTION: uma descrição do agente
     • REPOSITORY: o repositório do Artifact Registry que contém a imagem do contêiner
     • IMAGE: o nome da imagem do contêiner
     • TAG: a tag da imagem do contêiner
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: o nome do Gateway de Agente que você criou no modo de cliente para agente (entrada)

   • Para agentes que usam a API REST

     Do agente para qualquer lugar

     Use a seguinte solicitação de API REST para associar um agente atual a um gateway de agente para qualquer lugar para saída.

     curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
       "spec": {
         "deploymentSpec": {
           "agentGatewayConfig": {
             "agentToAnywhereConfig": {
               "agentGateway": "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
             }
           }
         }
       }
     }' \
     "https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

     Substitua:

     • AGENT_GATEWAY_PROJECT_ID: o ID do projeto em que o gateway está implantado
     • AGENT_RUNTIME_PROJECT_ID: o ID do projeto em que o agente está implantado
     • REGION: a região em que o agente e o gateway estão implantados
     • AGENT_GATEWAY_TO_ANYWHERE_NAME: o nome do Gateway de Agente que você criou no modo Agente para Qualquer Lugar (saída)
     • RESOURCE_ID: o ID do recurso do agente.

     Do cliente para o agente

     Use a seguinte solicitação de API REST para associar um agente atual a um gateway de cliente para agente para entrada.

     curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
       "spec": {
         "deploymentSpec": {
           "agentGatewayConfig": {
             "clientToAgentConfig": {
               "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
             }
           }
         }
       }
     }' \
     "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

     Substitua:

     • PROJECT_ID: o ID do projeto em que o agente e o gateway estão implantados
     • REGION: a região em que o agente e o gateway estão implantados
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: o nome do Gateway de Agente que você criou em Do cliente para o agente (entrada)
     • RESOURCE_ID: o ID do recurso do agente.

4. Registrar o agente no Agent Registry

   Verifique se o agente está registrado na instância do Agent Registry no mesmo projeto e região do Gateway de Agente.

   gcloud

   gcloud agent-registry services create RUNTIME_AGENT_SERVICE_NAME \
    --project=AGENT_GATEWAY_PROJECT_ID \
    --location=REGION \
    --display-name="RUNTIME_AGENT_DISPLAY_NAME" \
    --endpoint-spec-type=no-spec \
    --interfaces=url="https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID",protocolBinding="jsonrpc" \
    --format="value(registryResource)"
   

   Substitua:

   • RUNTIME_AGENT_SERVICE_NAME: o nome que você quer dar à entrada do agente no registro.
   • AGENT_GATEWAY_PROJECT_ID: o ID do projeto em que o gateway está implantado.
   • REGION: a região em que o agente e o gateway são implantados
   • RUNTIME_AGENT_DISPLAY_NAME: o nome de exibição legível por humanos da entrada do agente no registro.
   • RUNTIME_AGENT_PROJECT_NUMBER: o número do projeto em que o agente do ambiente de execução está implantado.
   • ENGINE_ID: o ID do recurso do agente.

   Terraform

   resource "google_agent_registry_service" "runtime_agent_entry" {
     project      = "AGENT_GATEWAY_PROJECT_ID"
     location     = "REGION"
     service_id   = "RUNTIME_AGENT_SERVICE_NAME"
     display_name = "RUNTIME_AGENT_DISPLAY_NAME"
   
     endpoint_spec {
       no_spec {}
     }
   
     interfaces {
       url              = "https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID"
       protocol_binding = "jsonrpc"
     }
   }
   

   Para mais informações, consulte Registrar agentes. Para saber mais sobre o registro manual de agentes em configurações de vários projetos, consulte Registrar um agente de outro projeto.

5. Criar uma vinculação de política do IAM de agente para registro

   Siga esta etapa no mesmo projeto e região do Gateway de Agente.

   gcloud

   gcloud iap web add-iam-policy-binding \
    --resource-type=agent-registry \
    --endpoint=AGENT_ENDPOINT_ID \
    --region=REGION \
    --project=AGENT_GATEWAY_PROJECT_ID \
    --member=MEMBER \
    --role=roles/iap.egressor
   

   Terraform

   resource "google_iap_agent_registry_endpoint_iam_member" "egress_binding" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     location    = "REGION"
     endpoint_id = "AGENT_ENDPOINT_ID"
     role        = "roles/iap.egressor"
     member      = "MEMBER"
   }
   

   Substitua:

   • AGENT_ENDPOINT_ID: o ID do endpoint de serviço do agente registrado. Você encontra essa informação na saída da etapa anterior.

   • MEMBER: o principal de identidade do agente a quem o papel será concedido. O formato de um mecanismo de raciocínio individual é: principal://TRUST_DOMAIN/resources/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID.

     Se você quiser conceder acesso de saída a todos os agentes em um projeto ou em toda a organização, em vez de vincular instâncias individuais, vincule a política do IAM a um conjunto de principais:

     • Para conceder acesso a todos os agentes em um projeto: principalSet://TRUST_DOMAIN/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER
     • Para conceder acesso a todos os agentes da organização: principalSet://TRUST_DOMAIN/*

     Nessas strings de principal, TRUST_DOMAIN geralmente é agents.global.org-ORGANIZATION_ID.system.id.goog.

6. Permitir APIs essenciais para operações do ambiente de execução

   Neste ponto, o tráfego do agente é direcionado pelo Gateway de Agente. No entanto, o Gateway de Agente adota uma política de negação padrão. Para ativar determinadas funções da Agent Platform, verifique se o agente pode se comunicar com os seguintes endpoints:

   A correspondência de nome do host no Gateway de Agente é exata. Caracteres curinga, como *.googleapis.com, ou formas de prefixo não são aceitos. É necessário registrar cada variante de nome do host padrão, regional e segura (mTLS) que o SDK do agente ou o aplicativo cliente resolve.

   Para ativar determinadas funções da plataforma de agentes e garantir a inicialização e a telemetria, permita o tráfego para os seguintes endpoints no registro de agentes:

   Endpoints essenciais da plataforma

   A tabela a seguir lista os endpoints essenciais da plataforma que os agentes precisam para operações padrão, rastreamento, geração de registros e resolução de metadados:

   Nome do serviço	Nome do host padrão	Nome do host do mTLS	Variantes regionais e outras
   Agent Registry	agentregistry.googleapis.com	—	—
   Cloud Logging	logging.googleapis.com	logging.mtls.googleapis.com	—
   Cloud Trace / Telemetria	telemetry.googleapis.com	telemetry.mtls.googleapis.com	—
   API Trace	cloudtrace.googleapis.com	cloudtrace.mtls.googleapis.com	—
   Cloud Monitoring	monitoring.googleapis.com	monitoring.mtls.googleapis.com	—
   Secret Manager	secretmanager.googleapis.com	secretmanager.mtls.googleapis.com	—
   Resource Manager	cloudresourcemanager.googleapis.com	cloudresourcemanager.mtls.googleapis.com	—
   Credenciais do IAM	iamcredentials.googleapis.com	iamcredentials.mtls.googleapis.com	—
   Plataforma de agente (aiplatform)	aiplatform.googleapis.com	aiplatform.mtls.googleapis.com	REGION-aiplatform.googleapis.com REGION-aiplatform.mtls.googleapis.com aiplatform.REGION.rep.googleapis.com

   Endpoints específicos de recursos

   Além disso, se os agentes usarem recursos como Sessões ou Memory Bank, você precisará garantir que eles possam se comunicar com os endpoints específicos usados por esses serviços:

   • Para sessões: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/sessions
   • Para o Memory Bank: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories

   Por motivos de segurança, recomendamos que você registre e inclua na lista de permissões apenas os URIs específicos que o agente acessa. Como o gateway faz a correspondência direta de nomes de host, é preciso registrar todas as variantes usadas pelo SDK do agente. Por exemplo, dependendo da versão do SDK, da configuração regional do cliente ou do uso de mTLS, uma API do Google pode ser resolvida pelos seguintes nomes de host de endpoint:

   • https://REGION-aiplatform.googleapis.com
   • https://REGION-aiplatform.mtls.googleapis.com
   • https://aiplatform.REGION.rep.googleapis.com

   Para saber como registrar endpoints, consulte Registrar endpoints. Se você tiver uma configuração de vários projetos, poderá registrar vários endpoints de API principais do Google em um único serviço de registro de agente. Para mais informações, consulte Registrar um endpoint composto de APIs do Google. Verifique também se o agente tem a permissão iap.resources.egressViaIAP para esses endpoints. Para instruções, consulte Criar uma política de saída de agente para endpoint.

7. Verificar a configuração do agente

   Console

   1. No console do Cloud de Confiance , acesse a página Implantações da plataforma de agentes.
      

      Acessar "Implantações"

   2. Clique no nome do agente que você implantou.

   3. Clique em Configurações de serviço. O painel Observabilidade do agente é aberto.

   4. Clique em Detalhes da implantação. As configurações de entrada e saída do Gateway de Agente estão disponíveis no campo Especificação de implantação.

   gcloud

   Use a seguinte solicitação de API REST para validar se o agente agora está associado ao gateway. Se a saída retornada for null, isso significa que o ambiente de execução não conseguiu se vincular ao gateway.

   curl -s -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
     | jq '.spec.deploymentSpec.agentGatewayConfig'

   Substitua:

   • AGENT_RUNTIME_PROJECT_ID: o ID do projeto;
   • REGION: a região em que o agente é implantado.
   • RESOURCE_ID: o ID do recurso do agente.

Configurar agentes de contêiner personalizado (BYOC) para o Gateway de Agente

Se você quiser rotear o tráfego de saída por um Gateway de Agente de agente para qualquer lugar (saída) para um agente implantado com uma imagem de contêiner personalizada (Traga seu próprio contêiner / BYOC), será necessário incorporar o certificado da autoridade certificadora raiz do gateway ao repositório de confiança da imagem do contêiner personalizada.

Como o Gateway de Agente realiza a descriptografia e a inspeção de TLS nas comunicações de saída do agente, as implantações de agentes que não são BYOC (baseadas em origem) injetam automaticamente o certificado da CA durante a criação da imagem. Para imagens de contêiner personalizadas, é necessário recuperar explicitamente o certificado de CA do gateway, instalá-lo no armazenamento de confiança de CA do sistema dentro do Dockerfile e definir as variáveis de ambiente do pacote de certificados exigidas pelos SDKs do Python, pelas bibliotecas de cliente HTTP e pelo gRPC.

Para configurar uma imagem de contêiner BYOC para saída do Gateway de Agente, siga estas etapas:

1. Recupere os certificados raiz do recurso do Gateway de Agente.

   Exporte a string PEM do certificado raiz da CA diretamente do campo agentGatewayCard.rootCertificates do recurso do Gateway de Agente:

   export AGW_CERT=$(gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
      --location=REGION \
      --project=PROJECT_ID \
      --format="value[delimiter=\\n](agentGatewayCard.rootCertificates)")

   Como alternativa, use a API REST para recuperar o recurso de gateway:

   curl -s -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://networkservices.googleapis.com/v1/projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \
      | jq -r '.agentGatewayCard.rootCertificates[]'

   Substitua:

   • AGENT_GATEWAY_NAME: o nome do Gateway de Agente de saída.
   • REGION: a região em que o gateway está implantado.
   • AGENT_GATEWAY_PROJECT_ID: o ID do projeto em que o gateway está implantado.

2. Atualize seu Dockerfile para confiar no certificado de CA.

   Adicione o argumento de build AGENT_GATEWAY_ROOT_CERTIFICATES ao Dockerfile. Os comandos de build dividem os certificados em arquivos separados, instalam-nos usando update-ca-certificates e definem variáveis de ambiente para que o OpenSSL, as bibliotecas de cliente HTTP do Python (requests, httpx) e o gRPC reconheçam a CA personalizada:

   # Install root certificates under root user
   USER root
   
   ARG AGENT_GATEWAY_ROOT_CERTIFICATES
   RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \
        echo "Installing Agent Gateway root certificates..."; \
        printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" | awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \
        update-ca-certificates; \
      fi
   
   # Configure SSL/TLS trust paths for Python HTTP libraries, OpenSSL, and gRPC
   ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   ENV AGENT_GATEWAY_ROOT_CERT_302034098528=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   
   # Switch back to application execution user
   USER 1000

3. Crie a imagem do contêiner usando o Cloud Build.

   Crie um arquivo cloudbuild.yaml para transmitir a string do certificado raiz para o Cloud Build usando substituições:

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args:
     - 'build'
     - '--build-arg'
     - 'AGENT_GATEWAY_ROOT_CERTIFICATES=${_AGW_CERT}'
     - '-t'
     - '$_IMAGE_URI'
     - '.'
   
   images:
   - '$_IMAGE_URI'
   

   Envie o build da imagem do contêiner para o Cloud Build:

   export IMAGE_URI="REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest"
   
   gcloud builds submit \
      --project=PROJECT_ID \
      --region=REGION \
      --config=cloudbuild.yaml \
      --substitutions=_IMAGE_URI="$IMAGE_URI",_AGW_CERT="$AGW_CERT" \
      .
   

   Substitua REPOSITORY_NAME e IMAGE_NAME pelos nomes do repositório e da imagem do Artifact Registry.

4. Implante o agente conteinerizado.

   Especifique o URI da imagem do contêiner criada com a configuração do Gateway de Agente na solicitação de implantação (usando agent_gateway_config em spec.deploymentSpec ou chamadas de implantação do SDK).

Restringir o Agent Runtime a gateways de agente aprovados

É possível criar restrições personalizadas de políticas da organização para definir o conjunto de recursos qualificados do Gateway de Agente que podem ser usados ao implantar agentes.

Criar restrições personalizadas da política da organização

Este exemplo cria restrições personalizadas que só permitem o tráfego de e para uma lista pré-aprovada de gateways.

Para mais informações sobre como usar restrições personalizadas da política da organização, consulte Criar restrições personalizadas.

Limitações

• A governança entre projetos tem as seguintes limitações:

  • As vinculações entre projetos entre agentes e gateways são compatíveis apenas no modo Agente para qualquer lugar (saída). No modo cliente para agente (entrada), o agente e o gateway de agente precisam estar no mesmo projeto.
  • É preciso usar a API REST ou a gcloud para configurar a governança entre projetos de ponta a ponta. O console do Cloud de Confiance Cloud de Confiance não permite criar vinculações de política do IAM entre projetos ou entradas do Agent Registry.

• Não é possível vincular um Gateway de Agente a mecanismos de raciocínio de ambiente de execução criados antes de 29 de abril de 2026.

• Embora um único projeto e região possam hospedar várias instâncias de Gateway de Agente de agente para qualquer lugar (saída) e de cliente para agente (entrada), todos os agentes do Agent Runtime implantados nesse mesmo projeto e região precisam se vincular às mesmas instâncias específicas de Gateway de Agente de saída e entrada.

  Por exemplo, se um projeto e uma região contiverem egress-gateway-X e egress-gateway-Y, todos os agentes nesse projeto e região precisarão ser configurados para usar o mesmo gateway para saída. Ou seja, todos os agentes usam egress-gateway-X ou todos os agentes usam egress-gateway-Y. Não é possível configurar agent-A para usar egress-gateway-X e agent-B para usar egress-gateway-Y.

  Essa mesma regra de vinculação também se aplica a gateways de entrada em um projeto e uma região.

• O serviço de detecção de ameaças do mecanismo de agente do Security Command Center não está disponível quando o Gateway de Agente está ativado para um agente.

• No modo de entrada (cliente para agente), o Gateway de Agente só pode controlar os métodos query e streamQuery do Agent Runtime. Para proteger outros métodos não compatíveis (como asyncQuery), aplique modelos do Model Armor diretamente do aplicativo ou agente. Consulte Limpar comandos e respostas ou este codelab sobre Como criar um sistema de agentes seguro com o Model Armor.

• Mudar uma vinculação de Gateway de Agente em um agente do Runtime arquiva todas as revisões pré-existentes do agente. O arquivamento é irreversível. Consulte Gateway de Agente e revisões.

  Para atualizar um agente sem alterar o ID do mecanismo de raciocínio ou quebrar as vinculações de política, atualize a instância do agente no local, conforme descrito em Como atualizar uma instância do Agent Runtime.

A seguir