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

Este documento fornece instruções para implantar um ambiente de desenvolvedor e usar o cliente Python do Agent Sandbox em um cluster do Google Kubernetes Engine (GKE).

Para uma visão geral de como o recurso do Agent Sandbox isola o código gerado por IA não confiável, consulte Sobre o GKE Agent Sandbox.

Custos

O Agent Sandbox é oferecido sem custo extra no GKE. Os preços do GKE se aplicam aos recursos criados.

Antes de começar

  1. No Google Cloud console do, na página do seletor de projetos, escolha ou crie um Google Cloud projeto do.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. É possível selecionar qualquer projeto em que você tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

    Acessar o seletor de projetos

  2. Verifique se o faturamento está ativado para o Google Cloud projeto.

  3. Ative o Artifact Registry e as APIs do Kubernetes Engine.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar as APIs

  4. No Google Cloud console do, ative o Cloud Shell.

    Ativar o Cloud Shell

  5. Verifique se você tem as permissões necessárias para concluir este guia.
  6. É necessário ter um cluster do GKE com o recurso do Agent Sandbox ativado. Se você não tiver um, siga as instruções em Ativar o Agent Sandbox no GKE para criar um novo cluster ou atualizar um já existente.

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar sandboxes, peça ao administrador para conceder a você o papel do IAM de administrador do Kubernetes Engine (roles/container.admin) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando personalizados papéis ou outros predefinidos papéis.

Definir as variáveis de ambiente

Para simplificar os comandos executados neste documento, é possível definir variáveis de ambiente no Cloud Shell. No Cloud Shell, defina as seguintes variáveis de ambiente úteis executando os comandos a seguir:

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"

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

  • PROJECT_ID: o ID do seu projeto atual. Google Cloud A definição dessa variável ajuda a garantir que todos os recursos, como o cluster do GKE, sejam criados no projeto correto.
  • CLUSTER_NAME: o nome do cluster do GKE, por exemplo, agent-sandbox-cluster.
  • LOCATION: aregião ou zona em que o cluster do GKE está localizado. Google Cloud Defina isso como a região (por exemplo, us-central1) se estiver usando um cluster do Autopilot ou a zona (por exemplo, us-central1-a) se estiver usando um cluster padrão.
  • 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 mais 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.

Implantar um ambiente em sandbox

Esta seção mostra como criar o modelo de sandbox (SandboxTemplate), implantar o roteador de rede necessário e instalar o cliente Python que você usará para interagir com o sandbox.

A maneira recomendada de criar e interagir com o sandbox é usando o cliente Python do Agentic Sandbox. Esse cliente fornece uma interface que simplifica todo o ciclo de vida de um sandbox, da criação à limpeza. É uma biblioteca Python que pode ser usada para criar, usar e excluir sandboxes de maneira programática.

O cliente usa um roteador de sandbox como um 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, para que você não precise expor nenhum endereço IP público. O uso de kubectl port-forward não é uma solução segura e o uso dele precisa ser limitado a ambientes de desenvolvimento.

Criar um SandboxTemplate e um SandboxWarmPool

Agora, defina a configuração do sandbox criando um recurso SandboxTemplate e um SandboxWarmPool. O SandboxTemplate atua como um modelo reutilizável que o controlador do Agent Sandbox usa para criar ambientes de sandbox consistentes e pré-configurados. O recurso SandboxWarmPool ajuda a garantir que um número especificado de pods pré-aquecidos 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 novos sandboxes sejam criados em menos de um segundo e evita a latência de inicialização de um sandbox normal:

  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
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      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"
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      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

Implantar o roteador de sandbox

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

Para este exemplo, use 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 de roteador de sandbox 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 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: 1
  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:latest-main
        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: "100m"
            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

  3. Verifique se a implantação do roteador de sandbox está em execução corretamente:

    kubectl get deployment sandbox-router-deployment

    Aguarde até que a implantação mostre 2/2 ou 1/1 na coluna READY.

Instalar o cliente Python

Agora que os componentes no cluster, como o roteador de sandbox, estão implantados, a etapa preparatória final é instalar o cliente Python do Agentic Sandbox 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ê o usará 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 do cliente:

    pip install k8s-agent-sandbox

Testar o sandbox

Com todos os componentes de configuração no lugar, agora é possível criar e interagir com um sandbox usando o cliente Python do Agentic Sandbox.

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

    from k8s_agent_sandbox import SandboxClient
from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig

# Automatically tunnels to svc/sandbox-router-svc
client = SandboxClient(
    connection_config=SandboxLocalTunnelConnectionConfig()
)

sandbox = client.create_sandbox(template="python-runtime-template", namespace="default")
try:
    print(sandbox.commands.run("echo 'Hello from the sandboxed environment!'").stdout)
except Exception as e:
    print(f"An error occurred: {e}")

  2. No terminal (com o ambiente virtual ainda ativo), execute o script de teste:

    python3 test_sandbox.py

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

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

Ao executar o script, o SandboxClient processa todas as etapas para você. Ele cria o recurso SandboxClaim para iniciar o sandbox, aguarda até que o sandbox esteja pronto e usa o método sandbox.run() para executar comandos 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.

Quando um recurso SandboxClaim é criado, um pod disponível é atribuído do pool quente ao objeto de sandbox e a reivindicação é marcada como pronta. O SandboxWarmPool é reabastecido automaticamente para manter o número configurado de réplicas.

Para verificar se um sandbox específico foi reivindicado ou está disponível, verifique as ownerReferences nos metadados do pod de sandbox. Se o valor do campo kind for Sandbox, o pod estará em uso. Se o valor do campo kind for SandboxWarmPool, o pod estará inativo e aguardando a reivindicação.

Executar sandboxes na produção

Neste documento, você interage com sandboxes de fora do cluster usando o Cloud Shell. O cliente Python usa suas credenciais de usuário para autenticar no cluster e gerenciar recursos de sandbox, e usa o comando kubectl port-forward para estabelecer uma conexão com sandboxes. Essas etapas funcionam bem para cenários de desenvolvimento.

Em um cenário de produção, um aplicativo de controlador (como um orquestrador de IA) é responsável por criar e gerenciar recursos de sandbox. Para usar o Agent Sandbox na produção, considere o seguinte:

  • Autenticação: o aplicativo do controlador precisa ser autenticado no servidor da API do cluster para executar sandboxes. A configuração da autenticação depende de onde o aplicativo do controlador é executado, da seguinte maneira:

  • Roteamento: as solicitações do cliente Python no aplicativo do controlador precisam chegar ao roteador de sandbox no cluster. Na produção, use um dos seguintes métodos para estabelecer uma conexão de rede:

    • Se o aplicativo do controlador for executado no mesmo cluster, use a função SandboxDirectConnectionConfig para segmentar o URL e a porta que o serviço de roteador de sandbox usa.
    • Se o aplicativo do controlador for executado fora do cluster, use a API GKE Gateway para criar um balanceador de carga interno ou externo. No código do cliente, use a função SandboxGatewayConnectionConfig para referenciar o gateway.

    Para mais informações sobre esses métodos de roteamento, consulte os exemplos de uso no GitHub e as etapas de implantação do gateway para o roteador.

  • Acesso de sandbox a Google Cloud recursos: se o código de sandbox precisar enviar solicitações para Google Cloud APIs, como o Cloud Storage, use uma política do IAM com Federação de Identidade da Carga de Trabalho para GKE para conceder à ServiceAccount do Kubernetes que o pod de sandbox usa as permissões necessárias para esse acesso.

Limpar recursos

Para evitar cobranças na sua Google Cloud conta, exclua o cluster do GKE criado:

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

A seguir