Isole a execução de código de IA com a sandbox de agentes

Este documento fornece instruções para instalar e executar o controlador da caixa de areia do agente num cluster do Google Kubernetes Engine (GKE). Também explica como implementar um ambiente de sandbox no cluster no qual pode testar comandos de shell não fidedignos.

O controlador da sandbox do agente oferece uma estrutura para criar e gerir ambientes de tempo de execução efémeros. Esta abordagem permite-lhe definir um modelo para o ambiente da sua app e, em seguida, criar instâncias do mesmo a pedido.

A área de testes do agente oferece um ambiente seguro e isolado para executar código não fidedigno, como código gerado por modelos de linguagem (conteúdo extenso) (MDIs/CEs). A execução deste tipo de código diretamente num cluster representa riscos de segurança, porque o código não fidedigno pode potencialmente aceder ou interferir com outras apps ou com o próprio nó do cluster subjacente.

O Agent Sandbox mitiga estes riscos através do fornecimento de um forte isolamento de processos, armazenamento e rede para o código que executa. Este isolamento é conseguido através do gVisor, uma tecnologia que cria uma barreira segura entre a aplicação e o sistema operativo do nó do cluster. Em alternativa, pode usar outras tecnologias de sandbox, por exemplo, contentores Kata. No entanto, o exemplo neste documento usa apenas o gVisor.

Este documento fornece instruções para executar a área de testes do agente num cluster do GKE Autopilot ou num cluster padrão.

O Agent Sandbox é um projeto de código aberto. Para mais informações sobre como contribuir para o projeto ou encontrar detalhes técnicos mais detalhados, consulte o projeto de código aberto da sandbox do agente.

Custos

Seguir os passos descritos neste documento implica encargos na sua Google Cloud conta. Os custos começam quando cria um cluster do GKE. Estes custos incluem cobranças por cluster para o GKE, conforme descrito na página de preços, e cobranças pela execução de VMs do Compute Engine.

Para evitar cobranças desnecessárias, certifique-se de que desativa o GKE ou elimina o projeto depois de concluir este documento.

