Prepare sandboxes com antecedência

Com a preparação antecipada de ambientes, você pode criar um sandbox hospedado pela OpenAI, instalar pacotes, carregar arquivos e executar comandos de configuração antes de criar uma sessão de agente. Quando chegar uma tarefa, vincule o ambiente preparado a uma sessão e inicie o agente.

Prepare o ambiente com antecedência quando a baixa latência for um requisito essencial. Por exemplo, um aplicativo de relatórios pode preparar suas dependências de Python enquanto o usuário escolhe um conjunto de dados. Da mesma forma, um fluxo de desenvolvimento pode preparar o espaço de trabalho enquanto o usuário escreve uma solicitação. Antecipar a configuração pode reduzir o tempo de espera do usuário.

Como funciona

O ambiente é o espaço de trabalho onde o agente executa ferramentas. A sessão armazena a configuração e a conversa do agente. Você pode preparar o espaço de trabalho de forma independente e vinculá-lo a uma sessão quando precisar dela.

O processo tem três etapas:

Crie um ambiente. Forneça os pacotes, os arquivos e os comandos de configuração necessários para a tarefa.
Aguarde até que o ambiente esteja pronto. Consulte o ambiente até que o status seja ready ou use um webhook.
Inicie uma sessão. Informe o ID do ambiente ao criar a sessão.

Você também pode vincular o ambiente enquanto a configuração estiver em andamento. O agente só terá acesso ao espaço de trabalho quando a configuração terminar.

Preços

A preparação antecipada de um sandbox é gratuita, inclusive o uso do contêiner antes de vincular o sandbox a uma sessão. Sandboxes preparados com antecedência expiram após 5 minutos se não forem vinculados a uma sessão.

Depois que você vincula um sandbox preparado com antecedência a uma sessão, passam a valer os preços padrão de uso de contêineres.

Prepare um espaço de trabalho para gerar relatórios

Este exemplo instala o pandas e carrega um pequeno arquivo CSV antes de iniciar um agente. Em seguida, o agente usa o espaço de trabalho preparado para calcular o total.

Para seguir este guia, use uma destas versões do SDK ou uma versão posterior para a linguagem escolhida: 3.28.0 para Python, 7.32.0 para Node.js, 4.80.0 para Java ou 0.103.0 para Ruby.

1. Crie o ambiente

Envie a configuração do espaço de trabalho para POST /v1/agents/environments:

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import OpenAI from "openai";

const client = new OpenAI();
const environment = await client.beta.agents.environments.create({
  environment: {
    type: "openai_hosted",
    packages: { python: ["pandas==2.2.3"] },
    files: [
      {
        type: "inline",
        path: "/workspace/amounts.csv",
        data: "YW1vdW50CjEwCjIwCjMwCg==",
      },
    ],
    setup_commands: [
      {
        command: 'python -c "import pandas; print(pandas.__version__)"',
        cwd: "/workspace",
      },
    ],
  },
});
const environmentId = environment.id;
console.log(environmentId);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "packages": {"python": ["pandas==2.2.3"]},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/amounts.csv",
                "data": "YW1vdW50CjEwCjIwCjMwCg==",
            }
        ],
        "setup_commands": [
            {
                "command": 'python -c "import pandas; print(pandas.__version__)"',
                "cwd": "/workspace",
            }
        ],
    }
)
environment_id = environment.id
print(environment_id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35import com.openai.client.okhttp.OpenAIOkHttpClient;

import com.openai.models.beta.agents.HostedEnvironmentFileParam;
import com.openai.models.beta.agents.SetupCommandParam;
import com.openai.models.beta.agents.environments.EnvironmentCreateParams;

var client = OpenAIOkHttpClient.fromEnv();
var environment =
    client
        .beta()
        .agents()
        .environments()
        .create(
            EnvironmentCreateParams.builder()
                .environment(
                    EnvironmentCreateParams.Environment.builder()
                        .packages(
                            EnvironmentCreateParams.Environment.Packages.builder()
                                .addPython("pandas==2.2.3")
                                .build())
                        .addFile(
                            HostedEnvironmentFileParam.Inline.builder()
                                .path("/workspace/amounts.csv")
                                .data("YW1vdW50CjEwCjIwCjMwCg==")
                                .build())
                        .addSetupCommand(
                            SetupCommandParam.builder()
                                .command(
                                    "python -c \"import pandas; print(pandas.__version__)\"")
                                .cwd("/workspace")
                                .build())
                        .build())
                .build());
String environmentId = environment.id();
System.out.println(environmentId);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"

client = OpenAI::Client.new
environment = client.beta.agents.environments.create(
  environment: {
    type: :openai_hosted,
    packages: { python: ["pandas==2.2.3"] },
    files: [
      {
        type: :inline,
        path: "/workspace/amounts.csv",
        data: "YW1vdW50CjEwCjIwCjMwCg=="
      }
    ],
    setup_commands: [
      {
        command: 'python -c "import pandas; print(pandas.__version__)"',
        cwd: "/workspace"
      }
    ]
  }
)
environment_id = environment.id
puts environment_id

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25curl https://api.openai.com/v1/agents/environments \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": {
      "type": "openai_hosted",
      "packages": {
        "python": ["pandas==2.2.3"]
      },
      "files": [
        {
          "type": "inline",
          "path": "/workspace/amounts.csv",
          "data": "YW1vdW50CjEwCjIwCjMwCg=="
        }
      ],
      "setup_commands": [
        {
          "command": "python -c \"import pandas; print(pandas.__version__)\"",
          "cwd": "/workspace"
        }
      ]
    }
  }'

