/SKILL.md` のような形でディスク上にある場合は、`LocalDir(...)` をそのソースルートに向けたうえで、引き続き `Skills(...)` を使って公開してください。既存のワークスペース契約が別のサンドボックス内レイアウトに依存していない限り、デフォルトの `skills_path=".agents"` を維持してください。
-適合する場合は、組み込み capabilities を優先してください。組み込みで対応できない sandbox 固有のツールや instructions の表面が必要な場合にのみ、カスタム capability を書いてください。
+適合する場合は組み込み機能を優先してください。組み込み機能でカバーされないサンドボックス固有のツールや命令の表面が必要な場合にのみ、カスタム機能を書いてください。
## 概念
### Manifest
-[`Manifest`][agents.sandbox.manifest.Manifest] は、新しい sandbox session のワークスペースを記述します。ワークスペースの `root` を設定し、ファイルやディレクトリを宣言し、ローカルファイルをコピーし、Git リポジトリを clone し、リモートストレージ mount を接続し、環境変数を設定し、ユーザーやグループを定義し、ワークスペース外の特定の絶対 path へのアクセスを許可できます。
+[`Manifest`][agents.sandbox.manifest.Manifest] は、新しいサンドボックスセッション用のワークスペースを記述します。ワークスペース `root` の設定、ファイルやディレクトリの宣言、ローカルファイルのコピー、Git リポジトリのクローン、リモートストレージマウントの接続、環境変数の設定、ユーザーやグループの定義、ワークスペース外の特定の絶対パスへのアクセス付与を行えます。
-Manifest エントリの path はワークスペース相対です。絶対 path にしたり、`..` でワークスペース外へ出たりはできないため、ローカル、Docker、hosted client 間でワークスペース契約の移植性が保たれます。
+Manifest エントリのパスはワークスペース相対です。絶対パスにはできず、`..` によってワークスペース外へ出ることもできません。これにより、ワークスペース契約はローカル、 Docker 、 hosted client 間で移植可能に保たれます。
-作業開始前にエージェントが必要とする資料には manifest エントリを使ってください。
+manifest エントリは、作業開始前にエージェントが必要とする資料に使います。
-| Manifest entry | Use it for |
+| Manifest エントリ | 用途 |
| --- | --- |
-| `File`、`Dir` | 小さな合成入力、補助ファイル、出力ディレクトリ。 |
-| `LocalFile`、`LocalDir` | sandbox 内に materialize すべきホストファイルまたはディレクトリ。 |
-| `GitRepo` | ワークスペースに取得すべきリポジトリ。 |
-| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`S3FilesMount` などの mounts | sandbox 内に表示すべき外部ストレージ。 |
+| `File`、`Dir` | 小さな合成入力、補助ファイル、または出力ディレクトリ。 |
+| `LocalFile`、`LocalDir` | サンドボックス内に実体化すべきホストファイルまたはディレクトリ。 |
+| `GitRepo` | ワークスペースへ取得すべきリポジトリ。 |
+| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` などのマウント | サンドボックス内に現れるべき外部ストレージ。 |
-mount エントリは、どのストレージを公開するかを記述します。mount strategy は、sandbox backend がそのストレージをどのように接続するかを記述します。mount オプションとプロバイダー対応については [Sandbox clients](clients.md#mounts-and-remote-storage) を参照してください。
+マウントエントリは、どのストレージを公開するかを記述します。マウント戦略は、サンドボックスバックエンドがそのストレージをどのように接続するかを記述します。マウントオプションとプロバイダーサポートについては [Sandbox clients](clients.md#mounts-and-remote-storage) を参照してください。
-よい manifest 設計とは通常、ワークスペース契約を狭く保ち、長いタスク手順を `repo/task.md` のようなワークスペースファイルに置き、instructions では `repo/task.md` や `output/report.md` のようにワークスペース相対 path を使うことです。エージェントが `Filesystem` capability の `apply_patch` ツールでファイルを編集する場合、patch path はシェルの `workdir` ではなく sandbox ワークスペースルート相対であることを忘れないでください。
+よい manifest 設計とは通常、ワークスペース契約を狭く保ち、長いタスク手順を `repo/task.md` のようなワークスペースファイルに置き、 instructions では `repo/task.md` や `output/report.md` のように相対ワークスペースパスを使うことです。エージェントが `Filesystem` 機能の `apply_patch` ツールでファイルを編集する場合、パッチパスはシェルの `workdir` ではなく、サンドボックスワークスペースルート相対であることを忘れないでください。
-`extra_path_grants` は、エージェントがワークスペース外の具体的な絶対 path を必要とする場合にのみ使ってください。たとえば、一時的なツール出力のための `/tmp` や、読み取り専用ランタイムのための `/opt/toolchain` などです。grant は、backend がファイルシステムポリシーを適用できる場所では、SDK ファイル API とシェル実行の両方に適用されます。
+`extra_path_grants` は、エージェントがワークスペース外の具体的な絶対パスを必要とする場合にのみ使用してください。たとえば、一時的なツール出力のための `/tmp` や、読み取り専用ランタイムのための `/opt/toolchain` です。付与は、バックエンドがファイルシステムポリシーを強制できる場合、SDK のファイル API とシェル実行の両方に適用されます。
```python
from agents.sandbox import Manifest, SandboxPathGrant
@@ -254,13 +254,13 @@ manifest = Manifest(
)
```
-snapshots と `persist_workspace()` には、引き続きワークスペースルートのみが含まれます。追加で許可された path は実行時アクセスであり、永続的なワークスペース state ではありません。
+スナップショットと `persist_workspace()` に含まれるのは、引き続きワークスペースルートのみです。追加で付与されたパスは実行時アクセスであり、永続的なワークスペース状態ではありません。
### 権限
-`Permissions` は manifest エントリのファイルシステム権限を制御します。これは sandbox が materialize するファイルに関するものであり、モデル権限、approval policy、API 資格情報に関するものではありません。
+`Permissions` は manifest エントリのファイルシステム権限を制御します。これはサンドボックスが実体化するファイルに関するものであり、モデル権限、承認ポリシー、 API 資格情報に関するものではありません。
-デフォルトでは、manifest エントリは owner に対して読み取り、書き込み、実行が可能であり、group と others に対しては読み取りと実行が可能です。ステージングされたファイルを非公開、読み取り専用、または実行可能にしたい場合は、これを上書きしてください。
+デフォルトでは、 manifest エントリは所有者に対して読み取り、書き込み、実行が可能で、グループとその他に対して読み取りと実行が可能です。配置されたファイルを非公開、読み取り専用、または実行可能にすべき場合はこれを上書きします。
```python
from agents.sandbox import FileMode, Permissions
@@ -276,9 +276,9 @@ private_notes = File(
)
```
-`Permissions` は、owner、group、other ごとの個別の bit と、そのエントリがディレクトリかどうかを保持します。直接構築することも、`Permissions.from_str(...)` で mode 文字列から解析することも、`Permissions.from_mode(...)` で OS mode から導出することもできます。
+`Permissions` は、所有者、グループ、その他それぞれのビットと、そのエントリがディレクトリかどうかを別々に保持します。直接構築することも、`Permissions.from_str(...)` でモード文字列から解析することも、`Permissions.from_mode(...)` で OS モードから導出することもできます。
-Users は、作業を実行できる sandbox ID です。その ID を sandbox 内に存在させたい場合は manifest に `User` を追加し、シェルコマンド、ファイル読み取り、patch などのモデル向け sandbox ツールをそのユーザーで実行したい場合は `SandboxAgent.run_as` を設定してください。`run_as` が manifest にまだないユーザーを指している場合、runner はそのユーザーを実効 manifest に自動で追加します。
+ユーザーは、作業を実行できるサンドボックス内の ID です。その ID をサンドボックス内に存在させたい場合は、 manifest に `User` を追加し、シェルコマンド、ファイル読み取り、パッチなどのモデル向けサンドボックスツールをそのユーザーとして実行したい場合は `SandboxAgent.run_as` を設定します。`run_as` が manifest 内にまだ存在しないユーザーを指している場合、ランナーはそのユーザーを実効 manifest に追加します。
```python
from agents import Runner
@@ -330,13 +330,13 @@ result = await Runner.run(
)
```
-ファイルレベルの共有ルールも必要な場合は、users と manifest groups、およびエントリの `group` metadata を組み合わせてください。`run_as` ユーザーは誰が sandbox ネイティブアクションを実行するかを制御し、`Permissions` は sandbox がワークスペースを materialize した後に、そのユーザーがどのファイルを読み取り、書き込み、実行できるかを制御します。
+ファイルレベルの共有ルールも必要な場合は、ユーザーを manifest のグループおよびエントリの `group` メタデータと組み合わせてください。`run_as` ユーザーはサンドボックスネイティブな操作を誰が実行するかを制御し、`Permissions` はサンドボックスがワークスペースを実体化した後に、そのユーザーがどのファイルを読み取り、書き込み、実行できるかを制御します。
### SnapshotSpec
-`SnapshotSpec` は、新しい sandbox session に対して、保存済みワークスペース内容をどこから復元し、どこへ永続化するかを指定します。これは sandbox ワークスペースの snapshot policy であり、`session_state` は特定の sandbox backend を再開するためのシリアライズ済み接続 state です。
+`SnapshotSpec` は、新しいサンドボックスセッションに対して、保存済みワークスペース内容をどこから復元し、どこへ永続化し直すかを指定します。これはサンドボックスワークスペースのスナップショットポリシーであり、`session_state` は特定のサンドボックスバックエンドを再開するためのシリアライズ済み接続状態です。
-ローカルの永続 snapshots には `LocalSnapshotSpec` を使い、アプリが remote snapshot client を提供する場合は `RemoteSnapshotSpec` を使ってください。ローカル snapshot のセットアップが利用できない場合は no-op snapshot が fallback として使われ、ワークスペース snapshot の永続化が不要な高度な呼び出し側はそれを明示的に使うこともできます。
+ローカル永続スナップショットには `LocalSnapshotSpec` を使い、アプリがリモートスナップショットクライアントを提供する場合は `RemoteSnapshotSpec` を使います。ローカルスナップショットのセットアップが利用できない場合は no-op スナップショットがフォールバックとして使用され、ワークスペーススナップショットの永続化を望まない高度な呼び出し元は明示的にそれを使用できます。
```python
from pathlib import Path
@@ -353,13 +353,13 @@ run_config = RunConfig(
)
```
-runner が新しい sandbox session を作成すると、その session 用の snapshot instance が sandbox client によって構築されます。開始時に snapshot が復元可能であれば、sandbox は保存済みワークスペース内容を復元してから実行を続行します。cleanup 時には、runner が所有する sandbox session がワークスペースをアーカイブし、snapshot を通じて再び永続化します。
+ランナーが新しいサンドボックスセッションを作成すると、そのセッション用にサンドボックスクライアントがスナップショットインスタンスを構築します。開始時にスナップショットが復元可能であれば、実行を続行する前にサンドボックスが保存済みワークスペース内容を復元します。クリーンアップ時には、ランナー所有のサンドボックスセッションがワークスペースをアーカイブし、スナップショット経由で再度永続化します。
-`snapshot` を省略すると、ランタイムは可能であればデフォルトのローカル snapshot 保存先を使おうとします。設定できない場合は no-op snapshot に fallback します。mount された path や一時的な path は、永続的なワークスペース内容として snapshots にコピーされません。
+`snapshot` を省略すると、ランタイムは可能な場合にデフォルトのローカルスナップショット保存先を使おうとします。設定できない場合は no-op スナップショットにフォールバックします。マウントされたパスや一時パスは、永続的なワークスペース内容としてスナップショットにコピーされません。
-### sandbox ライフサイクル
+### サンドボックスライフサイクル
-ライフサイクルモードは **SDK 所有** と **開発者所有** の 2 つです。
+ライフサイクルモードは **SDK 所有** と **開発者所有** の 2 種類です。
@@ -387,7 +387,7 @@ sequenceDiagram
-sandbox を 1 回の実行だけ存続させればよい場合は、SDK 所有ライフサイクルを使ってください。`client`、任意の `manifest`、任意の `snapshot`、client の `options` を渡すと、runner が sandbox を作成または再開し、開始し、エージェントを実行し、snapshot-backed なワークスペース state を永続化し、sandbox を停止し、runner 所有リソースを client に cleanup させます。
+サンドボックスを 1 回の実行だけ生かせばよい場合は、SDK 所有ライフサイクルを使用します。`client`、任意の `manifest`、任意の `snapshot`、および client `options` を渡すと、ランナーがサンドボックスを作成または再開し、開始し、エージェントを実行し、スナップショット対応ワークスペース状態を永続化し、サンドボックスを停止し、ランナー所有リソースを client にクリーンアップさせます。
```python
result = await Runner.run(
@@ -399,7 +399,7 @@ result = await Runner.run(
)
```
-sandbox を事前に作成したい、1 つのライブ sandbox を複数実行で再利用したい、実行後にファイルを確認したい、自分で作成した sandbox 上で stream したい、または cleanup のタイミングを厳密に制御したい場合は、開発者所有ライフサイクルを使ってください。`session=...` を渡すと、runner はそのライブ sandbox を使いますが、代わりに閉じることはしません。
+サンドボックスを事前に作成したい場合、1 つのライブサンドボックスを複数回の実行で再利用したい場合、実行後にファイルを確認したい場合、自分で作成したサンドボックス上でストリーミングしたい場合、またはクリーンアップのタイミングを厳密に制御したい場合は、開発者所有ライフサイクルを使用します。`session=...` を渡すと、ランナーはそのライブサンドボックスを使用しますが、ユーザーの代わりに閉じることはしません。
```python
sandbox = await client.create(manifest=agent.default_manifest)
@@ -410,7 +410,7 @@ async with sandbox:
await Runner.run(agent, "Write the final report.", run_config=run_config)
```
-通常の形は context manager です。entry 時に sandbox を開始し、exit 時に session cleanup ライフサイクルを実行します。アプリで context manager を使えない場合は、ライフサイクルメソッドを直接呼び出してください。
+コンテキストマネージャーが通常の形です。エントリ時にサンドボックスを開始し、終了時にセッションのクリーンアップライフサイクルを実行します。アプリでコンテキストマネージャーを使えない場合は、ライフサイクルメソッドを直接呼び出してください。
```python
sandbox = await client.create(
@@ -431,58 +431,58 @@ finally:
await sandbox.aclose()
```
-`stop()` は snapshot-backed なワークスペース内容を永続化するだけで、sandbox 自体は破棄しません。`aclose()` は完全な session cleanup 経路です。pre-stop hooks を実行し、`stop()` を呼び出し、sandbox リソースを停止し、session スコープの依存関係を閉じます。
+`stop()` はスナップショット対応ワークスペース内容を永続化するだけで、サンドボックス自体は破棄しません。`aclose()` は完全なセッションクリーンアップ経路です。停止前フックを実行し、`stop()` を呼び出し、サンドボックスリソースをシャットダウンし、セッションスコープ依存関係を閉じます。
-## `SandboxRunConfig` のオプション
+## `SandboxRunConfig` オプション
-[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、sandbox session の取得元と、新しい session をどのように初期化するかを決める実行ごとのオプションを保持します。
+[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、サンドボックスセッションの取得元と、新しいセッションをどのように初期化するかを決定する実行ごとのオプションを保持します。
-### sandbox の取得元
+### サンドボックス取得元
-これらのオプションは、runner が sandbox session を再利用、再開、または作成するかどうかを決定します。
+これらのオプションは、ランナーがサンドボックスセッションを再利用、再開、または作成すべきかを決定します。
-| Option | Use it when | Notes |
+| オプション | 使用場面 | 注記 |
| --- | --- | --- |
-| `client` | runner に sandbox session の作成、再開、cleanup を任せたい。 | ライブな sandbox `session` を渡さない限り必須です。 |
-| `session` | すでにライブな sandbox session を自分で作成している。 | ライフサイクルは呼び出し側が所有し、runner はそのライブ sandbox session を再利用します。 |
-| `session_state` | シリアライズ済み sandbox session state はあるが、ライブな sandbox session object はない。 | `client` が必要で、runner はその明示的 state から所有 session として再開します。 |
+| `client` | ランナーにサンドボックスセッションの作成、再開、クリーンアップを任せたい場合。 | ライブサンドボックス `session` を提供しない限り必須です。 |
+| `session` | すでに自分でライブサンドボックスセッションを作成している場合。 | ライフサイクルは呼び出し元が所有します。ランナーはそのライブサンドボックスセッションを再利用します。 |
+| `session_state` | サンドボックスセッション状態はシリアライズ済みだが、ライブサンドボックスセッションオブジェクトはない場合。 | `client` が必要です。ランナーはその明示的な状態から所有セッションとして再開します。 |
-実際には、runner は次の順序で sandbox session を解決します。
+実際には、ランナーは次の順序でサンドボックスセッションを解決します。
-1. `run_config.sandbox.session` を注入した場合、そのライブな sandbox session を直接再利用します。
-2. それ以外で、実行が `RunState` から再開される場合は、保存された sandbox session state を再開します。
-3. それ以外で、`run_config.sandbox.session_state` を渡した場合は、その明示的にシリアライズされた sandbox session state から runner が再開します。
-4. それ以外の場合、runner は新しい sandbox session を作成します。その新しい session には、指定があれば `run_config.sandbox.manifest`、なければ `agent.default_manifest` を使います。
+1. `run_config.sandbox.session` を注入した場合、そのライブサンドボックスセッションを直接再利用します。
+2. それ以外で、実行が `RunState` から再開されている場合は、保存済みサンドボックスセッション状態を再開します。
+3. それ以外で、`run_config.sandbox.session_state` を渡した場合、ランナーはその明示的なシリアライズ済みサンドボックスセッション状態から再開します。
+4. それ以外の場合、ランナーは新しいサンドボックスセッションを作成します。その新しいセッションには、`run_config.sandbox.manifest` が指定されていればそれを、なければ `agent.default_manifest` を使用します。
-### 新規 session の入力
+### 新規セッション入力
-これらのオプションは、runner が新しい sandbox session を作成するときにのみ重要です。
+これらのオプションは、ランナーが新しいサンドボックスセッションを作成する場合にのみ重要です。
-| Option | Use it when | Notes |
+| オプション | 使用場面 | 注記 |
| --- | --- | --- |
-| `manifest` | 一度限りの新規 session ワークスペース override が必要。 | 省略時は `agent.default_manifest` に fallback します。 |
-| `snapshot` | 新しい sandbox session を snapshot から初期化すべき。 | 再開に近いフローや remote snapshot client に有用です。 |
-| `options` | sandbox client に作成時オプションが必要。 | Docker image、Modal app 名、E2B template、timeouts など、client 固有設定でよく使われます。 |
+| `manifest` | 1 回限りの新規セッションワークスペース上書きを行いたい場合。 | 省略時は `agent.default_manifest` にフォールバックします。 |
+| `snapshot` | 新しいサンドボックスセッションをスナップショットから初期化したい場合。 | 再開に近いフローやリモートスナップショットクライアントに有用です。 |
+| `options` | サンドボックスクライアントが作成時オプションを必要とする場合。 | Docker イメージ、 Modal アプリ名、 E2B テンプレート、タイムアウトなど、 client 固有設定で一般的です。 |
-### materialization 制御
+### 実体化制御
-`concurrency_limits` は、どれだけの sandbox materialization 作業を並列実行できるかを制御します。大きな manifests やローカルディレクトリのコピーで、より厳密なリソース制御が必要な場合は `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` を使ってください。どちらかの値を `None` にすると、その特定の制限を無効化できます。
+`concurrency_limits` は、どれだけのサンドボックス実体化作業を並列実行できるかを制御します。大きな manifest やローカルディレクトリコピーでリソース制御をより厳密にしたい場合は、`SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` を使用してください。どちらかの値を `None` にすると、その特定の制限は無効になります。
-いくつかの含意を覚えておくとよいです。
+覚えておくべき影響をいくつか挙げます。
-- 新しい session: `manifest=` と `snapshot=` は、runner が新しい sandbox session を作成する場合にのみ適用されます。
-- 再開と snapshot: `session_state=` は以前にシリアライズした sandbox state に再接続するものであり、`snapshot=` は保存済みワークスペース内容から新しい sandbox session を初期化するものです。
-- client 固有オプション: `options=` は sandbox client に依存します。Docker や多くの hosted client では必須です。
-- 注入されたライブ session: 実行中の sandbox `session` を渡した場合、capability による manifest 更新で、互換性のある非 mount エントリを追加できます。ただし `manifest.root`、`manifest.environment`、`manifest.users`、`manifest.groups` を変更したり、既存エントリを削除したり、エントリ型を置き換えたり、mount エントリを追加または変更したりはできません。
-- Runner API: `SandboxAgent` の実行は、引き続き通常の `Runner.run()`、`Runner.run_sync()`、`Runner.run_streamed()` API を使います。
+- 新規セッション: `manifest=` と `snapshot=` は、ランナーが新しいサンドボックスセッションを作成する場合にのみ適用されます。
+- 再開とスナップショット: `session_state=` は以前にシリアライズしたサンドボックス状態へ再接続し、`snapshot=` は保存済みワークスペース内容から新しいサンドボックスセッションを初期化します。
+- client 固有オプション: `options=` はサンドボックスクライアントに依存します。Docker と多くの hosted client では必須です。
+- 注入されたライブセッション: 実行中のサンドボックス `session` を渡した場合、機能主導の manifest 更新では互換性のある非マウントエントリを追加できます。ただし、`manifest.root`、`manifest.environment`、`manifest.users`、`manifest.groups` の変更、既存エントリの削除、エントリ型の置換、マウントエントリの追加や変更はできません。
+- ランナー API: `SandboxAgent` の実行でも、通常の `Runner.run()`、`Runner.run_sync()`、`Runner.run_streamed()` API をそのまま使用します。
## 完全な例: コーディングタスク
@@ -564,19 +564,19 @@ if __name__ == "__main__":
)
```
-[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) を参照してください。この例では、小さなシェルベースのリポジトリを使っているため、Unix ローカル実行全体で決定的に検証できます。もちろん実際のタスクリポジトリは Python、JavaScript、その他何でも構いません。
+[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) を参照してください。この例では、 Unix ローカル実行間で決定的に検証できるよう、小さなシェルベースのリポジトリを使っています。実際のタスクリポジトリはもちろん Python 、 JavaScript 、その他何でも構いません。
## 一般的なパターン
-上記の完全な例から始めてください。多くの場合、同じ `SandboxAgent` はそのままで、sandbox client、sandbox-session の取得元、またはワークスペースの取得元だけを変更できます。
+まずは上の完全な例から始めてください。多くの場合、同じ `SandboxAgent` をそのままにして、サンドボックスクライアント、サンドボックスセッションの取得元、またはワークスペースの取得元だけを変更できます。
-### sandbox client の切り替え
+### サンドボックスクライアントの切り替え
-エージェント定義はそのままにして、run config だけを変更します。コンテナ分離やイメージの一致が必要なら Docker を使い、プロバイダー管理の実行が必要なら hosted provider を使ってください。例とプロバイダーオプションについては [Sandbox clients](clients.md) を参照してください。
+エージェント定義はそのままにして、実行設定だけを変更します。コンテナ分離やイメージの同一性が必要なら Docker を使い、プロバイダー管理の実行が必要なら hosted provider を使ってください。例とプロバイダーオプションについては [Sandbox clients](clients.md) を参照してください。
### ワークスペースの上書き
-エージェント定義はそのままにして、新規 session の manifest だけを差し替えます。
+エージェント定義はそのままにして、新規セッション manifest だけを差し替えます。
```python
from agents.run import RunConfig
@@ -596,11 +596,11 @@ run_config = RunConfig(
)
```
-同じエージェントの役割を、異なるリポジトリ、資料パケット、タスクバンドルに対して、エージェントを作り直さずに実行したい場合に使います。上の検証可能なコーディング例では、一度限りの override の代わりに `default_manifest` を使って同じパターンを示しています。
+これは、同じエージェントの役割を異なるリポジトリ、 packet 、またはタスクバンドルに対して実行したいが、エージェントを再構築したくない場合に使います。上の検証可能なコーディング例では、1 回限りの上書きではなく `default_manifest` で同じパターンを示しています。
-### sandbox session の注入
+### サンドボックスセッションの注入
-明示的なライフサイクル制御、実行後の確認、または出力コピーが必要な場合は、ライブな sandbox session を注入します。
+明示的なライフサイクル制御、実行後の確認、または出力コピーが必要な場合は、ライブサンドボックスセッションを注入します。
```python
from agents import Runner
@@ -621,11 +621,11 @@ async with sandbox:
)
```
-実行後にワークスペースを確認したい場合や、すでに開始済みの sandbox session 上で stream したい場合に使います。[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) と [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。
+これは、実行後にワークスペースを確認したい場合や、すでに開始済みのサンドボックスセッション上でストリーミングしたい場合に使います。[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) と [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。
-### session state からの再開
+### セッション状態からの再開
-すでに `RunState` の外で sandbox state をシリアライズしている場合は、その state から runner に再接続させてください。
+`RunState` の外でサンドボックス状態をすでにシリアライズしている場合は、ランナーにその状態から再接続させます。
```python
from agents.run import RunConfig
@@ -642,11 +642,11 @@ run_config = RunConfig(
)
```
-sandbox state が独自のストレージや job system にあり、`Runner` にそこから直接再開させたい場合に使います。serialize / deserialize の流れについては [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) を参照してください。
+これは、サンドボックス状態が独自のストレージやジョブシステムに保存されていて、`Runner` にそこから直接再開させたい場合に使います。シリアライズ / デシリアライズの流れについては [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) を参照してください。
-### snapshot からの開始
+### スナップショットから開始
-保存済みファイルや成果物から新しい sandbox を初期化します。
+保存済みファイルと成果物から新しいサンドボックスを初期化します。
```python
from pathlib import Path
@@ -663,11 +663,11 @@ run_config = RunConfig(
)
```
-新しい実行を、`agent.default_manifest` だけでなく保存済みワークスペース内容から開始したい場合に使います。ローカル snapshot フローについては [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)、remote snapshot client については [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py) を参照してください。
+これは、新しい実行を `agent.default_manifest` だけでなく、保存済みワークスペース内容から開始したい場合に使います。ローカルスナップショットフローについては [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)、リモートスナップショットクライアントについては [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py) を参照してください。
-### Git から skills を読み込む
+### Git からのスキル読み込み
-ローカル skill source を、リポジトリベースのものに差し替えます。
+ローカルスキルソースを、リポジトリベースのものに差し替えます。
```python
from agents.sandbox.capabilities import Capabilities, Skills
@@ -678,11 +678,11 @@ capabilities = Capabilities.default() + [
]
```
-skills bundle に独自のリリースサイクルがある場合や、複数の sandbox 間で共有したい場合に使います。[examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) を参照してください。
+これは、スキルバンドルに独自のリリースサイクルがある場合や、サンドボックス間で共有すべき場合に使います。[examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) を参照してください。
### ツールとして公開
-tool-agent は、独自の sandbox 境界を持つことも、親実行からライブな sandbox を再利用することもできます。再利用は、高速な読み取り専用 explorer agent に有用です。別の sandbox を作成、hydrate、snapshot するコストを払わずに、親が使っている正確なワークスペースを確認できます。
+ツールエージェントは、独自のサンドボックス境界を持つことも、親実行のライブサンドボックスを再利用することもできます。再利用は、高速な読み取り専用 explorer エージェントに便利です。別のサンドボックスを作成、ハイドレート、スナップショット化するコストを払わずに、親が使っている正確なワークスペースを確認できます。
```python
from agents import Runner
@@ -764,9 +764,9 @@ async with sandbox:
)
```
-ここでは、親エージェントは `coordinator` として実行され、explorer tool-agent は同じライブな sandbox session 内で `explorer` として実行されます。`pricing_packet/` のエントリは `other` ユーザーに対して読み取り可能なので、explorer はそれらを素早く確認できますが、書き込み bit はありません。`work/` ディレクトリは coordinator の user / group にのみ利用可能なので、親は最終成果物を書き込めますが、explorer は読み取り専用のままです。
+ここでは親エージェントは `coordinator` として動作し、 explorer ツールエージェントは同じライブサンドボックスセッション内で `explorer` として動作します。`pricing_packet/` のエントリは `other` ユーザーに対して読み取り可能なので、 explorer はそれらを素早く確認できますが、書き込みビットはありません。`work/` ディレクトリは coordinator のユーザー / グループだけが利用できるため、親は最終成果物を書き込めますが、 explorer は読み取り専用のままです。
-tool-agent に本当の分離が必要な場合は、独自の sandbox `RunConfig` を与えてください。
+ツールエージェントに本当の分離が必要な場合は、独自のサンドボックス `RunConfig` を与えます。
```python
from docker import from_env as docker_from_env
@@ -787,11 +787,11 @@ rollout_agent.as_tool(
)
```
-tool-agent が自由に変更を加えるべき場合、信頼できないコマンドを実行すべき場合、または別の backend / image を使うべき場合は、別の sandbox を使ってください。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。
+ツールエージェントが自由に変更を加える必要がある場合、信頼できないコマンドを実行する場合、または異なるバックエンド / イメージを使う場合は、別のサンドボックスを使用してください。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。
-### ローカルツールおよび MCP との組み合わせ
+### ローカルツールと MCP の併用
-同じエージェント上で通常のツールを使いつつ、sandbox ワークスペースも維持します。
+同じエージェント上で通常のツールを使いつつ、サンドボックスワークスペースも維持します。
```python
from agents.sandbox import SandboxAgent
@@ -806,46 +806,46 @@ agent = SandboxAgent(
)
```
-ワークスペース確認がエージェントの仕事の一部にすぎない場合に使います。[examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py) を参照してください。
+これは、ワークスペース確認がエージェントの仕事の一部にすぎない場合に使います。[examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py) を参照してください。
-## Memory
+## メモリ
-将来の sandbox-agent 実行が過去の実行から学習すべき場合は、`Memory` capability を使ってください。Memory は SDK の会話用 `Session` memory とは別物です。学びを sandbox ワークスペース内のファイルに要約し、後続の実行でそれらのファイルを読み取れるようにします。
+将来の sandbox-agent 実行が過去の実行から学習すべき場合は、`Memory` 機能を使用してください。メモリは SDK の会話用 `Session` メモリとは別物です。教訓をサンドボックスワークスペース内のファイルに抽出し、後続の実行がそれらのファイルを読み取れるようにします。
-セットアップ、読み取り / 生成の動作、複数 turn の会話、レイアウト分離については [Agent memory](memory.md) を参照してください。
+セットアップ、読み取り / 生成挙動、複数ターン会話、レイアウト分離については [Agent memory](memory.md) を参照してください。
## 構成パターン
-単一エージェントのパターンが明確になったら、次の設計上の問いは、より大きなシステムの中で sandbox 境界をどこに置くかです。
+単一エージェントパターンが明確になったら、次の設計上の問いは、より大きなシステムの中でどこにサンドボックス境界を置くかです。
-sandbox agents は、SDK の他の部分とも引き続き組み合わせられます。
+sandbox agents は引き続き SDK の他の部分と組み合わせられます。
-- [Handoffs](../handoffs.md): sandbox でない intake agent から、ドキュメント量の多い作業を sandbox reviewer に handoff します。
-- [Agents as tools](../tools.md#agents-as-tools): 複数の sandbox agent をツールとして公開します。通常は各 `Agent.as_tool(...)` 呼び出しに `run_config=RunConfig(sandbox=SandboxRunConfig(...))` を渡し、各ツールが独自の sandbox 境界を持つようにします。
-- [MCP](../mcp.md) と通常の関数ツール: sandbox capabilities は `mcp_servers` や通常の Python ツールと共存できます。
-- [Running agents](../running_agents.md): sandbox 実行も引き続き通常の `Runner` API を使います。
+- [Handoffs](../handoffs.md): サンドボックスではない intake エージェントから、ドキュメント中心の作業をサンドボックスレビュアーへ hand off します。
+- [Agents as tools](../tools.md#agents-as-tools): 複数の sandbox agents をツールとして公開します。通常は各 `Agent.as_tool(...)` 呼び出しで `run_config=RunConfig(sandbox=SandboxRunConfig(...))` を渡し、各ツールが独自のサンドボックス境界を持つようにします。
+- [MCP](../mcp.md) と通常の関数ツール: サンドボックス機能は `mcp_servers` や通常の Python ツールと共存できます。
+- [Running agents](../running_agents.md): サンドボックス実行でも通常の `Runner` API を使います。
-特によくあるパターンは次の 2 つです。
+特によくあるパターンは 2 つあります。
-- sandbox でないエージェントが、ワークスペース分離が必要なワークフロー部分だけ sandbox agent に handoff する
-- オーケストレーターが複数の sandbox agent をツールとして公開し、通常は各 `Agent.as_tool(...)` 呼び出しごとに別個の sandbox `RunConfig` を使って、各ツールが独自の分離ワークスペースを持つようにする
+- サンドボックスではないエージェントが、ワークスペース分離を必要とする部分だけを sandbox agent に hand off する
+- オーケストレーターが複数の sandbox agents をツールとして公開し、通常は各 `Agent.as_tool(...)` 呼び出しごとに別々のサンドボックス `RunConfig` を使って、各ツールが独自の分離ワークスペースを持つようにする
-### turn と sandbox 実行
+### ターンとサンドボックス実行
-handoff と agent-as-tool の呼び出しは分けて説明すると理解しやすくなります。
+handoff と agent-as-tool 呼び出しは分けて説明すると理解しやすくなります。
-handoff の場合、トップレベルの実行は 1 つで、トップレベルの turn loop も 1 つのままです。アクティブなエージェントは変わりますが、実行はネストしません。sandbox でない intake agent が sandbox reviewer に handoff すると、その同じ実行内の次のモデル呼び出しは sandbox agent 向けに準備され、その sandbox agent が次の turn を担当するエージェントになります。つまり handoff は、同じ実行の次の turn をどのエージェントが担当するかを変えるものです。[examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) を参照してください。
+handoff では、依然として 1 つのトップレベル実行と 1 つのトップレベルターンループがあります。アクティブエージェントは変わりますが、実行がネストされるわけではありません。サンドボックスではない intake エージェントがサンドボックスレビュアーへ hand off すると、その同じ実行内の次のモデル呼び出しはサンドボックスエージェント向けに準備され、そのサンドボックスエージェントが次のターンを担当します。つまり、handoff は同じ実行の次のターンをどのエージェントが担当するかを変えます。[examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) を参照してください。
-`Agent.as_tool(...)` の場合は関係が異なります。外側のオーケストレーターは 1 回の外側 turn を使ってツール呼び出しを決定し、そのツール呼び出しによって sandbox agent のネストされた実行が開始されます。ネストされた実行は独自の turn loop、`max_turns`、approvals、そして通常は独自の sandbox `RunConfig` を持ちます。1 回のネスト turn で終わることもあれば、複数回かかることもあります。外側のオーケストレーターの観点では、そのすべての作業は依然として 1 回のツール呼び出しの背後にあるため、ネストされた turn は外側の実行の turn counter を増やしません。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。
+`Agent.as_tool(...)` では関係が異なります。外側のオーケストレーターは 1 つの外側ターンを使ってツール呼び出しを決定し、そのツール呼び出しが sandbox agent のネストされた実行を開始します。ネストされた実行には独自のターンループ、`max_turns`、承認、そして通常は独自のサンドボックス `RunConfig` があります。1 回のネストされたターンで終わることもあれば、複数回かかることもあります。外側のオーケストレーターから見ると、そのすべての作業は依然として 1 回のツール呼び出しの背後にあるため、ネストされたターンは外側実行のターンカウンターを増やしません。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。
-approval の動作も同じ分割に従います。
+承認の挙動も同じ分割に従います。
-- handoff では、sandbox agent がその実行のアクティブエージェントになるため、approvals は同じトップレベル実行に留まります
-- `Agent.as_tool(...)` では、sandbox tool-agent 内で発生した approvals も外側の実行に現れますが、それらは保存されたネスト実行 state から来るものであり、外側の実行が再開されるとネストされた sandbox 実行も再開されます
+- handoff の場合、サンドボックスエージェントがその実行内でアクティブエージェントになるため、承認は同じトップレベル実行に留まります
+- `Agent.as_tool(...)` の場合、サンドボックスツールエージェント内で発生した承認も外側の実行に表れますが、それらは保存されたネスト実行状態から来るものであり、外側の実行が再開されるとネストされたサンドボックス実行も再開されます
-## 参考資料
+## 参考情報
- [Quickstart](quickstart.md): 1 つの sandbox agent を動かします。
-- [Sandbox clients](clients.md): ローカル、Docker、hosted、mount のオプションを選びます。
-- [Agent memory](memory.md): 過去の sandbox 実行から得た学びを保存して再利用します。
-- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 実行可能なローカル、コーディング、memory、handoff、エージェント構成パターンです。
\ No newline at end of file
+- [Sandbox clients](clients.md): ローカル、 Docker 、 hosted 、マウントオプションを選びます。
+- [Agent memory](memory.md): 以前のサンドボックス実行から得た教訓を保持し、再利用します。
+- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 実行可能なローカル、コーディング、メモリ、 handoff 、エージェント構成パターンです。
\ No newline at end of file
diff --git a/docs/ko/sandbox/clients.md b/docs/ko/sandbox/clients.md
index b549608119..4d9b3e1f83 100644
--- a/docs/ko/sandbox/clients.md
+++ b/docs/ko/sandbox/clients.md
@@ -4,38 +4,38 @@ search:
---
# 샌드박스 클라이언트
-이 페이지를 사용하여 샌드박스 작업을 어디에서 실행할지 선택하세요. 대부분의 경우 `SandboxAgent` 정의는 그대로 유지되고, 샌드박스 클라이언트와 클라이언트별 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경됩니다.
+이 페이지를 사용해 샌드박스 작업을 어디에서 실행할지 선택하세요. 대부분의 경우 `SandboxAgent` 정의는 동일하게 유지되고, 샌드박스 클라이언트와 클라이언트별 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경됩니다.
!!! warning "베타 기능"
- 샌드박스 에이전트는 베타입니다. 정식 출시 전에는 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
+ 샌드박스 에이전트는 베타입니다. 정식 출시 전까지 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
## 선택 가이드
-| 목표 | 시작 대상 | 이유 |
+| 목표 | 시작점 | 이유 |
| --- | --- | --- |
-| macOS 또는 Linux에서 가장 빠른 로컬 반복 작업 | `UnixLocalSandboxClient` | 추가 설치가 필요 없고, 로컬 파일시스템 개발이 단순합니다 |
-| 기본적인 컨테이너 격리 | `DockerSandboxClient` | 특정 이미지로 Docker 내부에서 작업을 실행합니다 |
-| 호스티드 실행 또는 프로덕션 수준 격리 | 호스티드 샌드박스 클라이언트 | 작업공간 경계를 제공업체가 관리하는 환경으로 옮깁니다 |
+| macOS 또는 Linux에서 가장 빠른 로컬 반복 작업 | `UnixLocalSandboxClient` | 추가 설치가 필요 없고, 로컬 파일시스템 개발이 간단합니다. |
+| 기본적인 컨테이너 격리 | `DockerSandboxClient` | 특정 이미지를 사용해 Docker 내부에서 작업을 실행합니다. |
+| 호스팅 실행 또는 프로덕션 수준 격리 | 호스팅 샌드박스 클라이언트 | 작업공간 경계를 공급자가 관리하는 환경으로 옮깁니다. |
## 로컬 클라이언트
-대부분의 사용자는 다음 두 샌드박스 클라이언트 중 하나로 시작하면 됩니다.
+대부분의 사용자에게는 다음 두 가지 샌드박스 클라이언트 중 하나로 시작하는 것을 권장합니다.
-| 클라이언트 | 설치 | 이 경우 선택 | 예제 |
+| 클라이언트 | 설치 | 이런 경우 선택 | 예제 |
| --- | --- | --- | --- |
-| `UnixLocalSandboxClient` | 없음 | macOS 또는 Linux에서 가장 빠른 로컬 반복 작업이 필요할 때. 로컬 개발의 좋은 기본값입니다 | [Unix-local 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) |
-| `DockerSandboxClient` | `openai-agents[docker]` | 로컬 환경 일치를 위해 컨테이너 격리나 특정 이미지가 필요할 때 | [Docker 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |
+| `UnixLocalSandboxClient` | 없음 | macOS 또는 Linux에서 가장 빠른 로컬 반복 작업이 필요할 때. 로컬 개발에 좋은 기본값입니다. | [Unix-local 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) |
+| `DockerSandboxClient` | `openai-agents[docker]` | 컨테이너 격리 또는 로컬 환경 일치를 위한 특정 이미지가 필요할 때 | [Docker 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |
-Unix-local은 로컬 파일시스템을 대상으로 개발을 시작하는 가장 쉬운 방법입니다. 더 강한 환경 격리나 프로덕션 수준의 환경 일치가 필요하면 Docker 또는 호스티드 제공업체로 이동하세요.
+Unix-local은 로컬 파일시스템을 대상으로 개발을 시작하는 가장 쉬운 방법입니다. 더 강력한 환경 격리나 프로덕션 수준의 환경 일치가 필요하면 Docker 또는 호스팅 공급자로 이동하세요.
Unix-local에서 Docker로 전환하려면 에이전트 정의는 그대로 두고 실행 구성만 변경하면 됩니다.
@@ -58,37 +58,37 @@ run_config = RunConfig(
## 마운트와 원격 스토리지
-마운트 항목은 어떤 스토리지를 노출할지 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 어떻게 연결할지 설명합니다. 내장 마운트 항목과 일반 전략은 `agents.sandbox.entries`에서 import하세요. 호스티드 제공업체 전략은 `agents.extensions.sandbox` 또는 제공업체별 확장 패키지에서 사용할 수 있습니다.
+마운트 항목은 어떤 스토리지를 노출할지 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 어떻게 연결할지 설명합니다. 내장 마운트 항목과 일반 전략은 `agents.sandbox.entries`에서 가져오세요. 호스팅 공급자 전략은 `agents.extensions.sandbox` 또는 공급자별 확장 패키지에서 사용할 수 있습니다.
일반적인 마운트 옵션:
-- `mount_path`: 스토리지가 샌드박스 내에서 표시되는 위치입니다. 상대 경로는 매니페스트 루트 아래에서 해석되고, 절대 경로는 그대로 사용됩니다
-- `read_only`: 기본값은 `True`입니다. 샌드박스가 마운트된 스토리지에 다시 써야 하는 경우에만 `False`로 설정하세요
-- `mount_strategy`: 필수입니다. 마운트 항목과 샌드박스 백엔드 둘 다에 맞는 전략을 사용하세요
+- `mount_path`: 샌드박스에서 스토리지가 나타나는 위치입니다. 상대 경로는 매니페스트 루트 아래에서 해석되고, 절대 경로는 그대로 사용됩니다.
+- `read_only`: 기본값은 `True`입니다. 샌드박스가 마운트된 스토리지에 다시 써야 하는 경우에만 `False`로 설정하세요.
+- `mount_strategy`: 필수입니다. 마운트 항목과 샌드박스 백엔드 모두에 맞는 전략을 사용하세요.
-마운트는 임시 작업공간 항목으로 처리됩니다. 스냅샷 및 영속성 흐름에서는 저장된 작업공간에 마운트된 원격 스토리지를 복사하는 대신, 마운트된 경로를 분리하거나 건너뜁니다.
+마운트는 일시적인 작업공간 항목으로 처리됩니다. 스냅샷 및 영속화 흐름에서는 마운트된 원격 스토리지를 저장된 작업공간에 복사하는 대신, 마운트된 경로를 분리하거나 건너뜁니다.
일반 로컬/컨테이너 전략:
-| 전략 또는 패턴 | 이 경우 사용 | 참고 |
+| 전략 또는 패턴 | 사용 시점 | 참고 |
| --- | --- | --- |
-| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | 샌드박스 이미지에서 `rclone`을 실행할 수 있을 때 | S3, GCS, R2, Azure Blob을 지원합니다. `RcloneMountPattern`은 `fuse` 모드 또는 `nfs` 모드로 실행할 수 있습니다 |
-| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 이미지에 `mount-s3`가 있고 Mountpoint 스타일의 S3 또는 S3 호환 액세스가 필요할 때 | `S3Mount` 및 `GCSMount`를 지원합니다 |
-| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 이미지에 `blobfuse2`와 FUSE 지원이 있을 때 | `AzureBlobMount`를 지원합니다 |
-| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 이미지에 `mount.s3files`가 있고 기존 S3 Files 마운트 대상에 연결할 수 있을 때 | `S3FilesMount`를 지원합니다 |
-| `DockerVolumeMountStrategy(driver=...)` | 컨테이너 시작 전에 Docker가 볼륨 드라이버 기반 마운트를 연결해야 할 때 | Docker 전용입니다. S3, GCS, R2, Azure Blob은 `rclone`을 지원하고, S3와 GCS는 `mountpoint`도 지원합니다 |
+| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | 샌드박스 이미지에서 `rclone`을 실행할 수 있을 때 | S3, GCS, R2, Azure Blob, Box를 지원합니다. `RcloneMountPattern`은 `fuse` 모드 또는 `nfs` 모드로 실행할 수 있습니다. |
+| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 이미지에 `mount-s3`가 있고 Mountpoint 방식의 S3 또는 S3 호환 액세스를 원할 때 | `S3Mount`와 `GCSMount`를 지원합니다. |
+| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 이미지에 `blobfuse2`와 FUSE 지원이 있을 때 | `AzureBlobMount`를 지원합니다. |
+| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 이미지에 `mount.s3files`가 있고 기존 S3 Files 마운트 대상에 접근할 수 있을 때 | `S3FilesMount`를 지원합니다. |
+| `DockerVolumeMountStrategy(driver=...)` | Docker가 컨테이너 시작 전에 볼륨 드라이버 기반 마운트를 연결해야 할 때 | Docker 전용입니다. S3, GCS, R2, Azure Blob, Box는 `rclone`을 지원하며, S3와 GCS는 `mountpoint`도 지원합니다. |
-## 지원되는 호스티드 플랫폼
+## 지원되는 호스팅 플랫폼
-호스티드 환경이 필요할 때도 일반적으로 동일한 `SandboxAgent` 정의를 그대로 사용할 수 있으며, [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트만 변경하면 됩니다.
+호스팅 환경이 필요할 때는 동일한 `SandboxAgent` 정의를 그대로 사용할 수 있으며, 일반적으로 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트만 변경하면 됩니다.
-이 저장소 체크아웃 대신 공개된 SDK를 사용 중이라면, 일치하는 패키지 extra를 통해 샌드박스 클라이언트 의존성을 설치하세요.
+이 저장소 체크아웃이 아니라 배포된 SDK를 사용 중이라면, 일치하는 패키지 extra를 통해 샌드박스 클라이언트 의존성을 설치하세요.
-제공업체별 설정 참고 사항과 저장소에 포함된 확장 예제 링크는 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)를 참고하세요.
+공급자별 설정 참고 사항과 저장소에 포함된 확장 예제 링크는 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)를 참고하세요.
@@ -104,20 +104,20 @@ run_config = RunConfig(
-호스티드 샌드박스 클라이언트는 제공업체별 마운트 전략을 제공합니다. 스토리지 제공업체에 가장 적합한 백엔드와 마운트 전략을 선택하세요.
+호스팅 샌드박스 클라이언트는 공급자별 마운트 전략을 제공합니다. 스토리지 공급자에 가장 적합한 백엔드와 마운트 전략을 선택하세요.
| 백엔드 | 마운트 참고 사항 |
| --- | --- |
-| Docker | `InContainerMountStrategy` 및 `DockerVolumeMountStrategy`와 같은 로컬 전략으로 `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `S3FilesMount`를 지원합니다 |
-| `ModalSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증 `GCSMount`에 대해 `ModalCloudBucketMountStrategy`를 사용한 Modal 클라우드 버킷 마운트를 지원합니다. 인라인 자격 증명 또는 이름이 지정된 Modal Secret을 사용할 수 있습니다 |
-| `CloudflareSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증 `GCSMount`에 대해 `CloudflareBucketMountStrategy`를 사용한 Cloudflare 버킷 마운트를 지원합니다 |
-| `BlaxelSandboxClient` | `S3Mount`, `R2Mount`, `GCSMount`에 대해 `BlaxelCloudBucketMountStrategy`를 사용한 클라우드 버킷 마운트를 지원합니다. 또한 `agents.extensions.sandbox.blaxel`의 `BlaxelDriveMount`와 `BlaxelDriveMountStrategy`를 사용한 영구 Blaxel Drive도 지원합니다 |
-| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy`를 사용한 클라우드 버킷 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`와 함께 사용하세요 |
-| `E2BSandboxClient` | `E2BCloudBucketMountStrategy`를 사용한 클라우드 버킷 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`와 함께 사용하세요 |
-| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy`를 사용한 클라우드 버킷 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`와 함께 사용하세요 |
-| `VercelSandboxClient` | 현재 호스티드 전용 마운트 전략이 노출되어 있지 않습니다. 대신 매니페스트 파일, 저장소, 또는 다른 작업공간 입력을 사용하세요 |
+| Docker | `InContainerMountStrategy` 및 `DockerVolumeMountStrategy`와 같은 로컬 전략을 사용해 `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount`를 지원합니다. |
+| `ModalSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증된 `GCSMount`에서 `ModalCloudBucketMountStrategy`를 사용한 Modal 클라우드 버킷 마운트를 지원합니다. 인라인 자격 증명 또는 이름 있는 Modal Secret을 사용할 수 있습니다. |
+| `CloudflareSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증된 `GCSMount`에서 `CloudflareBucketMountStrategy`를 사용한 Cloudflare 버킷 마운트를 지원합니다. |
+| `BlaxelSandboxClient` | `S3Mount`, `R2Mount`, `GCSMount`에서 `BlaxelCloudBucketMountStrategy`를 사용한 클라우드 버킷 마운트를 지원합니다. 또한 `agents.extensions.sandbox.blaxel`의 `BlaxelDriveMount` 및 `BlaxelDriveMountStrategy`를 사용한 영구 Blaxel Drive도 지원합니다. |
+| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy`를 사용한 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
+| `E2BSandboxClient` | `E2BCloudBucketMountStrategy`를 사용한 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
+| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy`를 사용한 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
+| `VercelSandboxClient` | 현재 호스팅 전용 마운트 전략이 노출되어 있지 않습니다. 대신 매니페스트 파일, 저장소 또는 기타 작업공간 입력을 사용하세요. |
@@ -125,17 +125,17 @@ run_config = RunConfig(
-| 백엔드 | AWS S3 | Cloudflare R2 | GCS | Azure Blob Storage | S3 Files |
-| --- | --- | --- | --- | --- | --- |
-| Docker | ✓ | ✓ | ✓ | ✓ | ✓ |
-| `ModalSandboxClient` | ✓ | ✓ | ✓ | - | - |
-| `CloudflareSandboxClient` | ✓ | ✓ | ✓ | - | - |
-| `BlaxelSandboxClient` | ✓ | ✓ | ✓ | - | - |
-| `DaytonaSandboxClient` | ✓ | ✓ | ✓ | ✓ | - |
-| `E2BSandboxClient` | ✓ | ✓ | ✓ | ✓ | - |
-| `RunloopSandboxClient` | ✓ | ✓ | ✓ | ✓ | - |
-| `VercelSandboxClient` | - | - | - | - | - |
+| 백엔드 | AWS S3 | Cloudflare R2 | GCS | Azure Blob Storage | Box | S3 Files |
+| --- | --- | --- | --- | --- | --- | --- |
+| Docker | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `ModalSandboxClient` | ✓ | ✓ | ✓ | - | - | - |
+| `CloudflareSandboxClient` | ✓ | ✓ | ✓ | - | - | - |
+| `BlaxelSandboxClient` | ✓ | ✓ | ✓ | - | - | - |
+| `DaytonaSandboxClient` | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| `E2BSandboxClient` | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| `RunloopSandboxClient` | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| `VercelSandboxClient` | - | - | - | - | - | - |
-더 많은 실행 가능한 예제는 로컬, 코딩, 메모리, 핸드오프, 에이전트 구성 패턴에 대해서는 [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)을, 호스티드 샌드박스 클라이언트에 대해서는 [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)를 살펴보세요.
\ No newline at end of file
+실행 가능한 예제를 더 보려면 로컬, 코딩, 메모리, 핸드오프, 에이전트 구성 패턴은 [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)를, 호스팅 샌드박스 클라이언트는 [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)를 살펴보세요.
\ No newline at end of file
diff --git a/docs/ko/sandbox/guide.md b/docs/ko/sandbox/guide.md
index 5d35d308d1..727ab59479 100644
--- a/docs/ko/sandbox/guide.md
+++ b/docs/ko/sandbox/guide.md
@@ -6,35 +6,35 @@ search:
!!! warning "베타 기능"
- 샌드박스 에이전트는 베타입니다. 정식 출시 전까지 API, 기본값, 지원 기능의 세부 사항이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
+ Sandbox Agents는 베타입니다. 정식 출시 전에 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
-현대적인 에이전트는 파일시스템의 실제 파일에서 작업할 수 있을 때 가장 잘 작동합니다. **Sandbox Agents**는 특수 도구와 셸 명령을 활용해 대규모 문서 집합을 검색하고 조작하며, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 모델에 지속적인 워크스페이스를 제공하며, 에이전트는 이를 사용해 사용자를 대신해 작업할 수 있습니다. Agents SDK의 샌드박스 에이전트는 샌드박스 환경과 연결된 에이전트를 쉽게 실행할 수 있도록 도와주며, 파일시스템에 올바른 파일을 손쉽게 배치하고, 샌드박스를 오케스트레이션하여 대규모로 작업을 시작, 중지, 재개하기 쉽게 만듭니다.
+최신 에이전트는 파일시스템의 실제 파일에서 작업할 수 있을 때 가장 잘 동작합니다. **Sandbox Agents**는 특화된 도구와 셸 명령을 사용해 대규모 문서 세트를 검색하고 조작하며, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 모델에 지속적인 워크스페이스를 제공하며, 에이전트는 이를 사용해 사용자를 대신해 작업을 수행할 수 있습니다. Agents SDK의 Sandbox Agents는 샌드박스 환경과 연결된 에이전트를 쉽게 실행할 수 있도록 도와주며, 파일시스템에 올바른 파일을 쉽게 배치하고, 대규모로 작업을 시작, 중지, 재개하기 쉽도록 샌드박스를 오케스트레이션할 수 있게 해줍니다.
-사용자는 에이전트에 필요한 데이터를 중심으로 워크스페이스를 정의합니다. GitHub 리포지토리, 로컬 파일과 디렉터리, 합성 작업 파일, S3나 Azure Blob Storage 같은 원격 파일시스템, 그리고 사용자가 제공하는 기타 샌드박스 입력에서 시작할 수 있습니다.
+워크스페이스는 에이전트가 필요로 하는 데이터를 중심으로 정의합니다. GitHub 리포지토리, 로컬 파일 및 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일시스템, 그리고 사용자가 제공하는 기타 샌드박스 입력에서 시작할 수 있습니다.
-
+
-`SandboxAgent`는 여전히 `Agent`입니다. `instructions`, `prompt`, `tools`, `handoffs`, `mcp_servers`, `model_settings`, `output_type`, 가드레일, 훅 등 일반적인 에이전트 표면은 그대로 유지하며, 일반 `Runner` API를 통해 실행됩니다. 달라지는 점은 실행 경계입니다.
+`SandboxAgent`는 여전히 `Agent`입니다. `instructions`, `prompt`, `tools`, `handoffs`, `mcp_servers`, `model_settings`, `output_type`, 가드레일, hooks 같은 일반적인 에이전트 표면을 그대로 유지하며, 여전히 일반적인 `Runner` API를 통해 실행됩니다. 달라지는 것은 실행 경계입니다.
-- `SandboxAgent`는 에이전트 자체를 정의합니다. 즉, 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스 전용 기본값과 파일시스템 도구, 셸 접근, 스킬, 메모리, 컴팩션 같은 기능을 포함합니다
-- `Manifest`는 파일, 리포지토리, 마운트, 환경을 포함해 새로운 샌드박스 워크스페이스의 원하는 시작 콘텐츠와 레이아웃을 선언합니다
-- 샌드박스 세션은 명령이 실행되고 파일이 변경되는 실제 격리 환경입니다
-- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 실행이 샌드박스 세션을 어떻게 얻을지 결정합니다. 예를 들어 세션을 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 다시 연결하거나, 샌드박스 클라이언트를 통해 새 샌드박스 세션을 생성할 수 있습니다
-- 저장된 샌드박스 상태와 스냅샷을 사용하면 이후 실행에서 이전 작업에 다시 연결하거나 저장된 콘텐츠를 기반으로 새로운 샌드박스 세션을 시드할 수 있습니다
+- `SandboxAgent`는 에이전트 자체를 정의합니다. 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스 전용 기본값과 파일시스템 도구, 셸 접근, 스킬, 메모리, 컴팩션 같은 기능을 포함합니다.
+- `Manifest`는 새 샌드박스 워크스페이스의 원하는 초기 콘텐츠와 레이아웃을 선언하며, 파일, 리포지토리, 마운트, 환경을 포함합니다.
+- 샌드박스 세션은 명령이 실행되고 파일이 변경되는 라이브 격리 환경입니다.
+- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 실행이 해당 샌드박스 세션을 어떻게 얻는지 결정합니다. 예를 들어 세션을 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 다시 연결하거나, 샌드박스 클라이언트를 통해 새로운 샌드박스 세션을 생성할 수 있습니다.
+- 저장된 샌드박스 상태와 스냅샷을 사용하면 이후 실행에서 이전 작업에 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 초기화할 수 있습니다.
-`Manifest`는 새 세션 워크스페이스 계약이지, 모든 실제 샌드박스의 전체 진실 소스는 아닙니다. 실행의 유효 워크스페이스는 대신 재사용된 샌드박스 세션, 직렬화된 샌드박스 세션 상태, 또는 실행 시점에 선택된 스냅샷에서 올 수 있습니다.
+`Manifest`는 새 세션 워크스페이스 계약이지, 모든 라이브 샌드박스의 전체 단일 진실 공급원은 아닙니다. 실행의 실제 워크스페이스는 재사용된 샌드박스 세션, 직렬화된 샌드박스 세션 상태, 또는 실행 시점에 선택된 스냅샷에서 대신 올 수 있습니다.
-이 페이지 전체에서 "샌드박스 세션"은 샌드박스 클라이언트가 관리하는 실제 실행 환경을 의미합니다. 이는 [Sessions](../sessions/index.md)에서 설명하는 SDK의 대화형 [`Session`][agents.memory.session.Session] 인터페이스와는 다릅니다.
+이 페이지 전체에서 "샌드박스 세션"은 샌드박스 클라이언트가 관리하는 라이브 실행 환경을 의미합니다. 이는 [Sessions](../sessions/index.md)에서 설명하는 SDK의 대화형 [`Session`][agents.memory.session.Session] 인터페이스와는 다릅니다.
-바깥쪽 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 bookkeeping을 담당합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 담당합니다. 이 분리는 모델의 핵심 요소입니다.
+바깥쪽 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 bookkeeping을 담당합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 담당합니다. 이러한 분리는 모델의 핵심 요소입니다.
### 구성 요소의 결합 방식
-샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성의 조합입니다. 러너는 에이전트를 준비하고, 이를 실제 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다.
+샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. 러너는 에이전트를 준비하고, 이를 라이브 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다.
```mermaid
flowchart LR
@@ -54,89 +54,89 @@ flowchart LR
수명 주기는 세 단계로 생각하면 됩니다.
-1. `SandboxAgent`, `Manifest`, 기능으로 에이전트와 새 워크스페이스 계약을 정의합니다
-2. 샌드박스 세션을 주입, 재개 또는 생성하는 `SandboxRunConfig`를 `Runner`에 제공해 실행합니다
-3. 러너가 관리하는 `RunState`, 명시적 샌드박스 `session_state`, 또는 저장된 워크스페이스 스냅샷에서 나중에 이어서 작업합니다
+1. `SandboxAgent`, `Manifest`, 기능을 사용해 에이전트와 새 워크스페이스 계약을 정의합니다.
+2. 샌드박스 세션을 주입, 재개 또는 생성하는 `SandboxRunConfig`를 `Runner`에 제공하여 실행합니다.
+3. 러너가 관리하는 `RunState`, 명시적 샌드박스 `session_state`, 또는 저장된 워크스페이스 스냅샷에서 나중에 이어서 작업합니다.
-셸 접근이 가끔 필요한 하나의 도구일 뿐이라면 [도구 가이드](../tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요.
+셸 접근이 가끔 사용하는 단일 도구일 뿐이라면 [tools guide](../tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요.
## 사용 시점
샌드박스 에이전트는 워크스페이스 중심 워크플로에 적합합니다. 예를 들면 다음과 같습니다.
-- 코딩 및 디버깅: 예를 들어 GitHub 리포지토리의 이슈 리포트에 대한 자동 수정 작업을 에이전트 오케스트레이션하고 대상 테스트를 실행하는 경우
-- 문서 처리 및 편집: 예를 들어 사용자의 재무 문서에서 정보를 추출하고 작성 완료된 세금 신고서 초안을 만드는 경우
-- 파일 기반 검토 또는 분석: 예를 들어 답변 전에 온보딩 패킷, 생성된 보고서, 또는 아티팩트 번들을 점검하는 경우
-- 격리된 멀티 에이전트 패턴: 예를 들어 각 검토자 또는 코딩 하위 에이전트에 자체 워크스페이스를 제공하는 경우
-- 다단계 워크스페이스 작업: 예를 들어 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개하는 경우
+- 코딩과 디버깅, 예를 들어 GitHub 리포지토리의 이슈 리포트에 대한 자동 수정 작업을 에이전트 오케스트레이션하고 대상 테스트를 실행하는 경우
+- 문서 처리 및 편집, 예를 들어 사용자의 금융 문서에서 정보를 추출하고 작성 완료된 세금 양식 초안을 생성하는 경우
+- 파일 기반 검토 또는 분석, 예를 들어 온보딩 패킷, 생성된 보고서, 또는 아티팩트 번들을 확인한 후 응답하는 경우
+- 격리된 멀티 에이전트 패턴, 예를 들어 각 검토자 또는 코딩 하위 에이전트에 자체 워크스페이스를 제공하는 경우
+- 다단계 워크스페이스 작업, 예를 들어 한 번의 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개하는 경우
파일이나 살아 있는 파일시스템에 접근할 필요가 없다면 계속 `Agent`를 사용하세요. 셸 접근이 가끔 필요한 기능일 뿐이라면 호스티드 셸을 추가하고, 워크스페이스 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요.
## 샌드박스 클라이언트 선택
-로컬 개발에는 `UnixLocalSandboxClient`부터 시작하세요. 컨테이너 격리나 이미지 동일성이 필요하면 `DockerSandboxClient`로 이동하세요. 공급자가 관리하는 실행이 필요하면 호스티드 공급자로 이동하세요.
+로컬 개발은 `UnixLocalSandboxClient`로 시작하세요. 컨테이너 격리 또는 이미지 일치가 필요하면 `DockerSandboxClient`로 전환하세요. 공급자 관리 실행이 필요하면 호스티드 공급자로 전환하세요.
-대부분의 경우 `SandboxAgent` 정의는 그대로 유지되고, 샌드박스 클라이언트와 그 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경됩니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요.
+대부분의 경우 `SandboxAgent` 정의는 그대로 유지되고, 샌드박스 클라이언트와 그 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경됩니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [Sandbox clients](clients.md)를 참고하세요.
## 핵심 구성 요소
-| 레이어 | 주요 SDK 구성 요소 | 답하는 질문 |
+| 계층 | 주요 SDK 구성 요소 | 답하는 질문 |
| --- | --- | --- |
-| 에이전트 정의 | `SandboxAgent`, `Manifest`, 기능 | 어떤 에이전트가 실행되며, 어떤 새 세션 워크스페이스 계약에서 시작해야 할까요? |
-| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 실제 샌드박스 세션 | 이 실행은 실제 샌드박스 세션을 어떻게 얻으며, 작업은 어디서 실행될까요? |
-| 저장된 샌드박스 상태 | `RunState` 샌드박스 페이로드, `session_state`, 스냅샷 | 이 워크플로는 이전 샌드박스 작업에 어떻게 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 어떻게 시드할까요? |
+| 에이전트 정의 | `SandboxAgent`, `Manifest`, 기능 | 어떤 에이전트가 실행되며, 어떤 새 세션 워크스페이스 계약에서 시작해야 하는가? |
+| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 라이브 샌드박스 세션 | 이 실행은 라이브 샌드박스 세션을 어떻게 얻고, 작업은 어디서 실행되는가? |
+| 저장된 샌드박스 상태 | `RunState` 샌드박스 payload, `session_state`, 스냅샷 | 이 워크플로는 이전 샌드박스 작업에 어떻게 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 초기화하는가? |
-주요 SDK 구성 요소는 다음과 같이 해당 레이어에 매핑됩니다.
+주요 SDK 구성 요소는 다음과 같이 이 계층에 매핑됩니다.
-| 구성 요소 | 담당 영역 | 던질 질문 |
+| 구성 요소 | 담당 범위 | 스스로에게 물어볼 질문 |
| --- | --- | --- |
-| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 에이전트 정의 | 이 에이전트는 무엇을 해야 하며, 어떤 기본값이 함께 따라가야 할까요? |
-| [`Manifest`][agents.sandbox.manifest.Manifest] | 새 세션 워크스페이스 파일 및 폴더 | 실행이 시작될 때 파일시스템에 어떤 파일과 폴더가 있어야 할까요? |
-| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 샌드박스 네이티브 동작 | 어떤 도구, instruction 조각, 런타임 동작이 이 에이전트에 연결되어야 할까요? |
-| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 실행별 샌드박스 클라이언트 및 샌드박스 세션 소스 | 이 실행은 샌드박스 세션을 주입, 재개, 생성해야 할까요? |
-| [`RunState`][agents.run_state.RunState] | 러너가 관리하는 저장된 샌드박스 상태 | 이전에 러너가 관리하던 워크플로를 재개하면서 샌드박스 상태를 자동으로 이어받고 있나요? |
-| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 명시적으로 직렬화된 샌드박스 세션 상태 | 이미 `RunState` 외부에서 직렬화한 샌드박스 상태에서 재개하고 싶나요? |
-| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 새 샌드박스 세션용 저장된 워크스페이스 콘텐츠 | 새 샌드박스 세션이 저장된 파일과 아티팩트에서 시작해야 하나요? |
+| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 에이전트 정의 | 이 에이전트는 무엇을 해야 하며, 어떤 기본값이 함께 따라가야 하는가? |
+| [`Manifest`][agents.sandbox.manifest.Manifest] | 새 세션 워크스페이스 파일 및 폴더 | 실행이 시작될 때 파일시스템에 어떤 파일과 폴더가 있어야 하는가? |
+| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 샌드박스 고유 동작 | 어떤 도구, 지시문 조각, 또는 런타임 동작을 이 에이전트에 연결해야 하는가? |
+| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 실행별 샌드박스 클라이언트 및 샌드박스 세션 소스 | 이 실행은 샌드박스 세션을 주입, 재개, 생성해야 하는가? |
+| [`RunState`][agents.run_state.RunState] | 러너가 관리하는 저장된 샌드박스 상태 | 이전에 러너가 관리하던 워크플로를 재개하면서 샌드박스 상태를 자동으로 이어받고 있는가? |
+| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 명시적으로 직렬화된 샌드박스 세션 상태 | `RunState` 외부에서 이미 직렬화한 샌드박스 상태에서 재개하고 싶은가? |
+| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 새 샌드박스 세션용 저장된 워크스페이스 콘텐츠 | 새 샌드박스 세션을 저장된 파일과 아티팩트에서 시작해야 하는가? |
실용적인 설계 순서는 다음과 같습니다.
-1. `Manifest`로 새 세션 워크스페이스 계약을 정의합니다
-2. `SandboxAgent`로 에이전트를 정의합니다
-3. 내장 또는 사용자 정의 기능을 추가합니다
-4. `RunConfig(sandbox=SandboxRunConfig(...))`에서 각 실행이 샌드박스 세션을 어떻게 얻을지 결정합니다
+1. `Manifest`로 새 세션 워크스페이스 계약을 정의합니다.
+2. `SandboxAgent`로 에이전트를 정의합니다.
+3. 내장 또는 사용자 정의 기능을 추가합니다.
+4. 각 실행이 샌드박스 세션을 어떻게 얻을지 `RunConfig(sandbox=SandboxRunConfig(...))`에서 결정합니다.
## 샌드박스 실행 준비 방식
-실행 시점에 러너는 이 정의를 구체적인 샌드박스 기반 실행으로 바꿉니다.
+실행 시점에 러너는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다.
-1. `SandboxRunConfig`에서 샌드박스 세션을 해석합니다
- `session=...`을 전달하면 해당 실제 샌드박스 세션을 재사용합니다
- 그렇지 않으면 `client=...`를 사용해 생성하거나 재개합니다
-2. 실행의 유효 워크스페이스 입력을 결정합니다
- 실행이 샌드박스 세션을 주입하거나 재개하는 경우, 기존 샌드박스 상태가 우선합니다
- 그렇지 않으면 러너는 일회성 manifest 재정의 또는 `agent.default_manifest`에서 시작합니다
- 이것이 `Manifest`만으로는 모든 실행의 최종 실제 워크스페이스를 정의하지 못하는 이유입니다
-3. 기능이 결과 manifest를 처리하도록 합니다
- 이를 통해 기능은 최종 에이전트가 준비되기 전에 파일, 마운트 또는 기타 워크스페이스 범위 동작을 추가할 수 있습니다
-4. 최종 instructions를 고정된 순서로 구성합니다
- SDK의 기본 샌드박스 프롬프트 또는 명시적으로 재정의한 경우 `base_instructions`, 그다음 `instructions`, 그다음 기능 instruction 조각, 그다음 원격 마운트 정책 텍스트, 그다음 렌더링된 파일시스템 트리 순서입니다
-5. 기능 도구를 실제 샌드박스 세션에 바인딩하고 준비된 에이전트를 일반 `Runner` API를 통해 실행합니다
+1. `SandboxRunConfig`에서 샌드박스 세션을 확인합니다.
+ `session=...`를 전달하면 해당 라이브 샌드박스 세션을 재사용합니다.
+ 그렇지 않으면 `client=...`를 사용해 세션을 생성하거나 재개합니다.
+2. 실행에 대한 실제 워크스페이스 입력을 결정합니다.
+ 실행이 샌드박스 세션을 주입하거나 재개하면 기존 샌드박스 상태가 우선합니다.
+ 그렇지 않으면 러너는 일회성 manifest override 또는 `agent.default_manifest`에서 시작합니다.
+ 따라서 `Manifest`만으로는 모든 실행의 최종 라이브 워크스페이스를 정의하지 않습니다.
+3. 기능이 결과 manifest를 처리하도록 합니다.
+ 이를 통해 기능은 최종 에이전트가 준비되기 전에 파일, 마운트 또는 기타 워크스페이스 범위 동작을 추가할 수 있습니다.
+4. 최종 instructions를 고정된 순서로 구성합니다.
+ SDK의 기본 샌드박스 프롬프트 또는 명시적으로 재정의한 경우 `base_instructions`, 그다음 `instructions`, 그다음 기능 지시문 조각, 그다음 원격 마운트 정책 텍스트, 마지막으로 렌더링된 파일시스템 트리 순서입니다.
+5. 기능 도구를 라이브 샌드박스 세션에 바인딩하고, 일반적인 `Runner` API를 통해 준비된 에이전트를 실행합니다.
-샌드박싱은 턴의 의미를 바꾸지 않습니다. 턴은 여전히 단일 셸 명령이나 샌드박스 작업이 아니라 모델 단계입니다. 샌드박스 측 작업과 턴 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 레이어 내부에 머무를 수 있고, 다른 작업은 또 다른 모델 단계가 필요한 도구 결과, 승인 또는 기타 상태를 반환할 수 있습니다. 실무적으로는 샌드박스 작업이 일어난 뒤 에이전트 런타임이 또 다른 모델 응답을 필요로 할 때만 추가 턴이 소비됩니다.
+샌드박싱은 turn의 의미를 바꾸지 않습니다. turn은 여전히 모델 단계이며, 단일 셸 명령이나 샌드박스 작업이 아닙니다. 샌드박스 측 작업과 turn 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 내부에 머물 수 있고, 다른 작업은 도구 결과, 승인 또는 또 다른 모델 단계가 필요한 기타 상태를 반환할 수 있습니다. 실질적으로는 샌드박스 작업이 발생한 후 에이전트 런타임이 또 다른 모델 응답을 필요로 할 때만 추가 turn이 소비됩니다.
-이러한 준비 단계 때문에 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`가 `SandboxAgent`를 설계할 때 생각해야 할 주요 샌드박스 전용 옵션입니다.
+이러한 준비 단계 때문에 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`가 `SandboxAgent`를 설계할 때 고려해야 할 주요 샌드박스 전용 옵션입니다.
## `SandboxAgent` 옵션
-다음은 일반적인 `Agent` 필드에 추가되는 샌드박스 전용 옵션입니다.
+일반적인 `Agent` 필드에 더해 있는 샌드박스 전용 옵션은 다음과 같습니다.
@@ -144,53 +144,53 @@ flowchart LR
| --- | --- |
| `default_manifest` | 러너가 생성하는 새 샌드박스 세션의 기본 워크스페이스 |
| `instructions` | SDK 샌드박스 프롬프트 뒤에 추가되는 역할, 워크플로, 성공 기준 |
-| `base_instructions` | SDK 샌드박스 프롬프트를 대체하는 고급 탈출구 |
-| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 네이티브 도구와 동작 |
+| `base_instructions` | SDK 샌드박스 프롬프트를 대체하는 고급 escape hatch |
+| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 고유 도구 및 동작 |
| `run_as` | 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구의 사용자 ID |
-샌드박스 클라이언트 선택, 샌드박스 세션 재사용, manifest 재정의, 스냅샷 선택은 에이전트가 아니라 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에 속합니다.
+샌드박스 클라이언트 선택, 샌드박스 세션 재사용, manifest override, 스냅샷 선택은 에이전트가 아니라 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에 속합니다.
### `default_manifest`
-`default_manifest`는 러너가 이 에이전트용 새 샌드박스 세션을 생성할 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 보통 시작해야 하는 파일, 리포지토리, 보조 자료, 출력 디렉터리, 마운트에 사용하세요.
+`default_manifest`는 러너가 이 에이전트용 새 샌드박스 세션을 생성할 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 일반적으로 시작해야 하는 파일, 리포지토리, 보조 자료, 출력 디렉터리, 마운트에 사용하세요.
-이는 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 재정의할 수 있으며, 재사용되거나 재개된 샌드박스 세션은 기존 워크스페이스 상태를 유지합니다.
+이것은 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 재정의할 수 있으며, 재사용되거나 재개된 샌드박스 세션은 기존 워크스페이스 상태를 유지합니다.
### `instructions`와 `base_instructions`
-`instructions`는 서로 다른 프롬프트에서도 유지되어야 하는 짧은 규칙에 사용하세요. `SandboxAgent`에서는 이 instructions가 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 내장 샌드박스 가이드는 유지하면서 고유한 역할, 워크플로, 성공 기준을 추가할 수 있습니다.
+서로 다른 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 내장 샌드박스 가이드를 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다.
-`base_instructions`는 SDK 샌드박스 기본 프롬프트를 대체하고 싶을 때만 사용하세요. 대부분의 에이전트는 이를 설정하지 않아야 합니다.
+SDK 샌드박스 기본 프롬프트를 대체하려는 경우에만 `base_instructions`를 사용하세요. 대부분의 에이전트는 이를 설정할 필요가 없습니다.
-| 넣을 위치 | 용도 | 예시 |
+| 다음 위치에 둘 것 | 용도 | 예시 |
| --- | --- | --- |
-| `instructions` | 에이전트의 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검사한 뒤 핸드오프하세요.", "최종 파일을 `output/`에 작성하세요." |
-| `base_instructions` | SDK 샌드박스 기본 프롬프트의 완전한 대체 | 사용자 정의 저수준 샌드박스 래퍼 프롬프트 |
+| `instructions` | 에이전트의 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검토한 뒤 핸드오프합니다.", "최종 파일은 `output/`에 작성합니다." |
+| `base_instructions` | SDK 샌드박스 기본 프롬프트를 완전히 대체 | 사용자 정의 저수준 샌드박스 래퍼 프롬프트 |
| 사용자 프롬프트 | 이 실행에 대한 일회성 요청 | "이 워크스페이스를 요약하세요." |
-| manifest의 워크스페이스 파일 | 더 긴 작업 명세, 리포지토리 로컬 instructions, 또는 제한된 참조 자료 | `repo/task.md`, 문서 번들, 샘플 패킷 |
+| manifest의 워크스페이스 파일 | 더 긴 작업 사양, 리포지토리 로컬 instructions, 또는 범위가 제한된 참고 자료 | `repo/task.md`, 문서 번들, 샘플 패킷 |
-`instructions`의 좋은 사용 예시는 다음과 같습니다.
+`instructions`의 좋은 사용 예는 다음과 같습니다.
-- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py)는 PTY 상태가 중요할 때 에이전트를 하나의 대화형 프로세스 안에 유지합니다
-- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)는 검사 후 샌드박스 검토자가 사용자에게 직접 답변하지 못하도록 합니다
-- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)는 최종 작성된 파일이 실제로 `output/`에 저장되도록 요구합니다
-- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)는 정확한 검증 명령을 고정하고 워크스페이스 루트 기준 패치 경로를 명확히 합니다
+- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py)는 PTY 상태가 중요할 때 에이전트를 하나의 대화형 프로세스 안에 유지합니다.
+- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)는 샌드박스 리뷰어가 검토 후 사용자에게 직접 응답하지 못하도록 금지합니다.
+- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)는 최종 작성 파일이 실제로 `output/`에 기록되도록 요구합니다.
+- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)는 정확한 검증 명령을 고정하고 워크스페이스 루트 기준 상대 패치 경로를 명확히 합니다.
-사용자의 일회성 작업을 `instructions`에 복사해 넣거나, manifest에 들어가야 할 긴 참조 자료를 포함하거나, 내장 기능이 이미 주입하는 도구 문서를 반복하거나, 모델이 실행 시점에 필요하지 않은 로컬 설치 메모를 섞는 것은 피하세요.
+사용자의 일회성 작업을 `instructions`에 복사해 넣거나, manifest에 들어가야 할 긴 참고 자료를 포함하거나, 내장 기능이 이미 주입하는 도구 문서를 반복하거나, 모델이 실행 시점에 필요로 하지 않는 로컬 설치 메모를 섞는 것은 피하세요.
-`instructions`를 생략하더라도 SDK는 기본 샌드박스 프롬프트를 포함합니다. 저수준 래퍼에는 충분하지만, 대부분의 사용자 대상 에이전트는 여전히 명시적인 `instructions`를 제공해야 합니다.
+`instructions`를 생략해도 SDK는 여전히 기본 샌드박스 프롬프트를 포함합니다. 이는 저수준 래퍼에는 충분하지만, 대부분의 사용자 대상 에이전트는 여전히 명시적인 `instructions`를 제공해야 합니다.
### `capabilities`
-기능은 샌드박스 네이티브 동작을 `SandboxAgent`에 연결합니다. 실행이 시작되기 전에 워크스페이스를 구성하고, 샌드박스 전용 instructions를 추가하고, 실제 샌드박스 세션에 바인딩되는 도구를 노출하며, 해당 에이전트의 모델 동작이나 입력 처리를 조정할 수 있습니다.
+기능은 샌드박스 고유 동작을 `SandboxAgent`에 연결합니다. 실행 시작 전에 워크스페이스를 구성하고, 샌드박스 전용 instructions를 추가하고, 라이브 샌드박스 세션에 바인딩되는 도구를 노출하며, 해당 에이전트의 모델 동작이나 입력 처리를 조정할 수 있습니다.
-내장 기능은 다음과 같습니다.
+내장 기능에는 다음이 포함됩니다.
@@ -198,31 +198,31 @@ flowchart LR
| --- | --- | --- |
| `Shell` | 에이전트에 셸 접근이 필요할 때 | `exec_command`를 추가하며, 샌드박스 클라이언트가 PTY 상호작용을 지원하면 `write_stdin`도 추가합니다 |
| `Filesystem` | 에이전트가 파일을 편집하거나 로컬 이미지를 검사해야 할 때 | `apply_patch`와 `view_image`를 추가합니다. 패치 경로는 워크스페이스 루트 기준 상대 경로입니다 |
-| `Skills` | 샌드박스에서 스킬 검색 및 구체화가 필요할 때 | 샌드박스 로컬 `SKILL.md` 스킬에는 `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 대신 이것을 권장합니다 |
-| `Memory` | 후속 실행이 메모리 아티팩트를 읽거나 생성해야 할 때 | `Shell`이 필요하며, 실시간 업데이트에는 `Filesystem`도 필요합니다 |
-| `Compaction` | 장시간 실행되는 플로에 컴팩션 항목 이후 컨텍스트 축소가 필요할 때 | 모델 샘플링과 입력 처리를 조정합니다 |
+| `Skills` | 샌드박스에서 스킬 검색과 materialization이 필요할 때 | 샌드박스 로컬 `SKILL.md` 스킬에는 `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 것보다 이 방식을 권장합니다 |
+| `Memory` | 후속 실행에서 메모리 아티팩트를 읽거나 생성해야 할 때 | `Shell`이 필요하며, 라이브 업데이트에는 `Filesystem`도 필요합니다 |
+| `Compaction` | 장기 실행 흐름에서 compaction 항목 이후 컨텍스트 축소가 필요할 때 | 모델 샘플링과 입력 처리를 조정합니다 |
-기본적으로 `SandboxAgent.capabilities`는 `Filesystem()`, `Shell()`, `Compaction()`을 포함하는 `Capabilities.default()`를 사용합니다. `capabilities=[...]`를 전달하면 이 목록이 기본값을 대체하므로, 여전히 원하는 기본 기능이 있다면 함께 포함해야 합니다.
+기본적으로 `SandboxAgent.capabilities`는 `Filesystem()`, `Shell()`, `Compaction()`을 포함하는 `Capabilities.default()`를 사용합니다. `capabilities=[...]`를 전달하면 이 목록이 기본값을 대체하므로, 여전히 원하는 기본 기능이 있다면 함께 포함하세요.
-스킬의 경우, 어떻게 구체화할지에 따라 소스를 선택하세요.
+스킬의 경우, materialization 방식을 기준으로 소스를 선택하세요.
-- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 모델이 먼저 인덱스를 탐색한 뒤 필요한 것만 로드할 수 있으므로 더 큰 로컬 스킬 디렉터리에 대한 좋은 기본값입니다
-- `Skills(from_=LocalDir(src=...))`는 작은 로컬 번들을 미리 배치하고 싶을 때 더 적합합니다
-- `Skills(from_=GitRepo(repo=..., ref=...))`는 스킬 자체가 리포지토리에서 와야 할 때 적합합니다
+- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 모델이 먼저 인덱스를 탐색하고 필요한 것만 로드할 수 있으므로 큰 로컬 스킬 디렉터리에 적합한 기본 선택입니다.
+- `Skills(from_=LocalDir(src=...))`는 작고 로컬인 번들을 미리 스테이징하고 싶을 때 더 적합합니다.
+- `Skills(from_=GitRepo(repo=..., ref=...))`는 스킬 자체를 리포지토리에서 가져와야 할 때 적합합니다.
-스킬이 이미 `.agents/skills//SKILL.md` 같은 경로에 디스크에 존재한다면, `LocalDir(...)`를 그 소스 루트로 지정하고 여전히 `Skills(...)`를 사용해 노출하세요. 샌드박스 내부 레이아웃이 다른 기존 워크스페이스 계약에 의존하지 않는 한 기본 `skills_path=".agents"`를 유지하세요.
+스킬이 이미 `.agents/skills//SKILL.md` 같은 경로 아래 디스크에 있다면, `LocalDir(...)`를 해당 소스 루트로 지정하고 여전히 `Skills(...)`를 사용해 이를 노출하세요. 샌드박스 내부 레이아웃이 다른 기존 워크스페이스 계약에 의존하지 않는 한, 기본 `skills_path=".agents"`를 유지하세요.
-적합하다면 내장 기능을 우선 사용하세요. 내장 기능이 다루지 않는 샌드박스 전용 도구나 instruction 표면이 필요할 때만 사용자 정의 기능을 작성하세요.
+적합하다면 내장 기능을 우선 사용하세요. 내장 기능으로 다루지 못하는 샌드박스 전용 도구 또는 instructions 표면이 필요할 때만 사용자 정의 기능을 작성하세요.
## 개념
### Manifest
-[`Manifest`][agents.sandbox.manifest.Manifest]는 새 샌드박스 세션의 워크스페이스를 설명합니다. 워크스페이스 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사하고, Git 리포지토리를 복제하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자나 그룹을 정의하고, 워크스페이스 외부의 특정 절대 경로에 대한 접근 권한을 부여할 수 있습니다.
+[`Manifest`][agents.sandbox.manifest.Manifest]는 새 샌드박스 세션의 워크스페이스를 설명합니다. 워크스페이스 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사해 넣고, Git 리포지토리를 복제하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자나 그룹을 정의하고, 워크스페이스 외부의 특정 절대 경로에 대한 접근 권한을 부여할 수 있습니다.
-Manifest 항목 경로는 워크스페이스 기준 상대 경로입니다. 절대 경로일 수 없고 `..`로 워크스페이스를 벗어날 수도 없으므로, 워크스페이스 계약이 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다.
+Manifest 항목 경로는 워크스페이스 기준 상대 경로입니다. 절대 경로일 수 없고 `..`를 사용해 워크스페이스를 벗어날 수도 없습니다. 이를 통해 워크스페이스 계약은 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다.
작업 시작 전에 에이전트가 필요로 하는 자료에는 manifest 항목을 사용하세요.
@@ -230,18 +230,18 @@ Manifest 항목 경로는 워크스페이스 기준 상대 경로입니다. 절
| Manifest 항목 | 용도 |
| --- | --- |
-| `File`, `Dir` | 작은 합성 입력, 보조 파일, 출력 디렉터리 |
-| `LocalFile`, `LocalDir` | 샌드박스 내부에 구체화되어야 하는 호스트 파일 또는 디렉터리 |
+| `File`, `Dir` | 작은 합성 입력, 보조 파일, 또는 출력 디렉터리 |
+| `LocalFile`, `LocalDir` | 샌드박스 안으로 materialization되어야 하는 호스트 파일 또는 디렉터리 |
| `GitRepo` | 워크스페이스로 가져와야 하는 리포지토리 |
-| `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `S3FilesMount` 같은 mounts | 샌드박스 내부에 나타나야 하는 외부 스토리지 |
+| `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount` 같은 mounts | 샌드박스 내부에 나타나야 하는 외부 스토리지 |
-마운트 항목은 어떤 스토리지를 노출할지 설명하고, 마운트 전략은 샌드박스 백엔드가 그 스토리지를 어떻게 연결할지 설명합니다. 마운트 옵션과 공급자 지원은 [샌드박스 클라이언트](clients.md#mounts-and-remote-storage)를 참조하세요.
+마운트 항목은 어떤 스토리지를 노출할지 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 어떻게 연결할지 설명합니다. 마운트 옵션과 공급자 지원은 [Sandbox clients](clients.md#mounts-and-remote-storage)를 참고하세요.
-좋은 manifest 설계는 보통 워크스페이스 계약을 좁게 유지하고, 긴 작업 절차는 `repo/task.md` 같은 워크스페이스 파일에 넣고, instructions에서는 예를 들어 `repo/task.md` 또는 `output/report.md`처럼 상대 워크스페이스 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` 기능의 `apply_patch` 도구로 파일을 편집한다면, 패치 경로는 셸 `workdir`가 아니라 샌드박스 워크스페이스 루트 기준 상대 경로라는 점을 기억하세요.
+좋은 manifest 설계는 보통 워크스페이스 계약을 좁게 유지하고, 긴 작업 지침은 `repo/task.md` 같은 워크스페이스 파일에 넣고, instructions에서는 예를 들어 `repo/task.md` 또는 `output/report.md`처럼 워크스페이스 기준 상대 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` 기능의 `apply_patch` 도구로 파일을 편집하는 경우, 패치 경로는 셸 `workdir`가 아니라 샌드박스 워크스페이스 루트 기준 상대 경로라는 점을 기억하세요.
-에이전트가 워크스페이스 외부의 구체적인 절대 경로(예: 임시 도구 출력용 `/tmp` 또는 읽기 전용 런타임용 `/opt/toolchain`)가 필요할 때만 `extra_path_grants`를 사용하세요. 부여는 백엔드가 파일시스템 정책을 강제할 수 있는 경우 SDK 파일 API와 셸 실행 모두에 적용됩니다.
+에이전트가 워크스페이스 밖의 구체적인 절대 경로가 필요할 때만 `extra_path_grants`를 사용하세요. 예를 들어 임시 도구 출력용 `/tmp`나 읽기 전용 런타임용 `/opt/toolchain` 등이 해당합니다. grant는 백엔드가 파일시스템 정책을 강제할 수 있는 경우 SDK 파일 API와 셸 실행 모두에 적용됩니다.
```python
from agents.sandbox import Manifest, SandboxPathGrant
@@ -254,13 +254,13 @@ manifest = Manifest(
)
```
-스냅샷과 `persist_workspace()`에는 여전히 워크스페이스 루트만 포함됩니다. 추가로 부여된 경로는 런타임 접근 권한이지, 지속되는 워크스페이스 상태가 아닙니다.
+스냅샷과 `persist_workspace()`는 여전히 워크스페이스 루트만 포함합니다. 추가로 부여된 경로는 런타임 접근 권한일 뿐, 영구적인 워크스페이스 상태가 아닙니다.
### 권한
-`Permissions`는 manifest 항목의 파일시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 대한 것이며, 모델 권한, 승인 정책, API 자격 증명에 대한 것이 아닙니다.
+`Permissions`는 manifest 항목의 파일시스템 권한을 제어합니다. 이는 샌드박스가 materialization하는 파일에 관한 것이며, 모델 권한, 승인 정책, API 자격 증명에 관한 것이 아닙니다.
-기본적으로 manifest 항목은 소유자에게 읽기/쓰기/실행 권한이 있고, 그룹과 기타 사용자에게 읽기/실행 권한이 있습니다. 배치된 파일이 비공개, 읽기 전용, 실행 가능이어야 하는 경우 이를 재정의하세요.
+기본적으로 manifest 항목은 소유자에게 읽기/쓰기/실행 권한이 있고, 그룹과 기타 사용자에게 읽기/실행 권한이 있습니다. 스테이징된 파일을 비공개, 읽기 전용, 또는 실행 가능하게 해야 한다면 이를 재정의하세요.
```python
from agents.sandbox import FileMode, Permissions
@@ -276,9 +276,9 @@ private_notes = File(
)
```
-`Permissions`는 디렉터리 여부와 함께 소유자, 그룹, 기타 사용자 각각의 비트를 별도로 저장합니다. 직접 생성할 수도 있고, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나, `Permissions.from_mode(...)`로 OS 모드에서 파생할 수도 있습니다.
+`Permissions`는 소유자, 그룹, 기타 사용자별 비트와 해당 항목이 디렉터리인지 여부를 별도로 저장합니다. 직접 구성할 수도 있고, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나 `Permissions.from_mode(...)`로 OS 모드에서 파생할 수도 있습니다.
-사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 해당 ID가 샌드박스에 존재해야 한다면 manifest에 `User`를 추가한 다음, 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구가 그 사용자로 실행되어야 할 때 `SandboxAgent.run_as`를 설정하세요. `run_as`가 manifest에 아직 없는 사용자를 가리키면 러너가 그 사용자를 유효 manifest에 자동으로 추가합니다.
+사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 해당 ID가 샌드박스 안에 존재해야 한다면 manifest에 `User`를 추가한 뒤, 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구가 그 사용자로 실행되도록 `SandboxAgent.run_as`를 설정하세요. `run_as`가 manifest에 아직 없는 사용자를 가리키면 러너가 이를 자동으로 실제 manifest에 추가합니다.
```python
from agents import Runner
@@ -330,13 +330,13 @@ result = await Runner.run(
)
```
-파일 수준 공유 규칙도 필요하다면 사용자와 manifest 그룹, 항목 `group` 메타데이터를 함께 사용하세요. `run_as` 사용자는 누가 샌드박스 네이티브 작업을 실행하는지를 제어하고, `Permissions`는 샌드박스가 워크스페이스를 구체화한 후 그 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지를 제어합니다.
+파일 수준 공유 규칙도 필요하다면, 사용자를 manifest 그룹 및 항목의 `group` 메타데이터와 함께 결합하세요. `run_as` 사용자는 샌드박스 고유 작업을 누가 실행하는지를 제어하고, `Permissions`는 샌드박스가 워크스페이스를 materialization한 뒤 해당 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지를 제어합니다.
### SnapshotSpec
-`SnapshotSpec`은 새 샌드박스 세션에 저장된 워크스페이스 콘텐츠를 어디서 복원하고 어디로 다시 저장할지 알려줍니다. 이는 샌드박스 워크스페이스의 스냅샷 정책이며, `session_state`는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다.
+`SnapshotSpec`은 새 샌드박스 세션에 저장된 워크스페이스 콘텐츠를 어디서 복원하고 어디로 다시 영속화할지 알려줍니다. 이는 샌드박스 워크스페이스의 스냅샷 정책이며, `session_state`는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다.
-로컬의 지속 가능한 스냅샷에는 `LocalSnapshotSpec`을, 애플리케이션이 원격 스냅샷 클라이언트를 제공하는 경우에는 `RemoteSnapshotSpec`을 사용하세요. 로컬 스냅샷 구성이 불가능하면 no-op 스냅샷이 대체 수단으로 사용되며, 고급 호출자는 워크스페이스 스냅샷 지속성을 원하지 않을 때 이를 명시적으로 사용할 수 있습니다.
+로컬의 영속 스냅샷에는 `LocalSnapshotSpec`를 사용하고, 앱이 원격 스냅샷 클라이언트를 제공하는 경우에는 `RemoteSnapshotSpec`를 사용하세요. 로컬 스냅샷 설정을 사용할 수 없을 때는 no-op 스냅샷이 대체로 사용되며, 고급 사용자는 워크스페이스 스냅샷 영속화가 필요 없을 때 이를 명시적으로 사용할 수 있습니다.
```python
from pathlib import Path
@@ -353,13 +353,13 @@ run_config = RunConfig(
)
```
-러너가 새 샌드박스 세션을 생성하면 샌드박스 클라이언트는 해당 세션용 스냅샷 인스턴스를 만듭니다. 시작 시 스냅샷이 복원 가능하면, 실행이 계속되기 전에 샌드박스가 저장된 워크스페이스 콘텐츠를 복원합니다. 정리 시 러너가 소유한 샌드박스 세션은 워크스페이스를 아카이브하고 스냅샷을 통해 다시 저장합니다.
+러너가 새 샌드박스 세션을 생성하면 샌드박스 클라이언트는 해당 세션용 스냅샷 인스턴스를 생성합니다. 시작 시 스냅샷을 복원할 수 있으면 실행이 계속되기 전에 저장된 워크스페이스 콘텐츠를 복원합니다. 정리 시 러너가 소유한 샌드박스 세션은 워크스페이스를 아카이브하고 스냅샷을 통해 다시 영속화합니다.
-`snapshot`을 생략하면 런타임은 가능할 경우 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 이를 설정할 수 없으면 no-op 스냅샷으로 대체됩니다. 마운트된 경로와 일시적 경로는 지속되는 워크스페이스 콘텐츠로 스냅샷에 복사되지 않습니다.
+`snapshot`을 생략하면 런타임은 가능할 경우 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 이를 설정할 수 없으면 no-op 스냅샷으로 대체합니다. 마운트된 경로와 임시 경로는 영구 워크스페이스 콘텐츠로 스냅샷에 복사되지 않습니다.
### 샌드박스 수명 주기
-수명 주기 모드는 **SDK 소유**와 **개발자 소유** 두 가지입니다.
+수명 주기 모드는 두 가지입니다. **SDK 소유**와 **개발자 소유**입니다.
@@ -387,7 +387,7 @@ sequenceDiagram
-샌드박스가 한 번의 실행 동안만 살아 있으면 될 때는 SDK 소유 수명 주기를 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 그리고 클라이언트 `options`를 전달하면 러너가 샌드박스를 생성 또는 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 워크스페이스 상태를 저장하고, 샌드박스를 종료하고, 클라이언트가 러너 소유 리소스를 정리하도록 합니다.
+샌드박스가 한 번의 실행 동안만 살아 있으면 SDK 소유 수명 주기를 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 러너가 샌드박스를 생성하거나 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 워크스페이스 상태를 영속화하고, 샌드박스를 종료하고, 클라이언트가 러너 소유 리소스를 정리하도록 합니다.
```python
result = await Runner.run(
@@ -399,7 +399,7 @@ result = await Runner.run(
)
```
-샌드박스를 미리 생성하거나, 하나의 실제 샌드박스를 여러 실행에 재사용하거나, 실행 후 파일을 검사하거나, 직접 만든 샌드박스에서 스트리밍하거나, 정리 시점을 정확히 제어하고 싶다면 개발자 소유 수명 주기를 사용하세요. `session=...`을 전달하면 러너는 그 실제 샌드박스를 사용하지만, 사용자를 대신해 닫지는 않습니다.
+샌드박스를 미리 생성하거나, 하나의 라이브 샌드박스를 여러 실행에서 재사용하거나, 실행 후 파일을 검사하거나, 직접 만든 샌드박스에서 스트리밍하거나, 정리 시점을 정확히 제어하고 싶다면 개발자 소유 수명 주기를 사용하세요. `session=...`를 전달하면 러너는 해당 라이브 샌드박스를 사용하지만, 이를 대신 닫아주지는 않습니다.
```python
sandbox = await client.create(manifest=agent.default_manifest)
@@ -410,7 +410,7 @@ async with sandbox:
await Runner.run(agent, "Write the final report.", run_config=run_config)
```
-컨텍스트 매니저가 일반적인 형태입니다. 진입 시 샌드박스를 시작하고 종료 시 세션 정리 수명 주기를 실행합니다. 애플리케이션이 컨텍스트 매니저를 사용할 수 없다면 수명 주기 메서드를 직접 호출하세요.
+컨텍스트 매니저가 일반적인 형태입니다. 진입 시 샌드박스를 시작하고 종료 시 세션 정리 수명 주기를 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 수명 주기 메서드를 직접 호출하세요.
```python
sandbox = await client.create(
@@ -431,32 +431,32 @@ finally:
await sandbox.aclose()
```
-`stop()`은 스냅샷 기반 워크스페이스 콘텐츠만 저장하며 샌드박스를 해제하지는 않습니다. `aclose()`는 전체 세션 정리 경로입니다. pre-stop 훅을 실행하고, `stop()`을 호출하고, 샌드박스 리소스를 종료하고, 세션 범위 종속성을 닫습니다.
+`stop()`은 스냅샷 기반 워크스페이스 콘텐츠만 영속화하며, 샌드박스를 해제하지는 않습니다. `aclose()`는 전체 세션 정리 경로입니다. pre-stop hooks를 실행하고, `stop()`을 호출하고, 샌드박스 리소스를 종료하고, 세션 범위 종속성을 닫습니다.
## `SandboxRunConfig` 옵션
-[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 샌드박스 세션의 출처와 새 세션의 초기화 방식을 결정하는 실행별 옵션을 담습니다.
+[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 샌드박스 세션이 어디서 오는지와 새 세션을 어떻게 초기화할지를 결정하는 실행별 옵션을 담습니다.
### 샌드박스 소스
-다음 옵션은 러너가 샌드박스 세션을 재사용, 재개, 생성할지를 결정합니다.
+다음 옵션은 러너가 샌드박스 세션을 재사용, 재개 또는 생성할지를 결정합니다.
-| 옵션 | 사용 시점 | 참고 |
+| 옵션 | 사용할 시점 | 참고 |
| --- | --- | --- |
-| `client` | 러너가 샌드박스 세션을 생성, 재개, 정리하도록 맡기고 싶을 때 | 실제 샌드박스 `session`을 제공하지 않는 한 필요합니다 |
-| `session` | 이미 사용자가 직접 실제 샌드박스 세션을 생성했을 때 | 수명 주기는 호출자가 소유하며, 러너는 해당 실제 샌드박스 세션을 재사용합니다 |
-| `session_state` | 직렬화된 샌드박스 세션 상태는 있지만 실제 샌드박스 세션 객체는 없을 때 | `client`가 필요하며, 러너는 그 명시적 상태에서 소유 세션으로 재개합니다 |
+| `client` | 러너가 샌드박스 세션의 생성, 재개, 정리를 대신 처리하길 원할 때 | 라이브 샌드박스 `session`을 제공하지 않는 한 필수입니다 |
+| `session` | 사용자가 이미 직접 라이브 샌드박스 세션을 생성한 경우 | 수명 주기는 호출자가 소유하며, 러너는 해당 라이브 샌드박스 세션을 재사용합니다 |
+| `session_state` | 샌드박스 세션 상태는 직렬화했지만 라이브 샌드박스 세션 객체는 없는 경우 | `client`가 필요하며, 러너는 해당 명시적 상태에서 소유 세션으로 재개합니다 |
-실제로 러너는 다음 순서로 샌드박스 세션을 해석합니다.
+실제로 러너는 다음 순서로 샌드박스 세션을 확인합니다.
-1. `run_config.sandbox.session`을 주입하면 해당 실제 샌드박스 세션을 직접 재사용합니다
-2. 그렇지 않고 실행이 `RunState`에서 재개되는 경우, 저장된 샌드박스 세션 상태를 재개합니다
-3. 그렇지 않고 `run_config.sandbox.session_state`를 전달하면 러너는 해당 명시적 직렬화 샌드박스 세션 상태에서 재개합니다
-4. 그렇지 않으면 러너는 새 샌드박스 세션을 생성합니다. 이 새 세션에는 제공된 경우 `run_config.sandbox.manifest`를 사용하고, 그렇지 않으면 `agent.default_manifest`를 사용합니다
+1. `run_config.sandbox.session`을 주입하면 해당 라이브 샌드박스 세션을 직접 재사용합니다.
+2. 그렇지 않고 실행이 `RunState`에서 재개되는 경우 저장된 샌드박스 세션 상태를 재개합니다.
+3. 그렇지 않고 `run_config.sandbox.session_state`를 전달하면 러너는 해당 명시적 직렬화 샌드박스 세션 상태에서 재개합니다.
+4. 그렇지 않으면 러너는 새 샌드박스 세션을 생성합니다. 이 새 세션에는 제공된 경우 `run_config.sandbox.manifest`를 사용하고, 없으면 `agent.default_manifest`를 사용합니다.
### 새 세션 입력
@@ -464,29 +464,29 @@ finally:
-| 옵션 | 사용 시점 | 참고 |
+| 옵션 | 사용할 시점 | 참고 |
| --- | --- | --- |
-| `manifest` | 일회성 새 세션 워크스페이스 재정의를 원할 때 | 생략하면 `agent.default_manifest`로 대체됩니다 |
-| `snapshot` | 새 샌드박스 세션이 스냅샷에서 시드되어야 할 때 | 재개와 유사한 플로 또는 원격 스냅샷 클라이언트에 유용합니다 |
-| `options` | 샌드박스 클라이언트에 생성 시점 옵션이 필요할 때 | Docker 이미지, Modal 앱 이름, E2B 템플릿, 타임아웃, 유사한 클라이언트별 설정에서 흔합니다 |
+| `manifest` | 일회성 새 세션 워크스페이스 override가 필요할 때 | 생략 시 `agent.default_manifest`로 대체됩니다 |
+| `snapshot` | 새 샌드박스 세션을 스냅샷에서 초기화해야 할 때 | 재개와 유사한 흐름이나 원격 스냅샷 클라이언트에 유용합니다 |
+| `options` | 샌드박스 클라이언트에 생성 시점 옵션이 필요할 때 | Docker 이미지, Modal 앱 이름, E2B 템플릿, 타임아웃 등 클라이언트별 설정에 흔히 사용됩니다 |
-### 구체화 제어
+### materialization 제어
-`concurrency_limits`는 샌드박스 구체화 작업이 병렬로 얼마나 많이 실행될 수 있는지를 제어합니다. 큰 manifest나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요하면 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요.
+`concurrency_limits`는 얼마나 많은 샌드박스 materialization 작업을 병렬로 실행할 수 있을지 제어합니다. 큰 manifest나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요하다면 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요.
-다음 몇 가지 함의는 염두에 둘 만합니다.
+유념할 만한 몇 가지 사항은 다음과 같습니다.
- 새 세션: `manifest=`와 `snapshot=`은 러너가 새 샌드박스 세션을 생성할 때만 적용됩니다
-- 재개 vs 스냅샷: `session_state=`는 이전에 직렬화된 샌드박스 상태에 다시 연결하고, `snapshot=`은 저장된 워크스페이스 콘텐츠로 새 샌드박스 세션을 시드합니다
-- 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 달라지며, Docker와 많은 호스티드 클라이언트는 이를 필요로 합니다
-- 주입된 실제 세션: 실행 중인 샌드박스 `session`을 전달하면 기능 기반 manifest 업데이트는 호환 가능한 비마운트 항목을 추가할 수 있습니다. 하지만 `manifest.root`, `manifest.environment`, `manifest.users`, `manifest.groups`를 변경하거나, 기존 항목을 제거하거나, 항목 유형을 교체하거나, 마운트 항목을 추가 또는 변경할 수는 없습니다
-- 러너 API: `SandboxAgent` 실행은 여전히 일반 `Runner.run()`, `Runner.run_sync()`, `Runner.run_streamed()` API를 사용합니다
+- 재개와 스냅샷: `session_state=`는 이전에 직렬화한 샌드박스 상태에 다시 연결하고, `snapshot=`은 저장된 워크스페이스 콘텐츠에서 새 샌드박스 세션을 초기화합니다
+- 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 다르며, Docker와 많은 호스티드 클라이언트는 이를 요구합니다
+- 주입된 라이브 세션: 실행 중인 샌드박스 `session`을 전달하면 기능 기반 manifest 업데이트는 호환되는 비마운트 항목을 추가할 수 있습니다. 하지만 `manifest.root`, `manifest.environment`, `manifest.users`, `manifest.groups`를 변경하거나, 기존 항목을 제거하거나, 항목 유형을 교체하거나, 마운트 항목을 추가 또는 변경할 수는 없습니다
+- 러너 API: `SandboxAgent` 실행은 여전히 일반적인 `Runner.run()`, `Runner.run_sync()`, `Runner.run_streamed()` API를 사용합니다
## 전체 예제: 코딩 작업
-이 코딩 스타일 예제는 좋은 기본 출발점입니다.
+이 코딩 스타일 예제는 기본 시작점으로 적합합니다.
```python
import asyncio
@@ -564,19 +564,19 @@ if __name__ == "__main__":
)
```
-[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참고하세요. 이 예제는 Unix 로컬 실행 전반에서 예제를 결정적으로 검증할 수 있도록 작은 셸 기반 리포지토리를 사용합니다. 물론 실제 작업 리포지토리는 Python, JavaScript, 그 밖의 어떤 것이든 사용할 수 있습니다.
+[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참고하세요. 예제가 Unix 로컬 실행 전반에서 결정적으로 검증될 수 있도록 작은 셸 기반 리포지토리를 사용합니다. 실제 작업 리포지토리는 물론 Python, JavaScript 또는 다른 어떤 것이어도 됩니다.
## 일반 패턴
-위의 전체 예제에서 시작하세요. 많은 경우 동일한 `SandboxAgent`는 그대로 두고 샌드박스 클라이언트, 샌드박스 세션 소스, 또는 워크스페이스 소스만 바꾸면 됩니다.
+위의 전체 예제에서 시작하세요. 많은 경우 동일한 `SandboxAgent`를 유지한 채 샌드박스 클라이언트, 샌드박스 세션 소스, 또는 워크스페이스 소스만 변경하면 됩니다.
### 샌드박스 클라이언트 전환
-에이전트 정의는 그대로 유지하고 실행 구성만 변경하세요. 컨테이너 격리나 이미지 동일성이 필요하면 Docker를 사용하고, 공급자 관리 실행이 필요하면 호스티드 공급자를 사용하세요. 예제와 공급자 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요.
+에이전트 정의는 그대로 두고 실행 구성만 변경하세요. 컨테이너 격리 또는 이미지 일치가 필요하면 Docker를 사용하고, 공급자 관리 실행이 필요하면 호스티드 공급자를 사용하세요. 예시와 공급자 옵션은 [Sandbox clients](clients.md)를 참고하세요.
### 워크스페이스 재정의
-에이전트 정의는 그대로 유지하고 새 세션 manifest만 바꾸세요.
+에이전트 정의는 그대로 두고 새 세션 manifest만 교체하세요.
```python
from agents.run import RunConfig
@@ -596,11 +596,11 @@ run_config = RunConfig(
)
```
-에이전트를 다시 만들지 않고 동일한 에이전트 역할을 서로 다른 리포지토리, 패킷, 작업 번들에 대해 실행해야 할 때 사용하세요. 위의 검증된 코딩 예제는 일회성 재정의 대신 `default_manifest`를 사용해 같은 패턴을 보여줍니다.
+동일한 에이전트 역할을 서로 다른 리포지토리, 패킷 또는 작업 번들에 대해 에이전트를 다시 만들지 않고 실행해야 할 때 사용하세요. 위의 검증된 코딩 예제는 일회성 override 대신 `default_manifest`를 사용하는 동일한 패턴을 보여줍니다.
### 샌드박스 세션 주입
-명시적인 수명 주기 제어, 실행 후 검사, 출력 복사가 필요하면 실제 샌드박스 세션을 주입하세요.
+명시적인 수명 주기 제어, 실행 후 검사, 또는 출력 복사가 필요하다면 라이브 샌드박스 세션을 주입하세요.
```python
from agents import Runner
@@ -621,11 +621,11 @@ async with sandbox:
)
```
-실행 후 워크스페이스를 검사하거나 이미 시작된 샌드박스 세션에서 스트리밍하고 싶을 때 사용하세요. [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)와 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요.
+실행 후 워크스페이스를 검사하거나 이미 시작된 샌드박스 세션에서 스트리밍하고 싶을 때 사용하세요. [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 및 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요.
### 세션 상태에서 재개
-이미 `RunState` 외부에서 샌드박스 상태를 직렬화했다면, 러너가 해당 상태에서 다시 연결하도록 하세요.
+이미 `RunState` 외부에서 샌드박스 상태를 직렬화했다면 러너가 해당 상태에서 다시 연결하도록 하세요.
```python
from agents.run import RunConfig
@@ -642,11 +642,11 @@ run_config = RunConfig(
)
```
-샌드박스 상태가 자체 스토리지나 작업 시스템에 있고 `Runner`가 거기서 직접 재개하기를 원할 때 사용하세요. 직렬화/역직렬화 플로는 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)를 참고하세요.
+샌드박스 상태가 자체 스토리지나 작업 시스템에 있고 `Runner`가 그 상태에서 직접 재개하길 원할 때 사용하세요. 직렬화/역직렬화 흐름은 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)를 참고하세요.
### 스냅샷에서 시작
-저장된 파일과 아티팩트에서 새 샌드박스를 시드합니다.
+저장된 파일과 아티팩트에서 새 샌드박스를 초기화합니다.
```python
from pathlib import Path
@@ -663,7 +663,7 @@ run_config = RunConfig(
)
```
-새 실행이 `agent.default_manifest`만이 아니라 저장된 워크스페이스 콘텐츠에서 시작해야 할 때 사용하세요. 로컬 스냅샷 플로는 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py), 원격 스냅샷 클라이언트는 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)를 참고하세요.
+새 실행이 `agent.default_manifest`만이 아니라 저장된 워크스페이스 콘텐츠에서 시작해야 할 때 사용하세요. 로컬 스냅샷 흐름은 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py), 원격 스냅샷 클라이언트는 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)를 참고하세요.
### Git에서 스킬 로드
@@ -678,11 +678,11 @@ capabilities = Capabilities.default() + [
]
```
-스킬 번들이 자체 릴리스 주기를 가지거나 샌드박스 간 공유되어야 할 때 사용하세요. [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)를 참고하세요.
+스킬 번들이 자체 릴리스 주기를 가지거나 샌드박스 간에 공유되어야 할 때 사용하세요. [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)를 참고하세요.
### 도구로 노출
-도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고, 상위 실행의 실제 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색 에이전트에 유용합니다. 다른 샌드박스를 생성, hydrate, 스냅샷하는 비용 없이 상위가 사용하는 정확한 워크스페이스를 검사할 수 있기 때문입니다.
+도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고 부모 실행의 라이브 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색 에이전트에 유용합니다. 별도의 샌드박스를 생성, hydration, 스냅샷하는 비용 없이 부모가 사용하는 정확한 워크스페이스를 검사할 수 있기 때문입니다.
```python
from agents import Runner
@@ -764,9 +764,9 @@ async with sandbox:
)
```
-여기서 상위 에이전트는 `coordinator`로 실행되고, 탐색기 도구 에이전트는 동일한 실제 샌드박스 세션 안에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색기가 빠르게 검사할 수 있지만 쓰기 비트는 없습니다. `work/` 디렉터리는 coordinator의 사용자/그룹에만 제공되므로 상위는 최종 아티팩트를 쓸 수 있지만 탐색기는 읽기 전용으로 유지됩니다.
+여기서 부모 에이전트는 `coordinator`로 실행되고, 탐색기 도구 에이전트는 동일한 라이브 샌드박스 세션 안에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색기가 이를 빠르게 검사할 수 있지만 쓰기 비트는 없습니다. `work/` 디렉터리는 coordinator의 사용자/그룹만 사용할 수 있으므로 부모는 최종 아티팩트를 쓸 수 있고 탐색기는 읽기 전용으로 유지됩니다.
-도구 에이전트에 실제 격리가 필요하다면 자체 샌드박스 `RunConfig`를 제공하세요.
+대신 도구 에이전트에 실제 격리가 필요하다면 자체 샌드박스 `RunConfig`를 제공하세요.
```python
from docker import from_env as docker_from_env
@@ -791,7 +791,7 @@ rollout_agent.as_tool(
### 로컬 도구 및 MCP와 결합
-동일한 에이전트에서 일반 도구를 계속 사용하면서 샌드박스 워크스페이스를 유지하세요.
+동일한 에이전트에서 일반 도구를 계속 사용하면서 샌드박스 워크스페이스도 유지할 수 있습니다.
```python
from agents.sandbox import SandboxAgent
@@ -810,42 +810,42 @@ agent = SandboxAgent(
## 메모리
-향후 샌드박스 에이전트 실행이 이전 실행에서 학습해야 한다면 `Memory` 기능을 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와는 별개입니다. 샌드박스 워크스페이스 내부 파일에 교훈을 추출해 저장하고, 이후 실행은 그 파일을 읽을 수 있습니다.
+향후 샌드박스 에이전트 실행이 이전 실행에서 학습해야 한다면 `Memory` 기능을 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와는 별개입니다. 샌드박스 워크스페이스 내부의 파일로 교훈을 정제하고, 이후 실행에서 해당 파일을 읽을 수 있습니다.
-설정, 읽기/생성 동작, 멀티턴 대화, 레이아웃 격리에 대해서는 [에이전트 메모리](memory.md)를 참조하세요.
+설정, 읽기/생성 동작, 멀티턴 대화, 레이아웃 격리는 [Agent memory](memory.md)를 참고하세요.
## 구성 패턴
단일 에이전트 패턴이 명확해지면, 다음 설계 질문은 더 큰 시스템에서 샌드박스 경계를 어디에 둘 것인가입니다.
-샌드박스 에이전트는 여전히 SDK의 나머지 부분과 조합됩니다.
+샌드박스 에이전트는 여전히 SDK의 나머지 부분과 조합할 수 있습니다.
-- [Handoffs](../handoffs.md): 샌드박스가 아닌 intake 에이전트에서 문서 중심 작업을 샌드박스 검토자로 핸드오프
-- [Agents as tools](../tools.md#agents-as-tools): 여러 샌드박스 에이전트를 도구로 노출. 보통 각 `Agent.as_tool(...)` 호출에 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`를 전달해 각 도구가 자체 샌드박스 경계를 갖게 함
-- [MCP](../mcp.md) 및 일반 함수 도구: 샌드박스 기능은 `mcp_servers` 및 일반 Python 도구와 공존 가능
-- [Running agents](../running_agents.md): 샌드박스 실행도 여전히 일반 `Runner` API를 사용
+- [Handoffs](../handoffs.md): 샌드박스가 아닌 intake 에이전트에서 문서 중심 작업을 샌드박스 리뷰어로 핸드오프합니다
+- [Agents as tools](../tools.md#agents-as-tools): 여러 샌드박스 에이전트를 도구로 노출합니다. 일반적으로 각 도구가 자체 샌드박스 경계를 갖도록 각 `Agent.as_tool(...)` 호출에 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`를 전달합니다
+- [MCP](../mcp.md) 및 일반 함수 도구: 샌드박스 기능은 `mcp_servers` 및 일반 Python 도구와 공존할 수 있습니다
+- [Running agents](../running_agents.md): 샌드박스 실행도 여전히 일반적인 `Runner` API를 사용합니다
-특히 흔한 패턴은 다음 두 가지입니다.
+특히 흔한 패턴은 두 가지입니다.
-- 샌드박스가 아닌 에이전트가 워크스페이스 격리가 필요한 워크플로 부분에서만 샌드박스 에이전트로 핸드오프하는 패턴
-- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출하는 패턴. 보통 각 `Agent.as_tool(...)` 호출마다 별도의 샌드박스 `RunConfig`를 사용해 각 도구가 자체 격리 워크스페이스를 갖게 함
+- 워크스페이스 격리가 필요한 워크플로의 일부에 대해서만 샌드박스가 아닌 에이전트가 샌드박스 에이전트로 핸드오프하는 패턴
+- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출하는 패턴으로, 보통 각 도구가 자체 격리 워크스페이스를 갖도록 각 `Agent.as_tool(...)` 호출마다 별도의 샌드박스 `RunConfig`를 사용합니다
-### 턴과 샌드박스 실행
+### Turns와 샌드박스 실행
핸드오프와 agent-as-tool 호출은 별도로 설명하는 것이 도움이 됩니다.
-핸드오프에서는 여전히 하나의 최상위 실행과 하나의 최상위 턴 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 샌드박스가 아닌 intake 에이전트가 샌드박스 검토자에게 핸드오프하면, 동일한 실행 안의 다음 모델 호출은 샌드박스 에이전트를 위해 준비되고, 그 샌드박스 에이전트가 다음 턴을 담당하게 됩니다. 즉, 핸드오프는 동일한 실행의 다음 턴을 어떤 에이전트가 소유하는지만 바꿉니다. [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)를 참고하세요.
+핸드오프에서는 여전히 하나의 최상위 실행과 하나의 최상위 turn 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 샌드박스가 아닌 intake 에이전트가 샌드박스 리뷰어로 핸드오프하면, 같은 실행에서 다음 모델 호출은 샌드박스 에이전트에 맞게 준비되고, 그 샌드박스 에이전트가 다음 turn을 수행하는 주체가 됩니다. 즉, 핸드오프는 같은 실행의 다음 turn을 어떤 에이전트가 담당할지 바꿉니다. [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)를 참고하세요.
-`Agent.as_tool(...)`에서는 관계가 다릅니다. 바깥 오케스트레이터는 하나의 바깥 턴에서 도구 호출을 결정하고, 그 도구 호출이 샌드박스 에이전트에 대한 중첩 실행을 시작합니다. 중첩 실행은 자체 턴 루프, `max_turns`, 승인, 그리고 보통 자체 샌드박스 `RunConfig`를 가집니다. 한 번의 중첩 턴에서 끝날 수도 있고 여러 번 걸릴 수도 있습니다. 바깥 오케스트레이터 관점에서는 이 모든 작업이 여전히 하나의 도구 호출 뒤에 있으므로, 중첩 턴은 바깥 실행의 턴 카운터를 증가시키지 않습니다. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참고하세요.
+`Agent.as_tool(...)`에서는 관계가 다릅니다. 바깥쪽 오케스트레이터는 하나의 바깥쪽 turn을 사용해 도구 호출을 결정하고, 그 도구 호출은 샌드박스 에이전트에 대한 중첩 실행을 시작합니다. 중첩 실행은 자체 turn 루프, `max_turns`, 승인, 그리고 보통 자체 샌드박스 `RunConfig`를 가집니다. 한 번의 중첩 turn으로 끝날 수도 있고 여러 번 걸릴 수도 있습니다. 바깥쪽 오케스트레이터 관점에서는 이 모든 작업이 여전히 하나의 도구 호출 뒤에 있으므로, 중첩된 turns는 바깥쪽 실행의 turn 카운터를 증가시키지 않습니다. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참고하세요.
승인 동작도 같은 분리를 따릅니다.
-- 핸드오프에서는 샌드박스 에이전트가 이제 그 실행의 활성 에이전트이므로 승인이 동일한 최상위 실행에 남습니다
-- `Agent.as_tool(...)`에서는 샌드박스 도구 에이전트 내부에서 발생한 승인도 바깥 실행에 노출되지만, 저장된 중첩 실행 상태에서 오며 바깥 실행이 재개될 때 중첩 샌드박스 실행도 함께 재개됩니다
+- 핸드오프에서는 샌드박스 에이전트가 이제 해당 실행의 활성 에이전트이므로 승인은 동일한 최상위 실행에 유지됩니다
+- `Agent.as_tool(...)`에서는 샌드박스 도구 에이전트 내부에서 발생한 승인도 여전히 바깥쪽 실행에 표시되지만, 저장된 중첩 실행 상태에서 발생하며 바깥쪽 실행이 재개될 때 중첩된 샌드박스 실행도 재개됩니다
## 추가 읽을거리
-- [Quickstart](quickstart.md): 샌드박스 에이전트 하나를 실행하기
-- [Sandbox clients](clients.md): 로컬, Docker, 호스티드, 마운트 옵션 선택
-- [Agent memory](memory.md): 이전 샌드박스 실행의 교훈 보존 및 재사용
+- [Quickstart](quickstart.md): 하나의 샌드박스 에이전트를 실행합니다
+- [Sandbox clients](clients.md): 로컬, Docker, 호스티드, 마운트 옵션을 선택합니다
+- [Agent memory](memory.md): 이전 샌드박스 실행의 교훈을 보존하고 재사용합니다
- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 실행 가능한 로컬, 코딩, 메모리, 핸드오프, 에이전트 구성 패턴
\ No newline at end of file
diff --git a/docs/zh/sandbox/clients.md b/docs/zh/sandbox/clients.md
index 2a732d9b96..912c375faf 100644
--- a/docs/zh/sandbox/clients.md
+++ b/docs/zh/sandbox/clients.md
@@ -4,11 +4,11 @@ search:
---
# Sandbox 客户端
-使用本页来选择 sandbox 工作应在何处运行。在大多数情况下，`SandboxAgent` 定义保持不变，而 sandbox 客户端和客户端特定选项会在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中变化。
+使用本页来选择 sandbox 工作应在哪运行。在大多数情况下，`SandboxAgent` 定义保持不变，而 sandbox 客户端和特定于客户端的选项会在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中发生变化。
!!! warning "Beta 功能"
- sandbox 智能体目前处于 beta 阶段。预计 API 的细节、默认值以及支持的能力会在正式可用前发生变化，并且随着时间推移会提供更高级的功能。
+ Sandbox 智能体处于 beta 阶段。预计 API 的细节、默认值和支持的能力会在正式可用前发生变化，并且更多高级功能也会随着时间逐步推出。
## 决策指南
@@ -16,28 +16,28 @@ search:
| 目标 | 起步选择 | 原因 |
| --- | --- | --- |
-| 在 macOS 或 Linux 上进行最快的本地迭代 | `UnixLocalSandboxClient` | 无需额外安装，适合简单的本地文件系统开发。 |
-| 基本的容器隔离 | `DockerSandboxClient` | 在 Docker 内使用特定镜像运行工作。 |
-| 托管执行或生产环境风格的隔离 | 托管 sandbox 客户端 | 将工作区边界转移到由提供方管理的环境中。 |
+| 在 macOS 或 Linux 上实现最快的本地迭代 | `UnixLocalSandboxClient` | 无需额外安装，适合简单的本地文件系统开发。 |
+| 基本的容器隔离 | `DockerSandboxClient` | 在 Docker 中使用特定镜像运行工作负载。 |
+| 托管执行或生产风格的隔离 | 托管 sandbox 客户端 | 将工作区边界转移到由提供商管理的环境中。 |
## 本地客户端
-对大多数用户来说，建议从以下两个 sandbox 客户端之一开始：
+对于大多数用户，请从以下两种 sandbox 客户端之一开始：
| 客户端 | 安装 | 适用场景 | 示例 |
| --- | --- | --- | --- |
-| `UnixLocalSandboxClient` | 无 | 在 macOS 或 Linux 上进行最快的本地迭代。是本地开发的良好默认选择。 | [Unix 本地入门](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) |
-| `DockerSandboxClient` | `openai-agents[docker]` | 你希望获得容器隔离，或为本地一致性使用特定镜像。 | [Docker 入门](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |
+| `UnixLocalSandboxClient` | 无 | 在 macOS 或 Linux 上进行最快的本地迭代。适合作为本地开发的默认选择。 | [Unix 本地入门](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) |
+| `DockerSandboxClient` | `openai-agents[docker]` | 你需要容器隔离，或希望使用特定镜像来实现本地一致性。 | [Docker 入门](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |
-Unix 本地方式是在本地文件系统上开始开发的最简单方法。当你需要更强的环境隔离或生产环境风格的一致性时，再迁移到 Docker 或托管提供方。
+Unix 本地方式是开始针对本地文件系统进行开发的最简单方法。当你需要更强的环境隔离或生产风格的一致性时，再迁移到 Docker 或托管提供商。
-要从 Unix 本地切换到 Docker，保持智能体定义不变，只修改 run config：
+若要从 Unix 本地切换到 Docker，请保持智能体定义不变，仅修改运行配置：
```python
from docker import from_env as docker_from_env
@@ -54,19 +54,19 @@ run_config = RunConfig(
)
```
-当你需要容器隔离或镜像一致性时，请使用这种方式。参见 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。
+当你需要容器隔离或镜像一致性时，请使用此方式。请参见[examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。
## 挂载与远程存储
-挂载条目描述要暴露哪些存储；挂载策略描述 sandbox 后端如何附加这些存储。从 `agents.sandbox.entries` 导入内置挂载条目和通用策略。托管提供方策略可从 `agents.extensions.sandbox` 或提供方特定扩展包中获取。
+挂载条目用于描述要暴露的存储；挂载策略用于描述 sandbox 后端如何附加该存储。从 `agents.sandbox.entries` 导入内置挂载条目和通用策略。托管提供商策略可从 `agents.extensions.sandbox` 或提供商专用扩展包中获取。
常见挂载选项：
- `mount_path`：存储在 sandbox 中显示的位置。相对路径会在清单根目录下解析；绝对路径会按原样使用。
-- `read_only`：默认为 `True`。仅当 sandbox 应将内容写回挂载存储时才设置为 `False`。
-- `mount_strategy`：必填。使用同时与挂载条目和 sandbox 后端匹配的策略。
+- `read_only`：默认为 `True`。仅当 sandbox 需要将内容写回挂载存储时，才设置为 `False`。
+- `mount_strategy`：必填。请使用同时匹配挂载条目和 sandbox 后端的策略。
-挂载会被视为临时工作区条目。快照和持久化流程会分离或跳过挂载路径，而不是将挂载的远程存储复制到保存的工作区中。
+挂载会被视为临时工作区条目。快照和持久化流程会分离或跳过已挂载路径，而不是将已挂载的远程存储复制到保存的工作区中。
通用本地/容器策略：
@@ -74,21 +74,21 @@ run_config = RunConfig(
| 策略或模式 | 适用场景 | 说明 |
| --- | --- | --- |
-| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | sandbox 镜像可以运行 `rclone`。 | 支持 S3、GCS、R2 和 Azure Blob。`RcloneMountPattern` 可运行于 `fuse` 模式或 `nfs` 模式。 |
-| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 镜像内有 `mount-s3`，且你希望使用 Mountpoint 风格的 S3 或 S3 兼容访问。 | 支持 `S3Mount` 和 `GCSMount`。 |
-| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 镜像内有 `blobfuse2` 且支持 FUSE。 | 支持 `AzureBlobMount`。 |
-| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 镜像内有 `mount.s3files`，并且可以访问现有的 S3 Files 挂载目标。 | 支持 `S3FilesMount`。 |
-| `DockerVolumeMountStrategy(driver=...)` | Docker 应在容器启动前附加一个由 volume driver 支持的挂载。 | 仅适用于 Docker。S3、GCS、R2 和 Azure Blob 支持 `rclone`；S3 和 GCS 还支持 `mountpoint`。 |
+| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | sandbox 镜像可以运行 `rclone`。 | 支持 S3、GCS、R2、Azure Blob 和 Box。`RcloneMountPattern` 可在 `fuse` 模式或 `nfs` 模式下运行。 |
+| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 镜像中具有 `mount-s3`，且你希望使用 Mountpoint 风格的 S3 或兼容 S3 的访问方式。 | 支持 `S3Mount` 和 `GCSMount`。 |
+| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 镜像中具有 `blobfuse2` 且支持 FUSE。 | 支持 `AzureBlobMount`。 |
+| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 镜像中具有 `mount.s3files`，并且能够访问现有的 S3 Files 挂载目标。 | 支持 `S3FilesMount`。 |
+| `DockerVolumeMountStrategy(driver=...)` | Docker 应在容器启动前附加由卷驱动支持的挂载。 | 仅适用于 Docker。S3、GCS、R2、Azure Blob 和 Box 支持 `rclone`；S3 和 GCS 还支持 `mountpoint`。 |
## 支持的托管平台
-当你需要托管环境时，通常相同的 `SandboxAgent` 定义可以直接沿用，仅需在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中更换 sandbox 客户端。
+当你需要托管环境时，通常可以继续使用相同的 `SandboxAgent` 定义，而只需在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中更换 sandbox 客户端。
-如果你使用的是已发布的 SDK，而不是此仓库的检出版本，请通过对应的软件包 extra 安装 sandbox 客户端依赖。
+如果你使用的是已发布的 SDK，而不是此仓库的检出版本，请通过对应的包 extra 安装 sandbox 客户端依赖。
-有关提供方特定的设置说明以及已签入扩展示例的链接，请参见 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)。
+有关特定提供商的设置说明以及仓库内扩展示例的链接，请参见[examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)。
@@ -104,38 +104,38 @@ run_config = RunConfig(
-托管 sandbox 客户端会公开提供方特定的挂载策略。请选择最适合你的存储提供方的后端与挂载策略：
+托管 sandbox 客户端会暴露提供商特定的挂载策略。请选择最适合你的存储提供商的后端和挂载策略：
| 后端 | 挂载说明 |
| --- | --- |
-| Docker | 支持将 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount` 和 `S3FilesMount` 与本地策略（如 `InContainerMountStrategy` 和 `DockerVolumeMountStrategy`）配合使用。 |
-| `ModalSandboxClient` | 支持通过 `ModalCloudBucketMountStrategy` 在 `S3Mount`、`R2Mount` 和使用 HMAC 认证的 `GCSMount` 上挂载 Modal cloud bucket。你可以使用内联凭证或已命名的 Modal Secret。 |
-| `CloudflareSandboxClient` | 支持通过 `CloudflareBucketMountStrategy` 在 `S3Mount`、`R2Mount` 和使用 HMAC 认证的 `GCSMount` 上挂载 Cloudflare bucket。 |
-| `BlaxelSandboxClient` | 支持通过 `BlaxelCloudBucketMountStrategy` 在 `S3Mount`、`R2Mount` 和 `GCSMount` 上挂载 cloud bucket。还支持来自 `agents.extensions.sandbox.blaxel` 的 `BlaxelDriveMount` 和 `BlaxelDriveMountStrategy`，用于持久化 Blaxel Drive。 |
-| `DaytonaSandboxClient` | 支持通过 `DaytonaCloudBucketMountStrategy` 挂载 cloud bucket；可与 `S3Mount`、`GCSMount`、`R2Mount` 和 `AzureBlobMount` 搭配使用。 |
-| `E2BSandboxClient` | 支持通过 `E2BCloudBucketMountStrategy` 挂载 cloud bucket；可与 `S3Mount`、`GCSMount`、`R2Mount` 和 `AzureBlobMount` 搭配使用。 |
-| `RunloopSandboxClient` | 支持通过 `RunloopCloudBucketMountStrategy` 挂载 cloud bucket；可与 `S3Mount`、`GCSMount`、`R2Mount` 和 `AzureBlobMount` 搭配使用。 |
-| `VercelSandboxClient` | 当前未公开托管特定的挂载策略。请改用清单文件、仓库或其他工作区输入。 |
+| Docker | 支持将 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` 和 `S3FilesMount` 与 `InContainerMountStrategy`、`DockerVolumeMountStrategy` 等本地策略配合使用。 |
+| `ModalSandboxClient` | 支持在 `S3Mount`、`R2Mount` 和使用 HMAC 认证的 `GCSMount` 上通过 `ModalCloudBucketMountStrategy` 挂载 Modal cloud bucket。你可以使用内联凭证或命名的 Modal Secret。 |
+| `CloudflareSandboxClient` | 支持在 `S3Mount`、`R2Mount` 和使用 HMAC 认证的 `GCSMount` 上通过 `CloudflareBucketMountStrategy` 挂载 Cloudflare bucket。 |
+| `BlaxelSandboxClient` | 支持在 `S3Mount`、`R2Mount` 和 `GCSMount` 上通过 `BlaxelCloudBucketMountStrategy` 挂载 cloud bucket。还支持来自 `agents.extensions.sandbox.blaxel` 的 `BlaxelDriveMount` 和 `BlaxelDriveMountStrategy`，用于持久化的 Blaxel Drive。 |
+| `DaytonaSandboxClient` | 支持通过 `DaytonaCloudBucketMountStrategy` 挂载基于 rclone 的云存储；可与 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount` 和 `BoxMount` 搭配使用。 |
+| `E2BSandboxClient` | 支持通过 `E2BCloudBucketMountStrategy` 挂载基于 rclone 的云存储；可与 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount` 和 `BoxMount` 搭配使用。 |
+| `RunloopSandboxClient` | 支持通过 `RunloopCloudBucketMountStrategy` 挂载基于 rclone 的云存储；可与 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount` 和 `BoxMount` 搭配使用。 |
+| `VercelSandboxClient` | 当前未暴露托管专用的挂载策略。请改用清单文件、代码仓库或其他工作区输入方式。 |
-下表总结了每个后端可直接挂载的远程存储条目。
+下表总结了每个后端可以直接挂载的远程存储条目。
-| 后端 | AWS S3 | Cloudflare R2 | GCS | Azure Blob Storage | S3 Files |
-| --- | --- | --- | --- | --- | --- |
-| Docker | ✓ | ✓ | ✓ | ✓ | ✓ |
-| `ModalSandboxClient` | ✓ | ✓ | ✓ | - | - |
-| `CloudflareSandboxClient` | ✓ | ✓ | ✓ | - | - |
-| `BlaxelSandboxClient` | ✓ | ✓ | ✓ | - | - |
-| `DaytonaSandboxClient` | ✓ | ✓ | ✓ | ✓ | - |
-| `E2BSandboxClient` | ✓ | ✓ | ✓ | ✓ | - |
-| `RunloopSandboxClient` | ✓ | ✓ | ✓ | ✓ | - |
-| `VercelSandboxClient` | - | - | - | - | - |
+| 后端 | AWS S3 | Cloudflare R2 | GCS | Azure Blob Storage | Box | S3 Files |
+| --- | --- | --- | --- | --- | --- | --- |
+| Docker | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `ModalSandboxClient` | ✓ | ✓ | ✓ | - | - | - |
+| `CloudflareSandboxClient` | ✓ | ✓ | ✓ | - | - | - |
+| `BlaxelSandboxClient` | ✓ | ✓ | ✓ | - | - | - |
+| `DaytonaSandboxClient` | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| `E2BSandboxClient` | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| `RunloopSandboxClient` | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| `VercelSandboxClient` | - | - | - | - | - | - |
-如需更多可运行的示例，请浏览 [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)，其中包含本地、编码、内存、任务转移和智能体组合模式；托管 sandbox 客户端示例请参见 [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)。
\ No newline at end of file
+如需更多可运行的示例，请浏览[examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)了解本地、编码、内存、任务转移和智能体组合模式，并浏览[examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)了解托管 sandbox 客户端。
\ No newline at end of file
diff --git a/docs/zh/sandbox/guide.md b/docs/zh/sandbox/guide.md
index d45761db30..cc39db6cb0 100644
--- a/docs/zh/sandbox/guide.md
+++ b/docs/zh/sandbox/guide.md
@@ -6,35 +6,35 @@ search:
!!! warning "Beta 功能"
- Sandbox 智能体目前处于 beta 阶段。在正式可用之前，API 的细节、默认值和支持的能力都可能发生变化，未来也会逐步提供更高级的功能。
+ 沙盒智能体目前处于 beta 阶段。API 的细节、默认值和支持的能力在正式可用前都可能发生变化，并且功能会随着时间推移变得更高级。
-现代智能体在能够对文件系统中的真实文件进行操作时效果最佳。**Sandbox 智能体**可以使用专门的工具和 shell 命令，对大型文档集合进行搜索和处理、编辑文件、生成产物以及运行命令。sandbox 为模型提供了一个持久化工作区，智能体可以代表你在其中完成工作。Agents SDK 中的 Sandbox 智能体帮助你轻松运行与 sandbox 环境配对的智能体，使文件进入文件系统变得简单，并通过编排 sandbox，让大规模启动、停止和恢复任务变得容易。
+现代智能体在能够操作文件系统中的真实文件时效果最佳。**Sandbox Agents** 可以使用专门的工具和 shell 命令来搜索和处理大型文档集、编辑文件、生成产物以及运行命令。沙盒为模型提供了一个持久化工作区，智能体可以用它来代你完成工作。Agents SDK 中的沙盒智能体帮助你轻松运行与沙盒环境配对的智能体，使正确的文件进入文件系统变得简单，并对沙盒进行智能体编排，从而便于大规模启动、停止和恢复任务。
-你可以围绕智能体所需的数据来定义工作区。它可以从 GitHub 仓库、本地文件和目录、合成任务文件、远程文件系统（如 S3 或 Azure Blob Storage）以及你提供的其他 sandbox 输入开始。
+你可以围绕智能体所需的数据定义工作区。它可以从 GitHub 仓库、本地文件和目录、合成任务文件、S3 或 Azure Blob Storage 等远程文件系统，以及你提供的其他沙盒输入开始。
-
+
-`SandboxAgent` 仍然是一个 `Agent`。它保留了常规智能体的接口，例如 `instructions`、`prompt`、`tools`、`handoffs`、`mcp_servers`、`model_settings`、`output_type`、安全防护措施和 hooks，并且仍然通过常规的 `Runner` API 运行。变化之处在于执行边界：
+`SandboxAgent` 仍然是一个 `Agent`。它保留了常规智能体接口，例如 `instructions`、`prompt`、`tools`、`handoffs`、`mcp_servers`、`model_settings`、`output_type`、安全防护措施和 hooks，并且仍通过常规的 `Runner` API 运行。变化在于执行边界：
-- `SandboxAgent` 定义智能体本身：常规的智能体配置，加上 sandbox 专属默认值，例如 `default_manifest`、`base_instructions`、`run_as`，以及文件系统工具、shell 访问、skills、memory 或 compaction 等能力。
-- `Manifest` 声明一个全新 sandbox 工作区的期望初始内容和布局，包括文件、仓库、挂载和环境。
-- sandbox session 是命令运行和文件发生变化的实时隔离环境。
-- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]决定此次运行如何获得该 sandbox session，例如直接注入一个 session、从序列化的 sandbox session 状态重新连接，或通过 sandbox client 创建一个全新的 sandbox session。
-- 保存的 sandbox 状态和快照允许后续运行重新连接到先前的工作，或通过保存的内容为新的 sandbox session 提供初始数据。
+- `SandboxAgent` 定义智能体本身：常规的智能体配置，加上沙盒专属默认值，如 `default_manifest`、`base_instructions`、`run_as`，以及文件系统工具、shell 访问、skills、内存或压缩等能力。
+- `Manifest` 声明全新沙盒工作区所需的初始内容和布局，包括文件、仓库、挂载和环境。
+- 沙盒会话是命令运行和文件变更发生的实时隔离环境。
+- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 决定此次运行如何获得该沙盒会话，例如直接注入一个沙盒会话、从序列化的沙盒会话状态重新连接，或通过沙盒客户端创建一个全新的沙盒会话。
+- 已保存的沙盒状态和快照使后续运行能够重新连接到先前的工作，或用保存的内容为新的沙盒会话提供初始数据。
-`Manifest` 是全新 session 工作区的契约，而不是每个实时 sandbox 的完整事实来源。一次运行的实际工作区也可能来自复用的 sandbox session、序列化的 sandbox session 状态，或在运行时选择的快照。
+`Manifest` 是全新会话工作区的契约，而不是每个实时沙盒的完整事实来源。一次运行的实际工作区也可以来自复用的沙盒会话、序列化的沙盒会话状态，或在运行时选定的快照。
-在本页中，“sandbox session”指由 sandbox client 管理的实时执行环境。它不同于 [Sessions](../sessions/index.md) 中描述的 SDK 对话式 [`Session`][agents.memory.session.Session] 接口。
+在本页中，“沙盒会话”指由沙盒客户端管理的实时执行环境。它不同于 [Sessions](../sessions/index.md) 中描述的 SDK 会话式 [`Session`][agents.memory.session.Session] 接口。
-外层运行时仍然负责审批、追踪、任务转移和恢复记录。sandbox session 负责命令、文件更改和环境隔离。这种划分是该模型的核心部分。
+外层运行时仍负责审批、追踪、任务转移和恢复记录。沙盒会话负责命令、文件变更和环境隔离。这种划分是该模型的核心组成部分。
-### 组件关系
+### 组件配合方式
-一次 sandbox 运行会将一个智能体定义与按次运行的 sandbox 配置结合起来。runner 会准备智能体，将其绑定到一个实时 sandbox session，并且可以保存状态供后续运行使用。
+一次沙盒运行会将智能体定义与每次运行的沙盒配置组合起来。运行器会准备智能体，将其绑定到一个实时沙盒会话，并可为后续运行保存状态。
```mermaid
flowchart LR
@@ -50,33 +50,33 @@ flowchart LR
sandbox --> saved
```
-sandbox 专属默认值保留在 `SandboxAgent` 上。按次运行的 sandbox-session 选择保留在 `SandboxRunConfig` 中。
+沙盒专属默认值保留在 `SandboxAgent` 上。每次运行的沙盒会话选择保留在 `SandboxRunConfig` 中。
-可以将其生命周期分为三个阶段来理解：
+可以将生命周期理解为三个阶段：
-1. 使用 `SandboxAgent`、`Manifest` 和 capabilities 定义智能体以及全新工作区契约。
-2. 通过向 `Runner` 提供一个 `SandboxRunConfig` 来执行运行，该配置会注入、恢复或创建 sandbox session。
-3. 稍后通过 runner 管理的 `RunState`、显式的 sandbox `session_state`，或保存的工作区快照继续执行。
+1. 使用 `SandboxAgent`、`Manifest` 和能力定义智能体以及全新工作区契约。
+2. 通过向 `Runner` 提供一个 `SandboxRunConfig` 来执行运行，该配置用于注入、恢复或创建沙盒会话。
+3. 之后可从由运行器管理的 `RunState`、显式的沙盒 `session_state`，或已保存的工作区快照继续。
-如果 shell 访问只是一个偶尔用到的工具，请先从[工具指南](../tools.md)中的托管 shell 开始。当工作区隔离、sandbox client 选择或 sandbox-session 恢复行为本身就是设计的一部分时，再使用 sandbox 智能体。
+如果 shell 访问只是偶尔使用的工具，请先从[工具指南](../tools.md)中的托管 shell 开始。只有当工作区隔离、沙盒客户端选择或沙盒会话恢复行为是设计的一部分时，再使用沙盒智能体。
## 适用场景
-Sandbox 智能体非常适合以工作区为中心的工作流，例如：
+沙盒智能体非常适合以工作区为中心的工作流，例如：
-- 编码与调试，例如为 GitHub 仓库中的 issue 报告编排自动修复并运行有针对性的测试
-- 文档处理与编辑，例如从用户的财务文档中提取信息并创建已填写的报税表草稿
-- 基于文件的审查或分析，例如在回答之前检查入职材料、生成的报告或产物包
-- 隔离的多智能体模式，例如为每个审查者或编码子智能体分配各自的工作区
-- 多步骤工作区任务，例如一次运行中修复 bug，之后再添加回归测试，或从快照或 sandbox session 状态恢复
+- 编码与调试，例如在 GitHub 仓库中对 issue 报告进行自动修复编排并运行定向测试
+- 文档处理与编辑，例如从用户的财务文件中提取信息并创建已填写的报税表草稿
+- 基于文件的审查或分析，例如在回答前检查入职材料包、生成的报告或产物包
+- 隔离的多智能体模式，例如为每个审查者或编码子智能体提供其独立工作区
+- 多步骤工作区任务，例如一次运行中修复 bug，之后再添加回归测试，或从快照或沙盒会话状态恢复
-如果你不需要访问文件或持续存在的文件系统，继续使用 `Agent` 即可。如果 shell 访问只是偶尔需要的一项能力，可以添加托管 shell；如果工作区边界本身就是功能的一部分，请使用 sandbox 智能体。
+如果你不需要访问文件或一个活跃的文件系统，请继续使用 `Agent`。如果 shell 访问只是偶尔需要的能力，则添加托管 shell；如果工作区边界本身就是功能的一部分，则使用沙盒智能体。
-## sandbox client 选择
+## 沙盒客户端选择
-本地开发时先使用 `UnixLocalSandboxClient`。当你需要容器隔离或镜像一致性时，切换到 `DockerSandboxClient`。当你需要由提供方管理执行环境时，切换到托管提供方。
+本地开发时从 `UnixLocalSandboxClient` 开始。需要容器隔离或镜像一致性时，转到 `DockerSandboxClient`。需要由提供方托管执行时，转到托管提供方。
-在大多数情况下，`SandboxAgent` 定义保持不变，变化的是 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中的 sandbox client 及其选项。有关本地、Docker、托管和远程挂载选项，请参见[Sandbox clients](clients.md)。
+在大多数情况下，`SandboxAgent` 定义保持不变，而沙盒客户端及其选项在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中变化。有关本地、Docker、托管和远程挂载选项，请参见[沙盒客户端](clients.md)。
## 核心组件
@@ -84,164 +84,164 @@ Sandbox 智能体非常适合以工作区为中心的工作流，例如：
| 层级 | 主要 SDK 组件 | 它回答的问题 |
| --- | --- | --- |
-| 智能体定义 | `SandboxAgent`、`Manifest`、capabilities | 将运行什么智能体，以及它应从什么样的全新 session 工作区契约开始？ |
-| Sandbox 执行 | `SandboxRunConfig`、sandbox client 和实时 sandbox session | 这次运行如何获得一个实时 sandbox session，工作又是在何处执行？ |
-| 已保存的 sandbox 状态 | `RunState` 的 sandbox 载荷、`session_state` 和 snapshots | 该工作流如何重新连接到先前的 sandbox 工作，或通过已保存内容为新的 sandbox session 提供初始数据？ |
+| 智能体定义 | `SandboxAgent`、`Manifest`、能力 | 将运行什么智能体，它应从什么样的全新会话工作区契约开始？ |
+| 沙盒执行 | `SandboxRunConfig`、沙盒客户端和实时沙盒会话 | 此次运行如何获得一个实时沙盒会话，工作将在何处执行？ |
+| 已保存的沙盒状态 | `RunState` 沙盒负载、`session_state` 和快照 | 此工作流如何重新连接到先前的沙盒工作，或用保存的内容为新的沙盒会话提供初始数据？ |
-主要的 SDK 组件与这些层级的映射如下：
+主要 SDK 组件与这些层级的对应关系如下：
-| 组件 | 它负责的内容 | 问自己这个问题 |
+| 组件 | 它负责的内容 | 请问这个问题 |
| --- | --- | --- |
-| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 智能体定义 | 这个智能体应该做什么，哪些默认值应该随它一起传递？ |
-| [`Manifest`][agents.sandbox.manifest.Manifest] | 全新 session 工作区中的文件和文件夹 | 运行开始时，文件系统中应该有哪些文件和文件夹？ |
-| [`Capability`][agents.sandbox.capabilities.capability.Capability] | sandbox 原生行为 | 哪些工具、指令片段或运行时行为应附加到这个智能体上？ |
-| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 按次运行的 sandbox client 和 sandbox-session 来源 | 这次运行应该注入、恢复还是创建一个 sandbox session？ |
-| [`RunState`][agents.run_state.RunState] | 由 runner 管理的已保存 sandbox 状态 | 我是否在恢复一个先前由 runner 管理的工作流，并自动延续其 sandbox 状态？ |
-| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 显式序列化的 sandbox session 状态 | 我是否想从已经在 `RunState` 之外序列化好的 sandbox 状态恢复？ |
-| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 用于全新 sandbox sessions 的已保存工作区内容 | 一个新的 sandbox session 是否应该从已保存的文件和产物开始？ |
+| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 智能体定义 | 这个智能体应执行什么，以及哪些默认值应随其一起传递？ |
+| [`Manifest`][agents.sandbox.manifest.Manifest] | 全新会话工作区中的文件和文件夹 | 运行开始时，文件系统中应有哪些文件和文件夹？ |
+| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 沙盒原生行为 | 哪些工具、指令片段或运行时行为应附加到这个智能体上？ |
+| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 每次运行的沙盒客户端和沙盒会话来源 | 此次运行应注入、恢复还是创建一个沙盒会话？ |
+| [`RunState`][agents.run_state.RunState] | 由运行器管理的已保存沙盒状态 | 我是否正在恢复一个先前由运行器管理的工作流，并自动延续其沙盒状态？ |
+| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 显式序列化的沙盒会话状态 | 我是否希望从已在 `RunState` 之外序列化的沙盒状态恢复？ |
+| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 为新的沙盒会话保存的工作区内容 | 新的沙盒会话是否应从保存的文件和产物开始？ |
一个实用的设计顺序是：
-1. 用 `Manifest` 定义全新 session 工作区契约。
-2. 用 `SandboxAgent` 定义智能体。
-3. 添加内置或自定义 capabilities。
-4. 在 `RunConfig(sandbox=SandboxRunConfig(...))` 中决定每次运行应如何获取 sandbox session。
+1. 使用 `Manifest` 定义全新会话工作区契约。
+2. 使用 `SandboxAgent` 定义智能体。
+3. 添加内置或自定义能力。
+4. 在 `RunConfig(sandbox=SandboxRunConfig(...))` 中决定每次运行应如何获取其沙盒会话。
-## sandbox 运行的准备方式
+## 沙盒运行准备方式
-在运行时，runner 会将该定义转换为一次具体的、由 sandbox 支持的运行：
+在运行时，运行器会将该定义转换为一次具体的、由沙盒支持的运行：
-1. 它从 `SandboxRunConfig` 解析 sandbox session。
- 如果你传入 `session=...`，它会复用该实时 sandbox session。
- 否则它会使用 `client=...` 来创建或恢复一个。
-2. 它确定此次运行的实际工作区输入。
- 如果此次运行注入或恢复了一个 sandbox session，则该现有 sandbox 状态优先。
- 否则 runner 会从一次性的 manifest 覆盖项或 `agent.default_manifest` 开始。
- 这就是为什么仅凭 `Manifest` 无法定义每次运行最终的实时工作区。
-3. 它让 capabilities 处理生成的 manifest。
- 这样 capabilities 就可以在最终准备智能体之前，添加文件、挂载或其他工作区范围的行为。
-4. 它按固定顺序构建最终指令：
- SDK 的默认 sandbox 提示词，或者如果你显式覆盖则使用 `base_instructions`，然后是 `instructions`，然后是 capability 指令片段，再然后是任何远程挂载策略文本，最后是渲染后的文件系统树。
-5. 它将 capability 工具绑定到实时 sandbox session，并通过常规 `Runner` API 运行准备好的智能体。
+1. 它从 `SandboxRunConfig` 解析沙盒会话。
+ 如果你传入 `session=...`，它会复用该实时沙盒会话。
+ 否则它会使用 `client=...` 来创建或恢复一个会话。
+2. 它确定此次运行的实际工作区输入。
+ 如果运行注入或恢复了一个沙盒会话，则现有沙盒状态优先。
+ 否则，运行器从一次性 manifest 覆盖或 `agent.default_manifest` 开始。
+ 这就是为什么仅有 `Manifest` 并不能定义每次运行最终的实时工作区。
+3. 它让能力处理生成的 manifest。
+ 这样能力就可以在最终智能体准备完成前，添加文件、挂载或其他工作区范围的行为。
+4. 它按固定顺序构建最终指令：
+ SDK 的默认沙盒提示词，或者如果你显式覆盖了则使用 `base_instructions`，然后是 `instructions`，接着是能力指令片段，然后是任何远程挂载策略文本，最后是渲染后的文件系统树。
+5. 它将能力工具绑定到实时沙盒会话，并通过常规 `Runner` API 运行已准备好的智能体。
-sandbox 化不会改变一个 turn 的含义。turn 仍然是模型的一步，而不是单条 shell 命令或单个 sandbox 操作。sandbox 侧操作与 turn 之间不存在固定的 1:1 映射：有些工作可能停留在 sandbox 执行层中，而其他动作则会返回工具结果、审批或其他需要再次调用模型的状态。实际规则是，只有当智能体运行时在 sandbox 工作发生后还需要模型再次响应时，才会消耗另一个 turn。
+沙盒化不会改变一个 turn 的含义。turn 仍然是模型的一步，而不是单个 shell 命令或单次沙盒操作。沙盒侧操作与 turn 之间不存在固定的 1:1 映射：某些工作可能停留在沙盒执行层内部，而其他操作会返回工具结果、审批或其他需要模型再次响应的状态。实际规则是，只有当智能体运行时在沙盒工作发生后还需要模型再次响应时，才会消耗另一个 turn。
-这些准备步骤说明了为什么在设计 `SandboxAgent` 时，`default_manifest`、`instructions`、`base_instructions`、`capabilities` 和 `run_as` 是需要重点考虑的主要 sandbox 专属选项。
+这些准备步骤也是为什么在设计 `SandboxAgent` 时，`default_manifest`、`instructions`、`base_instructions`、`capabilities` 和 `run_as` 是主要需要考虑的沙盒专属选项。
## `SandboxAgent` 选项
-除了常规 `Agent` 字段外，还有以下 sandbox 专属选项：
+这些是在常规 `Agent` 字段基础上的沙盒专属选项：
| 选项 | 最佳用途 |
| --- | --- |
-| `default_manifest` | 由 runner 创建的全新 sandbox sessions 的默认工作区。 |
-| `instructions` | 在 SDK sandbox 提示词之后追加的额外角色、工作流和成功标准。 |
-| `base_instructions` | 用于替换 SDK sandbox 提示词的高级兜底选项。 |
-| `capabilities` | 应随此智能体一起传递的 sandbox 原生工具和行为。 |
-| `run_as` | 面向模型的 sandbox 工具（如 shell 命令、文件读取和补丁）所使用的用户身份。 |
+| `default_manifest` | 由运行器创建的新沙盒会话的默认工作区。 |
+| `instructions` | 追加在 SDK 沙盒提示词之后的额外角色、工作流和成功标准。 |
+| `base_instructions` | 用于替换 SDK 沙盒提示词的高级逃生口。 |
+| `capabilities` | 应随该智能体一起传递的沙盒原生工具和行为。 |
+| `run_as` | 面向模型的沙盒工具（如 shell 命令、文件读取和补丁）的用户身份。 |
-sandbox client 的选择、sandbox-session 的复用、manifest 覆盖以及 snapshot 选择属于 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]，而不是智能体本身。
+沙盒客户端选择、沙盒会话复用、manifest 覆盖和快照选择应放在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中，而不是放在智能体上。
### `default_manifest`
-`default_manifest` 是当 runner 为该智能体创建全新 sandbox session 时使用的默认 [`Manifest`][agents.sandbox.manifest.Manifest]。用它来放置智能体通常应当具备的文件、仓库、辅助材料、输出目录和挂载。
+`default_manifest` 是当运行器为该智能体创建新的沙盒会话时使用的默认 [`Manifest`][agents.sandbox.manifest.Manifest]。用它来定义智能体通常应具备的初始文件、仓库、辅助材料、输出目录和挂载。
-这只是默认值。运行时可以通过 `SandboxRunConfig(manifest=...)` 覆盖它，而复用或恢复的 sandbox session 会保留其现有工作区状态。
+这只是默认值。一次运行可以通过 `SandboxRunConfig(manifest=...)` 覆盖它，而复用或恢复的沙盒会话会保留其现有工作区状态。
### `instructions` 和 `base_instructions`
-将 `instructions` 用于那些应跨不同提示词保留的简短规则。在 `SandboxAgent` 中，这些指令会追加在 SDK 的 sandbox 基础提示词之后，因此你既能保留内置的 sandbox 指导，又能添加自己的角色、工作流和成功标准。
+使用 `instructions` 来放置那些应跨不同提示词保留的简短规则。在 `SandboxAgent` 中，这些指令会追加在 SDK 的沙盒基础提示词之后，因此你既保留了内置沙盒指导，也可以添加自己的角色、工作流和成功标准。
-只有在你想替换 SDK sandbox 基础提示词时，才使用 `base_instructions`。大多数智能体都不应设置它。
+仅当你想替换 SDK 沙盒基础提示词时才使用 `base_instructions`。大多数智能体都不应设置它。
-| 放在...里 | 用途 | 示例 |
+| 放在...中 | 用途 | 示例 |
| --- | --- | --- |
-| `instructions` | 智能体的稳定角色、工作流规则和成功标准。 | “检查入职文档，然后转交。”、“将最终文件写入 `output/`。” |
-| `base_instructions` | 完全替代 SDK sandbox 基础提示词。 | 自定义低层 sandbox 包装提示词。 |
-| 用户提示词 | 这次运行的一次性请求。 | “总结这个工作区。” |
-| manifest 中的工作区文件 | 更长的任务规范、仓库本地说明或有边界的参考材料。 | `repo/task.md`、文档包、样例资料包。 |
+| `instructions` | 智能体的稳定角色、工作流规则和成功标准。 | “检查入职文档，然后任务转移。”、“将最终文件写入 `output/`。” |
+| `base_instructions` | 对 SDK 沙盒基础提示词的完整替换。 | 自定义的底层沙盒包装提示词。 |
+| 用户提示词 | 此次运行的一次性请求。 | “总结这个工作区。” |
+| manifest 中的工作区文件 | 更长的任务规范、仓库本地说明或受限参考资料。 | `repo/task.md`、文档包、示例材料包。 |
`instructions` 的良好用法包括：
-- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) 在 PTY 状态重要时，让智能体保持在一个交互式进程中。
-- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) 禁止 sandbox 审查者在检查后直接回答用户。
-- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) 要求最终填写完成的文件必须实际落入 `output/`。
-- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 固定了精确的验证命令，并澄清了相对于工作区根目录的补丁路径。
+- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) 在 PTY 状态重要时让智能体保持在一个交互式进程中。
+- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) 禁止沙盒审查智能体在检查后直接回答用户。
+- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) 要求最终填写好的文件必须实际写入 `output/`。
+- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 固定了精确的验证命令，并明确补丁路径相对于工作区根目录。
-避免将用户的一次性任务复制到 `instructions` 中，避免嵌入本应属于 manifest 的长篇参考材料，避免重复内置 capabilities 已经注入的工具文档，也不要混入模型在运行时并不需要的本地安装说明。
+避免将用户的一次性任务复制到 `instructions` 中，避免嵌入应属于 manifest 的长参考材料，避免重复内置能力已经注入的工具文档，也不要混入模型在运行时并不需要的本地安装说明。
-如果你省略了 `instructions`，SDK 仍会包含默认的 sandbox 提示词。对于低层包装器来说这已经足够，但大多数面向用户的智能体仍应提供显式的 `instructions`。
+如果你省略 `instructions`，SDK 仍会包含默认的沙盒提示词。对于底层包装器来说这已经足够，但大多数面向用户的智能体仍应提供明确的 `instructions`。
### `capabilities`
-Capabilities 会将 sandbox 原生行为附加到 `SandboxAgent`。它们可以在运行开始前塑造工作区、追加 sandbox 专属指令、暴露绑定到实时 sandbox session 的工具，并调整该智能体的模型行为或输入处理方式。
+能力会将沙盒原生行为附加到 `SandboxAgent`。它们可以在运行开始前塑造工作区，追加沙盒专属说明，暴露绑定到实时沙盒会话的工具，并调整该智能体的模型行为或输入处理。
-内置 capabilities 包括：
+内置能力包括：
-| Capability | 在何时添加 | 说明 |
+| 能力 | 在何时添加 | 说明 |
| --- | --- | --- |
-| `Shell` | 智能体需要 shell 访问时。 | 添加 `exec_command`，并在 sandbox client 支持 PTY 交互时添加 `write_stdin`。 |
+| `Shell` | 智能体需要 shell 访问时。 | 添加 `exec_command`，当沙盒客户端支持 PTY 交互时还会添加 `write_stdin`。 |
| `Filesystem` | 智能体需要编辑文件或检查本地图像时。 | 添加 `apply_patch` 和 `view_image`；补丁路径相对于工作区根目录。 |
-| `Skills` | 你希望在 sandbox 中发现并具体化 skills 时。 | 对于 sandbox 本地的 `SKILL.md` skills，优先使用它，而不是手动挂载 `.agents` 或 `.agents/skills`。 |
-| `Memory` | 后续运行应读取或生成 memory 产物时。 | 需要 `Shell`；实时更新还需要 `Filesystem`。 |
-| `Compaction` | 长时间运行的流程在 compaction 项之后需要裁剪上下文时。 | 会调整模型采样和输入处理。 |
+| `Skills` | 你希望在沙盒中进行 skill 发现和实例化时。 | 对于沙盒本地的 `SKILL.md` skills，优先使用它，而不是手动挂载 `.agents` 或 `.agents/skills`。 |
+| `Memory` | 后续运行应读取或生成内存产物时。 | 需要 `Shell`；实时更新还需要 `Filesystem`。 |
+| `Compaction` | 长时间运行的流程在压缩项之后需要裁剪上下文时。 | 会调整模型采样和输入处理。 |
-默认情况下，`SandboxAgent.capabilities` 使用 `Capabilities.default()`，其中包括 `Filesystem()`、`Shell()` 和 `Compaction()`。如果你传入 `capabilities=[...]`，该列表会替换默认值，因此请加入你仍然需要的默认 capabilities。
+默认情况下，`SandboxAgent.capabilities` 使用 `Capabilities.default()`，其中包括 `Filesystem()`、`Shell()` 和 `Compaction()`。如果你传入 `capabilities=[...]`，该列表会替换默认值，因此请包含你仍然需要的默认能力。
-对于 skills，请根据你希望它们如何被具体化来选择来源：
+对于 skills，请根据你希望它们如何实例化来选择来源：
-- `Skills(lazy_from=LocalDirLazySkillSource(...))` 是较大的本地 skill 目录的良好默认选择，因为模型可以先发现索引，只加载所需内容。
-- `Skills(from_=LocalDir(src=...))` 更适合你希望预先放入的小型本地打包内容。
-- `Skills(from_=GitRepo(repo=..., ref=...))` 适合 skills 本身应来自某个仓库的情况。
+- `Skills(lazy_from=LocalDirLazySkillSource(...))` 适合作为较大本地 skill 目录的默认选项，因为模型可以先发现索引，只加载其需要的部分。
+- `Skills(from_=LocalDir(src=...))` 更适合较小的本地 bundle，并且你希望它们一开始就被准备好。
+- `Skills(from_=GitRepo(repo=..., ref=...))` 适用于 skills 本身应来自某个仓库的情况。
-如果你的 skills 已经以 `.agents/skills//SKILL.md` 之类的形式位于磁盘上，请将 `LocalDir(...)` 指向该源根目录，并仍然使用 `Skills(...)` 来暴露它们。除非你已有依赖不同 sandbox 内部布局的工作区契约，否则请保留默认的 `skills_path=".agents"`。
+如果你的 skills 已经以 `.agents/skills//SKILL.md` 之类的形式位于磁盘上，请将 `LocalDir(...)` 指向该源根目录，并仍然使用 `Skills(...)` 来暴露它们。除非你已有的工作区契约依赖于不同的沙盒内布局，否则请保留默认的 `skills_path=".agents"`。
-在适用时，优先使用内置 capabilities。只有当你需要内置能力未覆盖的 sandbox 专属工具或指令接口时，才编写自定义 capability。
+当内置能力适用时，优先使用它们。只有当你需要内置能力未覆盖的沙盒专属工具或指令接口时，才编写自定义能力。
## 概念
### Manifest
-[`Manifest`][agents.sandbox.manifest.Manifest] 描述一个全新 sandbox session 的工作区。它可以设置工作区 `root`，声明文件和目录，复制本地文件，克隆 Git 仓库，附加远程存储挂载，设置环境变量，定义用户或组，并授予对工作区外特定绝对路径的访问权限。
+[`Manifest`][agents.sandbox.manifest.Manifest] 描述一个全新沙盒会话的工作区。它可以设置工作区 `root`，声明文件和目录，复制本地文件，克隆 Git 仓库，附加远程存储挂载，设置环境变量，定义用户或组，并授予对工作区外特定绝对路径的访问权限。
-Manifest 条目的路径相对于工作区。它们不能是绝对路径，也不能通过 `..` 逃离工作区，这使工作区契约能够在本地、Docker 和托管 client 之间保持可移植性。
+Manifest 条目的路径是相对于工作区的。它们不能是绝对路径，也不能通过 `..` 逃离工作区，这使工作区契约能够在本地、Docker 和托管客户端之间保持可移植性。
-将 manifest 条目用于智能体在开始工作前所需的材料：
+对智能体在工作开始前所需的材料，请使用 manifest 条目：
| Manifest 条目 | 用途 |
| --- | --- |
| `File`、`Dir` | 小型合成输入、辅助文件或输出目录。 |
-| `LocalFile`、`LocalDir` | 应在 sandbox 中具体化的主机文件或目录。 |
-| `GitRepo` | 应获取到工作区中的仓库。 |
-| 挂载，例如 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`S3FilesMount` | 应出现在 sandbox 内部的外部存储。 |
+| `LocalFile`、`LocalDir` | 应实例化到沙盒中的主机文件或目录。 |
+| `GitRepo` | 应拉取到工作区中的仓库。 |
+| 挂载，如 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` | 应出现在沙盒中的外部存储。 |
-挂载条目描述要暴露哪些存储；挂载策略描述 sandbox 后端如何附加这些存储。有关挂载选项和提供方支持，请参见 [Sandbox clients](clients.md#mounts-and-remote-storage)。
+挂载条目描述要暴露哪些存储；挂载策略描述沙盒后端如何附加这些存储。有关挂载选项和提供方支持，请参见[沙盒客户端](clients.md#mounts-and-remote-storage)。
-良好的 manifest 设计通常意味着保持工作区契约精简，将较长的任务配方放入工作区文件（例如 `repo/task.md`），并在指令中使用相对工作区路径，例如 `repo/task.md` 或 `output/report.md`。如果智能体使用 `Filesystem` capability 的 `apply_patch` 工具编辑文件，请记住补丁路径是相对于 sandbox 工作区根目录，而不是 shell 的 `workdir`。
+良好的 manifest 设计通常意味着保持工作区契约精简，将较长的任务说明放在工作区文件中，例如 `repo/task.md`，并在说明中使用相对工作区路径，例如 `repo/task.md` 或 `output/report.md`。如果智能体使用 `Filesystem` 能力的 `apply_patch` 工具编辑文件，请记住补丁路径是相对于沙盒工作区根目录，而不是 shell 的 `workdir`。
-仅当智能体需要访问工作区外的具体绝对路径时才使用 `extra_path_grants`，例如用于临时工具输出的 `/tmp`，或用于只读运行时环境的 `/opt/toolchain`。在后端能够执行文件系统策略的情况下，授权同时适用于 SDK 文件 API 和 shell 执行：
+仅当智能体需要访问工作区之外的具体绝对路径时才使用 `extra_path_grants`，例如用于临时工具输出的 `/tmp`，或作为只读运行时环境的 `/opt/toolchain`。在后端能够执行文件系统策略的情况下，授权同时适用于 SDK 文件 API 和 shell 执行：
```python
from agents.sandbox import Manifest, SandboxPathGrant
@@ -254,13 +254,13 @@ manifest = Manifest(
)
```
-Snapshots 和 `persist_workspace()` 仍然只包含工作区根目录。额外授予的路径属于运行时访问权限，而不是持久化的工作区状态。
+快照和 `persist_workspace()` 仍然只包含工作区根目录。额外授予的路径是运行时访问权限，而不是持久化工作区状态。
### 权限
-`Permissions` 控制 manifest 条目的文件系统权限。它针对的是 sandbox 具体化出来的文件，而不是模型权限、审批策略或 API 凭证。
+`Permissions` 控制 manifest 条目的文件系统权限。它针对的是沙盒实例化出来的文件，而不是模型权限、审批策略或 API 凭据。
-默认情况下，manifest 条目对所有者可读/可写/可执行，对组和其他用户可读/可执行。当放入的文件应为私有、只读或可执行时，可以覆盖此默认设置：
+默认情况下，manifest 条目对所有者可读/可写/可执行，对组和其他用户可读/可执行。当预置的文件应为私有、只读或可执行时，请覆盖此设置：
```python
from agents.sandbox import FileMode, Permissions
@@ -276,9 +276,9 @@ private_notes = File(
)
```
-`Permissions` 分别存储 owner、group 和 other 的位，以及该条目是否为目录。你可以直接构建它，也可以使用 `Permissions.from_str(...)` 从 mode 字符串解析，或使用 `Permissions.from_mode(...)` 从操作系统 mode 推导。
+`Permissions` 存储单独的所有者、组和其他用户位，以及该条目是否为目录。你可以直接构建它，用 `Permissions.from_str(...)` 从 mode 字符串解析，或用 `Permissions.from_mode(...)` 从操作系统 mode 派生。
-用户是可以执行工作的 sandbox 身份。当你希望某个身份存在于 sandbox 中时，可以向 manifest 添加一个 `User`，然后在面向模型的 sandbox 工具（如 shell 命令、文件读取和补丁）应以该用户身份运行时设置 `SandboxAgent.run_as`。如果 `run_as` 指向的用户尚未存在于 manifest 中，runner 会为你将其添加到实际 manifest 中。
+用户是可以执行工作的沙盒身份。当你希望某个身份存在于沙盒中时，请向 manifest 添加一个 `User`，然后在希望 shell 命令、文件读取和补丁等面向模型的沙盒工具以该用户身份运行时设置 `SandboxAgent.run_as`。如果 `run_as` 指向的用户尚未在 manifest 中，运行器会为你将其添加到实际 manifest 中。
```python
from agents import Runner
@@ -330,13 +330,13 @@ result = await Runner.run(
)
```
-如果你还需要文件级共享规则，请将用户与 manifest 组以及条目的 `group` 元数据结合使用。`run_as` 用户控制谁来执行 sandbox 原生操作；`Permissions` 则控制该用户在 sandbox 具体化工作区之后，可以读取、写入或执行哪些文件。
+如果你还需要文件级共享规则，请将用户与 manifest 组以及条目的 `group` 元数据结合使用。`run_as` 用户控制谁执行沙盒原生操作；`Permissions` 控制在沙盒实例化工作区之后，该用户可以读取、写入或执行哪些文件。
### SnapshotSpec
-`SnapshotSpec` 告诉一个全新 sandbox session 应从哪里恢复已保存的工作区内容，并在结束后持久化回哪里。它是 sandbox 工作区的快照策略，而 `session_state` 则是用于恢复特定 sandbox 后端的序列化连接状态。
+`SnapshotSpec` 告诉一个全新的沙盒会话应从哪里恢复已保存的工作区内容，以及将其持久化回哪里。它是沙盒工作区的快照策略，而 `session_state` 是用于恢复特定沙盒后端的序列化连接状态。
-本地持久快照请使用 `LocalSnapshotSpec`，当你的应用提供远程 snapshot client 时请使用 `RemoteSnapshotSpec`。当本地快照设置不可用时，会回退到一个 no-op snapshot；高级调用方如果不希望工作区快照持久化，也可以显式使用它。
+本地持久快照使用 `LocalSnapshotSpec`；当你的应用提供远程快照客户端时使用 `RemoteSnapshotSpec`。当本地快照设置不可用时，会退回使用无操作快照；高级调用方也可以在不希望工作区快照持久化时显式使用它。
```python
from pathlib import Path
@@ -353,13 +353,13 @@ run_config = RunConfig(
)
```
-当 runner 创建一个全新 sandbox session 时，sandbox client 会为该 session 构建一个 snapshot 实例。启动时，如果 snapshot 可恢复，sandbox 会在运行继续之前恢复已保存的工作区内容。清理时，由 runner 拥有的 sandbox sessions 会归档工作区，并通过 snapshot 将其持久化回去。
+当运行器创建一个全新的沙盒会话时，沙盒客户端会为该会话构建一个快照实例。启动时，如果快照可恢复，沙盒会在运行继续前恢复已保存的工作区内容。清理时，由运行器拥有的沙盒会话会归档工作区，并通过快照将其持久化回去。
-如果你省略 `snapshot`，运行时会在可能的情况下尝试使用默认的本地 snapshot 位置。如果无法设置，则会回退到 no-op snapshot。挂载路径和临时路径不会作为持久工作区内容复制到 snapshot 中。
+如果你省略 `snapshot`，运行时会在可行时尝试使用默认的本地快照位置。如果无法设置，则退回到无操作快照。挂载路径和临时路径不会作为持久工作区内容复制进快照中。
-### Sandbox 生命周期
+### 沙盒生命周期
-有两种生命周期模式：**SDK-owned** 和 **developer-owned**。
+有两种生命周期模式：**SDK 拥有**和**开发者拥有**。
@@ -387,7 +387,7 @@ sequenceDiagram
-当 sandbox 只需存活一次运行时，请使用 SDK-owned 生命周期。传入 `client`、可选的 `manifest`、可选的 `snapshot` 和 client `options`；runner 会创建或恢复 sandbox，启动它，运行智能体，持久化由 snapshot 支持的工作区状态，关闭 sandbox，并让 client 清理由 runner 拥有的资源。
+当沙盒只需要存活一个运行周期时，使用 SDK 拥有的生命周期。传入 `client`、可选的 `manifest`、可选的 `snapshot` 和客户端 `options`；运行器会创建或恢复沙盒、启动它、运行智能体、持久化由快照支持的工作区状态、关闭沙盒，并让客户端清理由运行器拥有的资源。
```python
result = await Runner.run(
@@ -399,7 +399,7 @@ result = await Runner.run(
)
```
-当你希望提前创建 sandbox、在多次运行中复用同一个实时 sandbox、在运行后检查文件、对你自己创建的 sandbox 进行流式处理，或精确决定清理时机时，请使用 developer-owned 生命周期。传入 `session=...` 会告诉 runner 使用该实时 sandbox，但不会替你关闭它。
+当你希望预先创建沙盒、在多次运行中复用一个实时沙盒、在运行后检查文件、对你自己创建的沙盒进行流式处理，或精确决定何时清理时，请使用开发者拥有的生命周期。传入 `session=...` 会告诉运行器使用该实时沙盒，但不会替你关闭它。
```python
sandbox = await client.create(manifest=agent.default_manifest)
@@ -410,7 +410,7 @@ async with sandbox:
await Runner.run(agent, "Write the final report.", run_config=run_config)
```
-上下文管理器是常见形式：进入时启动 sandbox，退出时运行 session 清理生命周期。如果你的应用无法使用上下文管理器，请直接调用生命周期方法：
+上下文管理器是常见形式：进入时启动沙盒，退出时执行会话清理生命周期。如果你的应用无法使用上下文管理器，请直接调用生命周期方法：
```python
sandbox = await client.create(
@@ -431,62 +431,62 @@ finally:
await sandbox.aclose()
```
-`stop()` 只会持久化由 snapshot 支持的工作区内容；它不会销毁 sandbox。`aclose()` 是完整的 session 清理路径：它会运行 pre-stop hooks，调用 `stop()`，关闭 sandbox 资源，并关闭 session 范围的依赖项。
+`stop()` 只持久化由快照支持的工作区内容；它不会拆除沙盒。`aclose()` 是完整的会话清理路径：它会运行停止前 hook，调用 `stop()`，关闭沙盒资源，并关闭会话范围的依赖项。
## `SandboxRunConfig` 选项
-[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 保存按次运行的选项，用于决定 sandbox session 来自哪里，以及全新 session 应如何初始化。
+[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 保存每次运行的选项，用于决定沙盒会话来自何处，以及全新会话应如何初始化。
-### Sandbox 来源
+### 沙盒来源
-这些选项决定 runner 是应复用、恢复还是创建 sandbox session：
+这些选项决定运行器应复用、恢复还是创建沙盒会话：
-| 选项 | 使用时机 | 说明 |
+| 选项 | 适用场景 | 说明 |
| --- | --- | --- |
-| `client` | 你希望 runner 为你创建、恢复并清理 sandbox sessions。 | 除非你提供一个实时 sandbox `session`，否则为必填项。 |
-| `session` | 你已经自行创建了一个实时 sandbox session。 | 生命周期由调用方负责；runner 会复用该实时 sandbox session。 |
-| `session_state` | 你拥有序列化的 sandbox session 状态，但没有实时 sandbox session 对象。 | 需要 `client`；runner 会从该显式状态恢复为一个自有 session。 |
+| `client` | 你希望运行器为你创建、恢复和清理沙盒会话。 | 除非你提供一个实时沙盒 `session`，否则必需。 |
+| `session` | 你已经自己创建了一个实时沙盒会话。 | 生命周期由调用方负责；运行器会复用该实时沙盒会话。 |
+| `session_state` | 你有已序列化的沙盒会话状态，但没有实时沙盒会话对象。 | 需要 `client`；运行器会从该显式状态恢复，并作为拥有者会话管理它。 |
-在实践中，runner 会按以下顺序解析 sandbox session：
+在实践中，运行器按以下顺序解析沙盒会话：
-1. 如果你注入 `run_config.sandbox.session`，则直接复用该实时 sandbox session。
-2. 否则，如果此次运行是从 `RunState` 恢复，则恢复其中存储的 sandbox session 状态。
-3. 否则，如果你传入 `run_config.sandbox.session_state`，runner 会从该显式序列化的 sandbox session 状态恢复。
-4. 否则，runner 会创建一个全新的 sandbox session。对于这个全新 session，它会在提供了 `run_config.sandbox.manifest` 时使用它，否则使用 `agent.default_manifest`。
+1. 如果你注入了 `run_config.sandbox.session`，则直接复用该实时沙盒会话。
+2. 否则，如果运行是从 `RunState` 恢复的，则恢复其中存储的沙盒会话状态。
+3. 否则，如果你传入了 `run_config.sandbox.session_state`，运行器会从该显式序列化的沙盒会话状态恢复。
+4. 否则，运行器会创建一个全新的沙盒会话。对于这个全新会话，如果提供了 `run_config.sandbox.manifest` 则使用它，否则使用 `agent.default_manifest`。
-### 全新 session 输入
+### 全新会话输入
-这些选项仅在 runner 创建全新 sandbox session 时才有意义：
+这些选项仅在运行器创建全新沙盒会话时才有意义：
-| 选项 | 使用时机 | 说明 |
+| 选项 | 适用场景 | 说明 |
| --- | --- | --- |
-| `manifest` | 你想要一次性的全新 session 工作区覆盖。 | 省略时回退到 `agent.default_manifest`。 |
-| `snapshot` | 一个全新的 sandbox session 应从 snapshot 提供初始内容。 | 适用于类似恢复的流程或远程 snapshot clients。 |
-| `options` | sandbox client 需要创建时选项。 | 常见于 Docker 镜像、Modal 应用名称、E2B 模板、超时，以及类似的 client 专属设置。 |
+| `manifest` | 你希望一次性覆盖全新会话工作区。 | 省略时回退到 `agent.default_manifest`。 |
+| `snapshot` | 全新的沙盒会话应从快照提供初始数据。 | 适用于类似恢复的流程或远程快照客户端。 |
+| `options` | 沙盒客户端需要创建时选项。 | 常见于 Docker 镜像、Modal 应用名、E2B 模板、超时等类似的客户端专属设置。 |
-### 具体化控制
+### 实例化控制
-`concurrency_limits` 控制有多少 sandbox 具体化工作可以并行运行。当大型 manifest 或本地目录复制需要更严格的资源控制时，请使用 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`。将任一值设为 `None` 可禁用对应限制。
+`concurrency_limits` 控制有多少沙盒实例化工作可以并行运行。当大型 manifest 或本地目录复制需要更严格的资源控制时，请使用 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`。将任一值设为 `None` 可禁用对应的限制。
-有几点值得注意：
+有几个值得记住的影响：
-- 全新 sessions：`manifest=` 和 `snapshot=` 仅在 runner 创建全新 sandbox session 时生效。
-- 恢复与 snapshot：`session_state=` 会重新连接到先前序列化的 sandbox 状态，而 `snapshot=` 则会通过已保存的工作区内容为新的 sandbox session 提供初始数据。
-- client 专属选项：`options=` 取决于 sandbox client；Docker 和许多托管 clients 都需要它。
-- 注入的实时 sessions：如果你传入一个正在运行的 sandbox `session`，由 capability 驱动的 manifest 更新可以添加兼容的非挂载条目。它们不能更改 `manifest.root`、`manifest.environment`、`manifest.users` 或 `manifest.groups`；不能删除现有条目；不能替换条目类型；也不能添加或更改挂载条目。
-- Runner API：`SandboxAgent` 的执行仍使用常规的 `Runner.run()`、`Runner.run_sync()` 和 `Runner.run_streamed()` API。
+- 全新会话：`manifest=` 和 `snapshot=` 仅在运行器创建全新沙盒会话时生效。
+- 恢复与快照：`session_state=` 重新连接到先前序列化的沙盒状态，而 `snapshot=` 则是从保存的工作区内容为一个新的沙盒会话提供初始数据。
+- 客户端专属选项：`options=` 取决于沙盒客户端；Docker 和许多托管客户端都需要它。
+- 注入的实时会话：如果你传入一个正在运行的沙盒 `session`，由能力驱动的 manifest 更新可以添加兼容的非挂载条目。它们不能更改 `manifest.root`、`manifest.environment`、`manifest.users` 或 `manifest.groups`；不能删除现有条目；不能替换条目类型；也不能添加或修改挂载条目。
+- 运行器 API：`SandboxAgent` 执行仍使用常规的 `Runner.run()`、`Runner.run_sync()` 和 `Runner.run_streamed()` API。
## 完整示例：编码任务
-这个编码风格的示例是一个很好的默认起点：
+这个编码风格示例是一个很好的默认起点：
```python
import asyncio
@@ -564,19 +564,19 @@ if __name__ == "__main__":
)
```
-参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用了一个基于 shell 的微型仓库，以便该示例能够在 Unix 本地运行中被确定性验证。你的真实任务仓库当然可以是 Python、JavaScript 或其他任何类型。
+参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用了一个很小的基于 shell 的仓库，以便该示例可以在 Unix 本地运行中被确定性验证。当然，你的真实任务仓库也可以是 Python、JavaScript 或其他任何内容。
## 常见模式
-从上面的完整示例开始。在许多情况下，同一个 `SandboxAgent` 可以保持不变，只需更改 sandbox client、sandbox-session 来源或工作区来源。
+从上面的完整示例开始。在很多情况下，同一个 `SandboxAgent` 可以保持不变，只改变沙盒客户端、沙盒会话来源或工作区来源。
-### 切换 sandbox clients
+### 切换沙盒客户端
-保持智能体定义不变，只更改运行配置。当你想要容器隔离或镜像一致性时使用 Docker；当你想要由提供方管理执行环境时使用托管提供方。示例和提供方选项请参见 [Sandbox clients](clients.md)。
+保持智能体定义不变，只修改运行配置。当你需要容器隔离或镜像一致性时使用 Docker；当你需要提供方托管执行时使用托管提供方。示例和提供方选项请参见[沙盒客户端](clients.md)。
### 覆盖工作区
-保持智能体定义不变，仅替换全新 session 的 manifest：
+保持智能体定义不变，只替换全新会话 manifest：
```python
from agents.run import RunConfig
@@ -596,11 +596,11 @@ run_config = RunConfig(
)
```
-当同一智能体角色需要针对不同仓库、资料包或任务包运行，而无需重新构建智能体时，可使用此方式。上面的验证型编码示例展示了相同模式，不过使用的是 `default_manifest` 而不是一次性覆盖。
+当同一个智能体角色需要针对不同仓库、材料包或任务包运行，而无需重建智能体时，请使用此方式。上面的已验证编码示例展示了使用 `default_manifest` 而非一次性覆盖的相同模式。
-### 注入 sandbox session
+### 注入沙盒会话
-当你需要显式生命周期控制、运行后检查或复制输出时，注入一个实时 sandbox session：
+当你需要显式生命周期控制、运行后检查或复制输出时，注入一个实时沙盒会话：
```python
from agents import Runner
@@ -621,11 +621,11 @@ async with sandbox:
)
```
-当你想在运行后检查工作区，或对一个已经启动的 sandbox session 进行流式处理时，可使用此方式。参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 和 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。
+当你希望在运行后检查工作区，或对一个已启动的沙盒会话进行流式处理时，请使用此方式。参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 和 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。
-### 从 session 状态恢复
+### 从会话状态恢复
-如果你已经在 `RunState` 之外序列化了 sandbox 状态，让 runner 从该状态重新连接：
+如果你已经在 `RunState` 之外序列化了沙盒状态，让运行器从该状态重新连接：
```python
from agents.run import RunConfig
@@ -642,11 +642,11 @@ run_config = RunConfig(
)
```
-当 sandbox 状态保存在你自己的存储或作业系统中，并且你希望 `Runner` 直接从中恢复时，可使用此方式。有关序列化/反序列化流程，请参见 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)。
+当沙盒状态位于你自己的存储或任务系统中，并且你希望 `Runner` 直接从中恢复时，请使用此方式。序列化/反序列化流程请参见 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)。
-### 从 snapshot 开始
+### 从快照开始
-通过已保存的文件和产物为一个新的 sandbox 提供初始内容：
+使用已保存的文件和产物为新的沙盒提供初始数据：
```python
from pathlib import Path
@@ -663,7 +663,7 @@ run_config = RunConfig(
)
```
-当一次全新运行应从已保存的工作区内容开始，而不只是 `agent.default_manifest` 时，可使用此方式。有关本地 snapshot 流程，请参见 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)；有关远程 snapshot client，请参见 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)。
+当一次新的运行应从已保存的工作区内容开始，而不只是 `agent.default_manifest` 时，请使用此方式。本地快照流程请参见 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)，远程快照客户端请参见 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)。
### 从 Git 加载 skills
@@ -678,11 +678,11 @@ capabilities = Capabilities.default() + [
]
```
-当 skills 包有自己的发布节奏，或应在多个 sandbox 之间共享时，可使用此方式。参见 [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)。
+当 skills bundle 有其自己的发布节奏，或应在多个沙盒之间共享时，请使用此方式。参见 [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)。
### 作为工具暴露
-工具智能体既可以拥有自己的 sandbox 边界，也可以复用父运行中的实时 sandbox。复用对于快速、只读的探索型智能体很有用：它可以检查父级正在使用的确切工作区，而无需付出创建、填充或快照另一个 sandbox 的成本。
+工具智能体既可以拥有自己的沙盒边界，也可以复用父运行中的实时沙盒。复用对于一个快速的只读探索智能体很有用：它可以检查父智能体正在使用的确切工作区，而无需为创建、填充或快照另一个沙盒付出成本。
```python
from agents import Runner
@@ -764,9 +764,9 @@ async with sandbox:
)
```
-这里父智能体以 `coordinator` 身份运行，而探索工具智能体则在同一个实时 sandbox session 中以 `explorer` 身份运行。`pricing_packet/` 条目对 `other` 用户可读，因此 explorer 可以快速检查它们，但它没有写权限。`work/` 目录仅对 coordinator 的用户/组可用，因此父级可以写入最终产物，而 explorer 保持只读。
+这里父智能体以 `coordinator` 身份运行，而探索工具智能体则以 `explorer` 身份在同一个实时沙盒会话中运行。`pricing_packet/` 条目对 `other` 用户可读，因此探索者可以快速检查它们，但没有写入位。`work/` 目录仅对协调者的用户/组可用，因此父智能体可以写入最终产物，而探索者保持只读。
-当工具智能体确实需要真正隔离时，请为它提供自己的 sandbox `RunConfig`：
+当工具智能体确实需要真正的隔离时，请给它自己的沙盒 `RunConfig`：
```python
from docker import from_env as docker_from_env
@@ -787,11 +787,11 @@ rollout_agent.as_tool(
)
```
-当工具智能体应能自由修改、运行不受信任的命令，或使用不同后端/镜像时，请使用单独的 sandbox。参见 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。
+当工具智能体应能自由修改、运行不受信任的命令，或使用不同的后端/镜像时，请使用单独的沙盒。参见 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。
### 与本地工具和 MCP 结合
-在保留 sandbox 工作区的同时，仍在同一个智能体上使用普通工具：
+在保留沙盒工作区的同时，仍在同一个智能体上使用普通工具：
```python
from agents.sandbox import SandboxAgent
@@ -806,46 +806,46 @@ agent = SandboxAgent(
)
```
-当工作区检查只是智能体工作的一部分时，可使用此方式。参见 [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)。
+当工作区检查只是智能体工作的一部分时，请使用此方式。参见 [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)。
-## Memory
+## 内存
-当未来的 sandbox-agent 运行应从先前运行中学习时，请使用 `Memory` capability。Memory 与 SDK 的对话式 `Session` memory 是分开的：它会将经验提炼为 sandbox 工作区中的文件，之后的运行就可以读取这些文件。
+当未来的沙盒智能体运行应从先前运行中学习时，请使用 `Memory` 能力。内存不同于 SDK 的会话式 `Session` 内存：它将经验提炼为沙盒工作区中的文件，之后的运行便可以读取这些文件。
-有关设置、读取/生成行为、多轮对话和布局隔离，请参见[Agent memory](memory.md)。
+有关设置、读取/生成行为、多轮对话和布局隔离，请参见[智能体内存](memory.md)。
## 组合模式
-当单智能体模式清晰之后，下一个设计问题就是在更大的系统中，sandbox 边界应放在哪里。
+当单智能体模式清晰后，下一个设计问题就是在更大的系统中应将沙盒边界放在哪里。
-Sandbox 智能体仍然可以与 SDK 的其他部分组合：
+沙盒智能体仍然可以与 SDK 的其他部分组合：
-- [Handoffs](../handoffs.md)：将文档密集型工作从非 sandbox 的接入智能体转交给 sandbox 审查智能体。
-- [Agents as tools](../tools.md#agents-as-tools)：将多个 sandbox 智能体作为工具暴露，通常是在每次 `Agent.as_tool(...)` 调用时传入 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`，以便每个工具拥有自己的 sandbox 边界。
-- [MCP](../mcp.md) 和常规函数工具：sandbox capabilities 可以与 `mcp_servers` 和普通 Python 工具共存。
-- [Running agents](../running_agents.md)：sandbox 运行仍然使用常规 `Runner` API。
+- [Handoffs](../handoffs.md)：将文档密集型工作从非沙盒的接入智能体任务转移给沙盒审查智能体。
+- [Agents as tools](../tools.md#agents-as-tools)：将多个沙盒智能体作为工具暴露，通常是在每次 `Agent.as_tool(...)` 调用时传入 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`，以便每个工具都拥有自己的沙盒边界。
+- [MCP](../mcp.md) 和普通工具调用：沙盒能力可以与 `mcp_servers` 和普通 Python 工具共存。
+- [运行智能体](../running_agents.md)：沙盒运行仍使用常规 `Runner` API。
有两种模式尤其常见：
-- 一个非 sandbox 智能体只在工作流中需要工作区隔离的那一部分转交给 sandbox 智能体
-- 一个编排器将多个 sandbox 智能体作为工具暴露，通常每次 `Agent.as_tool(...)` 调用都使用单独的 sandbox `RunConfig`，以便每个工具拥有自己的隔离工作区
+- 非沙盒智能体仅在工作流中需要工作区隔离的部分任务转移到沙盒智能体
+- 一个编排器将多个沙盒智能体作为工具暴露，通常为每次 `Agent.as_tool(...)` 调用提供单独的沙盒 `RunConfig`，以便每个工具都有各自隔离的工作区
-### Turns 和 sandbox 运行
+### Turns 与沙盒运行
-将 handoffs 与 agent-as-tool 调用分开说明会更容易理解。
+分别解释任务转移和作为工具的智能体调用会更容易理解。
-在 handoff 中，仍然只有一个顶层运行和一个顶层 turn 循环。活动智能体会改变，但运行不会变成嵌套。如果一个非 sandbox 的接入智能体转交给一个 sandbox 审查智能体，那么同一次运行中的下一次模型调用就会为该 sandbox 智能体准备，而该 sandbox 智能体会成为执行下一次 turn 的智能体。换句话说，handoff 改变的是同一次运行中由哪个智能体负责下一个 turn。参见 [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)。
+对于任务转移，仍然只有一个顶层运行和一个顶层 turn 循环。活跃智能体会变化，但运行不会变成嵌套。如果一个非沙盒接入智能体将任务转移给一个沙盒审查智能体，那么在同一运行中的下一次模型调用会为该沙盒智能体进行准备，而该沙盒智能体将成为执行下一个 turn 的智能体。换句话说，任务转移改变的是同一运行中由哪个智能体拥有下一个 turn。参见 [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)。
-而在 `Agent.as_tool(...)` 中，关系则不同。外层编排器用一个外层 turn 决定调用该工具，而这次工具调用会为 sandbox 智能体启动一次嵌套运行。该嵌套运行有自己的 turn 循环、`max_turns`、审批，以及通常也有自己的 sandbox `RunConfig`。它可能在一个嵌套 turn 中结束，也可能需要多个。从外层编排器的角度看，所有这些工作仍然位于一次工具调用之后，因此嵌套 turn 不会增加外层运行的 turn 计数。参见 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。
+对于 `Agent.as_tool(...)`，关系则不同。外层编排器使用一个外层 turn 来决定调用工具，而该工具调用会为沙盒智能体启动一次嵌套运行。该嵌套运行有自己的 turn 循环、`max_turns`、审批，通常还有自己的沙盒 `RunConfig`。它可能在一个嵌套 turn 中完成，也可能需要多个。从外层编排器的角度看，这些工作都隐藏在一次工具调用之后，因此嵌套 turn 不会增加外层运行的 turn 计数。参见 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。
-审批行为也遵循同样的划分：
+审批行为遵循相同的划分：
-- 在 handoffs 中，审批保留在同一个顶层运行上，因为 sandbox 智能体现在是该运行中的活动智能体
-- 在 `Agent.as_tool(...)` 中，sandbox 工具智能体内部触发的审批仍会显示在外层运行上，但它们来自已存储的嵌套运行状态，并会在外层运行恢复时恢复嵌套的 sandbox 运行
+- 对于任务转移，审批仍保留在同一个顶层运行中，因为沙盒智能体现在是该运行中的活跃智能体
+- 对于 `Agent.as_tool(...)`，在沙盒工具智能体内部触发的审批仍会出现在外层运行上，但它们来自已存储的嵌套运行状态，并会在外层运行恢复时恢复嵌套的沙盒运行
## 延伸阅读
-- [Quickstart](quickstart.md)：启动一个 sandbox 智能体。
-- [Sandbox clients](clients.md)：选择本地、Docker、托管和挂载选项。
-- [Agent memory](memory.md)：保留并复用先前 sandbox 运行中的经验。
-- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)：可运行的本地、编码、memory、handoff 和智能体组合模式。
\ No newline at end of file
+- [快速开始](quickstart.md)：运行一个沙盒智能体。
+- [沙盒客户端](clients.md)：选择本地、Docker、托管和挂载选项。
+- [智能体内存](memory.md)：保留并复用先前沙盒运行中的经验。
+- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)：可运行的本地、编码、内存、任务转移和智能体组合模式。
\ No newline at end of file