DigitalOcean

Consultez les exemples de gestion par l’application et par webhook dans l’OpenAI Cookbook.

Fonctionnement

Le service Managed Agents Runtime Services (M.A.R.S.) de DigitalOcean démarre une microVM Firecracker à partir de l’image codex-agentapi. Cette image inclut Codex et démarre l’exécuteur, qui établit une connexion sortante vers l’API Agents.

Choisissez le provisionnement géré par webhook pour démarrer ou réactiver des bacs à sable à partir d’événements OpenAI, ou le provisionnement géré par l’application pour les contrôler depuis votre application. Pour un démarrage rapide interactif, vous pouvez suivre le parcours avec la CLI DigitalOcean. Consultez Cycle de vie du bac à sable pour connaître le comportement de connexion et de récupération.

Avant de commencer

Vous avez besoin d’un compte DigitalOcean sur lequel les bacs à sable sont activés, avec accès à codex-agentapi, ainsi que d’un projet OpenAI disposant d’un accès à l’API Agents.

Pour les contrôleurs de webhook ou les applications Python, définissez DIGITALOCEAN_TOKEN et installez le SDK PyDo en version bêta avec la prise en charge des opérations asynchrones (pydo[aio]). Utilisez le SDK OpenAI pour les requêtes à l’API Agents. L’installation de la CLI n’est nécessaire que pour la procédure utilisant la CLI.

Gestion par webhook

1. Créez un agent enregistré et enregistrez son identifiant dans OPENAI_AGENT_ID. Déployez un contrôleur de webhook HTTPS sur DigitalOcean App Platform avec cet identifiant, OPENAI_API_KEY pour la lecture des sessions, DIGITALOCEAN_TOKEN et OPENAI_EXECUTOR_API_KEY.
2. Enregistrez son point de terminaison /webhook auprès de votre projet OpenAI. Activez agent.session.action_required et agent.session.failed, puis stockez le secret de signature dans OPENAI_WEBHOOK_SECRET et redéployez le contrôleur.
3. Suivez les étapes d’exécution d’une session avec la même valeur de OPENAI_AGENT_ID et /workspace comme répertoire de travail. Ouvrez le flux d’événements et envoyez une entrée. Lorsqu’OpenAI demande une environment_connection, le contrôleur vérifie la signature, récupère la session actuelle et vérifie l’identifiant de son agent ainsi que les actions requises. Il recherche mars-{session_id} dans DigitalOcean et réactive un bac à sable en pause, ou en crée un si aucun n’est actif.
4. À la réception de agent.session.failed, récupérez à nouveau la session et ne supprimez son bac à sable que si l’état actuel de la session est toujours failed.

L’image connecte l’exécuteur à l’environnement de la session. Votre application envoie les entrées et reçoit les résultats en streaming via l’API Agents ; le contrôleur gère le provisionnement et la reconnexion. Exécutez les opérations de provisionnement séquentiellement pour chaque session afin de gérer les livraisons en double et simultanées. Consultez les consignes sur le cycle de vie géré par webhook pour connaître les exigences applicables au contrôleur.

Essayez avec la CLI DigitalOcean

La CLI crée les deux ressources et vous permet d’interagir avec l’agent depuis votre terminal. Elle provisionne directement le bac à sable, sans contrôleur de webhook.

Installez la version bêta de doctl qui inclut harness-runtime, puis authentifiez-vous :

doctl auth init

Enregistrez ce manifeste sous le nom agents.yaml :

12345678910111213141516name: openai-codex-session
agent: codex-agentapi
config:
  agent:
    model: gpt-5.6-sol
    instructions: Work from the files in /workspace.
  environment:
    type: self_hosted
    workspace_directory: /workspace
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

Le bloc config correspond à la requête de création de session OpenAI. La CLI authentifie cette requête avec OPENAI_API_KEY, renseigne ${ENV_ID} à partir de la réponse et transmet uniquement la clé d’environnement au bac à sable. Ne consignez pas les manifestes résolus dans les journaux et ne les ajoutez pas au contrôle de version. Ajoutez à egress toutes les destinations dont vos outils ont besoin.

Créez la session et le bac à sable :

doctl harness-runtime create --spec agents.yaml

Par défaut, la commande attend jusqu’à 300 secondes que les ressources soient prêtes. Enregistrez l’identifiant de session OpenAI et l’identifiant de session DigitalOcean depuis les détails de la session, puis attachez-vous à celle-ci :

doctl harness-runtime launch openai-codex-session

Demandez à l’agent d’écrire hello dans /workspace/hello.txt, puis d’en lire le contenu. Appuyez sur Ctrl+D pour vous détacher de la session sans la supprimer, et exécutez la même commande launch pour vous y rattacher. Suivez les étapes de nettoyage lorsque vous avez terminé.

Gestion par l’application

Utilisez ce parcours lorsque votre application gère la création des sessions et le provisionnement des bacs à sable. Créez d’abord la session OpenAI :

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 et l’identifiant de l’environnement comme indiqué dans Connecter un bac à sable. Enregistrez ce manifeste, qui concerne uniquement le bac à sable, sous le nom sandbox.yaml ; la configuration de l’agent a déjà été envoyée à OpenAI :

12345678agent: codex-agentapi
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

1. Créez une instance de pydo.aio.Client avec DIGITALOCEAN_TOKEN et appelez client.agents.create_session. Définissez params.openai_session_id sur l’identifiant de session OpenAI, body.manifest sur le contenu de sandbox.yaml, et body.variables sur un dictionnaire associant ENV_ID et OPENAI_EXECUTOR_API_KEY à leurs valeurs. Enregistrez le session_id renvoyé par DigitalOcean.
2. Ouvrez le flux d’événements et envoyez une entrée demandant à l’agent d’écrire dans /workspace/hello.txt, puis d’en lire le contenu. L’entrée reste en attente jusqu’à la connexion de l’exécuteur. Vérifiez que l’événement de connexion a été reçu et qu’un tour s’est terminé, puis examinez la sortie de l’agent pour repérer d’éventuels échecs d’outils.
3. Récupérez le fichier avec workspace_download, en utilisant le chemin relatif hello.txt. Conservez les deux ressources pour les tours suivants, ou procédez au nettoyage.

Définissez des délais d’expiration bornés pour la configuration et l’exécution, et gérez les échecs de connexion dans votre application. N’associez pas de gestionnaire de webhook de provisionnement aux sessions que votre application ou votre CLI gère directement.

Nettoyage

Enregistrez les fichiers dont vous avez besoin, puis supprimez la session OpenAI et détruisez le bac à sable DigitalOcean. La suppression d’une session ne déclenche pas de webhook : effectuez donc les deux opérations et signalez les échecs de nettoyage.

Avec PyDo, appelez client.agents.destroy_session avec l’identifiant de session DigitalOcean. Avec la CLI, transmettez cet identifiant ou le nom du bac à sable :

doctl harness-runtime remove openai-codex-session

Supprimez l’enregistrement du webhook auprès d’OpenAI avant de supprimer un contrôleur de webhook.

Références

• Consultez la documentation sur la configuration des bacs à sable DigitalOcean
• Consultez la documentation du SDK Python DigitalOcean
• Consultez la version bêta de la CLI DigitalOcean