Os exemplos com SDK salvam o id retornado para as próximas etapas. Se estiver usando cURL, salve esse valor em uma variável do shell:

ENVIRONMENT_ID="ccarenv_REPLACE_WITH_RETURNED_ID"

Defina environment.type como openai_hosted ao criar um ambiente independente.

2. Verifique se o ambiente está pronto

Consulte o ambiente usando o ID salvo na etapa 1:

Python

const current = await client.beta.agents.environments.retrieve(environmentId);
console.log(current.status);

current = client.beta.agents.environments.retrieve(environment_id)
print(current.status)

current, err := client.Beta.Agents.Environments.Get(context.Background(), environmentID)
if err != nil {
	panic(err)
}
fmt.Println(current.Status)

var current = client.beta().agents().environments().retrieve(environmentId);
System.out.println(current.status());

current = client.beta.agents.environments.retrieve(environment_id)
puts current.status

curl \
  "https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Enquanto a configuração estiver em andamento, o status será pending. Quando o status mudar para ready, o espaço de trabalho estará pronto e poderá ser vinculado a uma sessão.

O fato de o ambiente estar pronto não significa que haja um agente conectado. O ambiente pode ter o status ready antes mesmo de existir uma sessão.

Para evitar consultas repetidas, configure um endpoint de webhook do projeto para receber os seguintes eventos:

agent.environment.ready
agent.environment.failed

Se vincular o ambiente antes do fim da configuração, acompanhe os eventos agent.session.environment.ready ou agent.session.environment.failed da sessão para verificar o status da configuração. Use o fluxo de resposta recebido ao criar a sessão com "stream": true ou abra uma conexão com GET /v1/agents/sessions/{session_id}/events. Consulte Eventos da sessão para saber mais sobre a transmissão de eventos.

3. Vincule o ambiente e execute uma tarefa

Crie uma sessão informando o ID do ambiente que você salvou, o agente e a primeira entrada para ele:

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14const stream = await client.beta.agents.sessions.create({
  agent: { model: "gpt-6-astra" },
  environment: { type: "openai_hosted", environment_id: environmentId },
  input:
    "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
  stream: true,
});
try {
  for await (const event of stream) {
    console.log(event);
  }
} finally {
  stream.controller.abort();
}

1
2
3
4
5
6
7
8
9stream = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={"type": "openai_hosted", "environment_id": environment_id},
    input="Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
    stream=True,
)
with stream:
    for event in stream:
        print(event.model_dump_json())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import com.openai.models.beta.agents.EnvironmentParam;

import com.openai.models.beta.agents.sessions.SessionCreateParams;

var params =
    SessionCreateParams.builder()
        .agent(SessionCreateParams.Agent.builder().model("gpt-6-astra").build())
        .environment(
            EnvironmentParam.OpenAIHosted.builder().environmentId(environmentId).build())
        .input(
            "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.")
        .build();
try (var stream = client.beta().agents().sessions().createStreaming(params)) {
  stream.stream().forEach(System.out::println);
}

1
2
3
4
5
6
7
8
9
10
11
12
13stream = client.beta.agents.sessions.create_streaming(
  agent: { model: "gpt-6-astra" },
  environment: {
    type: :openai_hosted,
    environment_id: environment_id
  },
  input: "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total."
)
begin
  stream.each { |event| puts event.to_json }
ensure
  stream.close
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "agent": {
    "model": "gpt-6-astra"
  },
  "environment": {
    "type": "openai_hosted",
    "environment_id": "$ENVIRONMENT_ID"
  },
  "input": "Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
  "stream": true
}
EOF

Erros comuns

Use a mensagem de erro e o status atual do ambiente para decidir como resolver o problema.

