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

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 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 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 gateway de agente está ativado para um agente.
  • Não é possível desvincular um agente de tempo de execução de um recurso do gateway de agente. Por isso, use um projeto de teste dedicado.

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.

    Também é necessário garantir que a instância do ambiente de execução tenha uma identidade do agente usando o parâmetro identity_type, 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 gateway do agente 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 cliente-agente (entrada), use o campo client_to_agent_config e substitua AGENT_GATEWAY_CLIENT_TO_AGENT_NAME 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.

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

Codelab

Aprenda a governar cargas de trabalho agênticas com o Agent Gateway na plataforma de agentes do Gemini Enterprise.

Guia

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

Guia

Saiba como monitorar o Agent Gateway.