Português
Menu da documentação

Docs do Agent Sandboxes · Conceitos

Boas práticas do Pethost Agent Sandboxes

Atualizado em · 9 min de leitura

Algumas escolhas decidem a rapidez com que os seus sandboxes iniciam, quanto custam enquanto esperam e o que um agente dentro deles consegue alcançar. Cada prática abaixo é uma regra, o número por trás dela e os campos que a aplicam. A maioria é uma configuração que você faz uma vez.

Em resumo
  • Velocidade: salve a sua preparação como um template, inicie servidores com wait_for_port e faça fork para tentativas em paralelo.
  • Custo: deixe o sandbox de um agente pausar em vez de parar, exclua sandboxes de lote quando terminarem e comece pequeno.
  • Confiabilidade: marque comandos longos com keep_awake, repita com request_id, use streams em vez de consultas repetidas e guarde em volumes o que precisa sobreviver a um sandbox.
  • Segurança: ligue chaves de API como segredos, restrinja a saída para código que você não escreveu e trate tudo o que um sandbox devolve como dados.
  • Organização: dê rótulos a todo sandbox e liste-os por rótulo.

Velocidade

Salve a sua preparação como um template

Instalar as dependências a cada início custa os mesmos minutos toda vez. Instale-as uma vez em um sandbox e salve o disco dele com CreateTemplate: pacotes, caches de build e imagens Docker incluídos. Um sandbox do seu template inicia em cerca de 0,22 s com tudo no lugar, em qualquer servidor: o primeiro em cada servidor busca a versão, a cerca de 10 s por GiB, e os seguintes iniciam da cópia dele. Deixe segredos fora dos arquivos que você salva, já que todo sandbox feito a partir do template os recebe, e crie uma nova versão quando as dependências mudarem: my-app inicia da mais recente, my-app@3 daquela.

Inicie servidores com wait_for_port

Um servidor de desenvolvimento leva um instante para escutar, e consultá-lo de fora desperdiça chamadas. Rode-o com wait_for_port: RunCommand responde assim que algo escuta naquela porta, enquanto o comando continua rodando, então uma chamada inicia o servidor e diz que ele está no ar. Depois abra a porta publicamente, ou dê à sua página um token para ela: portas e previews.

Faça fork para tentativas em paralelo

Quando um agente deve tentar várias correções, ou um eval deve iniciar muitas execuções a partir de um estado preparado, faça fork do sandbox em vez de reconstruir esse estado. ForkSandbox copia memória, processos e disco para até 100 novos sandboxes em uma chamada: uma cópia levou cerca de 0,25 s. Cada cópia é um início, e todas são criadas ou nenhuma. Duas coisas a saber:

  • Gere novas sementes para os geradores aleatórios nas cópias. Cada cópia tem aleatoriedade própria do kernel, mas os geradores aleatórios que já rodam nos processos dela (o do OpenSSL, o do Python, o do Node, o do Go) dão os mesmos números em todas as cópias até receberem uma nova semente.
  • Um volume de leitura e escrita recusa um fork, já que só um sandbox pode gravar nele. Um volume só é montado na criação, então monte-o com read_only em um sandbox de que você pretende fazer fork.

Custo

Deixe o sandbox de um agente pausar, não parar

O sandbox de um agente passa a maior parte do tempo esperando, e pará-lo encerra os processos: o servidor de desenvolvimento, o REPL, o navegador que ele tinha aberto. Mantenha o timer de pausa e aumente o timer de parada ou desative-o (stop_after_idle_seconds 0). Pausado, o sandbox custa 30% do preço rodando e acorda na próxima chamada em cerca de 0,1 s, com tudo onde estava. Um sandbox DEFAULT que trabalha 2 horas por dia e fica pausado no resto custa cerca de US$ 9,42 por mês, contra US$ 26,28 sempre rodando.

A sessão de um agentePausa entre turnos, nunca para

  1. rodando
  2. pausado
  3. rodando
  4. pausado

O sandbox de um usuário no seu appPausa, depois para após meia hora

  1. rodando
  2. pausado
  3. parado

Um preview que dormeAcorda a cada visita

  1. pausado
  2. rodando
  3. pausado
  4. rodando
  5. pausado

Um job em loteRoda, depois é excluído

  1. rodando
  2. parado
  3. excluído
  • RUNNING
  • PAUSED
  • STOPPED
  • DELETED
