サンドボックスの事前準備

環境を事前に準備すると、エージェントのセッションを作成する前に、OpenAI がホストするサンドボックスを作成し、パッケージのインストール、ファイルの読み込み、セットアップコマンドの実行を済ませておけます。タスクを受け取ったら、準備した環境をセッションにアタッチしてエージェントを起動します。

低レイテンシが重要な要件であれば、環境を事前に準備します。たとえば、レポート作成アプリでは、ユーザーがデータセットを選んでいる間に Python の依存パッケージを準備できます。コーディングのワークフローでは、ユーザーが依頼内容を書いている間にワークスペースを準備できます。セットアップを早めに始めることで、ユーザーの待ち時間を短縮できます。

仕組み

環境は、エージェントがツールを実行するワークスペースです。セッションには、エージェントの設定と会話が保存されます。ワークスペースはセッションとは独立して準備でき、セッションが必要になった時点でアタッチできます。

手順は次の 3 つです。

環境を作成します。タスクに必要なパッケージ、ファイル、セットアップコマンドを指定します。
準備が完了するまで待ちます。ステータスが ready になるまで環境の情報を繰り返し取得するか、Webhook を使用します。
セッションを開始します。セッションの作成時に環境 ID を渡します。

セットアップ中でも環境をアタッチできます。その場合、エージェントがワークスペースにアクセスできるのは、セットアップが完了してからです。

料金

サンドボックスの事前準備は無料です。セッションにアタッチする前のコンテナ利用にも料金はかかりません。事前に準備したサンドボックスは、アタッチしないまま 5 分経過すると有効期限が切れます。

事前に準備したサンドボックスをセッションにアタッチすると、標準のコンテナ利用料金が適用されます。

レポート作成用ワークスペースの準備

この例では、エージェントを起動する前に pandas をインストールし、小さな CSV ファイルを読み込みます。その後、エージェントが準備済みのワークスペースで合計を計算します。

このガイドでは、Python SDK 3.28.0、Node.js SDK 7.32.0、Java SDK 4.80.0、Ruby SDK 0.103.0 のいずれか、または各 SDK のそれ以降のバージョンを使用してください。

1. 環境の作成

ワークスペースの設定を 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"
        }
      ]
    }
  }'

各 SDK の例では、返された id を後続の手順で使用するために保存しています。cURL を使用する場合は、シェル変数に保存します。

ENVIRONMENT_ID="ccarenv_REPLACE_WITH_RETURNED_ID"

スタンドアロン環境を作成する際は、environment.type を openai_hosted に設定します。

2. 準備状況の確認

手順 1 で保存した ID を使って環境の情報を取得します。

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"

セットアップ中のステータスは pending です。ready になるとワークスペースの準備が完了し、セッションにアタッチできます。

準備が完了していても、エージェントが接続されているとは限りません。セッションを作成する前でも、環境のステータスは ready になることがあります。

ポーリングを避けるには、プロジェクトの Webhook エンドポイントで次のイベントを購読します。

agent.environment.ready
agent.environment.failed

セットアップが完了する前に環境をアタッチした場合は、セッションの agent.session.environment.ready または agent.session.environment.failed イベントでセットアップ状況を確認します。"stream": true を指定してセッションを作成したときのレスポンスストリームを使用するか、GET /v1/agents/sessions/{session_id}/events でストリームを開きます。ストリーミングの詳細は「セッションイベント」を参照してください。

3. 環境のアタッチとタスクの実行

保存した環境 ID、エージェント、エージェントへの最初の入力を指定してセッションを作成します。

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

よくあるエラー

エラーメッセージと環境の現在のステータスを確認し、対処方法を選びます。

新しく作成した共有環境には、最大 128 個のセッションをアタッチできます。複数のセッションで同じ環境を再利用でき、それらのセッションはワークスペースを共有します。以前に作成した環境には、引き続き単一セッション用のライフサイクルが適用される場合があります。

エラーまたは症状	対処方法
有効期限が切れた環境をアタッチしようとした。	新しい環境を作成し、その ID を使用します。未使用の環境は 5 分で有効期限が切れます。期限切れの ID で再試行しても、ワークスペースは復元されません。
`404`：環境が見つからない。	環境 ID を確認し、環境の作成リクエストと同じ組織、プロジェクト、認証主体を使用します。環境の有効期限が切れているか、すでに利用できない場合は、新しい環境を作成します。
`409`：共有環境のセッション数が上限に達した。	共有環境にアタッチできるセッションは最大 128 個です。既存のセッションを再利用するか、追加のセッション用に別の環境を作成します。

保存済みの環境テンプレートの使用

複数のタスクで同じパッケージとセットアップが必要な場合は、環境設定をテンプレートとして保存し、環境を事前に作成するたびにそのテンプレートの ID を指定します。

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

コンピューターの使用に向けたサンドボックスの事前準備

ブラウザを使うタスクでは、セッションを開始する前に、マネージドブラウザと仮想ディスプレイを準備します。環境の作成時に desktop.enabled を指定します。

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

