Aísla la ejecución de código de IA con Agent Sandbox

En este documento, se proporcionan instrucciones para instalar y ejecutar el controlador de Agent Sandbox en un clúster de Google Kubernetes Engine (GKE). También se explica cómo implementar un entorno de zona de pruebas en el clúster en el que puedes probar comandos de shell no confiables.

El controlador de Agent Sandbox proporciona un framework para crear y administrar entornos de ejecución efímeros. Este enfoque te permite definir una plantilla para el entorno de tu app y, luego, crear instancias de ella según sea necesario.

Agent Sandbox proporciona un entorno seguro y aislado para ejecutar código no confiable, como el código generado por modelos de lenguaje grandes (LLM). Ejecutar este tipo de código directamente en un clúster plantea riesgos de seguridad, ya que el código no confiable podría acceder a otras apps o al nodo del clúster subyacente, o interferir en ellos.

Agent Sandbox mitiga estos riesgos proporcionando un sólido aislamiento de procesos, almacenamiento y redes para el código que ejecuta. Este aislamiento se logra con gVisor, una tecnología que crea una barrera segura entre la aplicación y el sistema operativo del nodo del clúster. También se pueden usar otras tecnologías de zona de pruebas, por ejemplo, contenedores Kata. Sin embargo, el ejemplo de este documento solo usa gVisor.

En este documento, se proporcionan instrucciones para ejecutar Agent Sandbox en un clúster de GKE Autopilot o Standard.

Agent Sandbox es un proyecto de código abierto. Para obtener más información sobre cómo contribuir al proyecto o encontrar detalles técnicos más profundos, consulta el proyecto de código abierto de Agent Sandbox.

Costos

Si sigues los pasos que se indican en este documento, se generarán cargos en tu cuenta de Google Cloud. Los costos comienzan cuando creas un clúster de GKE. Estos costos incluyen los cargos por clúster de GKE, como se indica en la página de precios, y los cargos por ejecutar VMs de Compute Engine.

Para evitar cargos innecesarios, asegúrate de inhabilitar GKE o borrar el proyecto después de completar este documento.

Antes de comenzar

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Artifact Registry, Google Kubernetes Engine APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  4. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    Define las variables de entorno

    Para simplificar los comandos que ejecutas en este documento, puedes configurar variables de entorno en Cloud Shell. En Cloud Shell, define las siguientes variables de entorno útiles ejecutando los siguientes comandos:

    export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export GKE_LOCATION="us-central1"
export AGENT_SANDBOX_VERSION="v0.1.0"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"
export PYTHON_CLIENT_VERSION="main"

    A continuación, se explica cada una de estas variables de entorno:

    • PROJECT_ID: Es el ID de tu proyecto actual de Google Cloud . Definir esta variable ayuda a garantizar que todos los recursos, como tu clúster de GKE, se creen en el proyecto correcto.
    • CLUSTER_NAME: Es el nombre del clúster de GKE, por ejemplo, agent-sandbox-cluster.
    • GKE_LOCATION: La Google Cloud región en la que se crearán el clúster de GKE y el repositorio de Artifact Registry, por ejemplo, us-central1. Recomendamos colocarlos en el mismo lugar, ya que esto reduce la latencia de extracción de imágenes.
    • AGENT_SANDBOX_VERSION: Es la versión del controlador de Agent Sandbox que se implementará en tu clúster.
    • NODE_POOL_NAME: Es el nombre del grupo de nodos que ejecutará cargas de trabajo en zona de pruebas, por ejemplo, agent-sandbox-node-pool.
    • MACHINE_TYPE: Es el tipo de máquina de los nodos en tu grupo de nodos, por ejemplo, e2-standard-2. Para obtener detalles sobre las diferentes series de máquinas y elegir entre las distintas opciones, consulta la guía de comparación y recursos de familias de máquinas.
    • PYTHON_CLIENT_VERSION: Es la versión del cliente de Python de Agentic Sandbox que se instalará.

    Implementa la zona de pruebas del agente

    Ahora que configuraste tu proyecto Google Cloud y el entorno de Cloud Shell, puedes aprovisionar la infraestructura necesaria y, luego, implementar Agent Sandbox.

    Crea un clúster de GKE

    A continuación, crearás un clúster de GKE con gVisor habilitado. Este clúster proporciona el entorno de Kubernetes en el que implementarás y ejecutarás el controlador de la zona de pruebas del agente y la app de zona de pruebas de muestra. gVisor proporciona la tecnología de zona de pruebas para ejecutar de forma segura código no confiable.

    Puedes crear un clúster de Autopilot o Standard. Autopilot habilita gVisor automáticamente, mientras que los clústeres de Standard requieren que crees un grupo de nodos habilitado para gVisor de forma manual:

    Autopilot

    Para crear un clúster de Autopilot con gcloud CLI, ejecuta el siguiente comando:

    gcloud container clusters create-auto ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --project=${PROJECT_ID}

    Estándar

    Para crear un clúster estándar con gcloud CLI, sigue estos pasos:

    1. Crea el clúster:

      gcloud container clusters create ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

    2. Crea un grupo de nodos separado con gVisor habilitado:

      gcloud container node-pools create ${NODE_POOL_NAME} \
  --cluster=${CLUSTER_NAME} \
  --location=${GKE_LOCATION} \
  --machine-type=${MACHINE_TYPE} \
  --image-type=cos_containerd \
  --sandbox type=gvisor

    Recupera las credenciales del clúster para que la CLI de kubectl pueda conectarse a él. Este comando actualiza tu archivo de configuración de Kubernetes, que se almacena de forma predeterminada en el directorio ~/.kube/config. Este archivo de configuración contiene las credenciales que kubectl requiere para interactuar con tu clúster de GKE:

    gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

    Implementa el controlador de Agent Sandbox en tu clúster

    Puedes implementar el controlador de Agent Sandbox y sus componentes requeridos aplicando los manifiestos de la versión oficial a tu clúster. Estos manifiestos son archivos de configuración que le indican a Kubernetes que descargue todos los componentes necesarios para implementar y ejecutar el controlador de Agent Sandbox en tu clúster.

    Ejecuta los siguientes comandos para implementar el controlador de Agent Sandbox en tu clúster de GKE:

    kubectl apply \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml

    Verifica el controlador de Agent Sandbox

    Después de aplicar los manifiestos, verifica que el Pod del controlador de Agent Sandbox se ejecute correctamente en el espacio de nombres agent-sandbox-system:

    kubectl get pods -n agent-sandbox-system

    Espera a que el Pod muestre "Running" en la columna STATUS y "1/1" en la columna READY. Cuando el Pod se ejecuta correctamente, el resultado es similar al siguiente:

    NAME                         READY   STATUS    RESTARTS   AGE
