For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal

Sandboxes hospedados pela OpenAI

Execute código e crie arquivos para download sem gerenciar recursos computacionais.

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 do npm usando as listas python, system ou npm. Fixe versões quando necessário, como pandas==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óprio cwd opcional, 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, incluindo PATH, CODEX_* e OPENAI_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.accessComportamento
enabledPermite conexões de saída. Este é o padrão, a menos que você herde a política de um modelo.
disabledBloqueia conexões de saída.
restrictedPermite 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.

Crie summary.json
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

ProblemaO que verificar
A configuração falhaInspecione 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 é bloqueadaVerifique network e todos os hosts acessados por redirecionamentos.
Uma operação em arquivos no sandbox ativo falhaConfirme 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 5xxTente novamente com intervalos progressivamente maiores e um prazo limite. Guarde o ID da requisição se o erro persistir.