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

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

Antes de começar

  • Confira se você sabe como implantar agentes no Agent Runtime.

  • Saiba mais sobre o Gateway de Agente. É 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. Você usa o gateway no modo cliente-agente (entrada) para controlar quais clientes podem acessar seus agentes. O gateway permite escolher quais políticas de IAP e modelos do Model Armor precisam ser aplicados a essas interações.

    Uma única instância do ambiente de execução pode ser vinculada a um gateway Agent-to-Anywhere (saída) e a um gateway Client-to-Agent (entrada) simultaneamente.

  • Analise as limitações associadas às implantações de tempo 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 do 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).

    • No 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 estar na mesma região. Todas as associações de políticas do IAM e registros associados do Agent Registry precisam ser criados no mesmo projeto do Agent Gateway.

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

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

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

    Se o gateway do 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:

    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 Agent Gateway está implantado.

    2. 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.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.

  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 existente, escolha uma das seguintes opções:

    • Para novos agentes

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

      Se quiser usar recursos da plataforma mediados por gateway, como o Model Armor ou as políticas de governança semântica com esse agente, defina agent_gateway_config e identity_type=AGENT_IDENTITY na chamada de criação, conforme mostrado neste exemplo. Sem identity_type=AGENT_IDENTITY, o effectiveIdentity da instância do ambiente de execução volta para a conta de serviço padrão da Vertex AI, e as políticas de governança semântica silenciosamente filtram o agente do seletor de criação de políticas.

      Agente para qualquer lugar 

      remote_agent = client.agent_engines.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 Agent Gateway está implantado.
      • REGION: a região em que o agente e o gateway são implantados
      • AGENT_GATEWAY_TO_ANYWHERE_NAME: o nome do Gateway de Agente que você criou no modo Agente para qualquer lugar (saída)

      Cliente para agente 

      remote_agent = client.agent_engines.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 são implantados.
      • REGION: a região em que o agente e o gateway são implantados
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: o nome do gateway do agente que você criou no modo de cliente para agente (entrada)

    • Para agentes atuais

      Agente para qualquer lugar

      Use a solicitação de API REST a seguir para associar um agente a um gateway Agent-to-Anywhere 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 é implantado
      • REGION: a região em que o agente e o gateway sã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

      Cliente para agente

      Use a seguinte solicitação de API REST para associar um agente 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 são implantados.
      • REGION: a região em que o agente e o gateway são implantados
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: o nome do gateway do agente que você criou em "Cliente para 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 Agent Gateway.

    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 da entrada do agente no registro
    • RUNTIME_AGENT_PROJECT_NUMBER: o número do projeto em que o agente de execução está implantado.
    • ENGINE_ID: o ID do recurso do agente

    Para mais informações, consulte Registrar um agente.

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

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

    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

    Substitua:

    • AGENT_ENDPOINT_ID: o ID do endpoint de serviço do agente registrado. Você recebe isso na saída da etapa anterior.

    • MEMBER: o principal de identidade do agente a quem conceder o papel. O formato geralmente é: principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID.

  6. Adicionar à lista de permissões as APIs essenciais para operações de ambiente de execução

    Nesse 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:

    • Para ativar a descoberta automática de agentes, servidores MCP e endpoints, o gateway de agente precisa permitir o tráfego para o endpoint https://agentregistry.googleapis.com/.

    • Se o Cloud Trace estiver ativado, o Gateway de Agente precisará permitir o tráfego para o endpoint https://telemetry.googleapis.com/.

      Se as variáveis de ambiente GOOGLE_API_USE_CLIENT_CERTIFICATE e GOOGLE_API_USE_MTLS_ENDPOINT estiverem definidas, verifique se o tráfego para https://telemetry.mtls.googleapis.com/ também é permitido.

    • Se o Cloud Logging estiver ativado, o Gateway de Agente precisará permitir o tráfego para o endpoint https://logging.googleapis.com/.

      Se as variáveis de ambiente GOOGLE_API_USE_CLIENT_CERTIFICATE e GOOGLE_API_USE_MTLS_ENDPOINT estiverem definidas, verifique se o tráfego para https://logging.mtls.googleapis.com/ também é permitido.

    Além disso, se os agentes chamarem LLMs ou usarem recursos como Sessões e Banco de memória, verifique se eles podem se comunicar com os endpoints usados por esses serviços. Exemplo:

    • 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 coloque na lista de permissões apenas os URIs específicos acessados pelo agente. Como o gateway corresponde diretamente aos nomes de host, registre 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. Também é necessário garantir que o agente tenha o papel de egressor da IAP para esses endpoints. Para instruções, consulte Criar uma política de saída do agente para o endpoint.

  7. Verificar a configuração do agente

    Console

    1. No Google Cloud console, acesse a página Implantações do Agent Platform.

      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 tempo 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 para qualquer lugar (saída) para um agente implantado com uma imagem de contêiner personalizada (Traga seu próprio contêiner / BYOC), é 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 Agent Gateway realiza descriptografia e inspeção de TLS em comunicações de saída do agente, implantações de agentes não BYOC (baseadas em origem) injetam automaticamente o certificado da CA durante a criação da imagem. Para imagens de contêiner personalizadas, você precisa recuperar explicitamente o certificado de CA do gateway, instalá-lo no repositório de confiança de CA do sistema dentro do seu 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 do agente, siga estas etapas:

  1. Recupere os certificados raiz do recurso do gateway do agente.

    Exporte a string PEM do certificado raiz da CA diretamente do campo agentGatewayCard.rootCertificates do recurso do gateway do 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 é implantado.
    • AGENT_GATEWAY_PROJECT_ID: o ID do projeto em que o gateway é implantado.

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

    Adicione o argumento de build AGENT_GATEWAY_ROOT_CERTIFICATES ao seu 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 OpenSSL, bibliotecas de cliente HTTP do Python (requests, httpx) e 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 ao 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 a criação 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 em contêiner.

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

