Cómo enrutar el tráfico de Agent Runtime a través de Agent Gateway

En esta página, se describe cómo enrutar el tráfico de Agent Runtime a través de Agent Gateway. Agent Gateway es un componente central de redes y seguridad del ecosistema de Agent Platform de Gemini Enterprise. Proporciona conectividad segura y administrada para todas las interacciones de agentes, ya sea que ocurran entre usuarios y agentes, agentes y herramientas, o entre los propios agentes.

Antes de comenzar

  • Asegúrate de estar familiarizado con la implementación de agentes en Agent Runtime.

  • Obtén información sobre Agent Gateway. Puedes usar Agent Gateway en el modo de agente a cualquier lugar (salida) para proteger y controlar todas las comunicaciones salientes con el tráfico saliente a herramientas, modelos, APIs y otros agentes. Usas la puerta de enlace en el modo de cliente a agente (entrada) para controlar qué clientes pueden acceder a tus agentes. La puerta de enlace te permite elegir qué políticas de IAP y plantillas de Model Armor se deben aplicar a estas interacciones.

  • Crea un proyecto de prueba dedicado para probar este flujo de trabajo. Evita usar proyectos que también estén destinados a otras cargas de trabajo críticas.

Limitaciones

  • Para un proyecto y una región determinados, solo puede haber una instancia de agente a cualquier lugar (salida) y una instancia de cliente a agente (entrada) de Agent Gateway. Todos los agentes de Agent Runtime dentro de ese mismo proyecto y región que estén configurados para usar Agent Gateway deben usar estas instancias de puerta de enlace específicas.
  • El servicio de detección de amenazas de Agent Engine de Security Command Center no está disponible cuando Agent Gateway está habilitado para un agente.
  • No puedes desvincular un agente de entorno de ejecución de un recurso de Agent Gateway. Por este motivo, asegúrate de usar un proyecto de prueba dedicado.

Permisos necesarios

Debes otorgar al agente de servicio de Reasoning Engine el permiso para usar el recurso de Agent Gateway que crearás.

  1. Si aún no existe, crea la cuenta de servicio. Por lo general, la cuenta de servicio de Reasoning Engine se crea automáticamente cuando usas Reasoning Engine por primera vez.

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

    Reemplaza PROJECT_ID por el ID del proyecto.

  2. Para usar la puerta de enlace, necesitas los siguientes permisos:

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

    Crea un rol personalizado con todos estos permisos y, luego, otórgale el rol a la cuenta de servicio de 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"

    Reemplaza lo siguiente:

    • AGENT_GATEWAY_ROLE_NAME: El nombre del rol personalizado.
    • AGENT_PROJECT_ID: El ID del proyecto en el que deseas implementar el agente.

  3. Asigna el rol a la cuenta de servicio de Agent Runtime.

    gcloud alpha projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com" \
    --role="projects/PROJECT_ID/roles/AGENT_GATEWAY_ROLE_NAME"

    Reemplaza lo siguiente:

    • PROJECT_ID: ID del proyecto
    • PROJECT_NUMBER: El número de tu proyecto
    • AGENT_GATEWAY_ROLE_NAME: El nombre del rol personalizado que creaste.

  4. Además, si deseas usar plantillas de Model Armor para la autorización y estas plantillas están en un proyecto diferente al agente (y la puerta de enlace), debes otorgar los siguientes permisos al agente de servicio de Reasoning Engine y a la cuenta de servicio de Agent Gateway:

    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

    Reemplaza lo siguiente:

    • AGENT_PROJECT_ID: El ID del proyecto en el que deseas implementar el agente.
    • AGENT_PROJECT_NUMBER: El número del proyecto en el que deseas implementar el agente.
    • MODEL_ARMOR_PROJECT_ID: El ID del proyecto en el que se crea Model Armor.

Enruta el tráfico de Agent Runtime a través de Agent Gateway

Para enrutar el tráfico de Agent Runtime a través de Agent Gateway, sigue estos pasos:

  1. Crea un recurso de Agent Gateway y adjunta las políticas de autorización según sea necesario. Puedes crear una puerta de enlace en el modo de agente a cualquier lugar (salida) o de cliente a agente (entrada). Ten en cuenta que el agente y la puerta de enlace deben crearse en el mismo proyecto y región. Para obtener instrucciones, consulta Configura Agent Gateway.

    Asegúrate de que la puerta de enlace esté configurada para satisfacer las necesidades de tu implementación. Por ejemplo, si tu agente requiere acceso a LLM, configura la puerta de enlace para permitir este acceso y evitar posibles fallas en la implementación de Agent Runtime.

  2. Especifica el recurso de puerta de enlace mientras implementas tu agente. Por ejemplo, para implementar el agente en Agent Runtime, usa client.agent_engines.create para pasar el objeto local_agent junto con cualquier configuración opcional.

    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,
  },
)

    Reemplaza AGENT_GATEWAY_TO_ANYWHERE_RESOURCE_ID por la ruta de acceso completa de Agent Gateway que creaste en el modo de agente a cualquier lugar (salida). Por ejemplo, projects/PROJECT_NAME/locations/REGION/agentGateways/AGENT_GATEWAY_NAME.

    Si creaste una puerta de enlace en el modo de cliente a agente (entrada), usa el campo client_to_agent_config y reemplaza AGENT_GATEWAY_CLIENT_TO_AGENT_RESOURCE_ID por la ruta de acceso completa de Agent Gateway que creaste para la entrada.

  3. Registra tu agente con la instancia de Agent Registry en el mismo proyecto y región que el agente y la puerta de enlace. Para obtener más información, consulta Registra un agente.

