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
Theme

Sandboxes hospedados pela OpenAI

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

Um sandbox hospedado pela OpenAI oferece ao agente um espaço de trabalho 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 próprios recursos computacionais ou sua rede privada.

Para tarefas que interagem com sites por meio de um navegador, consulte Uso do computador.

Para preparar o espaço de trabalho antes de criar uma sessão, consulte Preparar sandboxes com antecedência.

Configure o sandbox

Defina environment.type como openai_hosted na solicitação de criação da sessão. Inclua apenas as configurações necessárias para sua carga de trabalho. O diretório de trabalho do sandbox é /workspace.

Use container_size e network para escolher os recursos e o acesso à rede de que a tarefa precisa. Se você usar um modelo de ambiente, as configurações omitidas herdarão os valores do modelo.

Prepare os pacotes e arquivos

Use as configurações a seguir para disponibilizar dependências e arquivos de entrada no sandbox.

  • packages: instale pacotes Python, pacotes do sistema ou pacotes globais do npm usando as listas python, system ou npm, respectivamente. Quando necessário, fixe a versão, como em pandas==2.2.3.
  • files: forneça arquivos de entrada usando o ID do arquivo na API de arquivos ou incluindo o conteúdo em base64 diretamente na solicitação.

Execute comandos de preparação

Use setup_commands para executar comandos de shell em sequência antes que o agente seja iniciado. Por exemplo, [{ "command": "mkdir -p reports" }] cria um diretório. Cada comando pode definir seu próprio cwd. O padrão é /workspace.

O sandbox prepara os pacotes e arquivos de entrada antes de executar os comandos de preparação. Use um desses comandos para verificar as dependências ou os arquivos necessários. Se um comando de preparação retornar um código de saída diferente de zero, o agente não será iniciado.

Defina as variáveis de ambiente

Use env para definir variáveis de ambiente com valores de texto. O código gerado pelo agente pode ler esses valores.

Para manter os valores reais dos segredos fora do sandbox, use as credenciais do cofre. O ambiente de execução rejeita nomes reservados, como PATH, CODEX_* e OPENAI_API_KEY.

Escolha o tamanho do contêiner

Ao criar uma sessão, defina environment.container_size para escolher os recursos de CPU e memória disponíveis para o sandbox. O valor padrão é medium.

Tamanho vCPU Memória
small 1 1 GB
medium 2 4 GB
large 4 16 GB

Por exemplo, inclua o ambiente abaixo na solicitação POST /v1/agents/sessions para selecionar o tamanho small.

{
  "environment": {
    "type": "openai_hosted",
    "container_size": "small"
  }
}

A sessão retornada informa o tamanho selecionado em environment.container_size. Essa configuração se aplica apenas a sandboxes hospedados pela OpenAI.

Controle o acesso à rede

network.access Comportamento
enabled Permite conexões de saída. É o padrão, a menos que o ambiente herde a política de um modelo.
disabled Bloqueia conexões de saída.
restricted Permite conexões apenas com os hosts listados em allowed_domains.

O modo restrito aceita de 1 a 100 nomes exatos de host, 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 enabled. Consulte os requisitos para servidores MCP que usam stdio.

Adicione habilidades e plugins

Use skills, plugins e capability_directories para adicionar habilidades e plugins.

Reutilize configurações entre sessões

Defina environment_template_id para reutilizar uma configuração salva. As configurações omitidas herdam os valores do modelo. Ao substituir as configurações de rede, você só pode conceder acesso dentro dos limites da política do modelo. Os modelos salvam a configuração, mas não preservam um espaço de trabalho em execução.

Verifique se a preparação foi bem-sucedida

A resposta à solicitação de criação da sessão indica que a preparação começou. Para verificar o status, faça uma solicitação GET /v1/agents/environments/{environment_id} usando o valor de environment.id da sessão.

Status O que fazer
provisioning Aguarde enquanto o ambiente é preparado.
connected A preparação foi bem-sucedida. Você já pode adicionar ou listar arquivos no sandbox em execução.
failed Consulte environment.error no evento agent.session.environment.failed.

Aguarde o status connected antes de adicionar ou listar arquivos no sandbox em execução.

Arquivos e duração do sandbox

Cada sessão tem um espaço de trabalho separado. Os arquivos persistem entre turnos enquanto o sandbox da sessão existir. Ao final de cada turno, os arquivos em /workspace/outputs são publicados como artefatos imutáveis. Essas cópias continuam disponíveis para download após a expiração do sandbox.

Consulte Arquivos e artefatos para saber como enviar e baixar arquivos, quais regras se aplicam aos caminhos, como trabalhar com arquivos no sandbox em execução e quais são os limites. Salve os resultados de que precisa antes de excluir a sessão.

Expiração do sandbox

Sandboxes conectados recebem sinais de manutenção da conexão, inclusive entre os turnos. Se o sandbox passar uma hora sem atividade e sem receber esses sinais, ele poderá ser excluído. Esse prazo não é configurável.

Quando terminar, exclua a sessão para solicitar a limpeza do sandbox. Se a solicitação de exclusão retornar 409 enquanto a preparação ou a execução estiver em andamento, aguarde e tente novamente, limitando o número de tentativas. Fechar o fluxo de eventos não cancela a tarefa.

Preços

Os sandboxes hospedados pela OpenAI seguem as tarifas padrão de contêineres. O uso do modelo é cobrado separadamente, de acordo com as tarifas da API para o modelo selecionado.

Exemplo de criação de um relatório

Forneça ao agente um arquivo CSV com os valores 10, 20 e 30. O agente executa código Python para calcular a soma e grava o resultado em /workspace/outputs/summary.json.

Defina OPENAI_API_KEY no terminal do seu aplicativo seguindo os pré-requisitos do guia de início rápido. Mantenha essa chave fora do sandbox. Use uma versão do SDK da OpenAI que inclua a versão beta da API de agentes.

Criar 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.with_result_collection():
    for event in stream:
        print(event.model_dump_json())
    result = stream.get_final_result()

client.beta.agents.sessions.artifacts.for_result(result).download(
    "/workspace/outputs/summary.json", to="summary.json"
)

O valor em base64 no campo files contém os dados do CSV de entrada. O código imprime os eventos da sessão. Salve o valor de session.id do evento agent.session.created. Após o evento agent.session.turn.completed, liste os artefatos, localize summary.json e baixe o arquivo. O conteúdo esperado é o seguinte.

{ "total": 60 }

A conclusão do turno não garante que todas as ferramentas tenham sido executadas com sucesso. Se a tarefa falhar ou o fluxo de eventos terminar antes da conclusão, examine os itens salvos da sessão. Exclua a sessão quando terminar.

Solução de problemas

Problema O que verificar
A preparação falha Examine o evento de falha do ambiente e corrija o erro no pacote, no arquivo de entrada ou no comando de preparação antes de criar outra sessão.
Uma solicitação do sandbox é bloqueada Verifique network e todos os hosts acessados por redirecionamento.
Uma operação em um arquivo do sandbox em execução falha Confirme se o sandbox está com o status connected. Se ele tiver expirado, crie uma sessão e forneça novamente os arquivos de entrada.
Uma solicitação de consulta de status ou de listagem de arquivos retorna 5xx Tente novamente com intervalos cada vez maiores e defina um prazo para encerrar as tentativas. Guarde o ID da solicitação se o erro persistir.