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

Pré-lançamento particular: Agent Gateway

Este recurso está sujeito aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Esse recurso oferece recursos para controlar e proteger agentes de IA. Portanto, os Termos Específicos de Serviço de "Serviços de IA agêntica" se aplicam. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para solicitar acesso ao Agent Gateway com o Agent Runtime, consulte a página de solicitação de acesso.

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 plataforma de agentes do Gemini Enterprise. 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 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 Client-to-Agent (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.

• Crie um projeto de teste dedicado para experimentar esse fluxo de trabalho. Evite usar projetos que também sejam destinados a outras cargas de trabalho críticas.

Limitações

• Embora um único projeto e região possam hospedar várias instâncias do Agent Gateway Agent-to-Anywhere (saída) e Client-to-Agent (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 Agent Engine do Security Command Center não está disponível quando o Agent Gateway está ativado para um agente.

• Não é possível desvincular um agente do Runtime de um recurso do Agent Gateway. Por esse motivo, use um projeto de teste dedicado.

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 Agent-to-Anywhere (saída) ou Client-to-Agent (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 ao LLM, configure o gateway para permitir esse acesso e evitar possíveis falhas de implantação do Agent Runtime.

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

   Também é necessário garantir que a instância do Runtime receba uma identidade de agente usando o identity_type parâmetro, conforme mostrado neste exemplo.

   remote_agent = client.agent_engines.create(
     agent=local_agent,
     config={
         "agent_gateway_config": {
           "agent_to_anywhere_config": {"agent_gateway": AGENT_GATEWAY_TO_ANYWHERE_NAME},
           # "client_to_agent_config": {"agent_gateway": 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 caminho completo do Agent Gateway criado no modo Agent-to-Anywhere (saída). Por exemplo, projects/PROJECT/locations/REGION/agentGateways/AGENT_GATEWAY_ID.

   Se você criou um gateway no modo Client-to-Agent (entrada), use o campo client_to_agent_config e substitua AGENT_GATEWAY_CLIENT_TO_AGENT_NAME pelo caminho completo do Agent Gateway criado para entrada.

3. Registre o agente na instância do Agent Registry no mesmo projeto e região que o agente e o gateway. Para mais informações, consulte Registrar um agente.

Restringir o Agent Runtime a gateways de agentes aprovados

É possível criar restrições de políticas organizacionais personalizadas 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 organizacionais personalizadas

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

Agent-to-Anywhere

1. Para definir uma restrição personalizada para o modo Agent-to-Anywhere (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 alpha 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 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 alpha org-policies set-policy EGRESS_POLICY_PATH
   

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

Client-to-Agent

1. Para definir uma restrição personalizada para o modo Client-to-Agent (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 alpha 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 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 alpha org-policies set-policy INGRESS_POLICY_PATH
   

   Substitua INGRESS_POLICY_PATH pelo caminho completo do 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 organizacionais personalizadas, consulte Criar restrições personalizadas.

A seguir

Codelab

Codelab: Govern agentic workloads with Agent Platform

Aprenda a controlar cargas de trabalho com agentes 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 ao IAP, ao Model Armor ou ao seu próprio serviço de autorização personalizado.

Guia

Monitorar o Agent Gateway

Aprenda a monitorar o Agent Gateway.