Um ambiente compartilhado recém-criado aceita até 128 sessões vinculadas. Você pode reutilizá-lo em várias sessões, que compartilharão o mesmo espaço de trabalho. Ambientes mais antigos ainda podem ter um ciclo de vida limitado a uma única sessão.

Erro ou sintoma	Como resolver
Tentativa de vincular um ambiente expirado.	Crie outro ambiente e use o novo ID. Ambientes não utilizados expiram após 5 minutos. Tentar novamente com o ID de um ambiente expirado não restaura o espaço de trabalho.
`404`: ambiente não encontrado.	Verifique o ID do ambiente e use a mesma organização, o mesmo projeto e a mesma identidade usados na solicitação de criação. Se o ambiente tiver expirado ou não estiver mais disponível, crie outro.
`409`: o ambiente compartilhado atingiu o limite de sessões.	Um ambiente compartilhado aceita até 128 sessões vinculadas. Reutilize uma sessão existente ou crie outro ambiente para as sessões adicionais.

Use um modelo de ambiente salvo

Se várias tarefas exigirem os mesmos pacotes e a mesma configuração, salve a configuração do ambiente como modelo e informe o ID do modelo ao criar cada ambiente com antecedência:

Python

1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";

const client = new OpenAI();
const environment = await client.beta.agents.environments.create({
  environment: {
    type: "openai_hosted",
    environment_template_id: "envtmpl_REPLACE_WITH_TEMPLATE_ID",
  },
});
console.log(environment.id);

1
2
3
4
5
6
7
8
9
10from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "environment_template_id": "envtmpl_REPLACE_WITH_TEMPLATE_ID",
    }
)
print(environment.id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.environments.EnvironmentCreateParams;

var client = OpenAIOkHttpClient.fromEnv();
var environment =
    client
        .beta()
        .agents()
        .environments()
        .create(
            EnvironmentCreateParams.builder()
                .environment(
                    EnvironmentCreateParams.Environment.builder()
                        .environmentTemplateId("envtmpl_REPLACE_WITH_TEMPLATE_ID")
                        .build())
                .build());
System.out.println(environment.id());

1
2
3
4
5
6
7
8
9
10require "openai"

client = OpenAI::Client.new
environment = client.beta.agents.environments.create(
  environment: {
    type: :openai_hosted,
    environment_template_id: "envtmpl_REPLACE_WITH_TEMPLATE_ID"
  }
)
puts environment.id

1
2
3
4
5
6
7
8
9
10curl https://api.openai.com/v1/agents/environments \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": {
    "type": "openai_hosted",
    "environment_template_id": "envtmpl_REPLACE_WITH_TEMPLATE_ID"
  }
}'

Prepare um sandbox com antecedência para o Uso do computador

Para tarefas no navegador, prepare o navegador gerenciado e a tela virtual antes de iniciar a sessão. Inclua desktop.enabled ao criar o ambiente:

Python

1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";

const client = new OpenAI();
const environment = await client.beta.agents.environments.create({
  environment: {
    type: "openai_hosted",
    desktop: { enabled: true },
  },
});
console.log(environment.id);

1
2
3
4
5
6
7
8
9
10from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "desktop": {"enabled": True},
    }
)
print(environment.id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.environments.EnvironmentCreateParams;

var client = OpenAIOkHttpClient.fromEnv();
var environment =
    client
        .beta()
        .agents()
        .environments()
        .create(
            EnvironmentCreateParams.builder()
                .environment(
                    EnvironmentCreateParams.Environment.builder()
                        .desktop(
                            EnvironmentCreateParams.Environment.Desktop.builder()
                                .enabled(true)
                                .build())
                        .build())
                .build());
System.out.println(environment.id());

1
2
3
4
5
6
7
8
9
10require "openai"

client = OpenAI::Client.new
environment = client.beta.agents.environments.create(
  environment: {
    type: :openai_hosted,
    desktop: { enabled: true }
  }
)
puts environment.id

1
2
3
4
5
6
7
8
9
10
11
12curl https://api.openai.com/v1/agents/environments \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": {
    "type": "openai_hosted",
    "desktop": {
      "enabled": true
    }
  }
}'

Ao criar uma sessão, use o ID salvo para vincular o ambiente e disponibilize a ferramenta computer_use para o agente. A sessão usa a configuração da área de trabalho salva no ambiente. Consulte Uso do computador para saber como configurar a ferramenta e aprovar origens no navegador.

Liste seus ambientes

Use GET /v1/agents/environments para encontrar os ambientes ativos criados com a sua identidade na organização e no projeto atuais:

Python

1
2
3
4
5const environments = await client.beta.agents.environments.list({
  limit: 20,
  order: "desc",
});
console.log(environments.data);