Restringir o Agent Runtime a gateways de agente aprovados

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

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

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

Agente para qualquer lugar

  1. Para definir uma restrição personalizada para o modo "Agente para qualquer lugar" (saída), crie um arquivo chamado constraint-agent-gateway-egress.yaml.

    No exemplo a seguir, o campo condition especifica que a operação só é permitida se um recurso do Gateway de Agente for especificado (o campo está presente e não está vazio) e se o gateway especificado estiver na lista pré-aprovada.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    Substitua:

    • ORGANIZATION_ID: o código da sua organização.
    • AGENT_PROJECT_ID: o ID do projeto.
    • REGION: a região em que o gateway foi criado.
    • AGENT_GATEWAY_ID: o ID do gateway.

  2. Aplique a restrição personalizada.

    gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    Substitua EGRESS_CONSTRAINT_PATH pelo caminho completo do arquivo de restrição personalizada criado na etapa anterior.

  3. Crie a política da organização para aplicar a restrição. Para definir a política da organização, crie um arquivo YAML chamado policy-agent-gateway-egress.yaml. Neste exemplo, aplicamos essa restrição no nível do projeto, mas também é possível defini-la no nível da organização ou da pasta.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Substitua AGENT_PROJECT_ID pela ID do seu projeto.

  4. Aplique a política da organização.

    gcloud org-policies set-policy EGRESS_POLICY_PATH

    Substitua EGRESS_POLICY_PATH pelo caminho completo para o arquivo YAML da política da organização criado na etapa anterior. A política leva até 15 minutos para entrar em vigor.

Cliente para agente

  1. Para definir uma restrição personalizada para o modo cliente-agente (entrada), crie um arquivo chamado constraint-agent-gateway-ingress.yaml.

    No exemplo a seguir, o campo condition especifica que a operação só é permitida se um recurso do Gateway de Agente for especificado (o campo está presente e não está vazio) e se o gateway especificado estiver na lista pré-aprovada.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    Substitua:

    • ORGANIZATION_ID: o código da sua organização.
    • AGENT_PROJECT_ID: o ID do projeto.
    • REGION: a região em que o gateway foi criado.
    • AGENT_GATEWAY_ID: o ID do gateway.

  2. Aplique a restrição personalizada.

    gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH

    Substitua INGRESS_CONSTRAINT_PATH pelo caminho completo do arquivo de restrição personalizada criado na etapa anterior.

  3. Crie a política da organização para aplicar a restrição. Para definir a política da organização, crie um arquivo YAML chamado policy-agent-gateway-ingress.yaml. Neste exemplo, aplicamos essa restrição no nível do projeto, mas também é possível defini-la no nível da organização ou da pasta.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Substitua AGENT_PROJECT_ID pela ID do seu projeto.

  4. Aplique a política da organização.

    gcloud org-policies set-policy INGRESS_POLICY_PATH

    Substitua INGRESS_POLICY_PATH pelo caminho completo para o arquivo YAML da política da organização criado na etapa anterior. A política leva até 15 minutos para entrar em vigor.

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ó são compatíveis no modo Agent-to-Anywhere (saída). No modo cliente-agente (entrada), o agente e o gateway do agente precisam estar no mesmo projeto.
    • É necessário usar a API REST ou a gcloud para configurar a governança entre projetos de ponta a ponta. O console Google Cloud Google Cloud não permite criar vinculações de política do IAM entre projetos nem entradas do Registro de agentes.

  • Um gateway de agente não pode ser vinculado a mecanismos de inferência de tempo de execução criados antes de 29 de abril de 2026.

  • Embora um único projeto e região possam hospedar várias instâncias do Agent Gateway de agente para qualquer lugar (saída) e de cliente para agente (entrada), todos os agentes do Agent Runtime implantados no mesmo projeto e região precisam ser vinculados às mesmas instâncias específicas do Agent Gateway 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 de saída. Ou seja, todos os agentes usam egress-gateway-X ou 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 cliente-para-agente (entrada), 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 Sanitizar comandos e respostas ou este codelab sobre Como criar um sistema de agentes seguro com o Model Armor.

  • O VPC Service Controls não é compatível com o Agent Gateway.

  • O Gateway de Agente não é compatível com agentes do Agent Runtime que usam revisões. Não será possível usar recursos relacionados ao controle de versões, como configuração de divisão de tráfego e consultas por revisão, se um Gateway de Agente estiver anexado à configuração de um agente.

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

A seguir

Codelab

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

Guia

Saiba como delegar a autorização do Gateway de Agente ao IAP, ao Model Armor ou ao seu próprio serviço de autorização personalizada.

Guia

Saiba como monitorar o Gateway de Agente.

Solução de problemas

Saiba como resolver problemas de conectividade do Gateway de Agente.