Um sandbox hospedado pela OpenAI oferece ao seu agente um workspace Linux com Python, Node.js e ferramentas de linha de comando. A OpenAI provisiona e conecta o sandbox; seu aplicativo fornece a tarefa e recupera os resultados. Escolha um sandbox auto-hospedado quando precisar usar sua própria imagem, seus recursos computacionais ou sua rede privada.
Configure o sandbox
Defina environment.type como openai_hosted e adicione apenas as configurações necessárias
para sua carga de trabalho. O diretório de trabalho é /workspace.
packages: Instale pacotes Python, pacotes do sistema ou pacotes globais donpmusando as listaspython,systemounpm. Fixe versões quando necessário, comopandas==2.2.3.setup_commands: Execute comandos de shell em ordem antes de iniciar o agente, como[{ "command": "mkdir -p reports" }]. Cada comando tem seu própriocwdopcional, cujo valor padrão é/workspace.files: Forneça arquivos de entrada pelo ID da API de Arquivos ou como conteúdo base64 embutido.env: Defina variáveis do ambiente com valores do tipo string. Nomes reservados pelo ambiente de execução, incluindoPATH,CODEX_*eOPENAI_API_KEY, são rejeitados.skills,plugins,capability_directories: Adicione habilidades e plug-ins.environment_template_id: Reutilize configurações salvas entre sessões. As configurações omitidas herdam os valores do modelo; substituições nas configurações de rede não podem ampliar as permissões da política do modelo.
Os pacotes e arquivos de entrada são preparados antes da execução dos comandos de configuração. Um código de saída diferente de zero na configuração impede a inicialização do agente. Use um comando de configuração para verificar as dependências ou os arquivos necessários. Os modelos salvam configurações, não um workspace em execução.
Controle o acesso à rede
network.access | Comportamento |
|---|---|
enabled | Permite conexões de saída. Este é o padrão, a menos que você herde a política de um modelo. |
disabled | Bloqueia conexões de saída. |
restricted | Permite apenas os hosts listados em allowed_domains. |
O modo restrito aceita de 1 a 100 nomes de host exatos, como api.example.com.
Não inclua curingas, protocolos, caminhos ou portas. Subdomínios e destinos de redirecionamento
precisam de entradas próprias. Atualmente, servidores MCP hospedados que usam stdio exigem
acesso definido como enabled; consulte os requisitos de MCP via stdio.
Verifique se a configuração foi concluída com sucesso
A resposta de criação da sessão indica que a configuração foi iniciada. Consulte
GET /v1/agents/environments/{environment_id} usando o environment.id da sessão:
provisioning indica que a configuração está em andamento; connected indica que ela foi concluída com sucesso.
Para failed, leia environment.error no evento agent.session.environment.failed.
Aguarde o estado connected antes de adicionar ou listar arquivos no sandbox ativo.
Arquivos e tempo de vida
Cada sessão tem um workspace separado. Os arquivos persistem entre os turnos enquanto
o sandbox da sessão existir. Os arquivos em /workspace/outputs são publicados como artefatos imutáveis
quando um turno é concluído; essas cópias continuam disponíveis para download após
o sandbox expirar.
Consulte Arquivos e artefatos para obter informações sobre uploads, regras de caminhos, operações em arquivos no sandbox ativo, downloads e limites. Salve as saídas de que precisar antes de excluir a sessão.
Expiração do sandbox
Sandboxes conectados recebem sinais de manutenção da conexão, inclusive entre turnos. Se não houver atividade nem sinais de manutenção da conexão por uma hora, o sandbox poderá ser excluído. Esse tempo limite não é configurável.
Exclua a sessão quando terminar para solicitar a limpeza do sandbox. Se a exclusão
retornar 409 enquanto a configuração ou a execução estiver sendo concluída, aguarde e tente novamente, limitando
o número de tentativas. Fechar um fluxo de eventos não cancela a tarefa.
Preços
Os sandboxes hospedados pela OpenAI usam as tarifas padrão de contêineres. O uso do modelo é cobrado separadamente, de acordo com as tarifas de API do modelo selecionado.
Exemplo: Crie um relatório
Forneça ao agente um CSV contendo 10, 20 e 30. Ele executa Python para calcular
a soma e grava o arquivo /workspace/outputs/summary.json.
Defina OPENAI_API_KEY no terminal do seu aplicativo seguindo os
pré-requisitos do início rápido.
Mantenha essa chave fora do sandbox. Use uma versão do seu
SDK da OpenAI que inclua a API de Agentes em versão beta.
from openai import OpenAI
client = OpenAI()
stream = client.beta.agents.sessions.create(
agent={"model": "gpt-6-astra"},
environment={
"type": "openai_hosted",
"network": {"access": "disabled"},
"files": [
{
"type": "inline",
"path": "/workspace/amounts.csv",
"data": "YW1vdW50CjEwCjIwCjMwCg==",
}
],
},
input="Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
stream=True,
)
with stream:
for event in stream:
print(event.model_dump_json())O valor base64 em files contém o CSV de entrada. O código exibe os eventos da sessão.
Salve o session.id do evento agent.session.created. Após agent.session.turn.completed,
liste os artefatos, encontre summary.json
e baixe o arquivo. O conteúdo deve ser:
{ "total": 60 }
Um turno concluído não garante que todas as ferramentas tenham sido executadas com sucesso. Se a tarefa falhar ou o fluxo terminar antes da conclusão, inspecione os itens salvos da sessão. Exclua a sessão quando terminar.
Solução de problemas
| Problema | O que verificar |
|---|---|
| A configuração falha | Inspecione o evento de falha do ambiente e corrija o erro no pacote, no arquivo de entrada ou no comando de configuração antes de criar outra sessão. |
| Uma requisição do sandbox é bloqueada | Verifique network e todos os hosts acessados por redirecionamentos. |
| Uma operação em arquivos no sandbox ativo falha | Confirme que o sandbox está no estado connected. Se ele tiver expirado, crie uma nova sessão e forneça as entradas novamente. |
Uma requisição de status ou de listagem de arquivos retorna 5xx | Tente novamente com intervalos progressivamente maiores e um prazo limite. Guarde o ID da requisição se o erro persistir. |