Bacs à sable autohébergés

Connectez votre propre environnement si vous souhaitez mieux contrôler l’environnement de l’agent ou utiliser des ressources de calcul auxquelles vous faites confiance. Il peut s’agir d’un ordinateur portable, d’un conteneur ou d’un bac à sable distant. Pour qu’OpenAI provisionne l’environnement, utilisez un bac à sable hébergé par OpenAI.

Fonctionnement de la connexion

OpenAI exécute le harnais de l’agent. Vous exécutez codex exec-server, l’exécuteur, dans votre environnement. À la demande du harnais, l’exécuteur exécute des commandes shell, lit et écrit des fichiers et utilise des serveurs MCP locaux.

L’exécuteur s’enregistre auprès de l’API à l’aide d’un identifiant d’environnement et d’une clé API à permissions restreintes. Il se connecte ensuite via WebSocket pour recevoir des commandes et renvoyer les résultats. Toutes les connexions sont sortantes. L’exécuteur se reconnecte si la connexion est interrompue.

Préparez votre environnement

Préparez les fichiers et les dépendances dont votre agent a besoin. Isolez les environnements par utilisateur ou par charge de travail. Les agents qui partagent un environnement peuvent accéder aux mêmes fichiers, identifiants d’accès et autres ressources.

Créez le répertoire de travail et installez Codex CLI dans l’environnement. Cet exemple utilise /workspace :

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

Accès réseau

Autorisez les connexions sortantes vers les hôtes suivants :

• https://api.openai.com pour l’enregistrement de l’environnement.
• wss://codex-cloud-environments.chatgpt.com pour les commandes et les résultats.

Authentification

Utilisez OPENAI_API_KEY pour les requêtes de l’application. Accordez à cette clé les permissions api.agents.read et api.agents.write pour les opérations sur les sessions, ainsi que api.responses.write pour l’inférence des modèles. Ajoutez api.vaults.read et api.vaults.write si votre application gère des coffres-forts.

Créez une clé d’environnement distincte dans l’onglet Agents du tableau de bord de la plateforme. Elle doit appartenir à la même organisation, au même projet et au même utilisateur ou compte de service que la session. Définissez toutes les autres permissions sur Aucune.

Dans votre application ou votre service de provisionnement, attribuez cette clé d’environnement à OPENAI_EXECUTOR_API_KEY. Transmettez sa valeur au bac à sable via CODEX_API_KEY, que codex exec-server lit. Gardez la clé OPENAI_API_KEY de votre application en dehors du bac à sable.

Le code généré par l’agent peut lire la clé d’environnement, mais celle-ci permet uniquement de connecter des environnements. Elle ne peut autoriser aucune autre action de l’API. Ne l’incluez pas dans le code source, les images de conteneurs ou les journaux. Renouvelez-la ou révoquez-la si nécessaire.

Créez une session

Exécutez cet exemple dans votre application, en dehors de l’environnement. Si vous disposez déjà d’une session autohébergée, réutilisez-la.

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

Stockez session.id avec l’état de la conversation de votre application. Transmettez session.environment.id et session.environment.remote_url à l’exécuteur. Utilisez l’URL distante sans la modifier, y compris lors des reconnexions. Consultez Configuration des agents pour utiliser un agent enregistré.

Vous pouvez réutiliser votre image d’environnement, workspace_directory et capability_directories dans plusieurs sessions. Chaque session possède son propre identifiant d’environnement et nécessite son propre exécuteur. Les modèles d’environnement de l’API s’appliquent uniquement aux environnements hébergés par OpenAI.

Démarrez l’exécuteur

Ouvrez le flux d’événements de la session depuis votre application pour recevoir les événements de connexion. Exécutez ensuite cette commande dans l’environnement, avec la clé d’environnement définie dans CODEX_API_KEY comme indiqué ci-dessus. Remplacez les valeurs fictives par les valeurs de l’environnement renvoyées par l’API :

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

Laissez l’exécuteur en cours d’exécution pendant que l’agent travaille.

Envoyez des tâches et surveillez la connexion

Envoyez des données d’entrée depuis votre application en gardant le flux d’événements ouvert. Pour commencer à travailler, l’agent a besoin à la fois d’un environnement connecté et de données d’entrée fournies par l’utilisateur.

Le flux signale les états de connexion suivants :

• agent.session.environment.pending : la session attend que l’exécuteur se connecte.
• agent.session.environment.connected : l’environnement est prêt.
• agent.session.environment.failed : la connexion a échoué. Vérifiez l’erreur de l’environnement et les journaux de l’exécuteur.

Continuez à suivre le flux pour connaître l’issue du tour et recevoir sa sortie. Consultez Cycle de vie de l’environnement pour gérer le démarrage, la reconnexion et l’arrêt depuis votre application ou via des webhooks.

Fournisseurs de bacs à sable

Choisissez un fournisseur de bacs à sable pour exécuter du code et travailler avec des fichiers. Consultez Cycle de vie du bac à sable pour comparer le provisionnement géré par l’application et celui géré par webhooks.

Pour le provisionnement géré par webhooks, implémentez un gestionnaire en vous appuyant sur Cycle de vie du bac à sable et sur le SDK ou l’API de votre fournisseur. Définissez clairement qui est responsable du provisionnement et les règles de nettoyage des ressources.