Restringe Agent Runtime a las puertas de enlace de agente aprobadas

Puedes crear restricciones personalizadas para las políticas de la organización para definir el conjunto de recursos de Agent Gateway aptos que se pueden usar durante la implementación de agentes.

Crea restricciones personalizadas para las políticas de la organización

En este ejemplo, se crean restricciones personalizadas que solo permiten el tráfico hacia y desde una lista de puertas de enlace aprobadas previamente.

Del agente a cualquier lugar

  1. Para definir una restricción personalizada para el modo de agente a cualquier lugar (salida), crea un archivo llamado constraint-agent-gateway-egress.yaml.

    En el siguiente ejemplo, el campo condition especifica que la operación solo se permite si se especifica un recurso de Agent Gateway (el campo está presente y no está vacío) y si la puerta de enlace especificada está en la lista aprobada previamente.

    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.

    Reemplaza lo siguiente:

    • ORGANIZATION_ID: Es el ID de tu organización.
    • PROJECT_ID: Es el ID del proyecto.
    • REGION: Es la región en la que se creó la puerta de enlace.
    • AGENT_GATEWAY_NAME: Es el nombre de tu puerta de enlace.

  2. Aplica la restricción personalizada.

    gcloud alpha org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    Reemplaza EGRESS_CONSTRAINT_PATH por la ruta de acceso completa al archivo de restricción personalizada que creaste en el paso anterior.

  3. Crea la política de la organización para aplicar la restricción. Para definir la política de la organización, crea un archivo de política en formato YAML llamado policy-agent-gateway-egress.yaml. En este ejemplo, aplicamos esta restricción a nivel del proyecto, pero también puedes configurarla a nivel de la organización o de la carpeta.

    name: projects/PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Reemplaza PROJECT_ID por el ID del proyecto.

  4. Aplica la política de la organización.

    gcloud alpha org-policies set-policy EGRESS_POLICY_PATH

    Reemplaza EGRESS_POLICY_PATH por la ruta de acceso completa al archivo YAML de la política de la organización que creaste en el paso anterior. La política tarda hasta 15 minutos en aplicarse.

De cliente a agente

  1. Para definir una restricción personalizada para el modo de cliente a agente (entrada), crea un archivo llamado constraint-agent-gateway-ingress.yaml.

    En el siguiente ejemplo, el campo condition especifica que la operación solo se permite si se especifica un recurso de Agent Gateway (el campo está presente y no está vacío) y si la puerta de enlace especificada está en la lista aprobada previamente.

    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.

    Reemplaza lo siguiente:

    • ORGANIZATION_ID: Es el ID de tu organización.
    • PROJECT_ID: Es el ID del proyecto.
    • REGION: Es la región en la que se creó la puerta de enlace.
    • AGENT_GATEWAY_NAME: Es el nombre de tu puerta de enlace.

  2. Aplica la restricción personalizada.

    gcloud alpha org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH

    Reemplaza INGRESS_CONSTRAINT_PATH por la ruta de acceso completa al archivo de restricción personalizada que creaste en el paso anterior.

  3. Crea la política de la organización para aplicar la restricción. Para definir la política de la organización, crea un archivo de política en formato YAML llamado policy-agent-gateway-ingress.yaml. En este ejemplo, aplicamos esta restricción a nivel del proyecto, pero también puedes configurarla a nivel de la organización o de la carpeta.

    name: projects/PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Reemplaza PROJECT_ID por el ID del proyecto.

  4. Aplica la política de la organización.

    gcloud alpha org-policies set-policy INGRESS_POLICY_PATH

    Reemplaza INGRESS_POLICY_PATH por la ruta de acceso completa al archivo YAML de la política de la organización que creaste en el paso anterior. La política tarda hasta 15 minutos en aplicarse.

Para obtener más información sobre cómo usar restricciones personalizadas para las políticas de la organización, consulta Crea restricciones personalizadas.

¿Qué sigue?