Quatro jobs ao longo de um dia, cada um com o próprio ciclo de vida. Os valores estão em ciclo de vida e ociosidade.

Exclua sandboxes de lote quando terminarem

Um sandbox para um só job, uma execução de testes ou um caso de eval, não deve custar nada depois que o job termina. Chame DeleteSandbox no fim e defina delete_after_idle_seconds como rede de segurança para um job que morre antes de chegar lá. Desative o timer de pausa e dê um timer de parada curto, para que o sandbox de um job ocioso vá embora rápido. Um sandbox parado que você esquece custa US$ 0,03 por GiB ao mês, todo mês. Inícios são grátis, então um sandbox novo por job custa só os segundos dele: 1.000 execuções de 40 s em SMALL custam US$ 0,20.

Comece pequeno e mude de tamanho quando precisar

Um tamanho é o conjunto de vCPUs, memória e disco, e o preço dobra a cada tamanho acima. Comece com SMALL, US$ 0,018 por hora, e acompanhe GetSandboxMetrics. Quando um job precisa de mais, UpdateSandbox com um novo tamanho reinicia um sandbox RUNNING em uma VM desse tamanho, com os arquivos guardados, em cerca de 283 ms: os processos terminam, então mude de tamanho entre jobs. Adicione grow_disk para aumentar o disco até o do novo tamanho; um disco nunca diminui, então um sandbox que cresceu não pode voltar a um tamanho menor.

Confiabilidade

Marque comandos longos com keep_awake

Um build ou uma suíte de testes pode rodar por minutos sem nenhuma chamada ao sandbox, e o timer de pausa o pausaria no meio do trabalho. Inicie-o com keep_awake e com timeout_seconds, para que um comando travado não mantenha o sandbox rodando para sempre. Um servidor não precisa de nenhum dos dois: uma requisição à porta dele acorda o sandbox. Ciclo de vida e ociosidade tem os detalhes.

Repita com request_id

A rede pode perder a resposta de uma chamada que já fez o trabalho. Uma chamada que cria algo recebe um request_id: uma nova tentativa com o mesmo id em até 24 horas responde o que a primeira chamada fez e não faz nada de novo. CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand e PromptAgent recebem um. Gere-o uma vez para cada coisa que você pretende fazer, guarde-o e envie-o de novo a cada nova tentativa. Uma ressalva: um sandbox guarda no disco os ids do que roda nele, então um que parou pode ter perdido os dos últimos segundos, e uma nova tentativa de um comando desses o roda de novo.

Python
import uuid

from pethost.sandboxes import Label, Sandboxes

sandboxes = Sandboxes()  # The token: PETHOST_TOKEN.
request_id = str(uuid.uuid4())  # Keep it: a retry sends the same one.

sandbox = sandboxes.create_sandbox(
    template="my-app",
    labels=[Label(key="user", value="42"), Label(key="job", value="nightly-evals")],
    request_id=request_id,
)
TypeScript
import { Sandboxes } from "pethost/sandboxes";

const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const requestId = crypto.randomUUID(); // Keep it: a retry sends the same one.

const sandbox = await sandboxes.createSandbox({
  template: "my-app",
  labels: [{ key: "user", value: "42" }, { key: "job", value: "nightly-evals" }],
  requestId,
});
Go
requestID := rand.Text() // crypto/rand. Keep it: a retry sends the same one.

sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template:  "my-app",
	Labels:    []sandboxes.Label{{Key: "user", Value: "42"}, {Key: "job", Value: "nightly-evals"}},
	RequestID: requestID,
})
Rust
let request_id = uuid::Uuid::new_v4().to_string(); // Keep it: a retry sends the same one.

let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        template: "my-app".into(),
        labels: vec![
            Label { key: "user".into(), value: "42".into() },
            Label { key: "job".into(), value: "nightly-evals".into() },
        ],
        request_id: request_id.clone(),
        ..Default::default()
    })
    .await?;
