Isolar a execução de código de IA com o sandbox do agente

Neste documento, fornecemos instruções para instalar e executar o controlador do sandbox do agente em um cluster do Google Kubernetes Engine (GKE). Ela também explica como implantar um ambiente de sandbox no cluster em que você pode testar comandos de shell não confiáveis.

O controlador do sandbox do agente fornece um framework para criar e gerenciar ambientes de execução efêmeros. Essa abordagem permite definir um modelo para o ambiente do app e criar instâncias dele sob demanda.

O sandbox do agente oferece um ambiente seguro e isolado para executar códigos não confiáveis, como os gerados por modelos de linguagem grandes (LLMs). Executar esse tipo de código diretamente em um cluster representa riscos de segurança, porque um código não confiável pode acessar ou interferir em outros apps ou no próprio nó do cluster.

O sandbox do agente mitiga esses riscos fornecendo um forte isolamento de processo, armazenamento e rede para o código que ele executa. Esse isolamento é alcançado usando o gVisor, uma tecnologia que cria uma barreira segura entre o aplicativo e o sistema operacional do nó do cluster. Outras tecnologias de isolamento, como os contêineres Kata, podem ser usadas. No entanto, o exemplo neste documento usa apenas o gVisor.

Este documento fornece instruções para executar a caixa de simulação do agente em um cluster do GKE Autopilot ou Standard.

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

Custos

