Préparation des bacs à sable en amont

Vous pouvez préparer un environnement à l’avance en créant un bac à sable hébergé par OpenAI, en y installant des paquets, en y chargeant des fichiers et en y exécutant des commandes de configuration avant de créer une session d’agent. Lorsqu’une tâche arrive, rattachez l’environnement préparé à une session et démarrez l’agent.

Préparez l’environnement à l’avance lorsqu’une faible latence est indispensable. Par exemple, une application de génération de rapports peut préparer ses dépendances Python pendant que l’utilisateur choisit un jeu de données. De même, un workflow de développement peut préparer son espace de travail pendant que l’utilisateur rédige sa demande. En lançant la configuration plus tôt, vous pouvez réduire le temps d’attente de l’utilisateur.

Fonctionnement

L’environnement est l’espace de travail dans lequel l’agent exécute ses outils. La session contient la configuration de l’agent et la conversation. Vous pouvez préparer l’espace de travail indépendamment, puis le rattacher à une session au moment où vous en avez besoin.

Le workflow comporte trois étapes.

Créez un environnement. Fournissez les paquets, les fichiers et les commandes de configuration nécessaires à votre tâche.
Attendez que l’environnement soit prêt. Interrogez l’environnement jusqu’à ce que son état passe à ready, ou utilisez un webhook.
Démarrez une session. Fournissez l’ID de l’environnement lors de la création de la session.

Vous pouvez aussi rattacher un environnement pendant sa configuration. L’agent pourra accéder à l’espace de travail une fois la configuration terminée.

Tarification

La préparation d’un bac à sable est gratuite, y compris l’utilisation du conteneur avant son rattachement. Un bac à sable préparé à l’avance expire au bout de 5 minutes s’il n’est rattaché à aucune session.

Une fois le bac à sable rattaché à une session, les tarifs standard des conteneurs s’appliquent.

Préparez un espace de travail pour générer un rapport

Cet exemple installe pandas et charge un petit fichier CSV avant de démarrer un agent. L’agent utilise ensuite l’espace de travail préparé pour calculer le total.

Pour suivre ce guide, utilisez au minimum la version 3.28.0 du SDK Python, 7.32.0 du SDK Node.js, 4.80.0 du SDK Java ou 0.103.0 du SDK Ruby, selon le langage choisi.

1. Créez l’environnement

Envoyez la configuration de l’espace de travail à 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"
        }
      ]
    }
  }'

Les exemples utilisant les SDK enregistrent la valeur du champ id renvoyé pour les étapes suivantes. Si vous utilisez cURL, enregistrez cette valeur dans une variable du shell.

ENVIRONMENT_ID="ccarenv_REPLACE_WITH_RETURNED_ID"

Définissez environment.type sur openai_hosted lorsque vous créez un environnement autonome.

2. Vérifiez que l’environnement est prêt

Récupérez l’environnement à l’aide de l’ID enregistré à l’étape 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"

Pendant la configuration, l’état de l’environnement est pending. Lorsqu’il passe à ready, l’espace de travail est prêt et peut être rattaché à une session.

Un environnement prêt n’a pas nécessairement d’agent connecté. Il peut atteindre l’état ready avant même la création d’une session.

Pour éviter d’interroger régulièrement l’environnement, abonnez un point de terminaison de webhook de votre projet aux événements suivants :

agent.environment.ready
agent.environment.failed

Si vous rattachez l’environnement avant la fin de la configuration, suivez les événements de session agent.session.environment.ready ou agent.session.environment.failed pour connaître l’état de la configuration. Utilisez le flux de réponse obtenu en créant la session avec "stream": true, ou ouvrez un flux via GET /v1/agents/sessions/{session_id}/events. Pour en savoir plus sur la réception des événements en continu, consultez la page Événements de session.

3. Rattachez l’environnement et exécutez une tâche

Créez une session en fournissant l’ID d’environnement enregistré, un agent et les premières données à lui transmettre.

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

Erreurs courantes

Consultez le message d’erreur et l’état actuel de l’environnement pour déterminer la marche à suivre.

Un environnement partagé nouvellement créé peut accueillir jusqu’à 128 sessions rattachées. Vous pouvez réutiliser cet environnement pour plusieurs sessions, qui partagent alors le même espace de travail. Les environnements plus anciens peuvent encore avoir un cycle de vie limité à une seule session.

Erreur ou symptôme	Solution
Tentative de rattachement d’un environnement expiré.	Créez un environnement et utilisez son nouvel ID. Les environnements inutilisés expirent au bout de 5 minutes. Une nouvelle tentative avec un ID expiré ne restaure pas l’espace de travail.
`404` : environnement introuvable.	Vérifiez l’ID de l’environnement et utilisez la même organisation, le même projet et la même identité que pour la requête de création. Si l’environnement a expiré ou n’est plus disponible, créez-en un autre.
`409` : l’environnement partagé a atteint sa limite de sessions.	Un environnement partagé peut accueillir jusqu’à 128 sessions rattachées. Réutilisez une session existante ou créez un autre environnement pour les sessions supplémentaires.

Utilisez un modèle d’environnement enregistré

Si plusieurs tâches nécessitent les mêmes paquets et la même configuration, enregistrez la configuration de l’environnement comme modèle, puis fournissez l’ID du modèle à chaque création d’un environnement préparé à l’avance.

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"
  }
}'

Préparez un bac à sable pour l’utilisation de l’ordinateur