agent-sandbox-controller-0   1/1     Running   0          44d

    Ahora que el controlador de Agent Sandbox está en ejecución, puede crear y administrar automáticamente entornos de zona de pruebas para cualquier recurso Sandbox que crees en tu clúster.

    Implementa un entorno de zona de pruebas

    Ahora que el controlador de Agent Sandbox se ejecuta en tu clúster de GKE, debes implementar los componentes para el entorno de prueba de ejemplo. En esta sección, se muestra cómo crear el blueprint de zona de pruebas (SandboxTemplate), implementar el router de redes necesario y, luego, instalar el cliente de Python que usarás para interactuar con la zona de pruebas.

    La forma recomendada de crear tu zona de pruebas y de interactuar con ella es usar el cliente de Python de Agentic Sandbox. Este cliente proporciona una interfaz que simplifica todo el ciclo de vida de un entorno de pruebas, desde la creación hasta la limpieza. Es una biblioteca de Python que puedes usar para crear, usar y borrar zonas de pruebas de forma programática.

    El cliente usa un enrutador de zona de pruebas como punto de entrada central para todo el tráfico. En el ejemplo que se describe en este documento, el cliente crea un túnel a este router con el comando kubectl port-forward, de modo que no es necesario exponer ninguna dirección IP pública. Ten en cuenta que usar kubectl port-forward no es una solución segura y su uso debe limitarse a los entornos de desarrollo.

    Crea un SandboxTemplate y un SandboxWarmPool

    Ahora definirás la configuración de tu zona de pruebas creando un recurso SandboxTemplate y un recurso SandboxWarmPool. El SandboxTemplate actúa como un plano reutilizable que el controlador de Agent Sandbox usa para crear entornos de zona de pruebas coherentes y preconfigurados. El recurso SandboxWarmPool garantiza que siempre se ejecute una cantidad especificada de Pods preparados y que estén listos para reclamarse. Una zona de pruebas precalentada es un Pod en ejecución que ya se inicializó. Esta preinicialización permite crear nuevas zonas de pruebas en menos de un segundo y evita la latencia de inicio de una zona de pruebas normal:

    1. En Cloud Shell, crea un archivo llamado sandbox-template-and-pool.yaml con el siguiente contenido:

      apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox: python-sandbox-example
    spec:
      runtimeClassName: gvisor
      containers:
      - name: python-runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
            ephemeral-storage: "512Mi"
      restartPolicy: "OnFailure"
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: python-runtime-template

    2. Aplica el manifiesto SandboxTemplate y SandboxWarmPool:

      kubectl apply -f sandbox-template-and-pool.yaml

    Implementa el router de zona de pruebas

    El cliente de Python que usarás para crear entornos de zona de pruebas y para interactuar con ellos usa un componente llamado Sandbox Router para comunicarse con las zonas de pruebas.

    En este ejemplo, usarás el modo de desarrollador del cliente para realizar pruebas. Este modo está diseñado para el desarrollo local y usa el comando kubectl port-forward para establecer un túnel directo desde tu máquina local al servicio de Sandbox Router que se ejecuta en el clúster. Este enfoque de tunelización evita la necesidad de una dirección IP pública o una configuración de entrada compleja, y simplifica la interacción con los entornos de pruebas desde tu entorno local.

    Sigue estos pasos para implementar el enrutador de zona de pruebas:

    1. En Cloud Shell, crea un archivo llamado sandbox-router.yaml con el siguiente contenido:

      # A ClusterIP Service to provide a stable endpoint for the router pods.
