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

Esta página descreve como encaminhar o tráfego do Agent Runtime pelo gateway de agente. O gateway de agente é 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 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 gateway de agente. É possível usar o gateway de agente no modo "Agente para qualquer lugar" (saída) para proteger e governar 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 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

Encaminhar o tráfego do Agent Runtime pelo gateway de agente

Para encaminhar o tráfego do Agent Runtime pelo gateway de agente, siga estas etapas:

  1. Crie um recurso do gateway de agente 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 gateway de agente.

    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 atribuir uma identidade de agente à instância do Runtime 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 gateway de agente criado no modo "Agente para qualquer lugar" (saída). Por exemplo, projects/PROJECT/locations/REGION/agentGateways/AGENT_GATEWAY_ID.

    Se você criou um gateway no modo "Cliente para agente" (entrada), use o campo client_to_agent_config e substitua AGENT_GATEWAY_CLIENT_TO_AGENT_NAME pelo caminho completo do gateway de agente criado para entrada.

  3. Registre o agente na instância do registro de agentes 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 agente aprovados

É possível criar restrições de políticas organizacionais personalizadas para definir o conjunto de recursos qualificados do gateway de agente que podem ser usados ao implantar agentes.

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.

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 gateway de agente 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.

Cliente para agente

  1. Para definir uma restrição personalizada para o modo "Cliente para 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 gateway de agente 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

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

Guia

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

Guia

Aprenda a monitorar o gateway de agente.