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 de 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. De votre côté, vous lancez codex exec-server, l’exécuteur, dans votre environnement. À la demande du harnais, l’exécuteur lance 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 aux permissions restreintes. Il se connecte ensuite via WebSocket pour recevoir les commandes et renvoyer les résultats. Toutes les connexions sont sortantes. Si la connexion est interrompue, l’exécuteur se reconnecte.

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 ont accès aux mêmes fichiers, identifiants d’accès et autres ressources.

Pour activer le mode d’approbation automatique avec review: "auto_review", lancez l’exécuteur standard dans un conteneur qui prend en charge l’exécution en bac à sable et autorise Codex à créer un bac à sable. Ce mode applique un profil de permissions qui utilise workspace-write comme base et limite l’accès au réseau. Vérifiez les prérequis du mode d’approbation automatique avant de l’activer.

Créez le répertoire de travail et installez la CLI Codex 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 enregistrer l’environnement.
• wss://codex-cloud-environments.chatgpt.com pour recevoir les commandes et renvoyer les résultats.

Authentification

Utilisez OPENAI_API_KEY pour les requêtes de votre 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 du modèle. 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. La clé doit relever de la même organisation et du même projet que la session, et appartenir au compte utilisateur ou au compte de service propriétaire de la session. Réglez toutes les autres permissions sur Aucune.

Dans votre application ou votre service de provisionnement, attribuez à OPENAI_EXECUTOR_API_KEY la valeur de cette clé d’environnement. Transmettez cette valeur au bac à sable via CODEX_API_KEY, que lit codex exec-server. Conservez 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 opération de l’API. Veillez à ce qu’elle ne figure ni dans le code source, ni dans les images de conteneurs, ni dans 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

Enregistrez session.id avec l’état de la conversation dans votre application. Transmettez session.environment.id et session.environment.remote_url à l’exécuteur. Utilisez l’URL distante telle quelle, y compris lors d’une reconnexion. Pour utiliser un agent enregistré, consultez Configuration des agents.

Vous pouvez réutiliser l’image de votre environnement ainsi que les paramètres 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

Depuis votre application, ouvrez le flux d’événements de la session pour recevoir les événements de connexion. Exécutez ensuite la commande ci-dessous dans l’environnement après avoir défini CODEX_API_KEY comme indiqué plus haut. Remplacez les valeurs entre chevrons par celles que l’API a renvoyées pour l’environnement :

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

Laissez l’exécuteur en marche 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 indique 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é. Consultez l’erreur signalée par l’environnement et les journaux de l’exécuteur.

Continuez à suivre le flux pour connaître l’issue du tour et recevoir les données de 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 manipuler 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 gérer le provisionnement par webhooks, implémentez un gestionnaire en suivant le guide Cycle de vie du bac à sable et en utilisant le SDK ou l’API de votre fournisseur. Précisez qui est responsable du provisionnement et quelles règles s’appliquent au nettoyage des ressources.