DigitalOcean

OpenAI Cookbook には、アプリケーションで管理する場合と Webhook で管理する場合の実装例があります。

仕組み

DigitalOcean の Managed Agents Runtime Services（M.A.R.S.）は、codex-agentapi イメージを使って Firecracker microVM を起動します。このイメージには Codex が含まれており、起動時にエグゼキュータが立ち上がります。エグゼキュータはサンドボックス側から Agents API に接続します。

プロビジョニング方式は、OpenAI のイベントを受けてサンドボックスを起動または再開する場合は「Webhook による管理」、アプリケーションからサンドボックスを制御する場合は「アプリケーションによる管理」を選びます。対話形式で試すには、DigitalOcean CLI を使った手順も利用できます。接続時と復旧時の動作については、サンドボックスのライフサイクルを参照してください。

前提条件

サンドボックスが有効で codex-agentapi にアクセスできる DigitalOcean アカウントと、Agents API にアクセスできる OpenAI プロジェクトが必要です。

Webhook コントローラまたは Python アプリケーションを使う場合は、DIGITALOCEAN_TOKEN を設定し、PyDo SDK のバージョン 0.41.0 以降を非同期処理に対応した構成（pydo[aio]）でインストールします。Agents API へのリクエストには OpenAI SDK を使います。CLI のインストールが必要なのは、CLI を使った手順を実行する場合だけです。

Webhook による管理

1. 保存済みエージェントを作成し、その ID を OPENAI_AGENT_ID として保存します。この ID、セッションの読み取りに使う OPENAI_API_KEY、DIGITALOCEAN_TOKEN、OPENAI_EXECUTOR_API_KEY を設定し、DigitalOcean App Platform に HTTPS の Webhook コントローラをデプロイします。
2. コントローラの /webhook エンドポイントを OpenAI プロジェクトに登録します。agent.session.action_required と agent.session.failed を有効にし、署名シークレットを OPENAI_WEBHOOK_SECRET として保存してから、コントローラを再デプロイします。
3. セッションの実行手順に従い、同じ OPENAI_AGENT_ID を使い、作業ディレクトリに /workspace を指定します。イベントストリームを開き、入力を送信します。OpenAI が environment_connection を要求すると、コントローラは署名を検証し、現在のセッションを取得して、エージェント ID と要求されているアクションを確認します。次に、DigitalOcean で mars-{session_id} を検索します。一時停止中のサンドボックスがあれば再開し、一時停止中のものも稼働中のものもなければ新しく作成します。
4. agent.session.failed を受信したら、セッションを再取得し、ステータスが引き続き failed の場合に限り、そのセッションのサンドボックスを削除します。

イメージの起動時に、エグゼキュータがセッションの環境に接続します。アプリケーションは Agents API を通じて入力を送信し、結果をストリームで受け取ります。プロビジョニングと再接続はコントローラが担当します。イベントの重複配信や同時配信に対応できるよう、同じセッションのプロビジョニング処理は直列化してください。コントローラの要件は、Webhook で管理するサンドボックスのライフサイクルを参照してください。

DigitalOcean CLI を使ったクイックスタート

CLI を使うと、セッションとサンドボックスの両方を作成し、ターミナルからエージェントとやり取りできます。CLI がサンドボックスを直接プロビジョニングするため、Webhook コントローラは不要です。

doctl のバージョン 1.170.0 以降をインストールします。このバージョンには harness-runtime が含まれています。次のコマンドで認証します。

doctl auth init

次のマニフェストを 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}

config ブロックは、OpenAI に送るセッション作成リクエストの内容です。CLI は OPENAI_API_KEY でリクエストを認証し、レスポンスから取得した値を ${ENV_ID} に代入します。サンドボックスに渡すキーは環境キーだけです。変数を展開したマニフェストは、ログに出力したりバージョン管理に含めたりしないでください。ツールに必要な接続先は egress に追加します。

セッションとサンドボックスを作成します。

doctl harness-runtime create --spec environment.yaml

このコマンドはデフォルトで、準備が整うまで最大 300 秒待機します。セッションの詳細に表示される OpenAI のセッション ID と DigitalOcean のセッション ID を保存し、次のコマンドでセッションに接続します。

doctl harness-runtime launch openai-codex-session

エージェントに、hello を /workspace/hello.txt に書き込んでから、その内容を読み取るよう依頼します。Ctrl+D を押すと、セッションを削除せずに切断できます。再接続するには、同じ launch コマンドを実行します。作業が終わったら、クリーンアップの手順に従ってください。

アプリケーションによる管理

アプリケーションでセッションの作成とサンドボックスのプロビジョニングを管理する場合は、次の手順を使います。まず、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

session.id と環境 ID を、サンドボックスの接続の手順に従って保存します。次のサンドボックス専用のマニフェストを sandbox.yaml として保存します。エージェントの設定はすでに 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. pydo.aio.Client を DIGITALOCEAN_TOKEN で初期化し、client.agents.create_session を呼び出します。params.openai_session_id には OpenAI のセッション ID を、body.manifest には sandbox.yaml の内容を、body.variables には ENV_ID と OPENAI_EXECUTOR_API_KEY をそれぞれの値に対応付けたマッピングを指定します。レスポンスに含まれる DigitalOcean の session_id を保存します。
2. イベントストリームを開いて入力を送信し、エージェントに /workspace/hello.txt への書き込みと読み取りを依頼します。入力はエグゼキュータが接続してから処理されます。接続イベントが届いたこととターンが完了したことを確認し、エージェントの出力を調べてツールの実行に失敗していないか確認します。
3. workspace_download で相対パス hello.txt を指定し、ファイルを取得します。次のターンに進む場合はセッションとサンドボックスの両方を残し、終了する場合はクリーンアップします。

アプリケーションでは、セットアップと実行のそれぞれにタイムアウトを設定し、接続に失敗した場合の処理を実装してください。アプリケーションまたは CLI が直接管理するセッションには、プロビジョニング用の Webhook ハンドラを設定しないでください。

クリーンアップ

必要なファイルを保存してから、OpenAI のセッションを削除し、DigitalOcean のサンドボックスを破棄します。セッションを削除しても Webhook イベントは送信されないため、必ず両方の操作を実行し、クリーンアップに失敗した場合は報告してください。

PyDo を使う場合は、client.agents.destroy_session に DigitalOcean のセッション ID を渡して呼び出します。CLI を使う場合は、その ID またはサンドボックス名を指定します。

doctl harness-runtime remove openai-codex-session

Webhook コントローラを削除する前に、OpenAI 側で Webhook の登録を解除してください。

参考資料

• DigitalOcean サンドボックスのセットアップを読む
• DigitalOcean Python SDK のドキュメントを読む
• DigitalOcean CLI のリリース情報を読む