OpenAI ホスト型サンドボックスでは、エージェントが Python、Node.js、コマンドラインツールを備えた Linux ワークスペースを利用できます。OpenAI がワークスペースを用意して接続し、アプリケーションはタスクを渡して結果を取得します。独自のイメージ、コンピューティングリソース、プライベートネットワークのいずれかが必要な場合は、セルフホスト型サンドボックスを選択してください。
ブラウザでウェブサイトを操作するタスクについては、コンピューターの使用を参照してください。
セッションの作成前にワークスペースを準備する方法については、サンドボックスの事前準備を参照してください。
セッション作成リクエストで environment.type を openai_hosted に設定します。ワークロードに必要な設定だけを追加してください。サンドボックスの作業ディレクトリは /workspace です。
タスクに必要なリソースとネットワークアクセスは、それぞれ container_size と network で指定します。環境テンプレートを使用する場合、省略した設定にはテンプレートの値が適用されます。
次の設定を使って、サンドボックスで依存パッケージや入力ファイルを利用できるようにします。
packages:Python パッケージ、システムパッケージ、グローバルにインストールする npm パッケージを、それぞれ python、system、npm のリストで指定してインストールします。必要に応じて、pandas==2.2.3 のようにバージョンを固定してください。
files:Files API のファイル ID またはインラインの base64 データで入力ファイルを渡します。
setup_commands を使うと、エージェントの起動前にシェルコマンドを指定した順序で実行できます。たとえば、[{ "command": "mkdir -p reports" }] はディレクトリを作成します。各コマンドの作業ディレクトリは cwd で個別に指定できます。デフォルトは /workspace です。
パッケージと入力ファイルの準備が完了してから、セットアップコマンドが実行されます。必要な依存パッケージやファイルがそろっているかどうかは、セットアップコマンドで確認できます。セットアップの終了ステータスが 0 以外の場合、エージェントは起動しません。
env を使って、文字列を値とする環境変数を設定します。エージェントが生成したコードからこれらの値を読み取れます。
シークレットにはボールトの認証情報を使用し、実際の値はサンドボックスの外部に保管してください。PATH、CODEX_*、OPENAI_API_KEY など、ランタイムが予約している名前は指定できません。
セッション作成時に environment.container_size を設定して、サンドボックスで使用できる vCPU 数とメモリ容量を選択します。デフォルトは medium です。
| サイズ |
vCPU |
メモリ |
small |
1 |
1 GB |
medium |
2 |
4 GB |
large |
4 |
16 GB |
たとえば、POST /v1/agents/sessions リクエストに次の環境設定を含めると、small を選択できます。
123456{
"environment": {
"type": "openai_hosted",
"container_size": "small"
}
}
返されたセッションの environment.container_size で、選択したサイズを確認できます。この設定は OpenAI ホスト型サンドボックスにのみ適用されます。
network.access |
動作 |
enabled |
外部へのアクセスを許可します。テンプレートのポリシーを継承する場合を除き、これがデフォルトです。 |
disabled |
外部へのアクセスをブロックします。 |
restricted |
allowed_domains に指定したホストへのアクセスだけを許可します。 |
制限モードでは、api.example.com のような完全一致のホスト名を 1~100 件指定できます。ワイルドカード、プロトコル、パス、ポートは含めないでください。サブドメインやリダイレクト先のホストは個別に指定する必要があります。ホスト型の stdio MCP サーバーを使用するには、現時点ではネットワークアクセスを enabled に設定する必要があります。stdio MCP の要件を参照してください。
skills、plugins、capability_directories を使って、スキルやプラグインを追加します。
environment_template_id を指定すると、保存済みの設定を再利用できます。省略した設定にはテンプレートの値が適用されます。ネットワーク設定を上書きしても、テンプレートのポリシーが許可するアクセス範囲を広げることはできません。テンプレートに保存されるのは設定だけで、実行中のワークスペースは保存されません。
セッション作成リクエストに対するレスポンスは、セットアップが開始されたことを示します。ステータスを確認するには、GET /v1/agents/environments/{environment_id} を呼び出します。環境 ID にはセッションの environment.id を使用してください。
| ステータス |
対応 |
provisioning |
セットアップが完了するまで待ちます。 |
connected |
セットアップが成功しました。実行中のサンドボックスにファイルを追加したり、ファイルの一覧を取得したりできます。 |
failed |
エラーの内容は environment.error で確認します。このフィールドは agent.session.environment.failed イベントに含まれます。 |
実行中のサンドボックスへのファイルの追加やファイル一覧の取得は、ステータスが connected になってから行ってください。
セッションごとに独立したワークスペースがあります。サンドボックスが存在する間、ファイルはターンをまたいで保持されます。/workspace/outputs 配下のファイルは、ターンが完了すると変更不可のアーティファクトとして公開されます。公開されたコピーは、サンドボックスの有効期限が切れた後もダウンロードできます。
アップロード、パスの指定規則、実行中のサンドボックスでのファイル操作、ダウンロード、各種制限については、ファイルとアーティファクトを参照してください。必要な出力はセッションを削除する前に保存してください。
接続中のサンドボックスには、ターンとターンの間もキープアライブが送信されます。アクティビティとキープアライブがともに 1 時間途絶えると、サンドボックスが削除されることがあります。このタイムアウトは変更できません。
作業が終わったら、セッションを削除してサンドボックスのクリーンアップをリクエストしてください。セットアップやタスクの実行が完了する前に削除をリクエストして 409 が返された場合は、完了を待ってから、試行回数に上限を設けて再試行してください。イベントストリームを閉じてもタスクはキャンセルされません。
OpenAI ホスト型サンドボックスには、標準のコンテナ料金が適用されます。モデルの利用料金は、選択したモデルの API 料金に基づいて別途請求されます。
10、20、30 を含む CSV ファイルをエージェントに渡します。エージェントは Python で合計を計算し、結果を /workspace/outputs/summary.json に書き込みます。
アプリケーションを実行するターミナルで OPENAI_API_KEY を設定してください。設定方法はクイックスタートの前提条件を参照してください。このキーはサンドボックスの外部に保管してください。OpenAI SDK は、ベータ版の Agents API に対応したバージョンを使用してください。
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 OpenAI from "openai";
import { agentFileDestination } from "openai/helpers/beta/agents/filesystem";
const client = new OpenAI();
const stream = await client.beta.agents.sessions.create({
agent: { model: "gpt-6-astra" },
environment: {
type: "openai_hosted",
network: { access: "disabled" },
files: [
{
type: "inline",
path: "/workspace/amounts.csv",
data: "YW1vdW50CjEwCjIwCjMwCg==",
},
],
},
input:
"Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
stream: true,
});
stream.withResultCollection();
try {
for await (const event of stream) {
console.log(event);
}
const result = await stream.finalResult();
await client.beta.agents.sessions.artifacts.forResult(result).download({
path: "/workspace/outputs/summary.json",
to: agentFileDestination("summary.json"),
});
} finally {
stream.controller.abort();
}
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
28from openai import OpenAI
client = OpenAI()
stream = client.beta.agents.sessions.create(
agent={"model": "gpt-6-astra"},
environment={
"type": "openai_hosted",
"network": {"access": "disabled"},
"files": [
{
"type": "inline",
"path": "/workspace/amounts.csv",
"data": "YW1vdW50CjEwCjIwCjMwCg==",
}
],
},
input="Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
stream=True,
)
with stream.with_result_collection():
for event in stream:
print(event.model_dump_json())
result = stream.get_final_result()
client.beta.agents.sessions.artifacts.for_result(result).download(
"/workspace/outputs/summary.json", to="summary.json"
)
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
35
36
37
38
39
40
41
42
43
44
45
46
47package main
import (
"context"
"fmt"
"os"
"github.com/openai/openai-go/v3"
)
func main() {
ctx := context.Background()
client := openai.NewClient()
stream := client.Beta.Agents.Sessions.NewStreaming(ctx, openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra")},
Environment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{
Network: openai.EnvironmentParamOpenAIHostedNetwork{Access: "disabled"},
Files: []openai.HostedEnvironmentFileParamUnion{{OfParamInline: &openai.HostedEnvironmentFileParamInline{
Path: "/workspace/amounts.csv",
Data: "YW1vdW50CjEwCjIwCjMwCg==",
}}},
}},
Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.")},
})
defer stream.Close()
openai.BetaAgentSessionWithResultCollection(stream)
for stream.Next() {
fmt.Println(stream.Current().RawJSON())
}
result, err := openai.BetaAgentSessionFinalResult(stream)
if err != nil {
panic(err)
}
destination, err := os.Create("summary.json")
if err != nil {
panic(err)
}
defer destination.Close()
_, err = client.Beta.Agents.Sessions.Artifacts.ForResult(result).Download(ctx, "/workspace/outputs/summary.json", destination)
if err != nil {
panic(err)
}
if err := destination.Close(); err != nil {
panic(err)
}
}
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
35
36
37
38
39
40
41import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.helpers.beta.agents.AgentArtifactDownloads;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.HostedEnvironmentFileParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import com.openai.services.beta.agents.AgentTurnResults;
import java.nio.file.Path;
public class HostedReport {
public static void main(String[] args) throws Exception {
var client = OpenAIOkHttpClient.fromEnv();
var params =
SessionCreateParams.builder()
.agent(SessionCreateParams.Agent.builder().model("gpt-6-astra").build())
.environment(
EnvironmentParam.OpenAIHosted.builder()
.network(
EnvironmentParam.OpenAIHosted.Network.builder()
.access(EnvironmentParam.OpenAIHosted.Network.Access.DISABLED)
.build())
.addFile(
HostedEnvironmentFileParam.Inline.builder()
.path("/workspace/amounts.csv")
.data("YW1vdW50CjEwCjIwCjMwCg==")
.build())
.build())
.input(
"Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object"
+ " with the total to /workspace/outputs/summary.json, then read it back to"
+ " verify it.")
.build();
try (var stream = client.beta().agents().sessions().createStreaming(params)) {
AgentTurnResults.withResultCollection(stream);
stream.stream().forEach(System.out::println);
var result = AgentTurnResults.getFinalResult(stream);
AgentArtifactDownloads.forResult(client.beta().agents().sessions().artifacts(), result)
.download("/workspace/outputs/summary.json", Path.of("summary.json"));
}
}
}
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
33require "openai"
require "json"
require "pathname"
client = OpenAI::Client.new
stream = client.beta.agents.sessions.create_streaming(
agent: { model: "gpt-6-astra" },
environment: {
type: :openai_hosted,
network: { access: :disabled },
files: [
{
type: :inline,
path: "/workspace/amounts.csv",
data: "YW1vdW50CjEwCjIwCjMwCg=="
}
]
},
input: "Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it."
)
begin
stream.with_result_collection
stream.each { |event| puts event.to_json }
result = stream.get_final_result
puts result.output_text
client.beta.agents.sessions.artifacts.for_result(result).download(
path: "/workspace/outputs/summary.json",
to: Pathname("summary.json")
)
ensure
stream.close
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra"
},
"environment": {
"type": "openai_hosted",
"network": {
"access": "disabled"
},
"files": [
{
"type": "inline",
"path": "/workspace/amounts.csv",
"data": "YW1vdW50CjEwCjIwCjMwCg=="
}
]
},
"input": "Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
"stream": true
}'
files の base64 値には、入力用の CSV データが含まれています。このコードはセッションイベントを出力します。session.id は agent.session.created イベントから取得して保存してください。agent.session.turn.completed イベントを受信したら、アーティファクトの一覧を取得し、summary.json を見つけてダウンロードします。ファイルの内容は次のようになります。
{ "total": 60 }
ターンが完了しても、すべてのツールの実行が成功したとは限りません。タスクが失敗した場合や、完了前にストリームが終了した場合は、保存済みのセッション項目を確認してください。作業が終わったら、セッションを削除してください。
| 問題 |
確認事項 |
| セットアップに失敗する |
環境のセットアップ失敗を通知するイベントを確認し、パッケージ、入力ファイル、セットアップコマンドのエラーを修正してから、別のセッションを作成してください。 |
| サンドボックスからのリクエストがブロックされる |
network の設定と、リダイレクト先のホストを確認してください。 |
| 実行中のサンドボックスでファイル操作に失敗する |
サンドボックスのステータスが connected であることを確認してください。有効期限が切れている場合は、新しいセッションを作成して入力ファイルを再度渡してください。 |
ステータスまたはファイル一覧の取得リクエストで 5xx が返される |
再試行の期限を設定し、待機時間を徐々に延ばしながら再試行してください。エラーが続く場合は、リクエスト ID を控えておいてください。 |