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

Pré-lançamento particular: gateway do agente

Esse 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 governar e proteger agentes de IA. Por isso, os Termos específicos de serviço "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 e usar o Agent Gateway com o Agent Runtime, consulte a página de solicitação de acesso.

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 plataforma de agentes do Gemini Enterprise. Ele oferece conectividade segura e governada 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 do agente. É 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 cliente-para-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.

• Crie um projeto de teste dedicado para testar esse fluxo de trabalho. Evite usar projetos destinados a outras cargas de trabalho críticas.

Limitações

• Para um determinado projeto e região, só pode haver uma instância de agente para qualquer lugar (saída) e uma instância de cliente para agente (entrada) do Agent Gateway. Todos os agentes do Agent Runtime no mesmo projeto e região configurados para usar o Agent Gateway precisam usar essas instâncias específicas do gateway.
• O serviço de detecção de ameaças do mecanismo de agente 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 ambiente de execução de um recurso do gateway de agente. Por isso, use um projeto de teste dedicado.

Permissões necessárias

Você precisa conceder ao agente de serviço do mecanismo de raciocínio a permissão para usar o recurso do gateway do agente que será criado.

1. Se ela ainda não existir, crie a conta de serviço. A conta de serviço do Reasoning Engine geralmente é criada automaticamente quando você usa o serviço pela primeira vez.

   gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT_ID
   

   Substitua PROJECT_ID pela ID do seu projeto.

2. Para usar o gateway, você precisa das seguintes permissões:

   • roles/networkservices.agentGateways.get
   • roles/networkservices.agentGateways.use
   • roles/networkservices.operations.get

   Crie uma função personalizada com todas essas permissões e conceda a função à conta de serviço do Reasoning Engine.

   gcloud alpha iam roles create AGENT_GATEWAY_ROLE_NAME \
     --project=AGENT_PROJECT_ID \
     --title="Custom Agent Gateway access role" \
     --description="Custom role for Agent Gateway" \
     --permissions="networkservices.operations.get,networkservices.agentGateways.get,networkservices.agentGateways.use"
   

   Substitua:

   • AGENT_GATEWAY_ROLE_NAME: o nome da função personalizada.
   • AGENT_PROJECT_ID: o ID do projeto em que você pretende implantar o agente.

3. Atribua o papel à conta de serviço do ambiente de execução do agente.

   gcloud alpha projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:[e-mail]" \
       --role="projects/PROJECT_ID/roles/AGENT_GATEWAY_ROLE_NAME"
   

   Substitua:

   • PROJECT_ID: o ID do projeto.
   • PROJECT_NUMBER: o número do projeto.
   • AGENT_GATEWAY_ROLE_NAME: o nome da função personalizada que você criou.

4. Além disso, se você pretende usar modelos do Model Armor para autorização e esses modelos estão em um projeto diferente do agente (e do gateway), conceda as seguintes permissões ao agente de serviço do Reasoning Engine e à conta de serviço do Agent Gateway:

   gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/modelarmor.calloutUser
   gcloud alpha projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/modelarmor.user
    gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/modelarmor.calloutUser
    gcloud alpha projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/modelarmor.user
    

   Substitua:

   • AGENT_PROJECT_ID: o ID do projeto em que você pretende implantar o agente.
   • AGENT_PROJECT_NUMBER: o número do projeto em que você pretende implantar o agente.
   • MODEL_ARMOR_PROJECT_ID: o ID do projeto em que o Model Armor é criado.

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

Para rotear o tráfego do ambiente de execução do agente pelo gateway do agente, 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 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 Agent Gateway.

   Verifique se o gateway está configurado para atender às necessidades da sua implantação. Por exemplo, se o agente precisar de 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. Especifique o recurso de gateway ao implantar o agente. Por exemplo, para fazer o implante do agente no ambiente de execução do agente, use client.agent_engines.create para transmitir o objeto local_agent junto com quaisquer configurações opcionais.

   remote_agent = client.agent_engines.create(
     agent=local_agent,
     config={
         "agent_gateway_config": {
           "agent_to_anywhere_config": {"agent_gateway": AGENT_GATEWAY_TO_ANYWHERE_RESOURCE_ID},
           # "client_to_agent_config": {"agent_gateway": AGENT_GATEWAY_CLIENT_TO_AGENT_RESOURCE_ID}
         },
         "identity_type": types.IdentityType.AGENT_IDENTITY,
         # Other optional configuration ...
         # "requirements": requirements,
         # "gcs_dir_name": gcs_dir_name,
     },
   )

   Substitua AGENT_GATEWAY_TO_ANYWHERE_RESOURCE_ID pelo caminho completo do gateway do agente criado no modo Agent-to-Anywhere (saída). Por exemplo, projects/PROJECT_NAME/locations/REGION/agentGateways/AGENT_GATEWAY_NAME.

   Se você criou um gateway no modo cliente-agente (entrada), use o campo client_to_agent_config e substitua AGENT_GATEWAY_CLIENT_TO_AGENT_RESOURCE_ID pelo caminho completo do gateway do agente criado para entrada.

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

Restringir o ambiente de execução do agente 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.

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 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 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/PROJECT_ID_1/locations/REGION/agentGateways/AGENT_GATEWAY_NAME_1',
     'projects/PROJECT_ID_2/locations/REGION/agentGateways/AGENT_GATEWAY_NAME_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.
   • 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 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 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.allowlistedEgressAgentGatewaysForAgentEngine
   spec:
     rules:
     - enforce: true
   

   Substitua PROJECT_ID pela 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 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.

Do cliente para o 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 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/PROJECT_ID_1/locations/REGION/agentGateways/AGENT_GATEWAY_NAME_1',
     'projects/PROJECT_ID_2/locations/REGION/agentGateways/AGENT_GATEWAY_NAME_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.
   • 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 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 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/PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
   spec:
     rules:
     - enforce: true
   

   Substitua PROJECT_ID pela 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 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

• Monitorar o tráfego pelo gateway do agente