1
2
3environments = client.beta.agents.environments.list(limit=20, order="desc")
for item in environments.data:
    print(item.model_dump_json())

1
2
3
4
5
6
7
8
9
10
11
12
13import com.openai.models.beta.agents.environments.EnvironmentListParams;

var environments =
    client
        .beta()
        .agents()
        .environments()
        .list(
            EnvironmentListParams.builder()
                .limit(20L)
                .order(EnvironmentListParams.Order.DESC)
                .build());
System.out.println(environments.items());

1
2
3
4
5environments = client.beta.agents.environments.list(
  limit: 20,
  order: :desc
)
(environments.data || []).each { |item| puts item.to_json }

1
2
3
4curl \
  "https://api.openai.com/v1/agents/environments?limit=20&order=desc" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

A lista inclui ambientes tanto antes quanto depois de serem vinculados a uma sessão, com os status pending, ready, connected, disconnected ou suspended. Ela exclui ambientes que falharam, expiraram, foram excluídos ou encerrados. Um ambiente que aparece na lista já pode estar vinculado a uma ou mais sessões.

Por padrão, os resultados aparecem do mais recente para o mais antigo. Se has_more for verdadeiro, defina after com o valor de last_id da resposta anterior para buscar a próxima página. limit aceita valores de 1 a 100 e tem valor padrão 20. order aceita asc ou desc.

Duração e reutilização

Várias sessões podem compartilhar um ambiente. Informe o mesmo environment_id ao criar cada sessão. As sessões compartilham o espaço de trabalho em execução, incluindo arquivos, processos, pacotes instalados e a configuração do ambiente. Cada sessão mantém seu próprio histórico de conversa. As alterações no espaço de trabalho ficam visíveis para as outras sessões vinculadas. Por isso, crie ambientes separados quando as tarefas exigirem espaços de trabalho distintos. Um ambiente compartilhado aceita até 128 sessões vinculadas. Esse comportamento se aplica aos ambientes independentes recém-criados. Os ambientes mais antigos mantêm seu ciclo de vida original.
Ambientes não utilizados expiram. Um ambiente que não for vinculado a uma sessão expira após 5 minutos. Prepare o ambiente perto do horário previsto para o início da tarefa.
Use a mesma identidade que criou o ambiente. Para consultar, listar ou vincular ambientes, use a mesma organização, o mesmo projeto e a mesma identidade autenticada usados na criação. Chaves de API diferentes da mesma identidade podem acessar os mesmos ambientes, inclusive após a rotação das chaves.
Ambientes compartilhados expiram por inatividade. O prazo de 20 minutos de inatividade começa quando você vincula a primeira sessão. Qualquer atividade em uma sessão vinculada ou por meio da API de arquivos do ambiente prorroga esse prazo. Enquanto houver trabalho pendente ou turnos em andamento, o ambiente não expira por inatividade. Quando você exclui uma sessão, ela é removida do ambiente e o espaço de trabalho compartilhado é preservado. Mesmo após a exclusão da última sessão, o ambiente continua disponível para vincular outras sessões até o fim do prazo de inatividade. A API não oferece um endpoint específico para excluir um ambiente.

Repita a solicitação de criação com segurança

Ao criar um ambiente, você pode enviar o cabeçalho Idempotency-Key. Se a solicitação exceder o tempo limite ou a resposta se perder, tente novamente com a mesma chave e o mesmo corpo da solicitação para evitar a criação de outro ambiente.

Enquanto o ambiente original estiver disponível, uma nova tentativa concluída retornará o ID e o estado atual desse ambiente. Uma solicitação com uma chave ainda retida pode retornar 409 se a criação ainda estiver em andamento, se o resultado da criação for incerto, se o ambiente não estiver mais disponível ou se os parâmetros forem diferentes. Nenhum desses conflitos cria um ambiente substituto. A API retém as chaves por 24 horas. Após esse prazo, repetir a solicitação com a mesma chave pode criar outro ambiente. Use uma nova chave quando a intenção for criar um novo ambiente.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Provedores de nuvem

Recursos

APIs legadas

Escolha um modelo

Texto e código

Como escrever prompts

Raciocínio

Imagens

Tempo real e áudio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Busca e recuperação de informações

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Coloque em produção

Desempenho e qualidade

Avaliação

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Planejar

Desenvolver

Testar e publicar

Especificações de conversão

Guias

Recursos

Identidade

Uso do plano do ChatGPT

Guias

Envio de arquivos

API

Mensuração

API para anunciantes

Referência da API

Primeiros passos

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Sites

dots

ChatGPT Space

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Ampliar os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Ampliar recursos e automatizar tarefas

Ambientes

Codex Cloud

Desenvolver com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

Configuração de recursos

Identidade e acesso