Pour les tâches à effectuer dans un navigateur, préparez le navigateur géré et l’affichage virtuel avant le démarrage de la session. Incluez desktop.enabled lors de la création de l’environnement.

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
    }
  }
}'

Lors de la création de la session, utilisez l’ID enregistré pour rattacher l’environnement et donnez à l’agent accès à l’outil computer_use. La session utilise la configuration de bureau enregistrée dans l’environnement. Pour configurer l’outil et approuver les origines web dans le navigateur, consultez la page Utilisation de l’ordinateur.

Listez vos environnements

Utilisez GET /v1/agents/environments pour trouver les environnements actifs que vous avez créés avec votre identité actuelle dans l’organisation et le projet en cours.

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"

La liste comprend les environnements avant et après leur rattachement à une session. Leur état peut être pending, ready, connected, disconnected ou suspended. La liste exclut les environnements en échec, expirés, supprimés ou arrêtés définitivement. Un environnement figurant dans la liste peut déjà être rattaché à une ou plusieurs sessions.

Par défaut, les résultats sont classés du plus récent au plus ancien. Si has_more vaut vrai, attribuez à after la valeur de last_id renvoyée dans la réponse précédente pour récupérer la page suivante. limit accepte les valeurs de 1 à 100 et vaut 20 par défaut. order accepte asc ou desc.

Durée de vie et réutilisation

Plusieurs sessions peuvent partager un même environnement. Fournissez le même environment_id à la création de chaque session. Les sessions partagent l’espace de travail en cours d’exécution, y compris les fichiers, les processus, les paquets installés et la configuration de l’environnement. Chaque session conserve son propre historique de conversation. Les modifications de l’espace de travail sont visibles dans les autres sessions rattachées. Créez donc des environnements distincts si vos tâches nécessitent des espaces de travail séparés. Un environnement partagé peut accueillir jusqu’à 128 sessions rattachées. Ce fonctionnement s’applique aux environnements autonomes nouvellement créés. Les environnements plus anciens conservent leur cycle de vie initial.
Les environnements inutilisés expirent. Un environnement qui reste sans session rattachée expire au bout de 5 minutes. Préparez-le peu avant l’heure prévue de démarrage de la tâche.
Utilisez la même identité que lors de la création. Pour récupérer, lister ou rattacher des environnements, utilisez la même organisation, le même projet et la même identité authentifiée que lors de leur création. Plusieurs clés API associées à cette identité peuvent accéder aux mêmes environnements, y compris après une rotation des clés.
Les environnements partagés expirent après une période d’inactivité. Le premier rattachement déclenche un délai d’inactivité de 20 minutes. Toute activité dans une session rattachée ou via l’API de gestion des fichiers de l’environnement repousse l’échéance. Tant que des tâches sont en attente ou qu’un tour de conversation est en cours, l’environnement ne peut pas expirer pour inactivité. Supprimer une session la détache de l’environnement tout en conservant l’espace de travail partagé. Même après la suppression de la dernière session, l’environnement reste disponible pour un nouveau rattachement jusqu’à l’expiration du délai d’inactivité. L’API ne propose aucun point de terminaison pour supprimer directement un environnement autonome.

Relancez une requête de création sans risque de doublon

Lors de la création d’un environnement, vous pouvez envoyer un en-tête Idempotency-Key. Si la requête expire ou si sa réponse est perdue, relancez-la avec la même clé et le même corps de requête pour éviter de créer un environnement supplémentaire.

Tant que l’environnement initial reste disponible, une nouvelle tentative qui aboutit renvoie son ID et son état actuel. Tant que la clé est conservée, sa réutilisation peut renvoyer 409 si la création est encore en cours, si son résultat est incertain, si l’environnement n’est plus disponible ou si les paramètres diffèrent. Aucun de ces conflits n’entraîne la création d’un environnement de remplacement. Les clés sont conservées pendant 24 heures. Passé ce délai, la même clé peut créer un nouvel environnement. Utilisez une nouvelle clé lorsque vous souhaitez délibérément créer un autre environnement.

Suggestions

Premiers pas

Notions fondamentales

SDK et CLI

Fournisseurs de services cloud

Ressources

Anciennes API

Choisissez un modèle

Texte et code

Rédaction de prompts

Raisonnement

Images

Temps réel et audio

Modèles spécialisés

API Agents

Agents SDK

ChatKit

Recherche et récupération d’informations

Connectez des outils et des sources de données

Créez des workflows qui font appel à des outils

Ordinateur et code

Médias

GPT-Live

Realtime API

Créer des applications vocales

Connexions

Traitement audio

Mise en production

Performances et qualité

Évaluation

Coût et débit

Sécurité et gouvernance

Infrastructure et accès

Opérations

Concepts clés

Planification

Développement

Tests et publication

Spécifications de conversion

Guides

Ressources

Identité

Utilisation du forfait ChatGPT

Guides

Envoi de fichiers

API

Mesure des performances

API pour les annonceurs

Référence de l’API

Premiers pas

Premiers pas

Notions de base

Explorer

Disponible sur

Versions

Workflows

Capacités

Sites

dots

Espace ChatGPT

Référence

Personnalisation

Fichier de configuration

Configuration des agents

Étendre les fonctionnalités de ChatGPT et de Codex

Linux

Windows

Workflows de développement

Extensions et automatisation

Environnements

Codex Cloud

Développer avec Codex

Intégrations tierces

Référence

Autorisations

Codex Security

Cybersécurité

Premiers pas

Configuration des fonctionnalités

Identité et accès