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

Limitações

  • Um gateway de agente não pode ser vinculado a mecanismos de raciocínio 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 Limpar 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.

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. 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). O agente e o gateway precisam ser criados no mesmo projeto e região. 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 Agent Runtime.

  2. Configure o agente para rotear o tráfego pelo gateway de agente.

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

      remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME},
        # "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 AGENT_GATEWAY_TO_ANYWHERE_NAME pelo nome do gateway de agente que você criou no modo Agent-to-Anywhere (saída).

      Se você criou um gateway no modo cliente-agente (entrada), use o campo client_to_agent_config e substitua AGENT_GATEWAY_CLIENT_TO_AGENT_NAME pelo nome do Gateway de Agente criado para 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/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Substitua:

      • PROJECT_ID: o ID do projeto;
      • REGION: a região em que o agente é implantado.
      • 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/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Substitua:

      • PROJECT_ID: o ID do projeto;
      • REGION: a região em que o agente é implantado.
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: o nome do Gateway de Agente que você criou em Cliente para Agente (entrada).
      • RESOURCE_ID: o ID do recurso do agente

  3. Registre-se na instância do Agent Registry no mesmo projeto e região do agente e do gateway.

    gcloud agent-registry services create SERVICE_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces='[{url="https://REGION-aiplatform.mtls.googleapis.com",protocolBinding="jsonrpc"}]' \
  --format="value(registryResource)"

    Substitua:

    • SERVICE_NAME: o nome que você quer dar ao recurso, por exemplo, allow-aiplatform-region-eu3.
    • PROJECT_ID: o ID do projeto.
    • REGION: a região do registro.
    • DISPLAY_NAME: o nome legível do endpoint.

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

  4. Crie uma vinculação de política do IAM de agente para registro.

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

    Substitua:

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

  5. Nesse ponto, o tráfego do agente será 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:

    • 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 estiverem chamando LLMs ou usando recursos como Sessões e Banco de memória, verifique se eles podem se comunicar com os endpoints usados por esses serviços. Por 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.

  6. Verifique 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/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
  | jq '.spec.deploymentSpec.agentGatewayConfig'

    Substitua:

    • 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 Gateway de Agente 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 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/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.
    • PROJECT_ID: o ID do projeto;

  2. Atualize seu Dockerfile para confiar no certificado de 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 de contêiner criada junto com a configuração do Agent Gateway 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 Gateway de Agente 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.

A seguir

Codelab

Aprenda a governar cargas de trabalho com agentes com o Gateway de Agente na Gemini Enterprise Agent Platform.

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.