DigitalOcean

OpenAI Cookbook のアプリケーション管理とウェブフック管理の例を参照してください。

仕組み

DigitalOcean の Managed Agents Runtime Services（M.A.R.S.）は、codex-agentapi イメージを使用して Firecracker microVM を起動します。このイメージには Codex が含まれており、Agents API にアウトバウンド接続するエグゼキューターを起動します。

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

事前準備

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

ウェブフックコントローラーや Python アプリケーションでは、DIGITALOCEAN_TOKEN を設定し、非同期処理に対応した PyDo ベータ版 SDK（pydo[aio]）をインストールします。Agents API へのリクエストには OpenAI SDK を使用します。CLI のインストールが必要なのは、CLI を使う手順の場合だけです。

ウェブフック管理

1. 保存済みエージェントを作成し、その ID を OPENAI_AGENT_ID として保存します。この ID、セッションの読み取り用の OPENAI_API_KEY、DIGITALOCEAN_TOKEN、OPENAI_EXECUTOR_API_KEY を設定して、DigitalOcean App Platform に HTTPS ウェブフックコントローラーをデプロイします。
2. OpenAI プロジェクトに、コントローラーの /webhook エンドポイントを登録します。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 を通じて入力を送信し、結果をストリーミングで受信します。コントローラーはプロビジョニングと再接続を処理します。重複配信や同時配信に対応するため、セッションごとにプロビジョニングを直列化してください。コントローラーの要件については、ウェブフック管理のライフサイクルガイドを参照してください。

DigitalOcean CLI での試用

CLI は両方のリソースを作成し、ターミナルからエージェントと対話できるようにします。ウェブフックコントローラーを介さず、サンドボックスを直接プロビジョニングします。

harness-runtime を含む doctl のベータ版リリースをインストールしてから、認証を行います。

doctl auth init

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

config ブロックは、OpenAI へのセッション作成リクエストです。CLI は OPENAI_API_KEY でこのリクエストを認証し、レスポンスの値を ${ENV_ID} に設定して、環境キーだけをサンドボックスに渡します。変数を展開したマニフェストは、ログに記録したり、ソース管理に含めたりしないでください。ツールに必要な接続先はすべて egress に追加します。

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

doctl harness-runtime create --spec agents.yaml

このコマンドは、デフォルトで準備が整うまで最大 300 秒待機します。セッションの詳細から OpenAI セッション ID と DigitalOcean セッション ID を保存し、アタッチします。

doctl harness-runtime launch openai-codex-session

/workspace/hello.txt に hello を書き込み、その内容を読み取るようエージェントに依頼します。 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 を保存します。エージェントの構成はすでに OpenAI に送信されているため、次のサンドボックス専用マニフェストを sandbox.yaml として保存します。

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. DIGITALOCEAN_TOKEN を使用して pydo.aio.Client を作成し、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. 相対パス hello.txt を指定して、workspace_download でファイルを取得します。後続のターンで使用する場合は両方のリソースを保持し、不要であればクリーンアップします。

セットアップと実行には上限のあるタイムアウトを設定し、アプリケーション内で接続の失敗に対処してください。アプリケーションや CLI が直接管理するセッションには、プロビジョニング用のウェブフックハンドラーを関連付けないでください。

クリーンアップ

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

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

doctl harness-runtime remove openai-codex-session

ウェブフックコントローラーを削除する前に、OpenAI のウェブフック登録を削除してください。

参考資料

• DigitalOcean サンドボックスのセットアップを参照
• DigitalOcean Python SDK を参照
• DigitalOcean CLI のベータ版リリースを参照