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

Esta página descreve como rotear o tráfego do Agent Runtime pelo Agent Gateway. 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 agênticas, sejam elas entre usuários e agentes, agentes e ferramentas ou entre os próprios agentes.

Antes de começar

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

• Saiba mais sobre o Agent Gateway. É possível usar o Agent Gateway no modo "Do agente para qualquer lugar" (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 "Do cliente para o 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 ser vinculada a um gateway "Do agente para qualquer lugar" (saída) e a um gateway "Do cliente para o agente" (entrada) simultaneamente.

Limitações

• Um Agent Gateway não pode ser vinculado a mecanismos de raciocínio do Runtime criados antes de 29 de abril de 2026.

• Embora um único projeto e região possam hospedar várias instâncias do Agent Gateway "Do agente para qualquer lugar" (saída) e "Do cliente para o 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 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 região.

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

• No modo "Do cliente para o agente" (entrada), o Agent Gateway só pode controlar os métodos query e streamQuery do Agent Runtime. Para proteger outros métodos não compatíveis (como asyncQuery), é possível aplicar 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.

Roteie o tráfego do Agent Runtime pelo Agent Gateway

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

1. Crie um recurso do Agent Gateway e anexe as políticas de autorização necessárias. É possível criar um gateway no modo "Do agente para qualquer lugar" (saída) ou "Do cliente para o agente" (entrada). O agente e o gateway precisam ser criados no mesmo projeto e região. Para instruções, consulte Configurar o Agent Gateway.

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

2. Configure o agente para rotear o tráfego pelo Agent Gateway.

   • Para novos agentes

     Especifique o recurso do 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 com todas as configurações opcionais.

     Se você quiser usar recursos da 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, conforme mostrado neste exemplo. Sem identity_type=AGENT_IDENTITY, o effectiveIdentity da instância do Runtime volta para a conta de serviço padrão da Vertex AI, e as políticas de governança semântica filtram o agente silenciosamente 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 Agent Gateway criado no modo "Do agente para qualquer lugar" (saída).

     Se você criou um gateway no modo "Do cliente para o agente" (entrada), use o campo client_to_agent_config e substitua AGENT_GATEWAY_CLIENT_TO_AGENT_NAME pelo nome do Agent Gateway criado para entrada.

   • Para agentes atuais

     Observação: atualizar um mecanismo de raciocínio atual para definir agentGatewayConfig _não_ muda o identity_type. Se o mecanismo foi criado originalmente sem identity_type=AGENT_IDENTITY, não é possível torná-lo retroativamente qualificado para políticas de governança semântica fazendo um patch. É necessário reimplantar um novo mecanismo de raciocínio com agent_gateway_config e identity_type=AGENT_IDENTITY definidos no momento da criação do agente.

     Do agente para qualquer lugar

     Use a solicitação da API REST a seguir para associar um agente atual a um gateway "Do 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/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 está implantado;
     • AGENT_GATEWAY_TO_ANYWHERE_NAME: o nome do Agent Gateway criado no modo "Do agente para qualquer lugar" (saída);
     • RESOURCE_ID: o ID do recurso do agente.

     Do cliente para o agente

     Use a solicitação da API REST a seguir para associar um agente atual a um gateway "Do cliente para o 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 está implantado;
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: o nome do Agent Gateway criado no modo "Do cliente para o 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 que o agente e o 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 que o papel será concedido. O formato é normalmente: principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID.

     Observação: se você quiser vincular todos os agentes em um projeto a um registro (incluindo todos os agentes do Runtime, os agentes do Gemini Enterprise e outros agentes criados no futuro), vincule a política do IAM a principal://TRUST_DOMAIN/attribute.container/projects/PROJECT_ID.

5. Nesse momento, o tráfego do agente será direcionado pelo Agent Gateway. No entanto, o Agent Gateway adota uma política de negação padrão. Para ativar determinadas funções da Plataforma de Agentes, é necessário garantir que o agente possa se comunicar com os seguintes endpoints:

   • Se o Cloud Trace estiver ativado, o Agent Gateway 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, confira se o tráfego para https://telemetry.mtls.googleapis.com/ também está permitido.

   • Se o Cloud Logging estiver ativado, o Agent Gateway 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, confira se o tráfego para https://logging.mtls.googleapis.com/ também está permitido.

   Além disso, se os agentes estiverem chamando LLMs ou usando recursos como sessões e Memory Bank, será necessário garantir que eles possam 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 permita apenas os URIs específicos que o agente acessa. Como o gateway corresponde diretamente aos nomes de host, é necessário registrar todas as variantes usadas pelo SDK do agente. Por exemplo, dependendo da versão do SDK, da configuração do cliente regional ou do uso de mTLS, uma API 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
   Cuidado: embora seja possível registrar um URI base (como https://REGION-aiplatform.googleapis.com/) por conveniência, isso fornece uma política de acesso ampla que permite que o agente acesse qualquer serviço nesse domínio. Mesmo que você registre um URI base, ainda será necessário registrar todas as variantes regionais e mTLS.

   Para saber como registrar endpoints, consulte Registrar endpoints. Também é necessário garantir que o agente tenha o papel de egressor do IAP para esses endpoints. Para instruções, consulte Criar uma política de saída de agente para endpoint.

6. Verifique a configuração do agente.

   Console

   1. No Google Cloud console do, acesse a página Implantações da Plataforma de Agentes.
      

      Acessar "Implantações"

   2. Clique no nome do agente implantado.

   3. Clique em Configuração do serviço. O painel Observabilidade do agente é aberto.

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

   gcloud

   Use a solicitação da API REST a seguir para validar se o agente agora está associado ao gateway. Se a saída retornada for null, isso significa que o Runtime 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 está implantado;
   • RESOURCE_ID: o ID do recurso do agente.

Restringir o Agent Runtime a gateways de agente aprovados

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

Observação: o VPC Service Controls não é compatível com o Agent Gateway. No entanto, se o VPC Service Controls for aplicado ao projeto, essas políticas da organização serão necessárias para garantir que os agentes usem apenas caminhos de saída aprovados, evitando a exfiltração de dados por gateways não autorizados.

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

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

Do agente para qualquer lugar

1. Para definir uma restrição personalizada para o modo "Do 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 Agent Gateway 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 ID da sua organização.
   • AGENT_PROJECT_ID: o ID do seu 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 para o 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 de política chamado policy-agent-gateway-egress.yaml. Neste exemplo, aplicamos essa restrição a envolvidos no 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 pelo 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 levará até 15 minutos para entrar em vigor.

Do cliente para o agente

1. Para definir uma restrição personalizada para o modo "Do cliente para o 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 Agent Gateway 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 ID da sua organização.
   • AGENT_PROJECT_ID: o ID do seu 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 para o 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 de política chamado policy-agent-gateway-ingress.yaml. Neste exemplo, aplicamos essa restrição a envolvidos no 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 pelo 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 levará até 15 minutos para entrar em vigor.

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

A seguir

Codelab

Codelab: controlar cargas de trabalho agênticas com a Plataforma de Agentes

Aprenda a controlar cargas de trabalho agênticas com o Agent Gateway na Gemini Enterprise Agent Platform.

Guia

Delegar autorização para o Agent Gateway

Aprenda a delegar a autorização do Agent Gateway para o IAP, o Model Armor ou seu próprio serviço de autorização personalizado.

Guia

Monitorar o Agent Gateway

Aprenda a monitorar o Agent Gateway.

Solução de problemas

Resolver problemas do Agent Gateway

Aprenda a resolver problemas de conectividade do Agent Gateway.