Selbst gehostete Sandboxen

Verbinde deine eigene Umgebung, wenn du mehr Kontrolle über die Umgebung des Agenten haben oder Rechenressourcen nutzen möchtest, denen du vertraust. Die Umgebung kann ein Laptop, ein Container oder eine Remote-Sandbox sein. Wenn OpenAI die Umgebung bereitstellen soll, verwende eine von OpenAI gehostete Sandbox.

So funktioniert die Verbindung

OpenAI betreibt den Agenten-Harness. Du führst codex exec-server, den Executor, in deiner Umgebung aus. Er führt auf Anforderung des Harness Shell-Befehle aus, liest und schreibt Dateien und nutzt lokale MCP-Server.

Der Executor registriert sich mit einer Umgebungs-ID und einem eingeschränkten API-Schlüssel bei der API. Anschließend stellt er eine WebSocket-Verbindung her, um Befehle zu empfangen und Ergebnisse zurückzugeben. Alle Verbindungen sind ausgehend. Bei einem Verbindungsabbruch stellt der Executor die Verbindung wieder her.

Deine Umgebung vorbereiten

Bereite die Dateien und Abhängigkeiten vor, die dein Agent benötigt. Isoliere Umgebungen nach Nutzenden oder Workloads. Agenten, die sich eine Umgebung teilen, können auf dieselben Dateien, Zugangsdaten und anderen Ressourcen zugreifen.

Erstelle das Arbeitsverzeichnis und installiere die Codex CLI in der Umgebung. In diesem Beispiel wird /workspace verwendet:

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

Netzwerkzugriff

Erlaube ausgehende Verbindungen zu diesen Hosts:

• https://api.openai.com zur Registrierung der Umgebung.
• wss://codex-cloud-environments.chatgpt.com für Befehle und Ergebnisse.

Authentifizierung

Verwende OPENAI_API_KEY für Anfragen deiner Anwendung. Erteile diesem Schlüssel die Berechtigungen api.agents.read und api.agents.write für Sitzungsoperationen sowie api.responses.write für die Modellinferenz. Füge api.vaults.read und api.vaults.write hinzu, wenn deine Anwendung Tresore verwaltet.

Erstelle im Plattform-Dashboard auf dem Tab „Agenten“ einen separaten Umgebungsschlüssel. Er muss derselben Organisation, demselben Projekt und demselben Benutzer- oder Dienstkonto zugeordnet sein wie die Sitzung. Setze alle anderen Berechtigungen auf Keine.

Setze OPENAI_EXECUTOR_API_KEY in deiner Anwendung oder deinem Bereitstellungsdienst auf diesen Umgebungsschlüssel. Übergib seinen Wert als CODEX_API_KEY an die Sandbox. Dieser Wert wird von codex exec-server gelesen. Bewahre den OPENAI_API_KEY deiner Anwendung außerhalb der Sandbox auf.

Von Agenten generierter Code kann den Umgebungsschlüssel lesen. Der Schlüssel erlaubt jedoch nur das Verbinden von Umgebungen. Er kann keine anderen API-Aktionen autorisieren. Halte ihn aus Quellcode, Container-Images und Logs heraus. Ersetze ihn bei Bedarf durch einen neuen Schlüssel oder widerrufe ihn.

Eine Sitzung erstellen

Führe dieses Beispiel in deiner Anwendung außerhalb der Umgebung aus. Wenn du bereits eine selbst gehostete Sitzung hast, verwende sie erneut.

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

Speichere session.id zusammen mit dem Gesprächszustand deiner Anwendung. Übergib session.environment.id und session.environment.remote_url an den Executor. Verwende die Remote-URL unverändert, auch beim Wiederherstellen der Verbindung. Unter Agenten konfigurieren erfährst du, wie du einen gespeicherten Agenten verwendest.

Du kannst das Image deiner Umgebung, workspace_directory und capability_directories für mehrere Sitzungen wiederverwenden. Jede Sitzung hat eine eigene Umgebungs-ID und benötigt einen eigenen Executor. Die Umgebungsvorlagen der API gelten nur für von OpenAI gehostete Umgebungen.

Den Executor starten

Öffne in deiner Anwendung den Ereignisstream der Sitzung, um Verbindungsereignisse zu empfangen. Führe anschließend diesen Befehl innerhalb der Umgebung aus. Dabei muss der Umgebungsschlüssel wie oben beschrieben als CODEX_API_KEY konfiguriert sein. Ersetze die Platzhalter durch die von der API zurückgegebenen Umgebungswerte:

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

Lass den Executor laufen, während der Agent arbeitet.

Aufgaben senden und die Verbindung überwachen

Sende Eingaben aus deiner Anwendung, während der Ereignisstream geöffnet bleibt. Der Agent benötigt sowohl eine verbundene Umgebung als auch eine Nutzereingabe, um mit der Arbeit zu beginnen.

Der Stream meldet diese Verbindungszustände:

• agent.session.environment.pending: Die Sitzung wartet darauf, dass der Executor eine Verbindung herstellt.
• agent.session.environment.connected: Die Umgebung ist bereit.
• agent.session.environment.failed: Die Verbindung ist fehlgeschlagen. Prüfe den Umgebungsfehler und die Protokolle des Executors.

Verfolge den Stream weiter, um das Ergebnis und die Ausgabe des Durchlaufs zu erhalten. Unter Lebenszyklus der Umgebung erfährst du, wie du Start, Wiederverbindung und Herunterfahren über deine Anwendung oder Webhooks verwaltest.

Sandbox-Anbieter

Wähle einen Sandbox-Anbieter, um Code auszuführen und mit Dateien zu arbeiten. Unter Sandbox-Lebenszyklus findest du einen Vergleich zwischen der Bereitstellung über die Anwendung und über Webhooks.

Implementiere für die Bereitstellung über Webhooks einen Handler mithilfe der Anleitung unter Sandbox-Lebenszyklus und des SDK oder der API deines Anbieters. Lege die Zuständigkeit für die Bereitstellung und die Regeln für die Bereinigung ausdrücklich fest.