Guia do sandbox nativo e do Manifest do OpenAI Agents SDK

A OpenAI lançou a atualização importante do Agents SDK em 15 de abril de 2026, e a pista estava na linha de instalação do post de lançamento: pip install "openai-agents>=0.14.0" (OpenAI). Essa linha de versão importa. Não era um novo template de prompt nem mais um wrapper de function calling. Era a OpenAI levando trabalho com arquivos, trabalho em shell, aplicação de patches, ciclo de vida de sandbox e descrição de workspace para primitivas no nível do SDK.

Para desenvolvedores que criam agentes de programação, agentes de documentos, agentes de limpeza de dados ou bots de manutenção de repositório, a mudança de design é simples: parar de fazer cada equipe reconstruir o mesmo harness frágil em torno de Docker, diretórios temporários, schemas de ferramentas, preparação de arquivos e lógica de retry. O SDK agora oferece um harness nativo para modelos, execução nativa em sandbox, ferramentas de sistema de arquivos, MCP, AGENTS.md, acesso a shell, apply_patch e uma abstração de Manifest para descrever workspaces portáveis.

A mudança: de chamadas de ferramentas para um workspace real

O Agents SDK original já era útil para orquestração: agentes, ferramentas, handoffs, guardrails, tracing. A atualização de abril adiciona o formato de runtime que faltava para agentes que precisam trabalhar com arquivos ao longo do tempo.

A OpenAI descreve o SDK atualizado como uma forma de ajudar desenvolvedores a criar agentes capazes de inspecionar arquivos, executar comandos, editar código e trabalhar em tarefas de longo horizonte dentro de ambientes de sandbox controlados (OpenAI). A expressão “workspace controlado” é a chave. Um agente sério que trabalha com arquivos precisa de mais do que uma lista de ferramentas. Ele precisa de um diretório raiz, entradas montadas, locais de saída, um shell, permissões, snapshots e uma forma de retomar quando o contêiner morre.

Antes dessa atualização, uma configuração típica de produção era assim:

• criar um workspace temporário
• copiar arquivos para ele
• expor ferramentas de leitura, escrita, shell e patch
• validar caminhos manualmente
• iniciar um sandbox ou contêiner
• coletar artefatos
• gerar snapshot do estado se o job durar muito
• traduzir tudo isso em instruções voltadas ao modelo

Esse código de cola é onde muitos projetos de agentes acabam ficando silenciosamente bagunçados. O novo SDK transforma boa parte disso em configuração de primeira classe.

O post de lançamento da OpenAI listou suporte integrado a Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop e Vercel como provedores de sandbox, além de um caminho para “trazer seu próprio sandbox” (OpenAI). São sete provedores hospedados no lançamento, além de caminhos para desenvolvimento local.

Manifest é a camada de portabilidade

A abstração Manifest é a parte mais prática do lançamento. Ela descreve o que o workspace do sandbox deve conter antes de o modelo começar a trabalhar.

Na documentação Python, Sandbox Agents estão marcados como beta, exigem Python 3.10 ou superior e são apresentados como uma forma de dar ao modelo um workspace persistente onde ele pode pesquisar conjuntos de documentos, editar arquivos, executar comandos, gerar artefatos e retomar a partir de um estado de sandbox salvo (documentação Python do OpenAI Agents SDK).

Um formato Python compacto fica assim:

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import LocalDir
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Repo maintainer",
    model="gpt-5.5",
    instructions="Read repo/task.md, edit with apply_patch, then run the targeted test.",
    default_manifest=Manifest(entries={"repo": LocalDir(src="./repo")}),
)

result = await Runner.run(
    agent,
    "Fix the failing test and summarize the change.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
    ),
)

A parte importante não é a sintaxe. É o contrato. O Manifest pode descrever arquivos locais, diretórios, repositórios Git, arquivos sintéticos, variáveis de ambiente, usuários, grupos, diretórios de saída e montagens de armazenamento remoto. A documentação JavaScript diz que os caminhos das entradas do Manifest são relativos ao workspace, não podem ser absolutos e não podem escapar do workspace com .., que é exatamente o tipo de restrição entediante que você quer que seja aplicada pelo runtime, em vez de precisar ser lembrada em todo prompt (documentação JS do OpenAI Agents SDK).

Capacidades: shell, sistema de arquivos, skills, memória, compactação

Um SandboxAgent não é apenas um agente normal com uma pasta temporária. Ele carrega capacidades específicas de sandbox.

A documentação de conceitos em JS lista capacidades integradas, incluindo shell(), filesystem(), skills(), memory() e compaction() (documentação JS do OpenAI Agents SDK). Os padrões importam aqui: a documentação afirma que Capabilities.default() inclui sistema de arquivos, shell e compactação. Isso significa que o loop comum de agente de programação deixa de ser um monte de definições de ferramentas sob medida.

A capacidade de sistema de arquivos expõe edições de arquivos em estilo patch. A capacidade de shell expõe execução de comandos dentro da sessão de sandbox. Skills permitem divulgar progressivamente instruções ou procedimentos especializados. Memória e compactação ajudam execuções mais longas a manter estado útil sem enfiar todos os tokens anteriores de volta no próximo turno.

Isso combina com a forma como agentes de programação fortes realmente trabalham. Eles inspecionam. Executam um comando. Editam um arquivo. Executam um comando menor. Inspecionam o diff. Resumem o que mudou. Se o seu harness trata cada etapa como uma chamada de API sem relação com as outras, o modelo gasta atenção demais reconstruindo seu mundo. Uma sessão de sandbox dá ao modelo um lugar para se apoiar.

