Sandboxes hospedados em infraestrutura própria

Conecte seu próprio ambiente quando quiser ter mais controle sobre o ambiente do agente ou usar recursos computacionais em que você confia. O ambiente pode ser um notebook, um contêiner ou um sandbox remoto. Para que a OpenAI provisione o ambiente, use um sandbox hospedado pela OpenAI.

Como a conexão funciona

A OpenAI executa o harness do agente. Você executa codex exec-server, o executor, dentro do seu ambiente. Ele executa comandos de shell, lê e grava arquivos e usa servidores MCP locais a pedido do harness.

O executor se registra na API usando um ID de ambiente e uma chave de API restrita. Em seguida, conecta-se via WebSocket para receber comandos e retornar resultados. Todas as conexões são de saída. O executor se reconecta se a conexão cair.

Prepare seu ambiente

Prepare os arquivos e as dependências de que seu agente precisa. Isole os ambientes por usuário ou carga de trabalho. Agentes que compartilham um ambiente podem acessar os mesmos arquivos, credenciais e outros recursos.

Crie o diretório de trabalho e instale o Codex CLI dentro do ambiente. Este exemplo usa /workspace:

mkdir -p /workspace
npm install -g @openai/codex@alpha

Acesso à rede

Permita conexões de saída para estes hosts:

• https://api.openai.com para o registro do ambiente.
• wss://codex-cloud-environments.chatgpt.com para comandos e resultados.

Autenticação

Use OPENAI_API_KEY para as requisições do aplicativo. Conceda a essa chave as permissões api.agents.read e api.agents.write para operações de sessão, além de api.responses.write para inferência de modelos. Adicione api.vaults.read e api.vaults.write se o aplicativo gerenciar cofres.

Crie uma chave de ambiente separada na aba Agentes do painel da plataforma. Ela deve pertencer à mesma organização, ao mesmo projeto e ao mesmo usuário ou conta de serviço que possui a sessão. Defina todas as outras permissões como Nenhuma.

Defina OPENAI_EXECUTOR_API_KEY com o valor dessa chave de ambiente no aplicativo ou serviço de provisionamento. Passe esse valor para o sandbox como CODEX_API_KEY, que é lido por codex exec-server. Mantenha a chave OPENAI_API_KEY do aplicativo fora do sandbox.

O código gerado pelo agente pode ler a chave de ambiente, mas ela permite apenas conectar ambientes. Ela não pode autorizar nenhuma outra ação da API. Mantenha essa chave fora do código-fonte, das imagens de contêiner e dos logs. Faça a rotação da chave ou revogue-a quando necessário.

Crie uma sessão

Execute este exemplo na sua aplicação, fora do ambiente. Se você já tiver uma sessão hospedada em infraestrutura própria, reutilize-a.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "You are a helpful coding assistant. Write clean code and verify that it works.",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

console.log(session);

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

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "You are a helpful coding assistant. Write clean code and verify that it works.",
    },
    environment={"type": "self_hosted", "workspace_directory": "/workspace"},
)
print(session.to_json())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model:        openai.String("gpt-6-astra"),
			Instructions: openai.String("You are a helpful coding assistant. Write clean code and verify that it works."),
		},
		Environment: openai.EnvironmentParamUnion{
			OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace"},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

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
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "You are a helpful coding assistant. Write clean code and verify"
                                + " that it works.")
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .build())
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "You are a helpful coding assistant. Write clean code and verify that it works."
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace"
  }
)
puts result

Armazene session.id junto com o estado da conversa da sua aplicação. Passe session.environment.id e session.environment.remote_url para o executor. Use a URL remota sem alterações, inclusive ao se reconectar. Consulte Configuração de Agentes para usar um agente armazenado.

Você pode reutilizar a imagem do ambiente, workspace_directory e capability_directories entre sessões. Cada sessão tem seu próprio ID de ambiente e precisa de seu próprio executor. Os modelos de ambiente da API se aplicam apenas a ambientes hospedados pela OpenAI.

Inicie o executor

Abra o fluxo de eventos da sessão a partir do aplicativo para receber eventos de conexão. Em seguida, execute este comando dentro do ambiente com a chave de ambiente configurada como CODEX_API_KEY, conforme descrito acima. Substitua os placeholders pelos valores de ambiente retornados pela API:

123codex exec-server \
  --remote "<session.environment.remote_url>" \
  --environment-id "<session.environment.id>"

Deixe o executor em execução enquanto o agente trabalha.

Envie tarefas e monitore a conexão

Envie entradas a partir da sua aplicação enquanto o fluxo de eventos permanece aberto. O agente precisa tanto de um ambiente conectado quanto de uma entrada do usuário para começar a trabalhar.

O fluxo informa estes estados de conexão:

• agent.session.environment.pending: A sessão está aguardando a conexão do executor.
• agent.session.environment.connected: O ambiente está pronto.
• agent.session.environment.failed: A conexão falhou. Verifique o erro do ambiente e os logs do executor.

Continue acompanhando o fluxo para obter o resultado e a saída do turno. Consulte Ciclo de vida do ambiente para gerenciar a inicialização, a reconexão e o encerramento a partir da sua aplicação ou por meio de webhooks.

Provedores de sandbox

Escolha um provedor de sandbox para executar código e trabalhar com arquivos. Consulte Ciclo de vida do sandbox para comparar o provisionamento gerenciado pela aplicação com o gerenciado por webhooks.

Para o provisionamento gerenciado por webhooks, implemente um manipulador usando o guia Ciclo de vida do sandbox e o SDK ou a API do seu provedor. Deixe explícitas a responsabilidade pelo provisionamento e as políticas de limpeza.