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 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ê 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 se destinam 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 gateway de agente. Todos os agentes do Agent Runtime no mesmo projeto e região que estão configurados para usar o gateway de agente precisam usar essas instâncias específicas do gateway.
O serviço de detecção de ameaças do mecanismo de agentes do Security Command Center Agent Engine Threat Detection não está disponível quando o gateway de agente 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 esse motivo, 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 de agente que será criado.

Se ainda não existir, crie a conta de serviço. A conta de serviço do mecanismo de raciocínio normalmente é criada automaticamente quando você usa o mecanismo de raciocínio pela primeira vez.
```
gcloud beta services identity create --service=aiplatform.googleapis.com --project=AGENT_PROJECT_ID
```
Substitua AGENT_PROJECT_ID pelo ID do projeto em que você pretende implantar o agente.
Para usar o gateway, você precisa das seguintes permissões:
- networkservices.agentGateways.get
- networkservices.agentGateways.use
- networkservices.operations.get
Crie uma função personalizada com todas essas permissões e conceda a função à conta de serviço do mecanismo de raciocínio.
```
gcloud alpha iam roles create AGENT_GATEWAY_ROLE_ID \
  --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_ID: o ID da função personalizada.
- AGENT_PROJECT_ID: o ID do projeto em que você pretende implantar o agente.
Atribua o papel à conta de serviço do Agent Runtime.
```
gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
    --member="serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
    --role="projects/AGENT_PROJECT_ID/roles/AGENT_GATEWAY_ROLE_ID"
```
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.
- AGENT_GATEWAY_ROLE_ID: o ID da função personalizada que você criou.

Além disso, se você pretende usar modelos do Model Armor para autorização de conteúdo, conceda as seguintes permissões ao agente de serviço do mecanismo de raciocínio e à conta de serviço do gateway de agente:

gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
    --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud alpha projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.user
 gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
     --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
     --role=roles/modelarmor.calloutUser
 gcloud alpha projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
     --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
     --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 os modelos do Model Armor são criados.

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:

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.

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.

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.

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 personalizadas da organização para definir o conjunto de recursos qualificados do gateway de agente que podem ser usados ao implantar agentes.

Criar restrições de políticas personalizadas 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

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.

Aplique a restrição personalizada.
```
gcloud alpha 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.
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.
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 levará até 15 minutos para entrar em vigor.

Cliente para agente

Para definir uma restrição personalizada para o modo "Cliente para agente" (entrada), crie um arquivo chamado constraint-agent-gateway-ingress.yaml.

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.

Aplique a restrição personalizada.
```
gcloud alpha org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH
```
Substitua INGRESS_CONSTRAINT_PATH pelo caminho completo para o arquivo de restrição personalizada criado na etapa anterior.
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.
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 levará até 15 minutos para entrar em vigor.

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

A seguir

Monitorar o tráfego pelo gateway de agente

Rotear o tráfego do Agent Runtime pelo gateway do agente Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Limitações

Permissões necessárias

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

Restringir o Agent Runtime a gateways de agente aprovados

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

Agente para qualquer lugar

Cliente para agente

A seguir

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