セッションの作成時に、保存した環境 ID を指定して環境をアタッチし、エージェントに computer_use ツールを設定します。セッションには、その環境に保存されているデスクトップ設定が適用されます。ツールの設定とブラウザのオリジンごとの承認については、「コンピューターの使用」を参照してください。

環境の一覧表示

GET /v1/agents/environments を使用すると、現在の組織とプロジェクトで、自分の認証主体が作成したアクティブな環境を確認できます。

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"

一覧には、セッションへのアタッチ前とアタッチ後の環境が含まれます。表示されるステータスは pending、ready、connected、disconnected、suspended のいずれかです。失敗した環境、有効期限が切れた環境、削除済みの環境、終了済みの環境は含まれません。一覧に表示されている環境が、すでに 1 つ以上のセッションにアタッチされている場合もあります。

デフォルトでは新しい順に表示されます。has_more が true の場合は、after に直前のレスポンスの last_id を指定して次のページを取得します。limit には 1～100 を指定でき、デフォルトは 20 です。order には asc または desc を指定できます。

有効期間と再利用

複数のセッションで 1 つの環境を共有できます。各セッションの作成時に同じ environment_id を渡します。各セッションは実行中のワークスペースを共有します。ファイル、プロセス、インストール済みのパッケージ、環境設定も共有されます。会話履歴はセッションごとに保持されます。ワークスペースの変更は、同じ環境にアタッチされている他のセッションにも反映されます。タスクごとにワークスペースを分ける必要がある場合は、別々の環境を作成してください。共有環境には最大 128 個のセッションをアタッチできます。この動作は新しく作成したスタンドアロン環境に適用されます。以前に作成した環境には、元のライフサイクルが引き続き適用されます。
未使用の環境には有効期限があります。環境をアタッチしないまま 5 分経過すると、有効期限が切れます。タスクの開始予定時刻に合わせて、その少し前に環境を準備してください。
環境の作成時と同じ認証主体を使用してください。環境の取得、一覧表示、アタッチには、環境の作成時と同じ組織、プロジェクト、認証主体が必要です。同じ認証主体の API キーであれば、別のキーでも同じ環境にアクセスできます。キーのローテーション後も同様です。
共有環境は一定時間アクティビティがないと有効期限が切れます。最初のセッションをアタッチした時点から、アイドル状態での有効期間は 20 分です。アタッチ済みのいずれかのセッションでアクティビティがあるか、環境のファイル API を使用すると、有効期間が延長されます。処理待ちの作業や進行中のターンがある間は、アイドル状態による期限切れは発生しません。セッションを削除すると、そのセッションだけが環境から外れ、共有ワークスペースは保持されます。最後のセッションを削除した後も、アイドル状態での有効期限が切れるまでは、環境をセッションにアタッチできます。スタンドアロン環境を削除するための API エンドポイントはありません。

環境作成の安全な再試行

環境の作成時には、Idempotency-Key ヘッダーを送信できます。リクエストがタイムアウトした場合やレスポンスを受信できなかった場合は、同じキーと同じリクエストボディで再試行すると、環境の重複作成を防げます。

元の環境が引き続き利用可能であれば、再試行が完了した時点で、その環境の ID と現在の状態が返されます。保持期間内のキーで再試行すると、作成がまだ進行中の場合、作成結果が確定していない場合、環境がすでに利用できない場合、またはパラメータが異なる場合に 409 が返されることがあります。こうした競合が発生しても、代わりの環境は作成されません。キーの保持期間は 24 時間です。保持期間が過ぎると、同じキーでも新しい環境が作成される場合があります。新しい環境を意図的に作成する場合は、新しいキーを使用してください。

おすすめ

はじめに

基本概念

SDK と CLI

クラウドプロバイダー

リソース

レガシー API

モデルの選び方

テキストとコード

プロンプトの書き方

推論

画像

リアルタイム処理とオーディオ

特化型モデル

Agents API

Agents SDK

ChatKit

検索と情報取得

ツールとデータの接続

ツールを使ったワークフローの構築

コンピューターとコード

メディア

GPT-Live

Realtime API

音声を使った開発

接続

音声処理

本番稼働の開始

パフォーマンスと品質

評価

コストとスループット

安全性とガバナンス

インフラとアクセス

業務運営

基本概念

計画

開発

テストと公開

コンバージョン仕様

ガイド

リソース

アイデンティティ

ChatGPT プランの利用状況

ガイド

ファイルのアップロード

API

効果測定

広告主向け API

API リファレンス

はじめに

はじめに

基礎

探す

対応プラットフォーム

リリース

ワークフロー

できること

Sites

dot

ChatGPT Space

リファレンス

カスタマイズ

設定ファイル

エージェントの設定

ChatGPT と Codex の機能拡張

Linux

Windows

開発ワークフロー

機能拡張と自動化

環境

Codex Cloud

Codex を使った開発

サードパーティ連携

リファレンス

権限

Codex Security

サイバー安全対策

はじめに

機能設定

ID とアクセス管理