Rotear o tráfego do Gemini Enterprise pelo Agent Gateway

Nesta página, descrevemos como rotear o tráfego do Gemini Enterprise 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

• Conheça os conceitos do Gemini Enterprise.
• Saiba mais sobre o Agent Gateway. O Gateway de Agente só é compatível com o Gemini Enterprise no modo Agente para Qualquer Lugar (saída). O tráfego de entrada não é compatível.
• Implantar um app do Gemini Enterprise (também conhecido como mecanismo). O procedimento nesta página pressupõe que você já tenha um app implantado. Para mais detalhes, consulte Criar um app.

Planejar os mapeamentos de local e do Agent Registry

Antes de implantar o Gateway de Agente, escolha a região em que você vai implantar o gateway e o Agent Registry em que vai registrar seus recursos. Observe os requisitos abaixo:

• Mapeamento de local: implante o Gateway de Agente na região específica que corresponde ao local do app do Gemini Enterprise para garantir o roteamento adequado.

• Mapeamento de registro: associe o Gateway de Agente à instância regional do Agent Registry no mesmo projeto e região do gateway. Consulte Planejar a implantação do Gateway de Agente para mais orientações sobre padrões de implantação.

Tabela: local do app Gemini Enterprise e mapeamentos do Agent Registry

Local do app Gemini Enterprise	Região obrigatória do Gateway de Agente	Instância obrigatória do Agent Registry para o Gateway de Agente
global	us-central1	us-central1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
us	us-central1	us-central1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
eu	europe-west1	europe-west1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/europe-west1)

Rotear o tráfego do Gemini Enterprise pelo Gateway de Agente

Importante: ativar o Gateway de Agente roteia todo o tráfego do Gemini Enterprise, incluindo chamadas de LLM, pelo gateway. Em seguida, é possível proteger esse tráfego usando políticas de autorização.

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

1. Crie um recurso de Gateway de Agente e siga a região e o registro selecionados na seção anterior. Para instruções, consulte Configurar o Gateway de Agente.

   Verifique a configuração do gateway. Use a API Network Services para recuperar a configuração do Gateway de Agente e inspecionar as configurações.

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   "https://networkservices.googleapis.com/v1/projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
   

   Veja um exemplo de saída de um gateway configurado corretamente:

   {
     "name": "projects/my-ge-project/locations/us-central1/agentGateways/my-egress-gateway",
     "description": "A full configuration for Agent Gateway for Gemini Enterprise egress",
     "googleManaged": {
       "governedAccessPath": "AGENT_TO_ANYWHERE"
     },
     "protocols": [
       "MCP"
     ],
     "registries": [
       "//agentregistry.googleapis.com/projects/my-ge-project/locations/us-central1"
     ]
   }
   

2. Vincule o gateway ao app do Gemini Enterprise usando a API UpdateEngine. Ao concluir essa etapa, todo o tráfego de agentes atual será roteado imediatamente pelo Gateway de Agente especificado.

   Console

   1. No console Google Cloud , acesse a página Gemini Enterprise.

      Gemini Enterprise

   2. Clique no nome do app que você quer associar a um Gateway de Agente.

   3. Clique em Segurança.

   4. Na guia Configuração, em Configuração do Gateway de Agente, insira o nome completo do recurso do gateway. Use o formato: projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME.

   5. Clique em Salvar.

   REST

   1. Use a solicitação a seguir para atualizar o app.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "X-Goog-User-Project: PROJECT_ID" \
      -d '{
        "agentGatewaySetting": {
          "defaultEgressAgentGateway": {
            "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
          }
        }
      }' \
      "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID?updateMask=agentGatewaySetting.defaultEgressAgentGateway.name"

      Substitua:

      • PROJECT_ID: o ID do projeto;
      • AGENT_GATEWAY_REGION: a região do Gateway de Agente.
      • AGENT_GATEWAY_NAME: o nome do Gateway de Agente.
      • ENDPOINT_LOCATION: o prefixo multirregional do endpoint de API que corresponde a GE_APP_LOCATION. Especifique global, us ou eu. Por exemplo, os apps eu usam eu-discoveryengine.googleapis.com. Para apps global, discoveryengine.googleapis.com sem um prefixo também é aceito.
      • PROJECT_NUMBER: o número do projeto.
      • GE_APP_LOCATION: o local do app Gemini Enterprise. Especifique global, us ou eu.
      • GE_APP_ID: o ID do app do Gemini Enterprise.

   2. Para verificar a configuração do app, use o seguinte comando para recuperar sua configuração e inspecionar as definições:

      curl -s -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "X-Goog-User-Project: PROJECT_ID" \
      -H "Content-Type: application/json" \
      "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID" \
      | jq '{name: .name, displayName: .displayName, agentGatewaySetting: .agentGatewaySetting}'
      

      Substitua:

      • PROJECT_ID: o ID do projeto;
      • ENDPOINT_LOCATION: o prefixo multirregional do endpoint de API que corresponde a GE_APP_LOCATION. Especifique global, us ou eu.
      • PROJECT_NUMBER: o número do projeto.
      • GE_APP_LOCATION: o local do app Gemini Enterprise. Especifique global, us ou eu.
      • GE_APP_ID: o ID do app do Gemini Enterprise.

      Veja um exemplo de saída para um app configurado corretamente:

      {
      "name": "projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID",
      "displayName": "GE_APP_ID",
      "agentGatewaySetting": {
        "defaultEgressAgentGateway": {
          "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
        }
      }
      }
      