Seguir as etapas deste documento gera cobranças na sua conta do Google Cloud. Os custos começam quando você cria um cluster do GKE. Esses custos incluem cobranças por cluster do 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, desative o GKE ou exclua 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

    Definir variáveis de ambiente

    Para simplificar os comandos executados neste documento, defina variáveis de ambiente no Cloud Shell. No Cloud Shell, defina as seguintes variáveis de ambiente úteis executando os comandos abaixo:

    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"

    Confira uma explicação dessas variáveis de ambiente:

    • PROJECT_ID: o ID do seu projeto Google Cloud atual. Definir essa variável ajuda a garantir que todos os recursos, como seu cluster do GKE, sejam criados no projeto correto.
    • CLUSTER_NAME: o nome do cluster do GKE. Por exemplo, agent-sandbox-cluster.
    • GKE_LOCATION: a Google Cloud região em que o cluster do GKE e o repositório do Artifact Registry serão criados, por exemplo, us-central1. Recomendamos a colocação conjunta porque isso reduz a latência de extração de imagens.
    • AGENT_SANDBOX_VERSION: a versão do controlador do Agent Sandbox a ser implantada no cluster.
    • NODE_POOL_NAME: o nome do pool 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 pool de nós. Por exemplo, e2-standard-2. Para detalhes sobre diferentes séries de máquinas e como escolher entre diferentes opções, consulte o Guia de comparação e recursos para famílias de máquinas.
    • PYTHON_CLIENT_VERSION: a versão do cliente Python do Agentic Sandbox a ser instalada.

    Implantar o sandbox do agente

    Agora que você configurou o projeto Google Cloud e o ambiente do Cloud Shell, está tudo pronto para provisionar a infraestrutura necessária e implantar o Agent Sandbox.

    Criar um cluster do GKE

    Em seguida, crie um cluster do GKE com o gVisor ativado. Esse cluster fornece o ambiente do Kubernetes em que você vai implantar e executar o controlador do sandbox do agente e o app de exemplo em sandbox. O gVisor fornece a tecnologia de sandbox para executar código não confiável com segurança.

    É possível criar um cluster do Autopilot ou Standard. O Autopilot ativa o gVisor automaticamente, enquanto os clusters Standard exigem que você crie um pool de nós ativado para gVisor manualmente:

    Piloto automático

    Para criar um cluster do Autopilot usando a CLI gcloud, execute o seguinte comando:

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

    Padrão

    Para criar um cluster padrão usando a gcloud CLI, siga estas etapas:

    1. Crie o cluster:

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

    2. Crie um pool de nós 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

    Recupere as credenciais do cluster para que a CLI kubectl possa se conectar a ele. Esse comando atualiza o arquivo de configuração do Kubernetes, que é armazenado por padrão no diretório ~/.kube/config. Esse arquivo de configuração contém as credenciais necessárias para que o kubectl interaja com o cluster do GKE:

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

    Implante o controlador do Agent Sandbox no cluster

    Implante o controlador do Sandbox do agente e os componentes necessários aplicando os manifestos de lançamento oficiais ao cluster. Esses manifestos são arquivos de configuração que instruem o Kubernetes a baixar todos os componentes necessários para implantar e executar o controlador do Agent Sandbox no cluster.

    Execute os comandos a seguir para implantar o controlador do sandbox do agente no 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

    Verificar o controlador do sandbox do agente

    Depois de aplicar os manifestos, verifique se o pod do controlador do Agent Sandbox está sendo executado corretamente no namespace agent-sandbox-system:

    kubectl get pods -n agent-sandbox-system

    Aguarde até que o pod mostre "Running" na coluna STATUS e "1/1" na coluna READY. Quando o pod estiver em execução corretamente, a saída será semelhante a esta:

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

    Agora que o controlador do sandbox do agente está em execução, ele pode criar e gerenciar automaticamente ambientes em sandbox para qualquer recurso Sandbox que você criar no cluster.

    Implantar um ambiente em sandbox

    Agora que o controlador do Agent Sandbox está em execução no seu cluster do GKE, é necessário implantar os componentes do ambiente de sandbox de exemplo. Nesta seção, mostramos como criar o blueprint do sandbox (SandboxTemplate), implantar o roteador de rede necessário e instalar o cliente Python que você vai usar para interagir com o sandbox.

    A maneira recomendada de criar e interagir com sua sandbox é usando o cliente Python da sandbox de agente. Esse cliente fornece uma interface que simplifica todo o ciclo de vida de uma sandbox, desde a criação até a limpeza. É uma biblioteca Python que pode ser usada para criar, usar e excluir sandboxes de forma programática.

    O cliente usa um roteador de sandbox como ponto de entrada central para todo o tráfego. No exemplo descrito neste documento, o cliente cria um túnel para esse roteador usando o comando kubectl port-forward. Assim, não é necessário expor nenhum endereço IP público. O uso de kubectl port-forward não é uma solução segura e deve ser limitado a ambientes de desenvolvimento.

    Criar um SandboxTemplate e um SandboxWarmPool

    Agora, defina a configuração da sua sandbox criando um recurso SandboxTemplate e SandboxWarmPool. O SandboxTemplate funciona como um blueprint reutilizável que o controlador do sandbox do agente usa para criar ambientes de sandbox consistentes e pré-configurados. O recurso SandboxWarmPool garante que um número especificado de pods preaquecidos esteja sempre em execução e pronto para ser reivindicado. Um sandbox pré-aquecido é um pod em execução que já foi inicializado. Essa pré-inicialização permite que novas caixas de areia sejam criadas em menos de um segundo e evita a latência de inicialização de uma caixa de areia comum:

    1. No Cloud Shell, crie um arquivo chamado 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 os manifestos SandboxTemplate e SandboxWarmPool:

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

    Implante o roteador do sandbox

    O cliente Python que você vai usar para criar e interagir com ambientes em sandbox usa um componente chamado roteador de sandbox para se comunicar com os sandboxes.

    Neste exemplo, você vai usar o modo de desenvolvedor do cliente para testes. Esse modo é destinado ao desenvolvimento local e usa o comando kubectl port-forward para estabelecer um túnel direto da máquina local para o serviço Sandbox Router em execução no cluster. Essa abordagem de tunelamento evita a necessidade de um endereço IP público ou uma configuração de entrada complexa e simplifica a interação com sandboxes do seu ambiente local.

    Siga estas etapas para implantar o roteador de sandbox:

    1. No Cloud Shell, crie um arquivo chamado 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 implantar o roteador no cluster:

      kubectl apply -f sandbox-router.yaml

    Instalar o cliente Python

    Agora que os componentes no cluster, como o roteador do Sandbox, foram implantados, a etapa preparatória final é instalar o cliente Python do Sandbox de agente na sua máquina local. Lembre-se de que esse cliente é uma biblioteca Python que permite criar, usar e excluir sandboxes de maneira programática. Você vai usá-lo na próxima seção 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 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"

    Testar o sandbox

    Com todos os componentes de configuração no lugar, agora você pode criar e interagir com um sandbox usando o cliente Python do sandbox de agente.

    1. No diretório agent-sandbox, crie um script Python chamado test_sandbox.py com 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. No terminal (com o ambiente virtual ainda ativo), execute o script de teste:

      python3 test_sandbox.py

    Você vai ver a mensagem "Hello from the sandboxed environment!", que é a saída da sandbox.

    Parabéns! Você executou um comando shell em um sandbox seguro. Usando o método sandbox.run(), é possível executar qualquer comando do shell, e o sandbox do agente executa o comando em uma barreira segura que protege os nós do cluster e outras cargas de trabalho contra código não confiável. Isso oferece uma maneira segura e confiável para um agente de IA ou qualquer fluxo de trabalho automatizado executar tarefas.

    Quando você executa o script, o SandboxClient processa todas as etapas. Ele cria o recurso SandboxClaim para iniciar o sandbox, aguarda que ele fique pronto e usa o método sandbox.run() para executar comandos do shell bash dentro do contêiner seguro. Em seguida, o cliente captura e imprime o stdout desse comando. O sandbox é excluído automaticamente após a execução do programa.

    Limpar recursos

    Para evitar cobranças na sua conta do Google Cloud , exclua o cluster do GKE que você criou:

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

    A seguir

    • Saiba mais sobre o projeto de código aberto do Agent Sandbox no GitHub.
    • Para entender a tecnologia subjacente que fornece isolamento de segurança para suas cargas de trabalho, consulte GKE Sandbox.
    • Para mais informações sobre como aumentar a segurança dos clusters e cargas de trabalho, consulte Visão geral da segurança do GKE.