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 lance l’exécuteur, qui établit une connexion sortante vers l’API Agents.

Choisissez le provisionnement par webhook pour démarrer ou réactiver les bacs à sable en réponse aux événements OpenAI, ou le provisionnement par l’application pour les piloter depuis votre application. Pour un démarrage rapide et interactif, vous pouvez utiliser la CLI DigitalOcean. Consultez le cycle de vie d’un bac à sable pour comprendre comment la connexion s’établit et se rétablit après une interruption.

Prérequis

Vous devez disposer d’un compte DigitalOcean sur lequel les bacs à sable sont activés et qui a accès à codex-agentapi, ainsi que d’un projet OpenAI ayant 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 0.41.0 ou ultérieure avec la prise en charge des appels asynchrones (pydo[aio]). Utilisez le SDK OpenAI pour les requêtes à l’API Agents. L’installation de la CLI est nécessaire uniquement si vous suivez la procédure en ligne de commande.

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 consulter les sessions, DIGITALOCEAN_TOKEN et OPENAI_EXECUTOR_API_KEY.
2. Enregistrez son point de terminaison /webhook dans votre projet OpenAI. Activez les événements agent.session.action_required et agent.session.failed, puis enregistrez le secret de signature dans OPENAI_WEBHOOK_SECRET et redéployez le contrôleur.
3. Suivez les étapes d’exécution d’une session en utilisant le même OPENAI_AGENT_ID et /workspace comme répertoire de travail. Ouvrez le flux d’événements et envoyez vos instructions. Lorsqu’OpenAI demande une action environment_connection, le contrôleur vérifie la signature, récupère la session en cours et contrôle l’identifiant de l’agent ainsi que les actions requises. Il recherche mars-{session_id} dans DigitalOcean, puis réactive le 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 supprimez son bac à sable uniquement si l’état de la session est toujours failed.

L’image connecte l’exécuteur à l’environnement de la session. Votre application envoie les instructions et reçoit les résultats en continu via l’API Agents. Le contrôleur se charge du provisionnement et de la reconnexion. Pour chaque session, exécutez les opérations de provisionnement l’une après l’autre afin de gérer les événements reçus plusieurs fois ou simultanément. Consultez les consignes de gestion du cycle de vie par webhook pour connaître les exigences applicables au contrôleur.

Faites un essai avec la CLI DigitalOcean

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

Installez doctl en version 1.170.0 ou ultérieure pour disposer de harness-runtime, puis authentifiez-vous :

doctl auth init

Enregistrez ce manifeste sous le nom environment.yaml :

12345678910111213141516name: openai-codex-session
agent: codex-agentapi
config:
  agent:
    model: gpt-6.1-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 contient la requête de création de session destinée à 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. Une fois les variables remplacées par leurs valeurs, veillez à exclure les manifestes des journaux et du dépôt de code source. Ajoutez à egress toutes les destinations dont vos outils ont besoin.

Créez la session et le bac à sable :

doctl harness-runtime create --spec environment.yaml

Par défaut, la commande attend jusqu’à 300 secondes que les ressources soient prêtes. Enregistrez les identifiants de session OpenAI et DigitalOcean affichés dans les détails de la session, puis connectez-vous à celle-ci :

doctl harness-runtime launch openai-codex-session

Demandez à l’agent d’écrire hello dans /workspace/hello.txt, puis de relire le fichier. Appuyez sur Ctrl+D pour vous déconnecter sans supprimer la session. Exécutez la même commande launch pour vous reconnecter. Lorsque vous avez terminé, suivez les étapes de nettoyage.

Gestion par l’application

Utilisez cette méthode lorsque votre application se charge de créer les sessions et de provisionner les 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 la section Connexion d’un bac à sable. Enregistrez le manifeste suivant sous le nom sandbox.yaml. Il concerne uniquement le bac à sable, car 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. Affectez à params.openai_session_id l’identifiant de la session OpenAI, à body.manifest le contenu de sandbox.yaml et à body.variables un dictionnaire associant ENV_ID et OPENAI_EXECUTOR_API_KEY à leurs valeurs respectives. Enregistrez le session_id renvoyé par DigitalOcean.
2. Ouvrez le flux d’événements et envoyez vos instructions en demandant à l’agent d’écrire dans /workspace/hello.txt, puis de relire le fichier. Les instructions restent en attente jusqu’à la connexion de l’exécuteur. Vérifiez que vous avez reçu l’événement de connexion et que le tour est terminé. Examinez la sortie de l’agent pour repérer d’éventuels échecs d’appels 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 supprimez-les.

Dans votre application, fixez des délais maximaux pour la mise en place et l’exécution, et gérez les échecs de connexion. 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 aucun webhook. Effectuez donc les deux opérations et signalez tout échec de nettoyage.

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

doctl harness-runtime remove openai-codex-session

Avant de supprimer un contrôleur de webhook, supprimez le webhook enregistré dans votre projet OpenAI.

Références

• Consultez le guide de configuration d’un bac à sable DigitalOcean
• Consultez la documentation du SDK Python de DigitalOcean
• Consultez les versions de la CLI DigitalOcean