AGENTS.md também se encaixa naturalmente nesse modelo. O site aberto do AGENTS.md o descreve como um formato Markdown para orientar agentes de programação e diz que ele é usado por mais de 60.000 projetos open source (AGENTS.md). Esse arquivo deve conter comandos de build, instruções de teste, regras de estilo e avisos específicos do repositório. No mundo do sandbox, AGENTS.md vira contexto operacional local ao workspace, em vez de um prompt gigante colado em toda tarefa.

Python primeiro, TypeScript correndo atrás

No lançamento, isso era Python-first. A TechCrunch informou em 15 de abril que o novo harness e as capacidades de sandbox seriam lançados primeiro em Python, com suporte a TypeScript planejado para depois (TechCrunch). O PyPI confirma a data: as versões 0.14.0 e 0.14.1 de openai-agents foram enviadas em 15 de abril de 2026 (PyPI).

Em 16 de junho de 2026, o quadro prático está mais equilibrado. A documentação JS oficial agora inclui Sandbox Agents em beta, exige Node.js 22 ou superior e mostra Manifest, SandboxAgent, UnixLocalSandboxClient, suporte a Docker e clientes de provedores hospedados por meio de @openai/agents-extensions (quickstart JS do OpenAI Agents SDK). A documentação JS também observa que Deno e Bun podem funcionar quando a resolução de pacotes e as APIs de runtime são compatíveis.

Área	Python	TypeScript / JavaScript
Status de lançamento em 15 de abril	Primeiro caminho suportado	Planejado para depois
Documentação atual de sandbox	Beta, Python 3.10+	Beta, Node.js 22+
Sandbox local	UnixLocalSandboxClient	UnixLocalSandboxClient
Sandbox Docker	openai-agents[docker]	DockerSandboxClient
Provedores hospedados	Suportados via integrações do SDK	Caminhos de provedores em @openai/agents-extensions

Isso não significa que os dois ecossistemas sejam idênticos. Python foi a superfície original de lançamento, e muitos exemplos ainda chegam lá primeiro. TypeScript agora tem superfície oficial suficiente para prototipar agentes de sandbox reais, mas detalhes de provedores hospedados, comportamento de PTY, montagens e suporte ao ciclo de vida ainda exigem leitura cuidadosa por backend.

Como eu estruturaria agora um agente que trabalha com arquivos

O erro é tratar o sandbox como uma caixa mágica de segurança. Ele é uma fronteira de runtime, não uma especificação de produto. Você ainda precisa desenhar o workspace.

Uma estrutura limpa se parece com isto:

• repo/: a árvore de trabalho ou repositório montado
• task.md: a especificação da tarefa que o modelo deve ler primeiro
• inputs/: documentos, datasets, screenshots ou logs somente leitura
• output/: o único lugar para onde artefatos finais gerados devem ir
• AGENTS.md: instruções de build, teste, estilo e segurança
• usuário do sandbox: uma identidade não root quando o backend oferecer suporte
• env do Manifest: configuração não secreta persistida por padrão, segredos marcados como efêmeros

O Manifest deve descrever as entradas. As instruções do agente devem descrever o fluxo de trabalho. O prompt do usuário deve descrever a tarefa pontual. Mantenha essas coisas separadas. A documentação JS alerta explicitamente contra enfiar material de referência longo em instructions quando ele pertence ao Manifest (documentação JS do OpenAI Agents SDK).

Para produção, escolha o backend com base no raio de impacto, não no caminho da demo. Unix-local é adequado para desenvolvimento. Docker é um padrão melhor quando você precisa de repetibilidade. Provedores hospedados fazem sentido quando você precisa de isolamento limpo por execução, execução remota, escala ou comportamento de snapshot específico do provedor. A documentação de clientes JS afirma que o suporte a provedores hospedados varia e que desenvolvedores devem consultar a documentação do provedor para variáveis de ambiente, portas, PTY, snapshots e comportamento de limpeza (clientes JS do OpenAI Agents SDK).

A leitura do ecossistema

Essa atualização é importante porque padroniza o formato de agentes que trabalham com arquivos. A indústria já convergiu em algumas primitivas: MCP para ferramentas externas, AGENTS.md para instruções de repositório, shell para inspeção real, patches para edições revisáveis e sandboxes para contenção. O Agents SDK da OpenAI agora empacota essas peças em um runtime que desenvolvedores conseguem realmente compor.

A aresta afiada continua sendo permissões. Um agente em sandbox com rede ampla, montagens graváveis, credenciais de longa duração e instruções vagas ainda pode causar dano. O Manifest ajuda porque torna visíveis as entradas do workspace e as concessões. Ele não elimina a necessidade de políticas de aprovação, higiene de segredos, pinagem de dependências e revisão de artefatos.

O melhor caso de uso hoje não é “o agente faz tudo”. É mais estreito e mais valioso: dê ao modelo um workspace delimitado, um arquivo de tarefa claro, instruções locais ao repositório, ferramentas de shell e patch, e um caminho explícito de verificação. Deixe-o trabalhar como um engenheiro júnior em um ambiente descartável. Depois, inspecione o diff.

Essa é uma abstração muito mais saudável do que criar manualmente mais um meio-sandbox em torno de um loop de chat.

Leitores que quiserem testar esses modelos na prática podem chamá-los via onehop com uma API compatível com OpenAI mudando um único base_url. É mais barato do que o provedor first-party, e novas contas recebem US$ 10 em crédito gratuito sem precisar de cartão: chame Claude e outros modelos na onehop, ou cadastre-se para receber US$ 10 em crédito gratuito.