Antes de começar

  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

    Defina variáveis de ambiente

    Para simplificar os comandos que executa neste documento, pode definir variáveis de ambiente no Cloud Shell. No Cloud Shell, defina as seguintes variáveis de ambiente úteis executando os seguintes 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"

    Segue-se uma explicação destas variáveis de ambiente:

    • PROJECT_ID: o ID do seu projeto Google Cloud atual. A definição desta variável ajuda a garantir que todos os recursos, como o cluster do GKE, são criados no projeto correto.
    • CLUSTER_NAME: o nome do seu cluster do GKE, por exemplo, agent-sandbox-cluster.
    • GKE_LOCATION: a Google Cloud região onde o seu cluster do GKE e o repositório do Artifact Registry vão ser criados, por exemplo, us-central1. Recomendamos que os coloque no mesmo local, porque isto reduz a latência de obtenção de imagens.
    • AGENT_SANDBOX_VERSION: a versão do controlador do Agent Sandbox a implementar no seu cluster.
    • NODE_POOL_NAME: o nome do conjunto de nós que vai executar cargas de trabalho em sandbox, por exemplo, agent-sandbox-node-pool.
    • MACHINE_TYPE: o tipo de máquina dos nós no seu conjunto de nós, por exemplo, e2-standard-2. Para ver detalhes sobre as diferentes séries de máquinas e escolher entre diferentes opções, consulte o recurso de famílias de máquinas e o guia de comparação.
    • PYTHON_CLIENT_VERSION: a versão do cliente Python do sandbox com agência a instalar.

    Implemente o sandbox do agente

    Agora que tem o Google Cloud projeto e o ambiente do Cloud Shell configurados, está tudo pronto para aprovisionar a infraestrutura necessária e implementar a Agent Sandbox.

    Crie um cluster do GKE

    Em seguida, crie um cluster do GKE com o gVisor ativado. Este cluster fornece o ambiente do Kubernetes onde vai implementar e executar o controlador da sandbox do agente e a app com sandbox de exemplo. O gVisor fornece a tecnologia de sandboxing para executar código não fidedigno de forma segura.

    Pode criar um cluster do Autopilot ou um cluster padrão. O Autopilot ativa o gVisor automaticamente, enquanto os clusters Standard requerem que crie manualmente um conjunto de nós com o gVisor ativado:

    Piloto automático

    Para criar um cluster do Autopilot através da CLI gcloud, execute o seguinte comando:

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

    Standard

    Para criar um cluster padrão com a CLI gcloud, siga estes passos:

    1. Crie o cluster:

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

    2. Crie um node pool separado com o gVisor ativado:

      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

    Obtenha as credenciais do cluster para que a CLI kubectl possa estabelecer ligação ao cluster. Este comando atualiza o ficheiro de configuração do Kubernetes, que é armazenado por predefinição no diretório ~/.kube/config. Este ficheiro de configuração contém as credenciais que o kubectl requer para interagir com o seu cluster do GKE:

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

    Implemente o controlador da sandbox do agente no seu cluster

    Pode implementar o controlador do Agent Sandbox e os respetivos componentes necessários aplicando os manifestos de lançamento oficiais ao seu cluster. Estes manifestos são ficheiros de configuração que indicam ao Kubernetes que transfira todos os componentes necessários para implementar e executar o controlador da sandbox do agente no seu cluster.

    Execute os seguintes comandos para implementar o controlador da sandbox do agente no seu cluster do 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

    Valide o controlador da Agent Sandbox

    Depois de aplicar os manifestos, verifique se o pod do controlador da sandbox do agente está a ser executado corretamente no espaço de nomes agent-sandbox-system:

    kubectl get pods -n agent-sandbox-system

    Aguarde até que o Pod apresente "Running" na coluna STATUS e "1/1" na coluna READY. Quando o pod está a ser executado corretamente, o resultado é semelhante ao seguinte:

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

    Agora que o controlador da sandbox do agente está em execução, pode criar e gerir automaticamente ambientes em sandbox para quaisquer recursos Sandbox que criar no cluster.

    Implemente um ambiente em sandbox

    Agora que tem o controlador da área de testes do agente em execução no cluster do GKE, tem de implementar os componentes para o ambiente de testes de exemplo. Esta secção mostra como criar o projeto da sandbox (SandboxTemplate), implementar o router de rede necessário e instalar o cliente Python que vai usar para interagir com a sandbox.

    A forma recomendada de criar e interagir com a sua sandbox é usar o cliente Python da sandbox com agentes. Este cliente fornece uma interface que simplifica todo o ciclo de vida de uma caixa de areia, desde a criação à limpeza. É uma biblioteca Python que pode usar para criar, usar e eliminar caixas de areia de forma programática.

    O cliente usa um router de sandbox como ponto de entrada central para todo o tráfego. No exemplo descrito neste documento, o cliente cria um túnel para este router através do comando kubectl port-forward, para que não tenha de expor endereços IP públicos. Tenha em atenção que a utilização de kubectl port-forward não é uma solução segura e a respetiva utilização deve ser limitada a ambientes de desenvolvimento.

    Crie um SandboxTemplate e um SandboxWarmPool

    Agora, define a configuração para a sua sandbox criando um recurso SandboxTemplate e um recurso SandboxWarmPool. O SandboxTemplate funciona como um modelo reutilizável que o controlador do isolamento de processos do agente usa para criar ambientes de isolamento de processos pré-configurados consistentes. O recurso SandboxWarmPool garante que um número especificado de pods pré-aquecidos está sempre em execução e pronto para ser reivindicado. Uma sandbox pré-aquecida é um pod em execução que já foi inicializado. Esta pré-inicialização permite a criação de novos sandboxes em menos de um segundo e evita a latência de arranque do lançamento de um sandbox normal:

    1. No Cloud Shell, crie um ficheiro denominado sandbox-template-and-pool.yaml com o seguinte conteúdo:

      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. Aplique o manifesto SandboxTemplate e SandboxWarmPool:

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

    Implemente o router de sandbox

    O cliente Python que vai usar para criar e interagir com ambientes em sandbox usa um componente denominado Router de sandbox para comunicar com as sandboxes.

    Para este exemplo, usa o modo de programador do cliente para testes. Este modo destina-se ao desenvolvimento local e usa o comando kubectl port-forward para estabelecer um túnel direto da sua máquina local para o serviço Sandbox Router em execução no cluster. Esta abordagem de tunelização evita a necessidade de um endereço IP público ou de uma configuração de entrada complexa e simplifica a interação com as caixas de areia a partir do seu ambiente local.

    Siga estes passos para implementar o router de sandbox:

    1. No Cloud Shell, crie um ficheiro denominado sandbox-router.yaml com o seguinte conteúdo:

      # 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. Aplique o manifesto para implementar o router no cluster:

      kubectl apply -f sandbox-router.yaml

    Instale o cliente Python

    Agora que os componentes no cluster, como o router da área restrita, estão implementados, o passo preparatório final é instalar o cliente Python da área restrita do agente na sua máquina local. Lembre-se de que este cliente é uma biblioteca Python que lhe permite criar, usar e eliminar caixas de areia programaticamente. Use-o na secção seguinte para testar o ambiente:

    1. Crie e ative um ambiente virtual Python:

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

    2. Instale o pacote de cliente a partir do repositório agent-sandbox:

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

    Teste a sandbox

    Com todos os componentes de configuração implementados, já pode criar e interagir com um ambiente de testes usando o cliente Python do ambiente de testes com agentes.

    1. No diretório agent-sandbox, crie um script Python com o nome test_sandbox.py e o seguinte conteúdo:

      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. A partir do terminal (com o ambiente virtual ainda ativo), execute o script de teste:

      python3 test_sandbox.py

    Deverá ver a mensagem "Olá do ambiente de sandbox!", que é produzida pela sandbox.

    Parabéns! Executou com êxito um comando de shell num ambiente de teste seguro. Com o método sandbox.run(), pode executar qualquer comando de shell e a sandbox do agente executa o comando numa barreira segura que protege os nós do cluster e outras cargas de trabalho de código não fidedigno. Isto oferece uma forma segura e fiável para um agente de IA ou qualquer fluxo de trabalho automatizado executar tarefas.

    Quando executa o script, o SandboxClient processa todos os passos por si. Cria o recurso SandboxClaim para iniciar o sandbox, aguarda que o sandbox fique pronto e, em seguida, usa o método sandbox.run() para executar comandos da shell bash no contentor seguro. Em seguida, o cliente captura e imprime o stdout desse comando. A sandbox é eliminada automaticamente após a execução do programa.

    Limpe recursos

    Para evitar incorrer em cobranças na sua Google Cloud conta, deve eliminar o cluster do GKE que criou:

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

    O que se segue?

    • Saiba mais sobre o projeto de código aberto Agent Sandbox no GitHub.
    • Para compreender a tecnologia subjacente que oferece isolamento de segurança para as suas cargas de trabalho, consulte o GKE Sandbox.
    • Para mais informações sobre como melhorar a segurança dos seus clusters e cargas de trabalho, consulte a vista geral da segurança do GKE.