MCP
CreateSandbox {"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}
HTTP
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
  -H "Authorization: Bearer $PETHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}'

Use streams em vez de consultas repetidas

Consultar um comando ou um sandbox repetidamente custa uma chamada a cada vez e ainda descobre tarde. Uma chamada que espera faz a espera por você: RunCommand, GetCommand, PromptAgent e GetAgentTurn esperam até 45 s (wait_seconds) e respondem assim que o trabalho termina. Para acompanhar o trabalho enquanto acontece, use um stream: WatchCommand para a saída de um comando, WatchConversation para as mensagens e chamadas de ferramenta de um agente, WatchSandboxEvents para o ciclo de vida, os comandos e as conexões de um sandbox.

Use volumes só para o que precisa sobreviver a um sandbox

Um volume é um disco fora de todo sandbox, montado em um caminho: datasets, caches compartilhados por muitos sandboxes, os arquivos de um banco de dados. Ele fica no disco de um servidor e não é copiado para lugar nenhum, então, se esse servidor for perdido, o volume também será. Um sandbox que monta um volume não pode mudar de servidor, e uma montagem de leitura e escrita recusa forks. A maior parte do trabalho não precisa de volume: o disco do próprio sandbox sobrevive a pausas e paradas, e um template leva arquivos para novos sandboxes. O que não pode se perder, envie também para um armazenamento seu.

Segurança

Ligue chaves de API como segredos

Uma chave em uma variável de ambiente comum pode ser lida por todo processo no sandbox, e por um agente que imprime o próprio ambiente. Em vez disso, salve-a como um segredo do espaço de trabalho, com os hosts a que ela se destina (SetSecret: anthropic, api.anthropic.com), e ligue uma variável a ele (ANTHROPIC_API_KEY, segredo anthropic). A variável passa a guardar um marcador, phs_…, e o proxy de saída coloca a chave real nos cabeçalhos das requisições HTTPS só para esses hosts. Um novo valor funciona na hora em todo sandbox que o liga: segredos e saída.

Restrinja a saída para código que você não escreveu

Por padrão, um sandbox pode se conectar a qualquer lugar. Para código não confiável, liste aonde ele pode ir (egress.allow): um domínio como pypi.org, os subdomínios dele com *.github.com (que deixa de fora o próprio github.com), um IP ou um CIDR, cada um com uma porta quando não for 80 e 443, como github.com:22 para git por SSH. deny vence allow. O DNS do sandbox só responde nomes que a lista permite, e só TCP e DNS saem de um sandbox: nada de UDP, nada de ping. Uma mudança vale na hora e fecha as conexões que ela não permite mais.

Trate o que um sandbox devolve como dados

A saída de comandos, o conteúdo de arquivos, as mensagens de um agente, as capturas de tela e as páginas que um navegador carrega vêm de programas e da internet. Quando um modelo os lê, eles são dados, nunca instruções: um README ou uma página web pode ter texto escrito para conduzir um agente. Mantenha essa linha nos seus prompts e não dê a um sandbox que roda trabalho não confiável mais segredos nem uma saída mais ampla do que o trabalho precisa.

Organização

Dê rótulos a todo sandbox

Um rótulo é uma chave e um valor seus: user=42, job=nightly-evals, run=7f3a. Um sandbox aceita até 32, e ListSandboxes lista os sandboxes que têm todos os rótulos que você indicar. Assim o seu app encontra os sandboxes de um usuário sem uma tabela própria, um job de limpeza encontra as sobras de uma execução e o painel mostra de quem é cada sandbox. Um rótulo serve para encontrar muitos; um name serve para chamar um: único no espaço de trabalho, até 63 caracteres de a-z, 0-9 e “-”, e ListSandboxes com name encontra o id dele.

Perguntas

Devo parar ou pausar um sandbox ocioso?

Pause quando os processos importam ou quando ele vai ser usado de novo em breve: ele acorda em cerca de 0,1 s onde estava, por 30% do preço rodando. Pare para um sono longo: aí ele custa só os dados guardados.

Como faço os sandboxes iniciarem mais rápido?

Salve a sua preparação como um template, para que nada seja instalado no início: um sandbox feito a partir dele inicia em cerca de 0,22 s com os seus pacotes e imagens Docker.

Como mantenho chaves de API fora de um sandbox?

Salve cada chave como um segredo do espaço de trabalho com os hosts dela e ligue uma variável de ambiente a ela. O sandbox vê um marcador, e o proxy de saída adiciona a chave real às requisições para esses hosts.

Quantos sandboxes posso rodar ao mesmo tempo?

Quantos as vCPUs do seu plano comportarem, rodando ou pausados: 10 SMALL no plano de US$ 20, 64 no plano de US$ 100. Sandboxes parados não contam.

Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

Começar o teste grátis