apiVersion: v1
kind: Service
metadata:
  name: sandbox-router-svc
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: sandbox-router
  ports:
  - name: http
    protocol: TCP
    port: 8080 # The port the service will listen on
    targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
---
# The Deployment to manage and run the router pods.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sandbox-router-deployment
  namespace: default
spec:
  replicas: 2 # Run at least two replicas for high availability
  selector:
    matchLabels:
      app: sandbox-router
  template:
    metadata:
      labels:
        app: sandbox-router
    spec:
      # Ensure pods are spread across different zones for HA
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: sandbox-router
      containers:
      - name: router
        image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:v20251124-v0.1.0-10-ge26ddb2
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000

    2. Aplica el manifiesto para implementar el router en tu clúster:

      kubectl apply -f sandbox-router.yaml

    Instala el cliente de Python

    Ahora que se implementaron los componentes del clúster, como el enrutador de Sandbox, el paso preparatorio final es instalar el cliente de Python de Agentic Sandbox en tu máquina local. Recuerda que este cliente es una biblioteca de Python que te permite crear, usar y borrar zonas de pruebas de forma programática. La usarás en la siguiente sección para probar el entorno:

    1. Crea y activa un entorno virtual de Python:

      python3 -m venv .venv
source .venv/bin/activate

    2. Instala el paquete del cliente desde el repositorio de agent-sandbox:

      pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@${PYTHON_CLIENT_VERSION}#subdirectory=clients/python/agentic-sandbox-client"

    Prueba la zona de pruebas

    Con todos los componentes de configuración en su lugar, ahora puedes crear una zona de pruebas y, luego, interactuar con ella usando el cliente de Python de Agentic Sandbox.

    1. En tu directorio agent-sandbox, crea una secuencia de comandos de Python llamada test_sandbox.py con el siguiente contenido:

      from agentic_sandbox import SandboxClient

# Automatically tunnels to svc/sandbox-router-svc
with SandboxClient(
    template_name="python-runtime-template",
    namespace="default"
) as sandbox:
    print(sandbox.run("echo 'Hello from the sandboxed environment!'").stdout
)

    2. Desde la terminal (con el entorno virtual aún activo), ejecuta la secuencia de comandos de prueba:

      python3 test_sandbox.py

    Deberías ver el mensaje “Hello from the sandboxed environment!”, que es el resultado de la zona de pruebas.

    ¡Felicitaciones! Ejecutaste correctamente un comando de shell dentro de un entorno de pruebas seguro. Con el método sandbox.run(), puedes ejecutar cualquier comando de shell, y Agent Sandbox ejecuta el comando dentro de una barrera segura que protege los nodos de tu clúster y otras cargas de trabajo del código no confiable. Esto proporciona una forma segura y confiable para que un agente de IA o cualquier flujo de trabajo automatizado ejecute tareas.

    Cuando ejecutas la secuencia de comandos, SandboxClient controla todos los pasos por ti. Crea el recurso SandboxClaim para iniciar el entorno de pruebas, espera a que esté listo y, luego, usa el método sandbox.run() para ejecutar comandos de shell bash dentro del contenedor seguro. Luego, el cliente captura e imprime el stdout de ese comando. El espacio aislado se borra automáticamente después de que se ejecuta el programa.

    Limpia los recursos

    Para evitar que se apliquen cargos a tu cuenta de Google Cloud , debes borrar el clúster de GKE que creaste:

    gcloud container clusters delete $CLUSTER_NAME --location=$GKE_LOCATION --quiet

    ¿Qué sigue?

    • Obtén más información sobre el proyecto de código abierto de Agent Sandbox en GitHub.
    • Para comprender la tecnología subyacente que proporciona aislamiento de seguridad para tus cargas de trabajo, consulta GKE Sandbox.
    • Para obtener más información sobre cómo mejorar la seguridad de tus clústeres y cargas de trabajo, consulta la descripción general de la seguridad de GKE.