3. Embora a governança de saída esteja ativada para seu app do Gemini Enterprise, ele não sabe automaticamente com quais recursos externos no Agent Registry pode interagir.

   É preciso importar explicitamente os agentes, endpoints e servidores MCP escolhidos para o app Gemini Enterprise. O recurso importado precisa ser referenciado usando o nome exato do recurso baseado no registro. Para ver instruções, consulte os seguintes guias:

   • Importar servidores MCP do Agent Registry
   • Importe agentes A2A do Agent Registry.

4. Para verificar se a saída está funcionando corretamente, siga estas etapas:

   1. Abra o aplicativo da Web do Gemini Enterprise.
   2. Envie uma consulta projetada para acionar uma ferramenta externa (por exemplo, "Me dê uma lista de problemas recentes do GitHub").
   3. Monitore a execução para garantir que a resposta seja recuperada. Nos bastidores, o agente do Gemini Enterprise empacota a solicitação, a roteia pelo Gateway de Agente (que aplica as políticas de autorização configuradas) e recupera a resposta do destino.

Restringir a vinculação do Gemini Enterprise aos Gateways de Agente aprovados

É possível criar restrições personalizadas de políticas da organização para limitar se um app do Gemini Enterprise pode se vincular a um ou todos os Gateways de Agente.

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

Este exemplo cria uma restrição personalizada que bloqueia todas as vinculações entre apps do Gemini Enterprise e gateways de agente.

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

   O exemplo a seguir mostra como aplicar o isolamento de rede estrito proibindo todas as vinculações. O campo condition especifica que a operação será negada se um recurso do Gateway de Agente for especificado (o campo está presente e não está vazio).

   name: organizations/ORGANIZATION_ID/customConstraints/custom.disallowGeminiEnterpriseAgentGatewayBinding
   resource_types:
   
   
   
   discoveryengine.googleapis.com/Engine
   condition: >-
   has(resource.agentGatewaySetting.defaultEgressAgentGateway.name) &&
   resource.agentGatewaySetting.defaultEgressAgentGateway.name != ''
   actionType: DENY
   displayName: "Disallow all Agent Gateway Bindings for Discovery Engines"
   description: "To enforce strict network isolation, Discovery Engines are not permitted to bind to any Agent Gateway."

Substitua:

• ORGANIZATION_ID: o ID da organização.
• PROJECT_ID: o ID do projeto.
• REGION: a região em que o gateway foi criado.
• AGENT_GATEWAY_NAME: o nome 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 no nível do projeto, mas também é possível defini-la no nível da organização ou da pasta.

   name: projects/PROJECT_ID/policies/custom.disallowGeminiEnterpriseAgentGatewayBinding
   spec:
   rules:
   
   
   
   enforce: true

Substitua PROJECT_ID pelo ID do 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.

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

A seguir

Codelab

Codelab: controlar cargas de trabalho de agentes com a Agent Platform

Saiba como controlar cargas de trabalho agênticas com o Gateway de Agente na Gemini Enterprise Agent Platform.

Guia

Delegar autorização para o Gateway de Agente

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

Guia

Gerenciar o Gateway de Agente

Saiba como visualizar, atualizar, desassociar e excluir recursos do Gateway de Agente.

Guia

Monitorar o Gateway de Agente

Saiba como monitorar o Gateway de Agente.

Solução de problemas

Resolver problemas do Gateway de Agente

Saiba como resolver problemas de conectividade do Gateway de Agente.