/SKILL.md` のような場所のディスク上にある場合は、そのソースルートを `LocalDir(...)` に指定し、それでも `Skills(...)` を使って公開してください。既存のワークスペース契約が別のサンドボックス内レイアウトに依存していない限り、デフォルトの `skills_path=".agents"` を維持してください。
-適合する場合は組み込み capabilities を優先してください。組み込みでカバーされないサンドボックス固有ツールや instruction インターフェイスが必要な場合にのみ、カスタム capability を作成してください。
+適合する場合は、組み込み機能を優先してください。組み込みではカバーされないサンドボックス固有のツールや指示サーフェスが必要な場合にのみ、カスタム機能を作成してください。
## 概念
### Manifest
-[`Manifest`][agents.sandbox.manifest.Manifest] は、新規サンドボックスセッションのワークスペースを記述します。ワークスペース `root` の設定、ファイルやディレクトリの宣言、ローカルファイルのコピー、Git リポジトリのクローン、リモートストレージマウントのアタッチ、環境変数の設定、ユーザーやグループの定義、ワークスペース外の特定の絶対パスへのアクセス付与が可能です。
+[`Manifest`][agents.sandbox.manifest.Manifest] は、新しいサンドボックスセッションのワークスペースを記述します。ワークスペース `root` の設定、ファイルとディレクトリの宣言、ローカルファイルのコピー、Git リポジトリのクローン、リモートストレージマウントの接続、環境変数の設定、ユーザーやグループの定義、ワークスペース外の特定の絶対パスへのアクセス許可を行えます。
-Manifest エントリのパスはワークスペース相対です。絶対パスにしたり、`..` でワークスペースを抜けたりすることはできません。これにより、ワークスペース契約はローカル、Docker、ホスト型クライアントの間でポータブルになります。
+マニフェストエントリのパスはワークスペース相対です。絶対パスにしたり、`..` でワークスペース外へ抜けたりすることはできません。これにより、ワークスペース契約はローカル、Docker、ホスト型クライアントをまたいで移植可能になります。
-作業開始前にエージェントが必要とする材料には manifest エントリを使用します。
+作業開始前にエージェントが必要とする素材には、マニフェストエントリを使用します。
-| Manifest エントリ | 用途 |
+| マニフェストエントリ | 用途 |
| --- | --- |
-| `File`、`Dir` | 小さな合成入力、ヘルパーファイル、または出力ディレクトリ。 |
-| `LocalFile`、`LocalDir` | サンドボックスに具現化すべきホストファイルまたはディレクトリ。 |
+| `File`、`Dir` | 小さな合成入力、補助ファイル、または出力ディレクトリ。 |
+| `LocalFile`、`LocalDir` | サンドボックス内にマテリアライズすべきホストファイルまたはディレクトリ。 |
| `GitRepo` | ワークスペースに取得すべきリポジトリ。 |
| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` などのマウント | サンドボックス内に表示すべき外部ストレージ。 |
-`Dir` は合成の子要素から、または出力場所として、サンドボックスワークスペース内にディレクトリを作成します。ホストファイルシステムから読み取りません。既存のホストディレクトリをサンドボックスワークスペースにコピーすべき場合は `LocalDir` を使用してください。
+`Dir` は、合成子要素から、または出力場所として、サンドボックスワークスペース内にディレクトリを作成します。ホストファイルシステムから読み取るわけではありません。既存のホストディレクトリをサンドボックスワークスペースにコピーする必要がある場合は、`LocalDir` を使用します。
-`LocalFile.src` と `LocalDir.src` は、デフォルトでは SDK プロセスの作業ディレクトリを基準に解決されます。ソースは `extra_path_grants` でカバーされていない限り、そのベースディレクトリの下に留まる必要があります。これにより、ローカルソースの具現化は、サンドボックス manifest の他の部分と同じホストパス信頼境界内に保たれます。
+`LocalFile.src` と `LocalDir.src` は、デフォルトでは SDK プロセスの作業ディレクトリを基準に解決されます。ソースは、`extra_path_grants` でカバーされていない限り、そのベースディレクトリ配下に留まる必要があります。これにより、ローカルソースのマテリアライズは、サンドボックスマニフェストの他の部分と同じホストパス信頼境界内に保たれます。
-マウントエントリは公開するストレージを記述し、マウント戦略はサンドボックスバックエンドがそのストレージをどのようにアタッチするかを記述します。マウントオプションとプロバイダーサポートについては、[サンドボックスクライアント](clients.md#mounts-and-remote-storage) を参照してください。
+マウントエントリは公開するストレージを記述し、マウント戦略はサンドボックスバックエンドがそのストレージをどのように接続するかを記述します。マウントオプションとプロバイダーサポートについては、[サンドボックスクライアント](clients.md#mounts-and-remote-storage) を参照してください。
-優れた manifest 設計では通常、ワークスペース契約を狭く保ち、長いタスク手順を `repo/task.md` のようなワークスペースファイルに置き、instructions では `repo/task.md` や `output/report.md` のような相対ワークスペースパスを使用します。エージェントが `Filesystem` capability の `apply_patch` ツールでファイルを編集する場合、パッチパスはシェルの `workdir` ではなく、サンドボックスワークスペースルートからの相対であることを忘れないでください。
+良いマニフェスト設計とは通常、ワークスペース契約を狭く保ち、長いタスク手順を `repo/task.md` のようなワークスペースファイルに置き、instructions 内では `repo/task.md` や `output/report.md` のような相対ワークスペースパスを使うことです。エージェントが `Filesystem` 機能の `apply_patch` ツールでファイルを編集する場合、パッチパスはシェルの `workdir` ではなく、サンドボックスワークスペースルートに対する相対であることに注意してください。
-`extra_path_grants` は、エージェントがワークスペース外の具体的な絶対パスを必要とする場合、または manifest が SDK プロセスの作業ディレクトリ外にある信頼済みローカルソースをコピーする必要がある場合にのみ使用してください。例として、一時的なツール出力用の `/tmp`、読み取り専用ランタイム用の `/opt/toolchain`、またはサンドボックスに具現化すべき生成済みスキルディレクトリがあります。grant は、ローカルソースの具現化、SDK ファイル API、およびバックエンドがファイルシステムポリシーを強制できる場合のシェル実行に適用されます。
+エージェントがワークスペース外の具体的な絶対パスを必要とする場合、またはマニフェストが SDK プロセスの作業ディレクトリ外の信頼済みローカルソースをコピーする必要がある場合にのみ、`extra_path_grants` を使用します。例として、一時的なツール出力用の `/tmp`、読み取り専用ランタイム用の `/opt/toolchain`、サンドボックスにマテリアライズすべき生成済みスキルディレクトリなどがあります。グラントは、ローカルソースのマテリアライズ、SDK ファイル API、およびバックエンドがファイルシステムポリシーを強制できる場合のシェル実行に適用されます。
```python
from agents.sandbox import Manifest, SandboxPathGrant
@@ -261,15 +261,15 @@ manifest = Manifest(
)
```
-`extra_path_grants` を含む manifests は、信頼済み設定として扱ってください。アプリケーションがそれらのホストパスをすでに承認していない限り、モデル出力やその他の信頼できないペイロードから grant を読み込まないでください。
+`extra_path_grants` を含むマニフェストは、信頼済み設定として扱ってください。アプリケーションがそれらのホストパスを既に承認していない限り、モデル出力やその他の信頼できないペイロードからグラントを読み込まないでください。
-スナップショットと `persist_workspace()` は、引き続きワークスペースルートのみを含みます。追加で grant されたパスはランタイムアクセスであり、永続的なワークスペース状態ではありません。
+スナップショットと `persist_workspace()` は引き続きワークスペースルートのみを含みます。追加で許可されたパスはランタイムアクセスであり、永続的なワークスペース状態ではありません。
-### Permissions
+### 権限
-`Permissions` は manifest エントリのファイルシステム権限を制御します。これはサンドボックスが具現化するファイルに関するものであり、モデル権限、承認ポリシー、API 認証情報に関するものではありません。
+`Permissions` は、マニフェストエントリのファイルシステム権限を制御します。これはサンドボックスがマテリアライズするファイルに関するものであり、モデル権限、承認ポリシー、API 認証情報に関するものではありません。
-デフォルトでは、manifest エントリは owner が読み取り/書き込み/実行可能で、group と others が読み取り/実行可能です。ステージングされたファイルをプライベート、読み取り専用、または実行可能にすべき場合は上書きしてください。
+デフォルトでは、マニフェストエントリは所有者が読み取り/書き込み/実行可能で、グループとその他は読み取り/実行可能です。ステージングされたファイルをプライベート、読み取り専用、または実行可能にする必要がある場合は、これを上書きします。
```python
from agents.sandbox import FileMode, Permissions
@@ -285,9 +285,9 @@ private_notes = File(
)
```
-`Permissions` は owner、group、other のビットと、そのエントリがディレクトリかどうかを別々に保持します。直接構築することも、`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 にまだ存在しないユーザーを指している場合、runner が実効 manifest にそのユーザーを追加します。
+ユーザーは、作業を実行できるサンドボックス ID です。その ID をサンドボックス内に存在させたい場合は、マニフェストに `User` を追加し、シェルコマンド、ファイル読み取り、パッチなどのモデル向けサンドボックスツールをそのユーザーとして実行する必要がある場合は、`SandboxAgent.run_as` を設定します。`run_as` がマニフェストにまだ存在しないユーザーを指している場合、ランナーが有効なマニフェストにそのユーザーを追加します。
```python
from agents import Runner
@@ -339,11 +339,11 @@ result = await Runner.run(
)
```
-ファイルレベルの共有ルールも必要な場合は、ユーザーと manifest グループおよびエントリの `group` メタデータを組み合わせてください。`run_as` ユーザーはサンドボックスネイティブアクションを誰が実行するかを制御し、`Permissions` はサンドボックスがワークスペースを具現化した後、そのユーザーがどのファイルを読み取り、書き込み、または実行できるかを制御します。
+ファイルレベルの共有ルールも必要な場合は、ユーザーをマニフェストグループおよびエントリの `group` メタデータと組み合わせます。`run_as` ユーザーは、誰がサンドボックスネイティブアクションを実行するかを制御します。`Permissions` は、サンドボックスがワークスペースをマテリアライズした後に、そのユーザーがどのファイルを読み取り、書き込み、または実行できるかを制御します。
### SnapshotSpec
-`SnapshotSpec` は、新しいサンドボックスセッションが保存済みワークスペース内容をどこから復元し、どこへ永続化するかを指定します。これはサンドボックスワークスペースのスナップショットポリシーであり、`session_state` は特定のサンドボックスバックエンドを再開するためのシリアライズ済み接続状態です。
+`SnapshotSpec` は、新しいサンドボックスセッションが保存済みワークスペース内容をどこから復元し、どこへ永続化し戻すかを指定します。これはサンドボックスワークスペースのスナップショットポリシーであり、`session_state` は特定のサンドボックスバックエンドを再開するためのシリアライズ済み接続状態です。
ローカルの永続スナップショットには `LocalSnapshotSpec` を使用し、アプリがリモートスナップショットクライアントを提供する場合は `RemoteSnapshotSpec` を使用します。ローカルスナップショットのセットアップが利用できない場合はフォールバックとして no-op スナップショットが使用され、高度な呼び出し元はワークスペーススナップショットの永続化を望まない場合に明示的に使用できます。
@@ -362,13 +362,13 @@ run_config = RunConfig(
)
```
-runner が新しいサンドボックスセッションを作成するとき、サンドボックスクライアントはそのセッション用のスナップショットインスタンスを構築します。開始時にスナップショットが復元可能であれば、実行が続行する前にサンドボックスは保存済みワークスペース内容を復元します。クリーンアップ時には、runner 所有のサンドボックスセッションがワークスペースをアーカイブし、スナップショットを通じて永続化します。
+ランナーが新しいサンドボックスセッションを作成すると、サンドボックスクライアントはそのセッション用のスナップショットインスタンスを構築します。開始時、スナップショットが復元可能であれば、サンドボックスは実行を続ける前に保存済みワークスペース内容を復元します。クリーンアップ時、ランナー所有のサンドボックスセッションはワークスペースをアーカイブし、スナップショットを通じて永続化し戻します。
-`snapshot` を省略すると、ランタイムは可能な場合にデフォルトのローカルスナップショット場所を使用しようとします。それをセットアップできない場合、no-op スナップショットにフォールバックします。マウントされたパスとエフェメラルなパスは、永続的なワークスペース内容としてスナップショットにコピーされません。
+`snapshot` を省略した場合、ランタイムは可能であればデフォルトのローカルスナップショット場所を使用しようとします。それをセットアップできない場合は、no-op スナップショットにフォールバックします。マウントされたパスと一時パスは、永続的なワークスペース内容としてスナップショットにコピーされません。
-### サンドボックスのライフサイクル
+### サンドボックスライフサイクル
-ライフサイクルモードは **SDK 所有** と **開発者所有** の 2 つです。
+ライフサイクルモードには **SDK 所有** と **開発者所有** の 2 つがあります。
@@ -396,7 +396,7 @@ sequenceDiagram
-サンドボックスが 1 回の実行だけで存在すればよい場合は、SDK 所有のライフサイクルを使用します。`client`、任意の `manifest`、任意の `snapshot`、およびクライアント `options` を渡します。runner はサンドボックスを作成または再開し、開始し、エージェントを実行し、スナップショット対応ワークスペース状態を永続化し、サンドボックスをシャットダウンし、クライアントに runner 所有リソースのクリーンアップを任せます。
+サンドボックスが 1 回の実行だけ存続すればよい場合は、SDK 所有ライフサイクルを使用します。`client`、任意の `manifest`、任意の `snapshot`、クライアント `options` を渡します。ランナーはサンドボックスを作成または再開し、開始し、エージェントを実行し、スナップショット対応のワークスペース状態を永続化し、サンドボックスをシャットダウンし、クライアントにランナー所有リソースをクリーンアップさせます。
```python
result = await Runner.run(
@@ -408,7 +408,7 @@ result = await Runner.run(
)
```
-サンドボックスを事前に作成したい場合、1 つの実行中サンドボックスを複数実行で再利用したい場合、実行後にファイルを検査したい場合、自分で作成したサンドボックス上でストリーミングしたい場合、またはクリーンアップのタイミングを正確に決めたい場合は、開発者所有のライフサイクルを使用します。`session=...` を渡すと、runner はその実行中サンドボックスを使用しますが、代わりに閉じることはありません。
+サンドボックスを事前に作成したい場合、稼働中の 1 つのサンドボックスを複数の実行で再利用したい場合、実行後にファイルを検査したい場合、自分で作成したサンドボックス上でストリーミングしたい場合、またはクリーンアップのタイミングを厳密に決めたい場合は、開発者所有ライフサイクルを使用します。`session=...` を渡すと、ランナーはその稼働中サンドボックスを使用しますが、ユーザーの代わりに閉じることはありません。
```python
sandbox = await client.create(manifest=agent.default_manifest)
@@ -419,7 +419,7 @@ async with sandbox:
await Runner.run(agent, "Write the final report.", run_config=run_config)
```
-通常はコンテキストマネージャーの形を使います。エントリ時にサンドボックスを開始し、終了時にセッションのクリーンアップライフサイクルを実行します。アプリでコンテキストマネージャーを使えない場合は、ライフサイクルメソッドを直接呼び出してください。
+通常の形はコンテキストマネージャーです。入るときにサンドボックスを開始し、抜けるときにセッションクリーンアップライフサイクルを実行します。アプリがコンテキストマネージャーを使えない場合は、ライフサイクルメソッドを直接呼び出します。
```python
sandbox = await client.create(
@@ -440,62 +440,64 @@ finally:
await sandbox.aclose()
```
-`stop()` はスナップショット対応ワークスペース内容のみを永続化します。サンドボックスを破棄するわけではありません。`aclose()` は完全なセッションクリーンアップ経路です。停止前フックを実行し、`stop()` を呼び出し、サンドボックスリソースをシャットダウンし、セッションスコープの依存関係を閉じます。
+`stop()` はスナップショット対応のワークスペース内容のみを永続化します。サンドボックスを破棄するわけではありません。`aclose()` は完全なセッションクリーンアップパスです。停止前フックを実行し、`stop()` を呼び出し、サンドボックスリソースをシャットダウンし、セッションスコープの依存関係を閉じます。
## `SandboxRunConfig` オプション
-[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、サンドボックスセッションの取得元と、新規セッションの初期化方法を決定する実行ごとのオプションを保持します。
+[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、サンドボックスセッションがどこから来るか、および新しいセッションをどのように初期化するべきかを決定する実行ごとのオプションを保持します。
### サンドボックスソース
-これらのオプションは、runner がサンドボックスセッションを再利用、再開、または作成すべきかを決定します。
+これらのオプションは、ランナーがサンドボックスセッションを再利用、再開、または作成するべきかを決定します。
| オプション | 使用する場合 | 注記 |
| --- | --- | --- |
-| `client` | runner にサンドボックスセッションの作成、再開、クリーンアップを任せたい場合。 | 実行中のサンドボックス `session` を提供しない限り必須です。 |
-| `session` | 実行中のサンドボックスセッションを自分ですでに作成している場合。 | 呼び出し元がライフサイクルを所有します。runner はその実行中サンドボックスセッションを再利用します。 |
-| `session_state` | シリアライズ済みサンドボックスセッション状態はあるが、実行中のサンドボックスセッションオブジェクトはない場合。 | `client` が必要です。runner はその明示的な状態から所有セッションとして再開します。 |
+| `client` | ランナーにサンドボックスセッションの作成、再開、クリーンアップを任せたい場合。 | 稼働中のサンドボックス `session` を提供しない限り必須です。 |
+| `session` | 稼働中のサンドボックスセッションを自分で既に作成している場合。 | 呼び出し元がライフサイクルを所有します。ランナーはその稼働中のサンドボックスセッションを再利用します。 |
+| `session_state` | シリアライズ済みサンドボックスセッション状態はあるが、稼働中のサンドボックスセッションオブジェクトはない場合。 | `client` が必要です。ランナーはその明示的な状態から、所有セッションとして再開します。 |
-実際には、runner は次の順序でサンドボックスセッションを解決します。
+実際には、ランナーは次の順序でサンドボックスセッションを解決します。
-1. `run_config.sandbox.session` を注入した場合、その実行中サンドボックスセッションが直接再利用されます。
-2. それ以外で、実行が `RunState` から再開している場合、保存済みのサンドボックスセッション状態が再開されます。
-3. それ以外で、`run_config.sandbox.session_state` を渡した場合、runner はその明示的なシリアライズ済みサンドボックスセッション状態から再開します。
-4. それ以外の場合、runner は新しいサンドボックスセッションを作成します。その新規セッションでは、提供されていれば `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` を使用します。
### 新規セッション入力
-これらのオプションは、runner が新しいサンドボックスセッションを作成する場合にのみ意味があります。
+これらのオプションは、ランナーが新しいサンドボックスセッションを作成する場合にのみ重要です。
| オプション | 使用する場合 | 注記 |
| --- | --- | --- |
| `manifest` | 一回限りの新規セッションワークスペース上書きを行いたい場合。 | 省略時は `agent.default_manifest` にフォールバックします。 |
-| `snapshot` | 新しいサンドボックスセッションをスナップショットから初期化すべき場合。 | 再開に近いフローやリモートスナップショットクライアントに便利です。 |
-| `options` | サンドボックスクライアントが作成時オプションを必要とする場合。 | Docker イメージ、Modal アプリ名、E2B テンプレート、タイムアウト、同様のクライアント固有設定で一般的です。 |
+| `snapshot` | 新しいサンドボックスセッションをスナップショットから初期化するべき場合。 | 再開に似たフローやリモートスナップショットクライアントに有用です。 |
+| `options` | サンドボックスクライアントが作成時オプションを必要とする場合。 | Docker イメージ、Modal アプリ名、E2B テンプレート、タイムアウト、および同様のクライアント固有設定で一般的です。 |
-### 具現化制御
+### マテリアライズ制御
-`concurrency_limits` は、サンドボックス具現化作業をどの程度並列で実行できるかを制御します。大きな manifests やローカルディレクトリコピーに、より厳密なリソース制御が必要な場合は `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` を使用します。特定の制限を無効にするには、どちらかの値を `None` に設定します。
+`concurrency_limits` は、サンドボックスのマテリアライズ作業をどれだけ並列で実行できるかを制御します。大きなマニフェストやローカルディレクトリコピーでリソース制御をより厳しくする必要がある場合は、`SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` を使用します。どちらかの値を `None` に設定すると、その特定の制限を無効にできます。
-覚えておく価値がある含意がいくつかあります。
+`archive_limits` は、アーカイブ展開に関する SDK 側のリソースチェックを制御します。SDK のデフォルトしきい値を有効にするには `archive_limits=SandboxArchiveLimits()` を設定し、アーカイブにより厳しいリソース制御が必要な場合は `SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)` のような明示的な値を渡します。SDK アーカイブリソース制限なしのデフォルト動作を維持するには `archive_limits=None` のままにし、個別フィールドを `None` に設定するとその制限だけを無効にできます。
-- 新規セッション: `manifest=` と `snapshot=` は、runner が新しいサンドボックスセッションを作成する場合にのみ適用されます。
-- 再開とスナップショット: `session_state=` は以前にシリアライズされたサンドボックス状態へ再接続し、`snapshot=` は保存済みワークスペース内容から新しいサンドボックスセッションを初期化します。
-- クライアント固有オプション: `options=` はサンドボックスクライアントに依存します。Docker と多くのホスト型クライアントでは必要です。
-- 注入された実行中セッション: 実行中のサンドボックス `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.root`、`manifest.environment`、`manifest.users`、`manifest.groups` を変更すること、既存エントリを削除すること、エントリタイプを置き換えること、マウントエントリを追加または変更することはできません。
+- ランナー API: `SandboxAgent` の実行は、引き続き通常の `Runner.run()`、`Runner.run_sync()`、`Runner.run_streamed()` API を使用します。
## 完全な例: コーディングタスク
-このコーディング形式の例は、優れたデフォルトの出発点です。
+このコーディング形式の例は、デフォルトの出発点として適しています。
```python
import asyncio
@@ -574,19 +576,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 を使用し、プロバイダー管理の実行が必要な場合はホスト型プロバイダーを使用します。例とプロバイダーオプションについては、[サンドボックスクライアント](clients.md) を参照してください。
### ワークスペースの上書き
-エージェント定義は同じに保ち、新規セッションの manifest だけを入れ替えます。
+エージェント定義は同じままにし、新規セッションのマニフェストだけを差し替えます。
```python
from agents.run import RunConfig
@@ -606,11 +608,11 @@ run_config = RunConfig(
)
```
-同じエージェントロールを、エージェントを再構築せずに異なるリポジトリ、パケット、またはタスクバンドルに対して実行すべき場合に使用します。上記の検証済みコーディング例では、一回限りの上書きではなく `default_manifest` で同じパターンを示しています。
+同じエージェントの役割を、エージェントを再構築せずに異なるリポジトリ、パケット、タスクバンドルに対して実行したい場合に使用します。上記の検証済みコーディング例では、一回限りの上書きではなく `default_manifest` を使って同じパターンを示しています。
### サンドボックスセッションの注入
-明示的なライフサイクル制御、実行後の検査、または出力コピーが必要な場合は、実行中のサンドボックスセッションを注入します。
+明示的なライフサイクル制御、実行後の検査、または出力コピーが必要な場合は、稼働中のサンドボックスセッションを注入します。
```python
from agents import Runner
@@ -631,11 +633,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` の外部でサンドボックス状態をすでにシリアライズしている場合は、runner にその状態から再接続させます。
+`RunState` の外で既にサンドボックス状態をシリアライズしている場合は、ランナーにその状態から再接続させます。
```python
from agents.run import RunConfig
@@ -652,7 +654,7 @@ 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) を参照してください。
### スナップショットからの開始
@@ -673,11 +675,11 @@ 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 からのスキル読み込み
-ローカルスキルソースを、リポジトリに基づくものへ入れ替えます。
+ローカルスキルソースを、リポジトリを基盤とするものに差し替えます。
```python
from agents.sandbox.capabilities import Capabilities, Skills
@@ -688,11 +690,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) を参照してください。
### ツールとしての公開
-ツールエージェントは、独自のサンドボックス境界を持つことも、親実行から実行中のサンドボックスを再利用することもできます。再利用は高速な読み取り専用探索エージェントに便利です。別のサンドボックスを作成、ハイドレート、スナップショットするコストを払わずに、親が使っている正確なワークスペースを検査できます。
+ツールエージェントは、独自のサンドボックス境界を持つことも、親実行から稼働中のサンドボックスを再利用することもできます。再利用は、高速な読み取り専用エクスプローラーエージェントに有用です。別のサンドボックスを作成、ハイドレート、またはスナップショットするコストを払わずに、親が使用している正確なワークスペースを検査できます。
```python
from agents import Runner
@@ -774,9 +776,9 @@ async with sandbox:
)
```
-ここでは親エージェントが `coordinator` として実行され、explorer ツールエージェントが同じ実行中サンドボックスセッション内で `explorer` として実行されます。`pricing_packet/` エントリは `other` ユーザーが読み取れるため、explorer はすばやく検査できますが、書き込みビットは持ちません。`work/` ディレクトリは coordinator のユーザー/グループだけが利用できるため、親は最終成果物を書き込み、explorer は読み取り専用のままでいられます。
+ここでは、親エージェントが `coordinator` として実行され、エクスプローラーツールエージェントが同じ稼働中サンドボックスセッション内で `explorer` として実行されます。`pricing_packet/` エントリは `other` ユーザーに読み取り可能なので、エクスプローラーはそれらをすばやく検査できますが、書き込みビットはありません。`work/` ディレクトリはコーディネーターのユーザー/グループにのみ利用可能なため、親は最終成果物を書き込める一方で、エクスプローラーは読み取り専用のままです。
-ツールエージェントに本当の隔離が必要な場合は、独自のサンドボックス `RunConfig` を与えます。
+ツールエージェントに実際の分離が必要な場合は、代わりに専用のサンドボックス `RunConfig` を与えます。
```python
from docker import from_env as docker_from_env
@@ -797,11 +799,11 @@ rollout_agent.as_tool(
)
```
-ツールエージェントが自由に変更する、信頼できないコマンドを実行する、または異なるバックエンド/イメージを使用すべき場合は、別のサンドボックスを使用します。[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 との組み合わせ
-同じエージェントで通常のツールを引き続き使用しながら、サンドボックスワークスペースを維持します。
+通常のツールを同じエージェントで使いながら、サンドボックスワークスペースを維持します。
```python
from agents.sandbox import SandboxAgent
@@ -820,42 +822,42 @@ agent = SandboxAgent(
## メモリ
-将来のサンドボックスエージェント実行が以前の実行から学ぶべき場合は、`Memory` capability を使用します。メモリは SDK の会話用 `Session` メモリとは別です。教訓をサンドボックスワークスペース内のファイルに抽出し、後続の実行がそれらのファイルを読めるようにします。
+将来のサンドボックスエージェント実行が以前の実行から学習するべき場合は、`Memory` 機能を使用します。メモリは SDK の会話用 `Session` メモリとは別物です。レッスンをサンドボックスワークスペース内のファイルに抽出し、後続の実行がそれらのファイルを読み取れるようにします。
-セットアップ、読み取り/生成動作、マルチターン会話、レイアウト隔離については [エージェントメモリ](memory.md) を参照してください。
+セットアップ、読み取り/生成動作、マルチターン会話、レイアウト分離については、[エージェントメモリ](memory.md) を参照してください。
## 構成パターン
-単一エージェントパターンが明確になったら、次の設計上の問いは、より大きなシステム内でサンドボックス境界をどこに置くかです。
+単一エージェントのパターンが明確になったら、次の設計上の問いは、より大きなシステムのどこにサンドボックス境界を置くかです。
サンドボックスエージェントは、引き続き SDK の他の部分と組み合わせられます。
-- [ハンドオフ](../handoffs.md): ドキュメント量の多い作業を、非サンドボックスの受付エージェントからサンドボックスレビュアーへハンドオフします。
-- [Agents as tools](../tools.md#agents-as-tools): 複数のサンドボックスエージェントをツールとして公開します。通常は各 `Agent.as_tool(...)` 呼び出しで `run_config=RunConfig(sandbox=SandboxRunConfig(...))` を渡し、各ツールに独自のサンドボックス境界を与えます。
-- [MCP](../mcp.md) と通常の関数ツール: サンドボックス capabilities は `mcp_servers` や通常の Python ツールと共存できます。
-- [エージェントの実行](../running_agents.md): サンドボックス実行は引き続き通常の `Runner` API を使用します。
+- [ハンドオフ](../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 を使用します。
-特によくあるパターンは 2 つです。
+特に一般的なパターンは次の 2 つです。
-- ワークフローのうちワークスペース隔離が必要な部分だけ、非サンドボックスエージェントがサンドボックスエージェントへハンドオフする
-- オーケストレーターが複数のサンドボックスエージェントをツールとして公開する。通常は各 `Agent.as_tool(...)` 呼び出しごとに別々のサンドボックス `RunConfig` を使い、各ツールに独自の隔離ワークスペースを与える
+- ワークフローのうちワークスペース分離が必要な部分だけ、非サンドボックスエージェントからサンドボックスエージェントへハンドオフする
+- オーケストレーターが複数のサンドボックスエージェントをツールとして公開する。通常は各 `Agent.as_tool(...)` 呼び出しごとに別々のサンドボックス `RunConfig` を使い、各ツールが独自の分離ワークスペースを持つようにする
### ターンとサンドボックス実行
-ハンドオフと agent-as-tool 呼び出しは別々に説明すると理解しやすくなります。
+ハンドオフと agent-as-tool 呼び出しは分けて説明すると理解しやすくなります。
-ハンドオフでは、依然として 1 つのトップレベル実行と 1 つのトップレベルターンループがあります。アクティブなエージェントは変わりますが、実行がネストされるわけではありません。非サンドボックスの受付エージェントがサンドボックスレビュアーにハンドオフすると、その同じ実行内の次のモデル呼び出しがサンドボックスエージェント用に準備され、そのサンドボックスエージェントが次のターンを担当します。言い換えると、ハンドオフは同じ実行の次のターンをどのエージェントが所有するかを変更します。[examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) を参照してください。
+ハンドオフでは、引き続き 1 つのトップレベル実行と 1 つのトップレベルターンループがあります。アクティブなエージェントは変わりますが、実行がネストされるわけではありません。非サンドボックスの取り込みエージェントがサンドボックスレビュアーへハンドオフすると、同じ実行内の次のモデル呼び出しはサンドボックスエージェント向けに準備され、そのサンドボックスエージェントが次のターンを受け持つものになります。言い換えると、ハンドオフは同じ実行の次のターンをどのエージェントが所有するかを変更します。[examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) を参照してください。
-`Agent.as_tool(...)` では、関係が異なります。外側のオーケストレーターは、ツール呼び出しを行うと決定するために外側の 1 ターンを使い、そのツール呼び出しがサンドボックスエージェントのネストされた実行を開始します。ネストされた実行は独自のターンループ、`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) を参照してください。
+`Agent.as_tool(...)` では、関係が異なります。外側のオーケストレーターは、ツールを呼び出すことを決定するために 1 つの外側ターンを使い、そのツール呼び出しがサンドボックスエージェントのネストされた実行を開始します。ネストされた実行は、独自のターンループ、`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) を参照してください。
-承認動作も同じ分割に従います。
+承認の動作も同じ分離に従います。
-- ハンドオフでは、サンドボックスエージェントがその実行のアクティブエージェントになるため、承認は同じトップレベル実行に留まります。
-- `Agent.as_tool(...)` では、サンドボックスツールエージェント内で発生した承認は外側の実行にも表示されますが、保存済みのネスト実行状態から来ており、外側の実行が再開したときにネストされたサンドボックス実行を再開します。
+- ハンドオフでは、サンドボックスエージェントがその実行のアクティブなエージェントになるため、承認は同じトップレベル実行に留まります。
+- `Agent.as_tool(...)` では、サンドボックスツールエージェント内で発生した承認は引き続き外側の実行に表示されますが、保存されたネスト実行状態に由来し、外側の実行が再開されるとネストされたサンドボックス実行を再開します。
## 関連資料
- [クイックスタート](quickstart.md): 1 つのサンドボックスエージェントを実行します。
-- [サンドボックスクライアント](clients.md): ローカル、Docker、ホスト型、マウントオプションを選択します。
-- [エージェントメモリ](memory.md): 以前のサンドボックス実行から得た教訓を保存し再利用します。
-- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 実行可能なローカル、コーディング、メモリ、ハンドオフ、エージェント構成パターンです。
\ No newline at end of file
+- [サンドボックスクライアント](clients.md): ローカル、Docker、ホスト型、マウントのオプションを選択します。
+- [エージェントメモリ](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/ko/sandbox/guide.md b/docs/ko/sandbox/guide.md
index 204264ecae..174bfeec65 100644
--- a/docs/ko/sandbox/guide.md
+++ b/docs/ko/sandbox/guide.md
@@ -6,11 +6,11 @@ search:
!!! warning "베타 기능"
- 샌드박스 에이전트는 베타입니다. 일반 제공 전까지 API, 기본값, 지원 기능의 세부 사항이 변경될 수 있으며, 시간이 지나며 더 고급 기능이 추가될 수 있습니다.
+ 샌드박스 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 출시 전에 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
-최신 에이전트는 파일시스템의 실제 파일을 다룰 수 있을 때 가장 잘 작동합니다. **샌드박스 에이전트**는 특수 도구와 셸 명령을 사용하여 대규모 문서 세트를 검색하고 조작하고, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 에이전트가 사용자를 대신해 작업할 수 있는 영구 워크스페이스를 모델에 제공합니다. Agents SDK의 샌드박스 에이전트는 샌드박스 환경과 짝지어진 에이전트를 쉽게 실행하도록 도와주며, 적절한 파일을 파일시스템에 배치하고 샌드박스를 오케스트레이션하여 대규모로 작업을 쉽게 시작, 중지, 재개할 수 있게 합니다.
+최신 에이전트는 파일시스템의 실제 파일에서 작업할 수 있을 때 가장 잘 동작합니다. **샌드박스 에이전트**는 특화된 도구와 셸 명령을 사용해 대규모 문서 집합을 검색하고 조작하며, 파일을 편집하고, 산출물을 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 모델이 사용자를 대신해 작업하는 데 사용할 수 있는 지속적인 작업공간을 제공합니다. Agents SDK의 샌드박스 에이전트는 샌드박스 환경과 짝을 이룬 에이전트를 쉽게 실행하도록 도와주며, 적절한 파일을 파일시스템에 배치하고 샌드박스를 오케스트레이션해 대규모로 작업을 쉽게 시작, 중지, 재개할 수 있게 합니다.
-에이전트에 필요한 데이터를 중심으로 워크스페이스를 정의합니다. GitHub 리포지토리, 로컬 파일과 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage와 같은 원격 파일시스템, 그리고 사용자가 제공하는 기타 샌드박스 입력에서 시작할 수 있습니다.
+에이전트에 필요한 데이터를 중심으로 작업공간을 정의합니다. GitHub 리포지토리, 로컬 파일과 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일시스템, 그리고 사용자가 제공하는 기타 샌드박스 입력에서 시작할 수 있습니다.
@@ -18,23 +18,23 @@ search:
-`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`, 가드레일, 훅 같은 일반적인 에이전트 표면을 유지하며, 여전히 일반 `Runner` API를 통해 실행됩니다. 달라지는 것은 실행 경계입니다.
- `SandboxAgent`는 에이전트 자체를 정의합니다. 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스별 기본값과 파일시스템 도구, 셸 접근, 스킬, 메모리, 컴팩션 같은 기능을 포함합니다.
-- `Manifest`는 파일, 리포지토리, 마운트, 환경을 포함하여 새 샌드박스 워크스페이스의 원하는 시작 콘텐츠와 레이아웃을 선언합니다.
-- 샌드박스 세션은 명령이 실행되고 파일이 변경되는 실제 격리 환경입니다.
-- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 실행이 해당 샌드박스 세션을 어떻게 가져올지 결정합니다. 예를 들어 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 다시 연결하거나, 샌드박스 클라이언트를 통해 새 샌드박스 세션을 만들 수 있습니다.
-- 저장된 샌드박스 상태와 스냅샷을 사용하면 이후 실행이 이전 작업에 다시 연결하거나 저장된 콘텐츠에서 새 샌드박스 세션을 시드할 수 있습니다.
+- `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] 인터페이스와 다릅니다.
-외부 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 북키핑을 소유합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 소유합니다. 이 분리는 모델의 핵심 부분입니다.
+외부 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 기록을 소유합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 소유합니다. 이 분리는 모델의 핵심 요소입니다.
### 구성 요소의 결합 방식
-샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. 러너는 에이전트를 준비하고 실제 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다.
+샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. 러너는 에이전트를 준비하고, 이를 살아 있는 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다.
```mermaid
flowchart LR
@@ -50,33 +50,33 @@ flowchart LR
sandbox --> saved
```
-샌드박스별 기본값은 `SandboxAgent`에 둡니다. 실행별 샌드박스 세션 선택은 `SandboxRunConfig`에 둡니다.
+샌드박스별 기본값은 `SandboxAgent`에 유지됩니다. 실행별 샌드박스 세션 선택은 `SandboxRunConfig`에 유지됩니다.
-라이프사이클을 세 단계로 생각하세요.
+생명주기는 세 단계로 생각할 수 있습니다.
-1. `SandboxAgent`, `Manifest`, 기능으로 에이전트와 새 워크스페이스 계약을 정의합니다.
-2. 샌드박스 세션을 주입, 재개, 또는 생성하는 `SandboxRunConfig`를 `Runner`에 제공하여 실행을 수행합니다.
-3. 러너가 관리하는 `RunState`, 명시적 샌드박스 `session_state`, 또는 저장된 워크스페이스 스냅샷에서 나중에 계속합니다.
+1. `SandboxAgent`, `Manifest`, 기능으로 에이전트와 새 작업공간 계약을 정의합니다.
+2. 샌드박스 세션을 주입, 재개 또는 생성하는 `SandboxRunConfig`를 `Runner`에 제공해 실행을 수행합니다.
+3. 러너가 관리하는 `RunState`, 명시적 샌드박스 `session_state`, 또는 저장된 작업공간 스냅샷에서 나중에 계속합니다.
-셸 접근이 가끔 사용하는 하나의 도구일 뿐이라면 [도구 가이드](../tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요.
+셸 접근이 가끔 쓰는 도구 하나에 불과하다면 [도구 가이드](../tools.md)의 호스티드 셸부터 시작하세요. 작업공간 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요.
-## 사용 시기
+## 사용 시점
-샌드박스 에이전트는 다음과 같은 워크스페이스 중심 워크플로에 적합합니다.
+샌드박스 에이전트는 다음과 같은 작업공간 중심 워크플로에 적합합니다.
-- 코딩과 디버깅, 예를 들어 GitHub 리포지토리의 이슈 보고서에 대한 자동 수정 조율 및 대상 테스트 실행
-- 문서 처리와 편집, 예를 들어 사용자의 금융 문서에서 정보를 추출하고 작성된 세금 양식 초안을 생성
-- 파일 기반 검토 또는 분석, 예를 들어 답변 전에 온보딩 패킷, 생성된 보고서, 아티팩트 번들을 확인
-- 격리된 다중 에이전트 패턴, 예를 들어 각 검토자 또는 코딩 하위 에이전트에 자체 워크스페이스 제공
-- 다단계 워크스페이스 작업, 예를 들어 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개
+- 코딩과 디버깅, 예를 들어 GitHub 리포지토리의 이슈 보고서에 대한 자동 수정 오케스트레이션 및 대상 테스트 실행
+- 문서 처리와 편집, 예를 들어 사용자의 금융 문서에서 정보를 추출하고 작성된 세금 양식 초안 생성
+- 파일 기반 검토 또는 분석, 예를 들어 답변 전 온보딩 패킷, 생성된 보고서, 산출물 번들 확인
+- 격리된 멀티 에이전트 패턴, 예를 들어 각 리뷰어 또는 코딩 하위 에이전트에 자체 작업공간 제공
+- 다단계 작업공간 작업, 예를 들어 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개
-파일이나 살아 있는 파일시스템에 접근할 필요가 없다면 `Agent`를 계속 사용하세요. 셸 접근이 가끔 필요한 기능 하나라면 호스티드 셸을 추가하세요. 워크스페이스 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요.
+파일이나 살아 있는 파일시스템에 접근할 필요가 없다면 `Agent`를 계속 사용하세요. 셸 접근이 가끔 필요한 기능 하나라면 호스티드 셸을 추가하세요. 작업공간 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요.
## 샌드박스 클라이언트 선택
-로컬 개발에는 `UnixLocalSandboxClient`로 시작하세요. 컨테이너 격리나 이미지 동일성이 필요하면 `DockerSandboxClient`로 이동하세요. 공급자 관리 실행이 필요하면 호스티드 공급자로 이동하세요.
+로컬 개발에는 `UnixLocalSandboxClient`부터 시작하세요. 컨테이너 격리 또는 이미지 동등성이 필요하면 `DockerSandboxClient`로 이동하세요. 공급자 관리 실행이 필요하면 호스티드 공급자로 이동하세요.
-대부분의 경우 `SandboxAgent` 정의는 그대로 두고, 샌드박스 클라이언트와 해당 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경합니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요.
+대부분의 경우 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트와 해당 옵션만 변경하고 `SandboxAgent` 정의는 그대로 유지됩니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요.
## 핵심 구성 요소
@@ -84,69 +84,69 @@ flowchart LR
| 계층 | 주요 SDK 구성 요소 | 답하는 질문 |
| --- | --- | --- |
-| 에이전트 정의 | `SandboxAgent`, `Manifest`, 기능 | 어떤 에이전트가 실행되며, 어떤 새 세션 워크스페이스 계약에서 시작해야 합니까? |
-| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 실제 샌드박스 세션 | 이 실행은 실제 샌드박스 세션을 어떻게 얻으며, 작업은 어디에서 실행됩니까? |
-| 저장된 샌드박스 상태 | `RunState` 샌드박스 페이로드, `session_state`, 스냅샷 | 이 워크플로는 이전 샌드박스 작업에 어떻게 다시 연결하거나 저장된 콘텐츠에서 새 샌드박스 세션을 시드합니까? |
+| 에이전트 정의 | `SandboxAgent`, `Manifest`, 기능 | 어떤 에이전트를 실행하며, 어떤 새 세션 작업공간 계약에서 시작해야 하나요? |
+| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 살아 있는 샌드박스 세션 | 이 실행은 살아 있는 샌드박스 세션을 어떻게 얻고, 작업은 어디에서 실행되나요? |
+| 저장된 샌드박스 상태 | `RunState` 샌드박스 페이로드, `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`로 새 세션 워크스페이스 계약을 정의합니다.
+1. `Manifest`로 새 세션 작업공간 계약을 정의합니다.
2. `SandboxAgent`로 에이전트를 정의합니다.
3. 기본 제공 또는 사용자 지정 기능을 추가합니다.
-4. 각 실행이 `RunConfig(sandbox=SandboxRunConfig(...))`에서 샌드박스 세션을 어떻게 획득해야 하는지 결정합니다.
+4. 각 실행이 `RunConfig(sandbox=SandboxRunConfig(...))`에서 샌드박스 세션을 어떻게 얻을지 결정합니다.
## 샌드박스 실행 준비 방식
-실행 시점에 러너는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다.
+실행 시 러너는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다.
1. `SandboxRunConfig`에서 샌드박스 세션을 해석합니다.
- `session=...`을 전달하면 해당 실제 샌드박스 세션을 재사용합니다.
- 그렇지 않으면 `client=...`를 사용하여 세션을 생성하거나 재개합니다.
-2. 실행의 유효 워크스페이스 입력을 결정합니다.
+ `session=...`을 전달하면 해당 살아 있는 샌드박스 세션을 재사용합니다.
+ 그렇지 않으면 `client=...`를 사용해 하나를 생성하거나 재개합니다.
+2. 실행의 실제 작업공간 입력을 결정합니다.
실행이 샌드박스 세션을 주입하거나 재개하면 기존 샌드박스 상태가 우선합니다.
그렇지 않으면 러너는 일회성 매니페스트 오버라이드 또는 `agent.default_manifest`에서 시작합니다.
- 이것이 `Manifest`만으로 모든 실행의 최종 실제 워크스페이스를 정의하지 않는 이유입니다.
-3. 기능이 결과 매니페스트를 처리하도록 합니다.
- 이를 통해 기능은 최종 에이전트가 준비되기 전에 파일, 마운트, 또는 기타 워크스페이스 범위 동작을 추가할 수 있습니다.
+ 이것이 `Manifest`만으로 모든 실행의 최종 라이브 작업공간이 정의되지 않는 이유입니다.
+3. 기능이 결과 매니페스트를 처리하게 합니다.
+ 이를 통해 기능은 최종 에이전트가 준비되기 전에 파일, 마운트, 또는 기타 작업공간 범위 동작을 추가할 수 있습니다.
4. 고정된 순서로 최종 instructions를 구성합니다.
- SDK의 기본 샌드박스 프롬프트 또는 명시적으로 재정의한 경우 `base_instructions`, 그다음 `instructions`, 기능 instruction 조각, 원격 마운트 정책 텍스트, 렌더링된 파일시스템 트리 순서입니다.
-5. 기능 도구를 실제 샌드박스 세션에 바인딩하고 준비된 에이전트를 일반 `Runner` API를 통해 실행합니다.
+ SDK의 기본 샌드박스 프롬프트 또는 명시적으로 오버라이드한 경우 `base_instructions`, 그다음 `instructions`, 그다음 기능 지침 조각, 그다음 원격 마운트 정책 텍스트, 그다음 렌더링된 파일시스템 트리입니다.
+5. 기능 도구를 살아 있는 샌드박스 세션에 바인딩하고 준비된 에이전트를 일반 `Runner` API를 통해 실행합니다.
-샌드박싱은 턴의 의미를 바꾸지 않습니다. 턴은 여전히 단일 셸 명령이나 샌드박스 작업이 아니라 모델 단계입니다. 샌드박스 측 작업과 턴 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 내부에 머물 수 있고, 다른 작업은 또 다른 모델 단계가 필요한 도구 결과, 승인, 또는 기타 상태를 반환할 수 있습니다. 실용적인 규칙으로는, 샌드박스 작업이 일어난 뒤 에이전트 런타임이 또 다른 모델 응답을 필요로 할 때만 다른 턴이 소비됩니다.
+샌드박싱은 턴의 의미를 바꾸지 않습니다. 턴은 여전히 모델 단계이지, 단일 셸 명령이나 샌드박스 작업이 아닙니다. 샌드박스 측 작업과 턴 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 안에 남을 수 있고, 다른 작업은 도구 결과, 승인, 또는 다른 모델 단계가 필요한 기타 상태를 반환할 수 있습니다. 실용적인 규칙으로, 샌드박스 작업이 발생한 후 에이전트 런타임이 또 다른 모델 응답을 필요로 할 때만 다른 턴이 소비됩니다.
-이러한 준비 단계 때문에 `SandboxAgent`를 설계할 때는 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`가 고려해야 할 주요 샌드박스별 옵션입니다.
+이러한 준비 단계 때문에 `SandboxAgent`를 설계할 때 고려해야 할 주요 샌드박스별 옵션은 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`입니다.
## `SandboxAgent` 옵션
-다음은 일반 `Agent` 필드 위에 추가되는 샌드박스별 옵션입니다.
+일반적인 `Agent` 필드에 더해 제공되는 샌드박스별 옵션은 다음과 같습니다.
-| 옵션 | 최적의 사용 |
+| 옵션 | 최적 사용 |
| --- | --- |
-| `default_manifest` | 러너가 생성하는 새 샌드박스 세션의 기본 워크스페이스 |
-| `instructions` | SDK 샌드박스 프롬프트 뒤에 추가되는 추가 역할, 워크플로, 성공 기준 |
+| `default_manifest` | 러너가 생성하는 새 샌드박스 세션의 기본 작업공간 |
+| `instructions` | SDK 샌드박스 프롬프트 뒤에 추가되는 역할, 워크플로, 성공 기준 |
| `base_instructions` | SDK 샌드박스 프롬프트를 대체하는 고급 탈출구 |
| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 네이티브 도구와 동작 |
-| `run_as` | 셸 명령, 파일 읽기, 패치와 같은 모델 대상 샌드박스 도구의 사용자 ID |
+| `run_as` | 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구의 사용자 ID |
@@ -154,101 +154,101 @@ flowchart LR
### `default_manifest`
-`default_manifest`는 러너가 이 에이전트에 대해 새 샌드박스 세션을 만들 때 사용되는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 보통 시작해야 하는 파일, 리포지토리, 도우미 자료, 출력 디렉터리, 마운트에 사용하세요.
+`default_manifest`는 러너가 이 에이전트에 대해 새 샌드박스 세션을 생성할 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 일반적으로 시작해야 하는 파일, 리포지토리, 보조 자료, 출력 디렉터리, 마운트에 사용하세요.
-이는 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 재정의할 수 있으며, 재사용되거나 재개된 샌드박스 세션은 기존 워크스페이스 상태를 유지합니다.
+이는 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 오버라이드할 수 있으며, 재사용되거나 재개된 샌드박스 세션은 기존 작업공간 상태를 유지합니다.
-### `instructions`와 `base_instructions`
+### `instructions` 및 `base_instructions`
-여러 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이러한 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 기본 제공 샌드박스 지침을 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다.
+다른 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이러한 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 기본 제공 샌드박스 안내를 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다.
-SDK 샌드박스 기본 프롬프트를 대체하려는 경우에만 `base_instructions`를 사용하세요. 대부분의 에이전트는 이를 설정하지 않는 것이 좋습니다.
+SDK 샌드박스 기본 프롬프트를 대체하려는 경우에만 `base_instructions`를 사용하세요. 대부분의 에이전트는 이를 설정하지 않아야 합니다.
-| 넣을 위치 | 사용 목적 | 예시 |
+| 넣을 위치 | 용도 | 예시 |
| --- | --- | --- |
-| `instructions` | 에이전트의 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검사한 뒤 핸드오프하세요.", "최종 파일을 `output/`에 작성하세요." |
+| `instructions` | 에이전트를 위한 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검사한 다음 핸드오프하세요.", "최종 파일을 `output/`에 작성하세요." |
| `base_instructions` | SDK 샌드박스 기본 프롬프트의 전체 대체 | 사용자 지정 저수준 샌드박스 래퍼 프롬프트 |
-| 사용자 프롬프트 | 이 실행에 대한 일회성 요청 | "이 워크스페이스를 요약하세요." |
-| 매니페스트의 워크스페이스 파일 | 더 긴 작업 명세, 리포지토리 로컬 지침, 또는 범위가 제한된 참고 자료 | `repo/task.md`, 문서 번들, 샘플 패킷 |
+| 사용자 프롬프트 | 이 실행을 위한 일회성 요청 | "이 작업공간을 요약하세요." |
+| 매니페스트의 작업공간 파일 | 더 긴 작업 명세, 리포지토리 로컬 지침, 또는 범위가 제한된 참고 자료 | `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)는 샌드박스 검토자가 검사 후 사용자에게 직접 답하지 못하게 합니다.
-- [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`에 복사하거나, 매니페스트에 들어가야 하는 긴 참고 자료를 포함하거나, 기본 제공 기능이 이미 주입하는 도구 문서를 다시 설명하거나, 런타임에 모델에 필요하지 않은 로컬 설치 메모를 섞지 마세요.
+사용자의 일회성 작업을 `instructions`에 복사하거나, 매니페스트에 있어야 할 긴 참고 자료를 포함하거나, 기본 제공 기능이 이미 주입하는 도구 문서를 다시 설명하거나, 모델이 실행 시 필요로 하지 않는 로컬 설치 메모를 섞는 것은 피하세요.
-`instructions`를 생략해도 SDK는 기본 샌드박스 프롬프트를 포함합니다. 이는 저수준 래퍼에는 충분하지만, 대부분의 사용자 대상 에이전트는 그래도 명시적인 `instructions`를 제공해야 합니다.
+`instructions`를 생략해도 SDK는 기본 샌드박스 프롬프트를 포함합니다. 이는 저수준 래퍼에는 충분하지만, 대부분의 사용자 대상 에이전트는 여전히 명시적 `instructions`를 제공해야 합니다.
### `capabilities`
-기능은 샌드박스 네이티브 동작을 `SandboxAgent`에 연결합니다. 기능은 실행 시작 전 워크스페이스를 형성하고, 샌드박스별 instructions를 추가하고, 실제 샌드박스 세션에 바인딩되는 도구를 노출하며, 해당 에이전트의 모델 동작이나 입력 처리를 조정할 수 있습니다.
+기능은 샌드박스 네이티브 동작을 `SandboxAgent`에 붙입니다. 실행이 시작되기 전에 작업공간을 형성하고, 샌드박스별 instructions를 추가하고, 살아 있는 샌드박스 세션에 바인딩되는 도구를 노출하며, 해당 에이전트의 모델 동작이나 입력 처리를 조정할 수 있습니다.
-기본 제공 기능에는 다음이 포함됩니다.
+기본 제공 기능은 다음과 같습니다.
| 기능 | 추가 시점 | 참고 |
| --- | --- | --- |
| `Shell` | 에이전트에 셸 접근이 필요할 때 | `exec_command`를 추가하며, 샌드박스 클라이언트가 PTY 상호작용을 지원하면 `write_stdin`도 추가합니다. |
-| `Filesystem` | 에이전트가 파일을 편집하거나 로컬 이미지를 검사해야 할 때 | `apply_patch`와 `view_image`를 추가합니다. 패치 경로는 워크스페이스 루트 기준입니다. |
-| `Skills` | 샌드박스에서 스킬 검색과 구체화를 원할 때 | `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 것보다 이를 선호하세요. `Skills`가 스킬을 인덱싱하고 샌드박스에 구체화합니다. |
-| `Memory` | 후속 실행이 메모리 아티팩트를 읽거나 생성해야 할 때 | `Shell`이 필요합니다. 실시간 업데이트에는 `Filesystem`도 필요합니다. |
-| `Compaction` | 장기 실행 흐름에서 컴팩션 항목 이후 컨텍스트 트리밍이 필요할 때 | 모델 샘플링과 입력 처리를 조정합니다. |
+| `Filesystem` | 에이전트가 파일을 편집하거나 로컬 이미지를 검사해야 할 때 | `apply_patch`와 `view_image`를 추가합니다. 패치 경로는 작업공간 루트 기준입니다. |
+| `Skills` | 샌드박스에서 스킬 발견과 구체화를 원할 때 | `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 것보다 이를 선호하세요. `Skills`가 스킬을 인덱싱하고 샌드박스에 구체화합니다. |
+| `Memory` | 후속 실행이 메모리 산출물을 읽거나 생성해야 할 때 | `Shell`이 필요합니다. 라이브 업데이트에는 `Filesystem`도 필요합니다. |
+| `Compaction` | 장기 실행 흐름에서 컴팩션 항목 이후 컨텍스트 정리가 필요할 때 | 모델 샘플링과 입력 처리를 조정합니다. |
-기본적으로 `SandboxAgent.capabilities`는 `Filesystem()`, `Shell()`, `Compaction()`을 포함하는 `Capabilities.default()`를 사용합니다. `capabilities=[...]`를 전달하면 해당 목록이 기본값을 대체하므로, 계속 원하는 기본 기능을 포함하세요.
+기본적으로 `SandboxAgent.capabilities`는 `Filesystem()`, `Shell()`, `Compaction()`을 포함하는 `Capabilities.default()`를 사용합니다. `capabilities=[...]`를 전달하면 해당 목록이 기본값을 대체하므로, 여전히 원하는 기본 기능을 포함하세요.
-스킬의 경우, 스킬을 어떻게 구체화할지에 따라 소스를 선택하세요.
+스킬의 경우, 어떻게 구체화할지에 따라 소스를 선택하세요.
-- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 모델이 먼저 인덱스를 발견하고 필요한 것만 로드할 수 있으므로 큰 로컬 스킬 디렉터리에 좋은 기본값입니다.
-- `LocalDirLazySkillSource(source=LocalDir(src=...))`는 SDK 프로세스가 실행 중인 파일시스템에서 읽습니다. 샌드박스 이미지나 워크스페이스 안에만 존재하는 경로가 아니라 원래 호스트 측 스킬 디렉터리를 전달하세요.
+- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 모델이 먼저 인덱스를 발견하고 필요한 것만 로드할 수 있으므로 더 큰 로컬 스킬 디렉터리에 좋은 기본값입니다.
+- `LocalDirLazySkillSource(source=LocalDir(src=...))`는 SDK 프로세스가 실행 중인 파일시스템에서 읽습니다. 샌드박스 이미지나 작업공간 내부에만 존재하는 경로가 아니라 원래 호스트 측 스킬 디렉터리를 전달하세요.
- `Skills(from_=LocalDir(src=...))`는 미리 스테이징하려는 작은 로컬 번들에 더 적합합니다.
- `Skills(from_=GitRepo(repo=..., ref=...))`는 스킬 자체가 리포지토리에서 와야 할 때 적합합니다.
-`LocalDir.src`는 SDK 호스트의 소스 경로입니다. `skills_path`는 `load_skill`이 호출될 때 스킬이 스테이징되는 샌드박스 워크스페이스 내부의 상대 대상 경로입니다.
+`LocalDir.src`는 SDK 호스트의 소스 경로입니다. `skills_path`는 `load_skill`이 호출될 때 스킬이 스테이징되는 샌드박스 작업공간 내부의 상대 대상 경로입니다.
-스킬이 이미 `.agents/skills//SKILL.md`와 같은 디스크 경로에 있다면, `LocalDir(...)`가 해당 소스 루트를 가리키게 하고 그래도 `Skills(...)`를 사용해 노출하세요. 다른 샌드박스 내부 레이아웃에 의존하는 기존 워크스페이스 계약이 없다면 기본 `skills_path=".agents"`를 유지하세요.
+스킬이 이미 디스크의 `.agents/skills//SKILL.md` 같은 위치에 있다면, `LocalDir(...)`가 해당 소스 루트를 가리키게 하고 그래도 `Skills(...)`를 사용해 노출하세요. 다른 샌드박스 내부 레이아웃에 의존하는 기존 작업공간 계약이 없다면 기본 `skills_path=".agents"`를 유지하세요.
-적합한 경우 기본 제공 기능을 선호하세요. 기본 제공 기능이 다루지 않는 샌드박스별 도구나 instruction 표면이 필요할 때만 사용자 지정 기능을 작성하세요.
+적합할 때는 기본 제공 기능을 선호하세요. 기본 제공 기능이 다루지 않는 샌드박스별 도구 또는 지침 표면이 필요할 때만 사용자 지정 기능을 작성하세요.
## 개념
-### Manifest
+### 매니페스트
-[`Manifest`][agents.sandbox.manifest.Manifest]는 새 샌드박스 세션을 위한 워크스페이스를 설명합니다. 워크스페이스 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사하고, Git 리포지토리를 클론하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자나 그룹을 정의하고, 워크스페이스 외부의 특정 절대 경로에 대한 접근을 부여할 수 있습니다.
+[`Manifest`][agents.sandbox.manifest.Manifest]는 새 샌드박스 세션의 작업공간을 설명합니다. 작업공간 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사하고, Git 리포지토리를 클론하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자 또는 그룹을 정의하고, 작업공간 외부의 특정 절대 경로에 대한 접근을 부여할 수 있습니다.
-매니페스트 엔트리 경로는 워크스페이스 상대 경로입니다. 절대 경로일 수 없고 `..`로 워크스페이스를 벗어날 수 없으므로, 로컬, Docker, 호스티드 클라이언트 전반에서 워크스페이스 계약이 이식 가능하게 유지됩니다.
+매니페스트 항목 경로는 작업공간 기준 상대 경로입니다. 절대 경로일 수 없고 `..`로 작업공간을 벗어날 수 없습니다. 이를 통해 작업공간 계약이 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다.
-작업 시작 전에 에이전트가 필요로 하는 자료에는 매니페스트 엔트리를 사용하세요.
+작업이 시작되기 전에 에이전트에 필요한 자료에는 매니페스트 항목을 사용하세요.
-| 매니페스트 엔트리 | 사용 목적 |
+| 매니페스트 항목 | 용도 |
| --- | --- |
-| `File`, `Dir` | 작은 합성 입력, 도우미 파일, 또는 출력 디렉터리 |
+| `File`, `Dir` | 작은 합성 입력, 보조 파일, 또는 출력 디렉터리 |
| `LocalFile`, `LocalDir` | 샌드박스에 구체화되어야 하는 호스트 파일 또는 디렉터리 |
-| `GitRepo` | 워크스페이스로 가져와야 하는 리포지토리 |
+| `GitRepo` | 작업공간으로 가져와야 하는 리포지토리 |
| `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount` 같은 마운트 | 샌드박스 내부에 나타나야 하는 외부 스토리지 |
-`Dir`는 합성 자식으로부터 또는 출력 위치로서 샌드박스 워크스페이스 내부에 디렉터리를 생성합니다. 호스트 파일시스템에서 읽지 않습니다. 기존 호스트 디렉터리를 샌드박스 워크스페이스로 복사해야 할 때는 `LocalDir`를 사용하세요.
+`Dir`은 합성 자식에서 또는 출력 위치로 샌드박스 작업공간 내부에 디렉터리를 생성합니다. 호스트 파일시스템에서 읽지 않습니다. 기존 호스트 디렉터리를 샌드박스 작업공간으로 복사해야 할 때는 `LocalDir`를 사용하세요.
-`LocalFile.src`와 `LocalDir.src`는 기본적으로 SDK 프로세스 작업 디렉터리를 기준으로 해석됩니다. 소스는 `extra_path_grants`로 포함되지 않는 한 해당 기본 디렉터리 아래에 있어야 합니다. 이는 로컬 소스 구체화를 샌드박스 매니페스트의 나머지 부분과 동일한 호스트 경로 신뢰 경계 안에 유지합니다.
+`LocalFile.src`와 `LocalDir.src`는 기본적으로 SDK 프로세스 작업 디렉터리를 기준으로 해석됩니다. 소스는 `extra_path_grants`로 커버되지 않는 한 해당 기본 디렉터리 아래에 머물러야 합니다. 이렇게 하면 로컬 소스 구체화가 샌드박스 매니페스트의 나머지 부분과 동일한 호스트 경로 신뢰 경계 안에 유지됩니다.
-마운트 엔트리는 노출할 스토리지를 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 마운트 옵션과 공급자 지원은 [샌드박스 클라이언트](clients.md#mounts-and-remote-storage)를 참조하세요.
+마운트 항목은 노출할 스토리지를 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 마운트 옵션과 공급자 지원은 [샌드박스 클라이언트](clients.md#mounts-and-remote-storage)를 참조하세요.
-좋은 매니페스트 설계란 보통 워크스페이스 계약을 좁게 유지하고, 긴 작업 레시피를 `repo/task.md` 같은 워크스페이스 파일에 넣고, instructions에서 `repo/task.md` 또는 `output/report.md` 같은 상대 워크스페이스 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` 기능의 `apply_patch` 도구로 파일을 편집하는 경우, 패치 경로는 셸 `workdir`가 아니라 샌드박스 워크스페이스 루트 기준이라는 점을 기억하세요.
+좋은 매니페스트 설계란 일반적으로 작업공간 계약을 좁게 유지하고, 긴 작업 레시피는 `repo/task.md` 같은 작업공간 파일에 넣으며, 지침에서 `repo/task.md` 또는 `output/report.md` 같은 상대 작업공간 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` 기능의 `apply_patch` 도구로 파일을 편집하는 경우, 패치 경로는 셸 `workdir`가 아니라 샌드박스 작업공간 루트를 기준으로 한다는 점을 기억하세요.
-에이전트가 워크스페이스 외부의 구체적인 절대 경로를 필요로 하거나, 매니페스트가 SDK 프로세스 작업 디렉터리 밖의 신뢰할 수 있는 로컬 소스를 복사해야 할 때만 `extra_path_grants`를 사용하세요. 예로는 임시 도구 출력을 위한 `/tmp`, 읽기 전용 런타임을 위한 `/opt/toolchain`, 또는 샌드박스에 구체화되어야 하는 생성된 스킬 디렉터리가 있습니다. grant는 로컬 소스 구체화, SDK 파일 API, 그리고 백엔드가 파일시스템 정책을 적용할 수 있는 경우 셸 실행에 적용됩니다.
+`extra_path_grants`는 에이전트가 작업공간 외부의 구체적인 절대 경로를 필요로 하거나, 매니페스트가 SDK 프로세스 작업 디렉터리 외부의 신뢰할 수 있는 로컬 소스를 복사해야 할 때만 사용하세요. 예로는 임시 도구 출력을 위한 `/tmp`, 읽기 전용 런타임을 위한 `/opt/toolchain`, 또는 샌드박스에 구체화되어야 하는 생성된 스킬 디렉터리가 있습니다. 권한 부여는 로컬 소스 구체화, SDK 파일 API, 그리고 백엔드가 파일시스템 정책을 강제할 수 있는 경우 셸 실행에 적용됩니다.
```python
from agents.sandbox import Manifest, SandboxPathGrant
@@ -261,15 +261,15 @@ manifest = Manifest(
)
```
-`extra_path_grants`가 포함된 매니페스트는 신뢰할 수 있는 구성으로 취급하세요. 애플리케이션이 해당 호스트 경로를 이미 승인하지 않았다면 모델 출력이나 기타 신뢰할 수 없는 페이로드에서 grant를 로드하지 마세요.
+`extra_path_grants`가 포함된 매니페스트는 신뢰할 수 있는 구성으로 취급하세요. 애플리케이션이 해당 호스트 경로를 이미 승인하지 않은 한, 모델 출력이나 기타 신뢰할 수 없는 페이로드에서 권한 부여를 로드하지 마세요.
-스냅샷과 `persist_workspace()`는 여전히 워크스페이스 루트만 포함합니다. 추가로 grant된 경로는 런타임 접근이지, 지속 가능한 워크스페이스 상태가 아닙니다.
+스냅샷과 `persist_workspace()`는 여전히 작업공간 루트만 포함합니다. 추가로 권한이 부여된 경로는 런타임 접근이지, 지속 가능한 작업공간 상태가 아닙니다.
### 권한
-`Permissions`는 매니페스트 엔트리의 파일시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 관한 것이며, 모델 권한, 승인 정책, 또는 API 자격 증명에 관한 것이 아닙니다.
+`Permissions`는 매니페스트 항목의 파일시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 관한 것이며, 모델 권한, 승인 정책, 또는 API 자격 증명에 관한 것이 아닙니다.
-기본적으로 매니페스트 엔트리는 소유자가 읽기/쓰기/실행할 수 있고 그룹과 기타 사용자가 읽기/실행할 수 있습니다. 스테이징된 파일이 비공개, 읽기 전용, 또는 실행 가능해야 할 때 이를 재정의하세요.
+기본적으로 매니페스트 항목은 소유자가 읽기/쓰기/실행 가능하고 그룹과 기타 사용자가 읽기/실행 가능합니다. 스테이징된 파일이 비공개, 읽기 전용, 또는 실행 가능해야 할 때 이를 오버라이드하세요.
```python
from agents.sandbox import FileMode, Permissions
@@ -285,9 +285,9 @@ private_notes = File(
)
```
-`Permissions`는 소유자, 그룹, 기타 비트를 별도로 저장하고, 엔트리가 디렉터리인지 여부도 저장합니다. 직접 만들거나, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나, `Permissions.from_mode(...)`로 OS 모드에서 파생할 수 있습니다.
+`Permissions`는 소유자, 그룹, 기타 비트를 별도로 저장하며, 항목이 디렉터리인지 여부도 저장합니다. 직접 빌드하거나, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나, `Permissions.from_mode(...)`로 OS 모드에서 파생할 수 있습니다.
-사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 샌드박스에 해당 ID가 존재하도록 하려면 매니페스트에 `User`를 추가한 다음, 셸 명령, 파일 읽기, 패치와 같은 모델 대상 샌드박스 도구가 해당 사용자로 실행되어야 할 때 `SandboxAgent.run_as`를 설정하세요. `run_as`가 매니페스트에 아직 없는 사용자를 가리키면 러너가 유효 매니페스트에 이를 추가합니다.
+사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 샌드박스에 해당 ID가 존재하게 하려면 매니페스트에 `User`를 추가한 다음, 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구가 해당 사용자로 실행되어야 할 때 `SandboxAgent.run_as`를 설정하세요. `run_as`가 매니페스트에 아직 없는 사용자를 가리키면, 러너가 이를 실제 매니페스트에 자동으로 추가합니다.
```python
from agents import Runner
@@ -339,13 +339,13 @@ result = await Runner.run(
)
```
-파일 수준 공유 규칙도 필요하다면 사용자를 매니페스트 그룹과 엔트리 `group` 메타데이터와 결합하세요. `run_as` 사용자는 누가 샌드박스 네이티브 작업을 실행하는지를 제어하고, `Permissions`는 샌드박스가 워크스페이스를 구체화한 뒤 해당 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지를 제어합니다.
+파일 수준 공유 규칙도 필요하다면 사용자와 매니페스트 그룹 및 항목 `group` 메타데이터를 결합하세요. `run_as` 사용자는 샌드박스 네이티브 작업을 누가 실행하는지 제어하고, `Permissions`는 샌드박스가 작업공간을 구체화한 후 해당 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지 제어합니다.
### SnapshotSpec
-`SnapshotSpec`은 새 샌드박스 세션이 저장된 워크스페이스 콘텐츠를 어디에서 복원하고 다시 어디에 지속할지 알려줍니다. 이는 샌드박스 워크스페이스에 대한 스냅샷 정책이며, `session_state`는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다.
+`SnapshotSpec`은 저장된 작업공간 콘텐츠를 어디에서 복원하고 다시 어디에 영속화할지 새 샌드박스 세션에 알려줍니다. 이는 샌드박스 작업공간의 스냅샷 정책이며, `session_state`는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다.
-로컬 지속 스냅샷에는 `LocalSnapshotSpec`를 사용하고, 앱이 원격 스냅샷 클라이언트를 제공하는 경우 `RemoteSnapshotSpec`를 사용하세요. 로컬 스냅샷 설정을 사용할 수 없을 때는 no-op 스냅샷이 폴백으로 사용되며, 고급 호출자는 워크스페이스 스냅샷 지속성을 원하지 않을 때 명시적으로 사용할 수 있습니다.
+로컬 지속 스냅샷에는 `LocalSnapshotSpec`를 사용하고, 앱이 원격 스냅샷 클라이언트를 제공할 때는 `RemoteSnapshotSpec`를 사용하세요. 로컬 스냅샷 설정을 사용할 수 없을 때는 대체로 no-op 스냅샷이 사용되며, 고급 호출자는 작업공간 스냅샷 영속성을 원하지 않을 때 이를 명시적으로 사용할 수 있습니다.
```python
from pathlib import Path
@@ -362,13 +362,13 @@ run_config = RunConfig(
)
```
-러너가 새 샌드박스 세션을 만들 때, 샌드박스 클라이언트는 해당 세션에 대한 스냅샷 인스턴스를 빌드합니다. 시작 시 스냅샷을 복원할 수 있으면, 실행이 계속되기 전에 샌드박스가 저장된 워크스페이스 콘텐츠를 복원합니다. 정리 시 러너 소유 샌드박스 세션은 워크스페이스를 보관하고 스냅샷을 통해 다시 지속합니다.
+러너가 새 샌드박스 세션을 생성하면 샌드박스 클라이언트가 해당 세션의 스냅샷 인스턴스를 빌드합니다. 시작 시 스냅샷이 복원 가능하면, 샌드박스는 실행을 계속하기 전에 저장된 작업공간 콘텐츠를 복원합니다. 정리 시 러너가 소유한 샌드박스 세션은 작업공간을 아카이브하고 스냅샷을 통해 다시 영속화합니다.
-`snapshot`을 생략하면 런타임은 가능한 경우 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 이를 설정할 수 없으면 no-op 스냅샷으로 폴백합니다. 마운트된 경로와 임시 경로는 지속 가능한 워크스페이스 콘텐츠로 스냅샷에 복사되지 않습니다.
+`snapshot`을 생략하면 런타임은 가능한 경우 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 설정할 수 없으면 no-op 스냅샷으로 폴백합니다. 마운트된 경로와 임시 경로는 지속 가능한 작업공간 콘텐츠로 스냅샷에 복사되지 않습니다.
-### 샌드박스 라이프사이클
+### 샌드박스 생명주기
-라이프사이클 모드는 **SDK 소유**와 **개발자 소유** 두 가지입니다.
+생명주기 모드는 **SDK 소유**와 **개발자 소유** 두 가지입니다.
@@ -396,7 +396,7 @@ sequenceDiagram
-샌드박스가 한 실행 동안만 살아 있으면 되는 경우 SDK 소유 라이프사이클을 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 러너가 샌드박스를 생성하거나 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 워크스페이스 상태를 지속하고, 샌드박스를 종료하고, 클라이언트가 러너 소유 리소스를 정리하게 합니다.
+샌드박스가 한 번의 실행 동안만 살아 있으면 되는 경우 SDK 소유 생명주기를 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 러너가 샌드박스를 생성하거나 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 작업공간 상태를 영속화하고, 샌드박스를 종료한 다음, 클라이언트가 러너 소유 리소스를 정리하게 합니다.
```python
result = await Runner.run(
@@ -408,7 +408,7 @@ result = await Runner.run(
)
```
-샌드박스를 미리 생성하거나, 여러 실행에서 하나의 실제 샌드박스를 재사용하거나, 실행 후 파일을 검사하거나, 직접 만든 샌드박스에서 스트리밍하거나, 정리 시점을 정확히 결정하고 싶을 때는 개발자 소유 라이프사이클을 사용하세요. `session=...`를 전달하면 러너는 해당 실제 샌드박스를 사용하지만 대신 닫아주지는 않습니다.
+샌드박스를 미리 생성하거나, 여러 실행에서 하나의 살아 있는 샌드박스를 재사용하거나, 실행 후 파일을 검사하거나, 직접 생성한 샌드박스에서 스트리밍하거나, 정리 시점을 정확히 결정하고 싶을 때 개발자 소유 생명주기를 사용하세요. `session=...`을 전달하면 러너가 해당 살아 있는 샌드박스를 사용하지만, 대신 닫아주지는 않습니다.
```python
sandbox = await client.create(manifest=agent.default_manifest)
@@ -419,7 +419,7 @@ async with sandbox:
await Runner.run(agent, "Write the final report.", run_config=run_config)
```
-컨텍스트 매니저가 일반적인 형태입니다. 진입 시 샌드박스를 시작하고, 종료 시 세션 정리 라이프사이클을 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 라이프사이클 메서드를 직접 호출하세요.
+컨텍스트 매니저가 일반적인 형태입니다. 진입 시 샌드박스를 시작하고 종료 시 세션 정리 생명주기를 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 생명주기 메서드를 직접 호출하세요.
```python
sandbox = await client.create(
@@ -440,62 +440,64 @@ finally:
await sandbox.aclose()
```
-`stop()`은 스냅샷 기반 워크스페이스 콘텐츠만 지속합니다. 샌드박스를 해체하지는 않습니다. `aclose()`는 전체 세션 정리 경로입니다. 중지 전 훅을 실행하고, `stop()`을 호출하고, 샌드박스 리소스를 종료하고, 세션 범위 종속성을 닫습니다.
+`stop()`은 스냅샷 기반 작업공간 콘텐츠만 영속화하며, 샌드박스를 해체하지 않습니다. `aclose()`는 전체 세션 정리 경로입니다. pre-stop 훅을 실행하고, `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`를 사용합니다.
### 새 세션 입력
-이 옵션들은 러너가 새 샌드박스 세션을 생성할 때만 의미가 있습니다.
+이 옵션은 러너가 새 샌드박스 세션을 생성할 때만 중요합니다.
| 옵션 | 사용 시점 | 참고 |
| --- | --- | --- |
-| `manifest` | 일회성 새 세션 워크스페이스 오버라이드를 원할 때 | 생략하면 `agent.default_manifest`로 폴백합니다. |
+| `manifest` | 일회성 새 세션 작업공간 오버라이드를 원할 때 | 생략 시 `agent.default_manifest`로 폴백합니다. |
| `snapshot` | 새 샌드박스 세션을 스냅샷에서 시드해야 할 때 | 재개와 유사한 흐름이나 원격 스냅샷 클라이언트에 유용합니다. |
-| `options` | 샌드박스 클라이언트에 생성 시점 옵션이 필요할 때 | Docker 이미지, Modal 앱 이름, E2B 템플릿, 타임아웃 및 유사한 클라이언트별 설정에 흔합니다. |
+| `options` | 샌드박스 클라이언트에 생성 시점 옵션이 필요할 때 | Docker 이미지, Modal 앱 이름, E2B 템플릿, 타임아웃, 유사한 클라이언트별 설정에 일반적입니다. |
### 구체화 제어
-`concurrency_limits`는 병렬로 실행될 수 있는 샌드박스 구체화 작업량을 제어합니다. 대규모 매니페스트나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요할 때 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요.
+`concurrency_limits`는 병렬로 실행될 수 있는 샌드박스 구체화 작업의 양을 제어합니다. 큰 매니페스트나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요할 때 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요.
-몇 가지 함의를 기억할 필요가 있습니다.
+`archive_limits`는 아카이브 추출에 대한 SDK 측 리소스 검사를 제어합니다. SDK 기본 임계값을 활성화하려면 `archive_limits=SandboxArchiveLimits()`를 설정하거나, 아카이브에 더 엄격한 리소스 제어가 필요할 때 `SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)` 같은 명시적 값을 전달하세요. SDK 아카이브 리소스 제한 없이 기본 동작을 유지하려면 `archive_limits=None`으로 두고, 해당 제한만 비활성화하려면 개별 필드를 `None`으로 설정하세요.
+
+유념할 만한 몇 가지 함의는 다음과 같습니다.
- 새 세션: `manifest=`와 `snapshot=`은 러너가 새 샌드박스 세션을 생성할 때만 적용됩니다.
-- 재개와 스냅샷: `session_state=`는 이전에 직렬화한 샌드박스 상태에 다시 연결하고, `snapshot=`은 저장된 워크스페이스 콘텐츠에서 새 샌드박스 세션을 시드합니다.
-- 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 달라집니다. Docker와 많은 호스티드 클라이언트에는 필요합니다.
-- 주입된 실제 세션: 실행 중인 샌드박스 `session`을 전달하면 기능 기반 매니페스트 업데이트가 호환되는 비마운트 엔트리를 추가할 수 있습니다. `manifest.root`, `manifest.environment`, `manifest.users`, 또는 `manifest.groups`를 변경하거나, 기존 엔트리를 제거하거나, 엔트리 유형을 대체하거나, 마운트 엔트리를 추가 또는 변경할 수는 없습니다.
+- 재개와 스냅샷: `session_state=`는 이전에 직렬화된 샌드박스 상태에 재연결하는 반면, `snapshot=`은 저장된 작업공간 콘텐츠에서 새 샌드박스 세션을 시드합니다.
+- 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 달라지며, Docker와 많은 호스티드 클라이언트에는 이것이 필요합니다.
+- 주입된 라이브 세션: 실행 중인 샌드박스 `session`을 전달하면 기능 기반 매니페스트 업데이트가 호환되는 비마운트 항목을 추가할 수 있습니다. `manifest.root`, `manifest.environment`, `manifest.users`, `manifest.groups`를 변경하거나, 기존 항목을 제거하거나, 항목 유형을 교체하거나, 마운트 항목을 추가 또는 변경할 수는 없습니다.
- 러너 API: `SandboxAgent` 실행은 여전히 일반 `Runner.run()`, `Runner.run_sync()`, `Runner.run_streamed()` API를 사용합니다.
-## 전체 예제: 코딩 작업
+## 전체 예시: 코딩 작업
-이 코딩 스타일 예제는 좋은 기본 시작점입니다.
+이 코딩 스타일 예시는 좋은 기본 시작점입니다.
```python
import asyncio
@@ -574,17 +576,17 @@ 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를 사용하고, 공급자 관리 실행을 원할 때 호스티드 공급자를 사용하세요. 예시와 공급자 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요.
-### 워크스페이스 재정의
+### 작업공간 오버라이드
에이전트 정의는 그대로 두고 새 세션 매니페스트만 교체하세요.
@@ -606,11 +608,11 @@ run_config = RunConfig(
)
```
-동일한 에이전트 역할을 서로 다른 리포지토리, 패킷, 또는 작업 번들에 대해 실행해야 하지만 에이전트를 다시 빌드하고 싶지 않을 때 사용하세요. 위의 검증된 코딩 예제는 일회성 오버라이드 대신 `default_manifest`를 사용해 같은 패턴을 보여줍니다.
+에이전트를 다시 빌드하지 않고 동일한 에이전트 역할을 다른 리포지토리, 패킷, 또는 작업 번들에 대해 실행해야 할 때 사용하세요. 위의 검증된 코딩 예시는 일회성 오버라이드 대신 `default_manifest`로 동일한 패턴을 보여줍니다.
### 샌드박스 세션 주입
-명시적 라이프사이클 제어, 실행 후 검사, 또는 출력 복사가 필요할 때 실제 샌드박스 세션을 주입하세요.
+명시적 생명주기 제어, 실행 후 검사, 또는 출력 복사가 필요할 때 살아 있는 샌드박스 세션을 주입하세요.
```python
from agents import Runner
@@ -631,11 +633,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
@@ -652,11 +654,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
@@ -673,7 +675,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에서 스킬 로드
@@ -688,11 +690,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)를 참조하세요.
### 도구로 노출
-도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고 부모 실행의 실제 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색기 에이전트에 유용합니다. 다른 샌드박스를 생성, 하이드레이션, 스냅샷하는 비용 없이 부모가 사용하는 정확한 워크스페이스를 검사할 수 있습니다.
+도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고 상위 실행의 살아 있는 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색 에이전트에 유용합니다. 다른 샌드박스를 생성, 하이드레이션, 스냅샷하는 비용 없이 부모가 사용하는 정확한 작업공간을 검사할 수 있습니다.
```python
from agents import Runner
@@ -774,7 +776,7 @@ async with sandbox:
)
```
-여기서 부모 에이전트는 `coordinator`로 실행되고, 탐색기 도구 에이전트는 같은 실제 샌드박스 세션 안에서 `explorer`로 실행됩니다. `pricing_packet/` 엔트리는 `other` 사용자에게 읽기 가능하므로 탐색기가 빠르게 검사할 수 있지만, 쓰기 비트는 없습니다. `work/` 디렉터리는 coordinator의 사용자/그룹에만 사용 가능하므로, 부모는 최종 아티팩트를 작성하는 동안 탐색기는 읽기 전용으로 유지됩니다.
+여기서 부모 에이전트는 `coordinator`로 실행되고, 탐색기 도구 에이전트는 동일한 살아 있는 샌드박스 세션 안에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색기는 이를 빠르게 검사할 수 있지만 쓰기 비트는 없습니다. `work/` 디렉터리는 coordinator의 사용자/그룹에만 제공되므로, 탐색기는 읽기 전용으로 유지되는 동안 부모는 최종 산출물을 쓸 수 있습니다.
도구 에이전트에 실제 격리가 필요하다면 자체 샌드박스 `RunConfig`를 제공하세요.
@@ -797,11 +799,11 @@ rollout_agent.as_tool(
)
```
-도구 에이전트가 자유롭게 변경하거나, 신뢰할 수 없는 명령을 실행하거나, 다른 백엔드/이미지를 사용해야 할 때 별도 샌드박스를 사용하세요. [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와 결합
-동일한 에이전트에서 일반 도구를 계속 사용하면서 샌드박스 워크스페이스를 유지하세요.
+동일한 에이전트에서 일반 도구를 사용하면서 샌드박스 작업공간을 유지하세요.
```python
from agents.sandbox import SandboxAgent
@@ -816,46 +818,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` 기능을 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와 별개입니다. 교훈을 샌드박스 워크스페이스 내부 파일로 추출한 다음, 이후 실행이 해당 파일을 읽을 수 있습니다.
+이후 샌드박스 에이전트 실행이 이전 실행에서 학습해야 할 때 `Memory` 기능을 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와 별개입니다. 교훈을 샌드박스 작업공간 내부의 파일로 정제하고, 이후 실행이 해당 파일을 읽을 수 있게 합니다.
-설정, 읽기/생성 동작, 다중 턴 대화, 레이아웃 격리는 [에이전트 메모리](memory.md)를 참조하세요.
+설정, 읽기/생성 동작, 멀티턴 대화, 레이아웃 격리는 [에이전트 메모리](memory.md)를 참조하세요.
## 구성 패턴
-단일 에이전트 패턴이 명확해지면, 다음 설계 질문은 더 큰 시스템에서 샌드박스 경계를 어디에 둘 것인지입니다.
+단일 에이전트 패턴이 명확해지면, 다음 설계 질문은 더 큰 시스템에서 샌드박스 경계를 어디에 둘 것인가입니다.
샌드박스 에이전트는 여전히 SDK의 나머지 부분과 구성할 수 있습니다.
-- [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 도구와 공존할 수 있습니다.
+- [핸드오프](../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를 사용합니다.
특히 흔한 두 가지 패턴은 다음과 같습니다.
-- 워크스페이스 격리가 필요한 워크플로 부분에 대해서만 비샌드박스 에이전트가 샌드박스 에이전트로 핸드오프
-- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출하며, 일반적으로 각 도구가 자체 격리된 워크스페이스를 갖도록 각 `Agent.as_tool(...)` 호출마다 별도의 샌드박스 `RunConfig`를 사용
+- 작업공간 격리가 필요한 워크플로 부분에만 비샌드박스 에이전트가 샌드박스 에이전트로 핸드오프
+- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출하며, 일반적으로 각 `Agent.as_tool(...)` 호출마다 별도의 샌드박스 `RunConfig`를 사용해 각 도구가 자체 격리 작업공간을 갖게 함
### 턴과 샌드박스 실행
-핸드오프와 에이전트-as-tool 호출은 별도로 설명하는 것이 도움이 됩니다.
+핸드오프와 agent-as-tool 호출은 별도로 설명하는 것이 도움이 됩니다.
-핸드오프에서는 여전히 하나의 최상위 실행과 하나의 최상위 턴 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 비샌드박스 접수 에이전트가 샌드박스 검토자에게 핸드오프하면, 같은 실행의 다음 모델 호출은 샌드박스 에이전트에 맞게 준비되고, 해당 샌드박스 에이전트가 다음 턴을 수행하는 주체가 됩니다. 즉, 핸드오프는 같은 실행의 다음 턴을 소유하는 에이전트를 바꿉니다. [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)를 참조하세요.
+핸드오프에서는 여전히 하나의 최상위 실행과 하나의 최상위 턴 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 비샌드박스 접수 에이전트가 샌드박스 리뷰어에게 핸드오프하면, 같은 실행에서 다음 모델 호출이 샌드박스 에이전트용으로 준비되고, 해당 샌드박스 에이전트가 다음 턴을 수행하는 에이전트가 됩니다. 즉, 핸드오프는 같은 실행의 다음 턴을 소유하는 에이전트를 변경합니다. [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(...)`에서는 관계가 다릅니다. 외부 오케스트레이터는 도구를 호출하기로 결정하는 데 외부 턴 하나를 사용하고, 해당 도구 호출은 샌드박스 에이전트의 중첩 실행을 시작합니다. 중첩 실행은 자체 턴 루프, `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(...)`에서는 샌드박스 도구 에이전트 내부에서 발생한 승인도 외부 실행에 표시되지만, 저장된 중첩 실행 상태에서 오며 외부 실행이 재개될 때 중첩 샌드박스 실행을 재개합니다.
+- 핸드오프에서는 샌드박스 에이전트가 이제 해당 실행의 활성 에이전트이므로 승인이 같은 최상위 실행에 유지됩니다.
+- `Agent.as_tool(...)`에서는 샌드박스 도구 에이전트 내부에서 발생한 승인도 외부 실행에 나타나지만, 저장된 중첩 실행 상태에서 오며 외부 실행이 재개될 때 중첩 샌드박스 실행을 재개합니다.
## 추가 자료
-- [빠른 시작](quickstart.md): 하나의 샌드박스 에이전트를 실행합니다.
+- [빠른 시작](quickstart.md): 샌드박스 에이전트 하나를 실행합니다.
- [샌드박스 클라이언트](clients.md): 로컬, Docker, 호스티드, 마운트 옵션을 선택합니다.
-- [에이전트 메모리](memory.md): 이전 샌드박스 실행에서 얻은 교훈을 보존하고 재사용합니다.
+- [에이전트 메모리](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/guide.md b/docs/zh/sandbox/guide.md
index 4e7c88f45d..5526856af4 100644
--- a/docs/zh/sandbox/guide.md
+++ b/docs/zh/sandbox/guide.md
@@ -6,35 +6,35 @@ search:
!!! warning "Beta 功能"
- 沙盒智能体处于 beta 阶段。在正式可用之前，API、默认值和受支持功能的细节可能会发生变化，并且未来会逐步提供更高级的功能。
+ 沙盒智能体目前处于 Beta 阶段。在正式可用之前，API 细节、默认值和受支持能力可能会发生变化，并且后续会提供更高级的功能。
-现代智能体在能够操作文件系统中的真实文件时效果最佳。**沙盒智能体**可以使用专用工具和 shell 命令来搜索和处理大型文档集、编辑文件、生成产物并运行命令。沙盒为模型提供一个持久化工作区，智能体可以用它代表你完成工作。Agents SDK 中的沙盒智能体帮助你轻松运行与沙盒环境配对的智能体，便于将正确的文件放到文件系统中，并编排沙盒以便大规模启动、停止和恢复任务。
+现代智能体在能够操作文件系统中的真实文件时效果最佳。**沙盒智能体**可以使用专用工具和 shell 命令来搜索和操作大型文档集、编辑文件、生成产物以及运行命令。沙盒会为模型提供一个持久工作区，智能体可以在其中代表你执行工作。Agents SDK 中的沙盒智能体可帮助你轻松运行与沙盒环境配对的智能体，便于将正确的文件放到文件系统中，并编排沙盒，从而更容易大规模启动、停止和恢复任务。
你可以围绕智能体所需的数据来定义工作区。它可以从 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` 定义智能体本身：常规智能体配置，以及 `default_manifest`、`base_instructions`、`run_as` 等沙盒特定默认值，还有文件系统工具、shell 访问、skills、memory 或 compaction 等能力。
-- `Manifest` 声明全新沙盒工作区所需的起始内容和布局，包括文件、仓库、挂载和环境。
-- 沙盒会话是命令运行和文件发生变化的实时隔离环境。
+- `SandboxAgent` 定义智能体本身：常规智能体配置，加上沙盒专用默认值，如 `default_manifest`、`base_instructions`、`run_as`，以及文件系统工具、shell 访问、技能、记忆或压缩等能力。
+- `Manifest` 声明全新沙盒工作区所需的初始内容和布局，包括文件、仓库、挂载和环境。
+- 沙盒会话是运行命令并发生文件变化的实时隔离环境。
- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 决定本次运行如何获得该沙盒会话，例如直接注入一个会话、从序列化的沙盒会话状态重新连接，或通过沙盒客户端创建一个全新的沙盒会话。
-- 保存的沙盒状态和快照让后续运行能够重新连接到先前的工作，或从已保存内容为全新沙盒会话播种。
+- 已保存的沙盒状态和快照可让后续运行重新连接到先前的工作，或从已保存内容为新的沙盒会话提供种子。
`Manifest` 是全新会话的工作区契约，而不是每个实时沙盒的完整事实来源。一次运行的有效工作区也可能来自复用的沙盒会话、序列化的沙盒会话状态，或运行时选择的快照。
在本页中，“沙盒会话”指由沙盒客户端管理的实时执行环境。它不同于 [Sessions](../sessions/index.md) 中描述的 SDK 对话式 [`Session`][agents.memory.session.Session] 接口。
-外层运行时仍然拥有审批、追踪、任务转移和恢复记账。沙盒会话拥有命令、文件变更和环境隔离。这种分离是该模型的核心部分。
+外层运行时仍负责审批、追踪、任务转移和恢复簿记。沙盒会话负责命令、文件变更和环境隔离。这种分离是该模型的核心部分。
-### 组件配合
+### 各部分的配合方式
-一次沙盒运行会将智能体定义与每次运行的沙盒配置结合起来。runner 会准备智能体，将其绑定到实时沙盒会话，并可保存状态以供后续运行使用。
+一次沙盒运行会将智能体定义与每次运行的沙盒配置结合起来。runner 会准备智能体，将其绑定到一个实时沙盒会话，并可保存状态以供后续运行使用。
```mermaid
flowchart LR
@@ -50,59 +50,59 @@ flowchart LR
sandbox --> saved
```
-沙盒特定默认值保留在 `SandboxAgent` 上。每次运行的沙盒会话选择保留在 `SandboxRunConfig` 中。
+沙盒专用默认值保留在 `SandboxAgent` 上。每次运行的沙盒会话选择保留在 `SandboxRunConfig` 中。
-可以将生命周期分为三个阶段：
+可以将生命周期看作三个阶段：
-1. 使用 `SandboxAgent`、`Manifest` 和能力定义智能体以及全新工作区契约。
-2. 通过向 `Runner` 提供一个会注入、恢复或创建沙盒会话的 `SandboxRunConfig` 来执行运行。
-3. 稍后从 runner 管理的 `RunState`、显式沙盒 `session_state`，或已保存的工作区快照继续。
+1. 使用 `SandboxAgent`、`Manifest` 和能力来定义智能体以及全新工作区契约。
+2. 通过向 `Runner` 提供会注入、恢复或创建沙盒会话的 `SandboxRunConfig` 来执行一次运行。
+3. 后续从 runner 管理的 `RunState`、显式沙盒 `session_state` 或已保存的工作区快照继续。
-如果 shell 访问只是偶尔使用的一个工具，请从[工具指南](../tools.md)中的托管 shell 开始。当工作区隔离、沙盒客户端选择或沙盒会话恢复行为是设计的一部分时，再使用沙盒智能体。
+如果 shell 访问只是偶尔使用的一个工具，请从 [工具指南](../tools.md) 中的托管 shell 开始。当工作区隔离、沙盒客户端选择或沙盒会话恢复行为属于设计的一部分时，再使用沙盒智能体。
## 使用场景
沙盒智能体非常适合以工作区为中心的工作流，例如：
-- 编码和调试，例如在 GitHub 仓库中为 issue 报告编排自动修复并运行有针对性的测试
-- 文档处理和编辑，例如从用户的财务文档中提取信息并创建已填写的税表草稿
-- 基于文件的审查或分析，例如在回答前检查入职资料包、生成的报告或产物包
-- 隔离的多智能体模式，例如为每个审查者或编码子智能体提供自己的工作区
-- 多步骤工作区任务，例如在一次运行中修复 bug，并稍后添加回归测试，或从快照或沙盒会话状态恢复
+- 编码和调试，例如为 GitHub 仓库中的问题报告编排自动修复并运行定向测试
+- 文档处理和编辑，例如从用户的财务文档中提取信息并创建填写完成的税表草稿
+- 基于文件的审阅或分析，例如在回答前检查入职材料包、生成的报告或产物包
+- 隔离的多智能体模式，例如为每个审阅者或编码子智能体提供自己的工作区
+- 多步骤工作区任务，例如在一次运行中修复 bug，稍后添加回归测试，或从快照或沙盒会话状态恢复
如果你不需要访问文件或实时文件系统，请继续使用 `Agent`。如果 shell 访问只是偶尔需要的一项能力，请添加托管 shell；如果工作区边界本身就是功能的一部分，请使用沙盒智能体。
## 沙盒客户端选择
-本地开发从 `UnixLocalSandboxClient` 开始。当需要容器隔离或镜像一致性时，切换到 `DockerSandboxClient`。当需要由提供商管理的执行环境时，切换到托管提供商。
+本地开发请从 `UnixLocalSandboxClient` 开始。当你需要容器隔离或镜像一致性时，切换到 `DockerSandboxClient`。当你需要由提供商管理的执行环境时，切换到托管提供商。
-在大多数情况下，`SandboxAgent` 定义保持不变，而沙盒客户端及其选项会在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中变化。有关本地、Docker、托管和远程挂载选项，请参阅[沙盒客户端](clients.md)。
+在大多数情况下，`SandboxAgent` 定义保持不变，而沙盒客户端及其选项会在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中变化。有关本地、Docker、托管和远程挂载选项，请参阅 [沙盒客户端](clients.md)。
## 核心组成
-| 层 | 主要 SDK 组件 | 回答的问题 |
+| 层级 | 主要 SDK 组件 | 回答的问题 |
| --- | --- | --- |
-| 智能体定义 | `SandboxAgent`、`Manifest`、能力 | 将运行什么智能体，它应该从什么全新会话工作区契约开始？ |
+| 智能体定义 | `SandboxAgent`、`Manifest`、能力 | 将运行哪个智能体，以及它应从什么全新会话工作区契约开始？ |
| 沙盒执行 | `SandboxRunConfig`、沙盒客户端和实时沙盒会话 | 本次运行如何获得实时沙盒会话，工作在哪里执行？ |
-| 已保存沙盒状态 | `RunState` 沙盒载荷、`session_state` 和快照 | 此工作流如何重新连接到先前的沙盒工作，或从已保存内容为全新沙盒会话播种？ |
+| 已保存沙盒状态 | `RunState` 沙盒载荷、`session_state` 和快照 | 该工作流如何重新连接到先前的沙盒工作，或从已保存内容为全新沙盒会话提供种子？ |
-主要 SDK 组件与这些层的映射如下：
+主要 SDK 组件与这些层级的对应关系如下：
-| 组件 | 拥有内容 | 要问的问题 |
+| 组件 | 拥有的内容 | 应提出的问题 |
| --- | --- | --- |
-| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 智能体定义 | 这个智能体应该做什么，哪些默认值应该随它一起携带？ |
-| [`Manifest`][agents.sandbox.manifest.Manifest] | 全新会话工作区文件和文件夹 | 运行开始时，文件系统中应存在什么文件和文件夹？ |
+| [`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] | runner 管理的已保存沙盒状态 | 我是否正在恢复先前由 runner 管理的工作流，并自动向前携带其沙盒状态？ |
-| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 显式序列化的沙盒会话状态 | 我是否想从已在 `RunState` 之外序列化的沙盒状态恢复？ |
-| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 用于全新沙盒会话的已保存工作区内容 | 新沙盒会话是否应从已保存文件和产物开始？ |
+| [`RunState`][agents.run_state.RunState] | Runner 管理的已保存沙盒状态 | 我是否正在恢复先前由 runner 管理的工作流，并自动继续携带其沙盒状态？ |
+| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 显式序列化的沙盒会话状态 | 我是否想从已在 `RunState` 外部序列化的沙盒状态恢复？ |
+| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 用于全新沙盒会话的已保存工作区内容 | 新的沙盒会话是否应从已保存文件和产物开始？ |
@@ -111,123 +111,123 @@ flowchart LR
1. 使用 `Manifest` 定义全新会话工作区契约。
2. 使用 `SandboxAgent` 定义智能体。
3. 添加内置或自定义能力。
-4. 在 `RunConfig(sandbox=SandboxRunConfig(...))` 中决定每次运行应如何获取其沙盒会话。
+4. 在 `RunConfig(sandbox=SandboxRunConfig(...))` 中决定每次运行应如何获得其沙盒会话。
-## 沙盒运行的准备过程
+## 沙盒运行的准备方式
-在运行时，runner 会将该定义转换为一个具体的沙盒支持运行：
+运行时，runner 会将该定义转换为具体的沙盒支持运行：
1. 它从 `SandboxRunConfig` 解析沙盒会话。
- 如果传入 `session=...`，它会复用该实时沙盒会话。
- 否则，它会使用 `client=...` 创建或恢复一个会话。
+ 如果你传入 `session=...`，它会复用该实时沙盒会话。
+ 否则，它使用 `client=...` 创建或恢复一个会话。
2. 它确定本次运行的有效工作区输入。
如果运行注入或恢复沙盒会话，则该现有沙盒状态优先。
- 否则，runner 会从一次性 manifest 覆盖或 `agent.default_manifest` 开始。
- 这就是为什么仅靠 `Manifest` 并不能为每次运行定义最终实时工作区。
+ 否则，runner 会从一次性的 manifest 覆盖或 `agent.default_manifest` 开始。
+ 这就是为什么单独的 `Manifest` 并不能定义每次运行最终的实时工作区。
3. 它让能力处理生成的 manifest。
- 通过这种方式，能力可以在最终智能体准备好之前添加文件、挂载或其他工作区范围的行为。
+ 能力可以通过这种方式在最终智能体准备完成之前添加文件、挂载或其他工作区范围的行为。
4. 它按固定顺序构建最终 instructions：
- SDK 默认沙盒提示词，或在你显式覆盖时使用 `base_instructions`，然后是 `instructions`，然后是能力指令片段，然后是任何远程挂载策略文本，最后是渲染后的文件系统树。
+ SDK 的默认沙盒提示词，或你显式覆盖时的 `base_instructions`，然后是 `instructions`，然后是能力指令片段，然后是任何远程挂载策略文本，最后是渲染后的文件系统树。
5. 它将能力工具绑定到实时沙盒会话，并通过常规 `Runner` API 运行准备好的智能体。
-沙盒化不会改变一个轮次的含义。一个轮次仍然是一次模型步骤，而不是单个 shell 命令或沙盒操作。沙盒侧操作与轮次之间不存在固定的 1:1 映射：有些工作可能留在沙盒执行层内部，而其他操作会返回工具结果、审批或其他需要另一个模型步骤的状态。作为实用规则，只有当智能体运行时在沙盒工作发生后需要另一个模型响应时，才会消耗另一个轮次。
+沙盒化不会改变一个 turn 的含义。一个 turn 仍然是一个模型步骤，而不是单个 shell 命令或沙盒操作。沙盒侧操作与 turn 之间没有固定的 1:1 映射：有些工作可能停留在沙盒执行层内部，而其他操作会返回工具结果、审批或其他需要另一个模型步骤的状态。作为实用规则，只有当智能体运行时在沙盒工作发生后需要另一个模型响应时，才会消耗另一个 turn。
-这些准备步骤说明了为什么在设计 `SandboxAgent` 时，`default_manifest`、`instructions`、`base_instructions`、`capabilities` 和 `run_as` 是需要重点考虑的主要沙盒特定选项。
+这些准备步骤说明了为什么在设计 `SandboxAgent` 时，`default_manifest`、`instructions`、`base_instructions`、`capabilities` 和 `run_as` 是需要重点考虑的主要沙盒专用选项。
## `SandboxAgent` 选项
-这些是在常规 `Agent` 字段之上的沙盒特定选项：
+这些是在常规 `Agent` 字段之上的沙盒专用选项：
| 选项 | 最佳用途 |
| --- | --- |
| `default_manifest` | runner 创建的全新沙盒会话的默认工作区。 |
-| `instructions` | 追加到 SDK 沙盒提示词之后的额外角色、工作流和成功标准。 |
-| `base_instructions` | 替换 SDK 沙盒提示词的高级逃生口。 |
-| `capabilities` | 应随该智能体一起携带的沙盒原生工具和行为。 |
+| `instructions` | 附加在 SDK 沙盒提示词之后的额外角色、工作流和成功标准。 |
+| `base_instructions` | 替换 SDK 沙盒提示词的高级逃生舱。 |
+| `capabilities` | 应随该智能体一起传递的沙盒原生工具和行为。 |
| `run_as` | 面向模型的沙盒工具（如 shell 命令、文件读取和补丁）的用户身份。 |
-沙盒客户端选择、沙盒会话复用、manifest 覆盖和快照选择应放在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中，而不是放在智能体上。
+沙盒客户端选择、沙盒会话复用、manifest 覆盖和快照选择应属于 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]，而不是智能体。
### `default_manifest`
-`default_manifest` 是 runner 为此智能体创建全新沙盒会话时使用的默认 [`Manifest`][agents.sandbox.manifest.Manifest]。将其用于智能体通常应以之开始的文件、仓库、辅助材料、输出目录和挂载。
+`default_manifest` 是 runner 为该智能体创建全新沙盒会话时使用的默认 [`Manifest`][agents.sandbox.manifest.Manifest]。可将它用于智能体通常应从中开始的文件、仓库、辅助材料、输出目录和挂载。
-这只是默认值。一次运行可以用 `SandboxRunConfig(manifest=...)` 覆盖它，而复用或恢复的沙盒会话会保留其现有工作区状态。
+这只是默认值。一次运行可以通过 `SandboxRunConfig(manifest=...)` 覆盖它，而复用或恢复的沙盒会话会保留其现有工作区状态。
### `instructions` 和 `base_instructions`
-使用 `instructions` 编写应在不同提示词下仍然保留的简短规则。在 `SandboxAgent` 中，这些 instructions 会追加到 SDK 的沙盒基础提示词之后，因此你可以保留内置沙盒指导，并添加自己的角色、工作流和成功标准。
+将 `instructions` 用于应在不同提示词之间保留的简短规则。在 `SandboxAgent` 中，这些 instructions 会附加在 SDK 的沙盒基础提示词之后，因此你会保留内置沙盒指导，并添加自己的角色、工作流和成功标准。
-仅当你想替换 SDK 沙盒基础提示词时才使用 `base_instructions`。大多数智能体不应设置它。
+仅在你想替换 SDK 沙盒基础提示词时使用 `base_instructions`。大多数智能体不应设置它。
-| 放入... | 用途 | 示例 |
+| 放在... | 用途 | 示例 |
| --- | --- | --- |
-| `instructions` | 智能体的稳定角色、工作流规则和成功标准。 | “检查入职文档，然后任务转移。”，“将最终文件写入 `output/`。” |
-| `base_instructions` | SDK 沙盒基础提示词的完整替换。 | 自定义低层级沙盒包装提示词。 |
+| `instructions` | 智能体的稳定角色、工作流规则和成功标准。 | “检查入职文档，然后进行任务转移。”、“将最终文件写入 `output/`。” |
+| `base_instructions` | SDK 沙盒基础提示词的完整替换。 | 自定义底层沙盒包装提示词。 |
| 用户提示词 | 本次运行的一次性请求。 | “总结这个工作区。” |
-| manifest 中的工作区文件 | 更长的任务规范、仓库本地指令或有界参考资料。 | `repo/task.md`、文档包、示例资料包。 |
+| manifest 中的工作区文件 | 更长的任务规范、仓库本地指令或有界参考材料。 | `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`。它们可以在运行开始前塑造工作区、追加沙盒专用指令、暴露绑定到实时沙盒会话的工具，并调整该智能体的模型行为或输入处理。
内置能力包括：
-| 能力 | 添加时机 | 备注 |
+| 能力 | 何时添加 | 备注 |
| --- | --- | --- |
-| `Shell` | 智能体需要 shell 访问。 | 添加 `exec_command`，并在沙盒客户端支持 PTY 交互时添加 `write_stdin`。 |
+| `Shell` | 智能体需要 shell 访问。 | 添加 `exec_command`，当沙盒客户端支持 PTY 交互时还会添加 `write_stdin`。 |
| `Filesystem` | 智能体需要编辑文件或检查本地图像。 | 添加 `apply_patch` 和 `view_image`；补丁路径相对于工作区根目录。 |
-| `Skills` | 你想要在沙盒中进行 skill 发现和物化。 | 优先使用它，而不是手动挂载 `.agents` 或 `.agents/skills`；`Skills` 会为你将 skills 编入索引并物化到沙盒中。 |
-| `Memory` | 后续运行应读取或生成 memory 产物。 | 需要 `Shell`；实时更新还需要 `Filesystem`。 |
-| `Compaction` | 长时间运行的流程需要在 compaction 项之后修剪上下文。 | 调整模型采样和输入处理。 |
+| `Skills` | 你想在沙盒中进行技能发现和物化。 | 优先使用它，而不是手动挂载 `.agents` 或 `.agents/skills`；`Skills` 会为你将技能索引并物化到沙盒中。 |
+| `Memory` | 后续运行应读取或生成记忆产物。 | 需要 `Shell`；实时更新还需要 `Filesystem`。 |
+| `Compaction` | 长时间运行的流程需要在压缩项之后裁剪上下文。 | 调整模型采样和输入处理。 |
-默认情况下，`SandboxAgent.capabilities` 使用 `Capabilities.default()`，其中包括 `Filesystem()`、`Shell()` 和 `Compaction()`。如果传入 `capabilities=[...]`，该列表会替换默认值，因此请包含你仍想要的任何默认能力。
+默认情况下，`SandboxAgent.capabilities` 使用 `Capabilities.default()`，其中包括 `Filesystem()`、`Shell()` 和 `Compaction()`。如果你传入 `capabilities=[...]`，该列表会替换默认值，因此请包含你仍想保留的任何默认能力。
-对于 skills，请根据你希望它们如何物化来选择来源：
+对于技能，请根据你希望它们如何物化来选择来源：
-- `Skills(lazy_from=LocalDirLazySkillSource(...))` 是较大本地 skill 目录的良好默认选择，因为模型可以先发现索引，并且只加载所需内容。
-- `LocalDirLazySkillSource(source=LocalDir(src=...))` 从 SDK 进程运行所在的文件系统读取。请传入原始主机侧 skills 目录，而不是仅存在于沙盒镜像或工作区内部的路径。
-- `Skills(from_=LocalDir(src=...))` 更适合你希望预先暂存的小型本地包。
-- `Skills(from_=GitRepo(repo=..., ref=...))` 适合 skills 本身应来自仓库的情况。
+- `Skills(lazy_from=LocalDirLazySkillSource(...))` 是较大本地技能目录的良好默认值，因为模型可以先发现索引，并只加载所需内容。
+- `LocalDirLazySkillSource(source=LocalDir(src=...))` 从运行 SDK 进程的文件系统读取。请传入原始主机侧技能目录，而不是仅存在于沙盒镜像或工作区内的路径。
+- `Skills(from_=LocalDir(src=...))` 更适合你想预先暂存的小型本地包。
+- `Skills(from_=GitRepo(repo=..., ref=...))` 适合技能本身应来自某个仓库的情况。
-`LocalDir.src` 是 SDK 主机上的源路径。`skills_path` 是沙盒工作区内的相对目标路径，在调用 `load_skill` 时 skills 会被暂存在那里。
+`LocalDir.src` 是 SDK 主机上的源路径。`skills_path` 是沙盒工作区内的相对目标路径，在调用 `load_skill` 时技能会被暂存到那里。
-如果你的 skills 已经位于磁盘上的类似 `.agents/skills//SKILL.md` 路径下，请将 `LocalDir(...)` 指向该源根目录，并仍使用 `Skills(...)` 来暴露它们。除非你有依赖不同沙盒内布局的现有工作区契约，否则保留默认 `skills_path=".agents"`。
+如果你的技能已经以类似 `.agents/skills//SKILL.md` 的结构存在于磁盘上，请将 `LocalDir(...)` 指向该源根目录，并仍使用 `Skills(...)` 暴露它们。除非你已有依赖不同沙盒内布局的工作区契约，否则请保留默认的 `skills_path=".agents"`。
-当内置能力适用时，优先使用它们。只有在需要内置能力未覆盖的沙盒特定工具或指令表面时，才编写自定义能力。
+在适用时优先使用内置能力。仅当你需要内置能力未覆盖的沙盒专用工具或指令界面时，才编写自定义能力。
## 概念
### Manifest
-[`Manifest`][agents.sandbox.manifest.Manifest] 描述全新沙盒会话的工作区。它可以设置工作区 `root`，声明文件和目录，复制本地文件，克隆 Git 仓库，附加远程存储挂载，设置环境变量，定义用户或组，并授权访问工作区之外的特定绝对路径。
+[`Manifest`][agents.sandbox.manifest.Manifest] 描述全新沙盒会话的工作区。它可以设置工作区 `root`，声明文件和目录，复制本地文件，克隆 Git 仓库，附加远程存储挂载，设置环境变量，定义用户或组，并授予对工作区外特定绝对路径的访问权限。
-Manifest 条目路径是相对于工作区的。它们不能是绝对路径，也不能用 `..` 逃逸工作区，这使工作区契约能够在本地、Docker 和托管客户端之间保持可移植。
+Manifest 条目路径是相对于工作区的。它们不能是绝对路径，也不能使用 `..` 逃逸工作区，这使工作区契约可在本地、Docker 和托管客户端之间移植。
-使用 manifest 条目放置智能体在开始工作前所需的材料：
+将 manifest 条目用于智能体在工作开始前所需的材料：
@@ -235,20 +235,20 @@ Manifest 条目路径是相对于工作区的。它们不能是绝对路径，
| --- | --- |
| `File`、`Dir` | 小型合成输入、辅助文件或输出目录。 |
| `LocalFile`、`LocalDir` | 应物化到沙盒中的主机文件或目录。 |
-| `GitRepo` | 应获取到工作区中的仓库。 |
-| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` 等挂载 | 应在沙盒中出现的外部存储。 |
+| `GitRepo` | 应拉取到工作区中的仓库。 |
+| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` 等挂载 | 应显示在沙盒内的外部存储。 |
-`Dir` 会从合成子项或作为输出位置在沙盒工作区内创建目录；它不会从主机文件系统读取。现有主机目录应复制到沙盒工作区时，请使用 `LocalDir`。
+`Dir` 会从合成子项创建沙盒工作区内的目录，或作为输出位置；它不会从主机文件系统读取。当已有主机目录应复制到沙盒工作区时，请使用 `LocalDir`。
-默认情况下，`LocalFile.src` 和 `LocalDir.src` 会相对于 SDK 进程工作目录解析。源必须保留在该基础目录之下，除非它被 `extra_path_grants` 覆盖。这会使本地源物化保持在与沙盒 manifest 其余部分相同的主机路径信任边界内。
+`LocalFile.src` 和 `LocalDir.src` 默认相对于 SDK 进程工作目录解析。源必须保持在该基础目录之下，除非它由 `extra_path_grants` 覆盖。这使本地源物化保持在与沙盒 manifest 其余部分相同的主机路径信任边界内。
-挂载条目描述要暴露什么存储；挂载策略描述沙盒后端如何附加该存储。有关挂载选项和提供商支持，请参阅[沙盒客户端](clients.md#mounts-and-remote-storage)。
+挂载条目描述要暴露哪些存储；挂载策略描述沙盒后端如何附加该存储。有关挂载选项和提供商支持，请参阅 [沙盒客户端](clients.md#mounts-and-remote-storage)。
-良好的 manifest 设计通常意味着保持工作区契约狭窄，将较长任务配方放入 `repo/task.md` 等工作区文件，并在 instructions 中使用相对工作区路径，例如 `repo/task.md` 或 `output/report.md`。如果智能体使用 `Filesystem` 能力的 `apply_patch` 工具编辑文件，请记住补丁路径相对于沙盒工作区根目录，而不是 shell 的 `workdir`。
+良好的 manifest 设计通常意味着保持工作区契约狭窄，将长任务配方放入工作区文件（如 `repo/task.md`），并在 instructions 中使用相对工作区路径，例如 `repo/task.md` 或 `output/report.md`。如果智能体使用 `Filesystem` 能力的 `apply_patch` 工具编辑文件，请记住补丁路径相对于沙盒工作区根目录，而不是 shell 的 `workdir`。
-仅当智能体需要工作区之外的具体绝对路径，或 manifest 需要复制 SDK 进程工作目录之外的受信任本地源时，才使用 `extra_path_grants`。示例包括用于临时工具输出的 `/tmp`、用于只读运行时的 `/opt/toolchain`，或应物化到沙盒中的已生成 skills 目录。grant 适用于本地源物化、SDK 文件 API，以及后端可执行文件系统策略时的 shell 执行：
+仅在智能体需要工作区外的具体绝对路径，或 manifest 需要复制 SDK 进程工作目录外的受信任本地源时，才使用 `extra_path_grants`。示例包括用于临时工具输出的 `/tmp`、用于只读运行时的 `/opt/toolchain`，或应物化到沙盒中的已生成技能目录。授权适用于本地源物化、SDK 文件 API，以及后端能够强制执行文件系统策略时的 shell 执行：
```python
from agents.sandbox import Manifest, SandboxPathGrant
@@ -261,15 +261,15 @@ manifest = Manifest(
)
```
-将包含 `extra_path_grants` 的 manifests 视为受信任配置。不要从模型输出或其他不受信任载荷中加载 grants，除非你的应用已经批准了这些主机路径。
+将包含 `extra_path_grants` 的 manifest 视为受信任配置。不要从模型输出或其他不受信任载荷中加载授权，除非你的应用已经批准这些主机路径。
-快照和 `persist_workspace()` 仍然只包含工作区根目录。额外授予的路径是运行时访问权限，而不是持久工作区状态。
+快照和 `persist_workspace()` 仍只包含工作区根目录。额外授权路径是运行时访问，不是持久工作区状态。
### 权限
-`Permissions` 控制 manifest 条目的文件系统权限。它关注沙盒物化的文件，而不是模型权限、审批策略或 API 凭证。
+`Permissions` 控制 manifest 条目的文件系统权限。它关注的是沙盒物化的文件，而不是模型权限、审批策略或 API 凭证。
-默认情况下，manifest 条目对所有者可读/可写/可执行，并对组和其他用户可读/可执行。当暂存文件应为私有、只读或可执行时，请覆盖此设置：
+默认情况下，manifest 条目可由所有者读取/写入/执行，并可由组和其他用户读取/执行。当暂存文件应为私有、只读或可执行时，请覆盖此设置：
```python
from agents.sandbox import FileMode, Permissions
@@ -285,9 +285,9 @@ private_notes = File(
)
```
-`Permissions` 存储独立的 owner、group 和 other 位，以及该条目是否为目录。你可以直接构建它，用 `Permissions.from_str(...)` 从模式字符串解析它，或用 `Permissions.from_mode(...)` 从 OS 模式派生它。
+`Permissions` 存储单独的所有者、组和其他用户位，以及该条目是否为目录。你可以直接构建它，使用 `Permissions.from_str(...)` 从模式字符串解析它，或使用 `Permissions.from_mode(...)` 从 OS 模式派生它。
-用户是可以执行工作的沙盒身份。当你希望该身份存在于沙盒中时，请向 manifest 添加一个 `User`；然后当面向模型的沙盒工具（如 shell 命令、文件读取和补丁）应以该用户运行时，设置 `SandboxAgent.run_as`。如果 `run_as` 指向一个尚未在 manifest 中的用户，runner 会为你将其添加到有效 manifest 中。
+用户是可以执行工作的沙盒身份。当你希望该身份存在于沙盒中时，请将 `User` 添加到 manifest，然后在面向模型的沙盒工具（如 shell 命令、文件读取和补丁）应以该用户运行时设置 `SandboxAgent.run_as`。如果 `run_as` 指向的用户尚不在 manifest 中，runner 会为你将其添加到有效 manifest 中。
```python
from agents import Runner
@@ -339,13 +339,13 @@ result = await Runner.run(
)
```
-如果还需要文件级共享规则，请将用户与 manifest 组和条目 `group` 元数据结合使用。`run_as` 用户控制谁执行沙盒原生动作；`Permissions` 控制沙盒物化工作区后，该用户可以读取、写入或执行哪些文件。
+如果还需要文件级共享规则，请将用户与 manifest 组和条目 `group` 元数据结合使用。`run_as` 用户控制谁执行沙盒原生操作；`Permissions` 控制沙盒物化工作区后，该用户可以读取、写入或执行哪些文件。
### SnapshotSpec
-`SnapshotSpec` 告诉全新沙盒会话应从哪里恢复已保存的工作区内容，并将其持久化回哪里。它是沙盒工作区的快照策略，而 `session_state` 是用于恢复特定沙盒后端的序列化连接状态。
+`SnapshotSpec` 告诉全新沙盒会话应从哪里恢复已保存工作区内容，以及应将其持久化回哪里。它是沙盒工作区的快照策略，而 `session_state` 是用于恢复特定沙盒后端的序列化连接状态。
-使用 `LocalSnapshotSpec` 保存本地持久快照；当你的应用提供远程快照客户端时使用 `RemoteSnapshotSpec`。当本地快照设置不可用时，会使用 no-op 快照作为回退；高级调用方在不希望持久化工作区快照时，也可以显式使用它。
+将 `LocalSnapshotSpec` 用于本地持久快照；当你的应用提供远程快照客户端时，使用 `RemoteSnapshotSpec`。当本地快照设置不可用时，会使用 no-op 快照作为回退；当高级调用方不想进行工作区快照持久化时，也可以显式使用它。
```python
from pathlib import Path
@@ -362,13 +362,13 @@ run_config = RunConfig(
)
```
-当 runner 创建全新沙盒会话时，沙盒客户端会为该会话构建一个快照实例。启动时，如果快照可恢复，沙盒会在运行继续前恢复已保存的工作区内容。清理时，runner 拥有的沙盒会话会归档工作区，并通过快照将其持久化回去。
+当 runner 创建全新沙盒会话时，沙盒客户端会为该会话构建一个快照实例。启动时，如果快照可恢复，沙盒会先恢复已保存的工作区内容，然后运行继续。清理时，runner 拥有的沙盒会话会归档工作区，并通过快照将其持久化回去。
-如果省略 `snapshot`，运行时会在可行时尝试使用默认本地快照位置。如果无法设置，它会回退到 no-op 快照。挂载路径和临时路径不会作为持久工作区内容复制到快照中。
+如果省略 `snapshot`，运行时会在可行时尝试使用默认本地快照位置。如果无法设置，则回退到 no-op 快照。挂载路径和临时路径不会作为持久工作区内容复制到快照中。
### 沙盒生命周期
-有两种生命周期模式：**SDK 拥有**和**开发者拥有**。
+有两种生命周期模式：**SDK 拥有** 和 **开发者拥有**。
@@ -396,7 +396,7 @@ sequenceDiagram
-当沙盒只需存在于一次运行期间时，使用 SDK 拥有的生命周期。传入 `client`、可选的 `manifest`、可选的 `snapshot` 和客户端 `options`；runner 会创建或恢复沙盒、启动它、运行智能体、持久化快照支持的工作区状态、关闭沙盒，并让客户端清理 runner 拥有的资源。
+当沙盒只需为一次运行存活时，请使用 SDK 拥有的生命周期。传入 `client`、可选 `manifest`、可选 `snapshot` 和客户端 `options`；runner 会创建或恢复沙盒、启动它、运行智能体、持久化由快照支持的工作区状态、关闭沙盒，并让客户端清理 runner 拥有的资源。
```python
result = await Runner.run(
@@ -408,7 +408,7 @@ result = await Runner.run(
)
```
-当你想提前创建沙盒、跨多次运行复用一个实时沙盒、在运行后检查文件、在自己创建的沙盒上流式处理，或精确决定何时清理时，使用开发者拥有的生命周期。传入 `session=...` 会告诉 runner 使用该实时沙盒，但不会替你关闭它。
+当你想提前创建沙盒、在多次运行中复用一个实时沙盒、在运行后检查文件、对你自己创建的沙盒进行流式传输，或精确决定何时清理时，请使用开发者拥有的生命周期。传入 `session=...` 会告诉 runner 使用该实时沙盒，但不会替你关闭它。
```python
sandbox = await client.create(manifest=agent.default_manifest)
@@ -419,7 +419,7 @@ async with sandbox:
await Runner.run(agent, "Write the final report.", run_config=run_config)
```
-上下文管理器是通常的形式：进入时启动沙盒，退出时运行会话清理生命周期。如果你的应用无法使用上下文管理器，请直接调用生命周期方法：
+上下文管理器是常见形式：进入时启动沙盒，退出时运行会话清理生命周期。如果你的应用无法使用上下文管理器，请直接调用生命周期方法：
```python
sandbox = await client.create(
@@ -440,11 +440,11 @@ finally:
await sandbox.aclose()
```
-`stop()` 只会持久化快照支持的工作区内容；它不会拆除沙盒。`aclose()` 是完整的会话清理路径：它会运行 pre-stop hooks、调用 `stop()`、关闭沙盒资源，并关闭会话范围的依赖项。
+`stop()` 只会持久化由快照支持的工作区内容；它不会拆除沙盒。`aclose()` 是完整的会话清理路径：它运行停止前 hooks，调用 `stop()`，关闭沙盒资源，并关闭会话范围的依赖项。
## `SandboxRunConfig` 选项
-[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 保存每次运行的选项，用于决定沙盒会话来自哪里，以及全新会话应如何初始化。
+[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 保存每次运行的选项，这些选项决定沙盒会话来自哪里，以及如何初始化全新会话。
### 沙盒来源
@@ -454,48 +454,50 @@ finally:
| 选项 | 使用时机 | 备注 |
| --- | --- | --- |
-| `client` | 你希望 runner 为你创建、恢复和清理沙盒会话。 | 除非提供实时沙盒 `session`，否则必需。 |
-| `session` | 你已经自行创建了实时沙盒会话。 | 调用方拥有生命周期；runner 复用该实时沙盒会话。 |
-| `session_state` | 你有序列化的沙盒会话状态，但没有实时沙盒会话对象。 | 需要 `client`；runner 会从该显式状态恢复为拥有型会话。 |
+| `client` | 你希望 runner 为你创建、恢复并清理沙盒会话。 | 除非你提供实时沙盒 `session`，否则必需。 |
+| `session` | 你已经自己创建了实时沙盒会话。 | 调用方拥有生命周期；runner 复用该实时沙盒会话。 |
+| `session_state` | 你有序列化的沙盒会话状态，但没有实时沙盒会话对象。 | 需要 `client`；runner 从该显式状态恢复为拥有型会话。 |
-实践中，runner 按以下顺序解析沙盒会话：
+实践中，runner 会按以下顺序解析沙盒会话：
-1. 如果注入 `run_config.sandbox.session`，则直接复用该实时沙盒会话。
+1. 如果你注入 `run_config.sandbox.session`，该实时沙盒会话会被直接复用。
2. 否则，如果运行正在从 `RunState` 恢复，则恢复已存储的沙盒会话状态。
-3. 否则，如果传入 `run_config.sandbox.session_state`，runner 会从该显式序列化沙盒会话状态恢复。
-4. 否则，runner 会创建全新的沙盒会话。对于该全新会话，它会在提供时使用 `run_config.sandbox.manifest`，否则使用 `agent.default_manifest`。
+3. 否则，如果你传入 `run_config.sandbox.session_state`，runner 会从该显式序列化沙盒会话状态恢复。
+4. 否则，runner 会创建一个全新的沙盒会话。对于该全新会话，如果提供了 `run_config.sandbox.manifest`，则使用它；否则使用 `agent.default_manifest`。
### 全新会话输入
-这些选项仅在 runner 创建全新沙盒会话时有意义：
+这些选项只在 runner 创建全新沙盒会话时生效：
| 选项 | 使用时机 | 备注 |
| --- | --- | --- |
-| `manifest` | 你想要一次性覆盖全新会话工作区。 | 省略时回退到 `agent.default_manifest`。 |
-| `snapshot` | 全新沙盒会话应从快照播种。 | 对类似恢复的流程或远程快照客户端很有用。 |
-| `options` | 沙盒客户端需要创建时选项。 | 常见于 Docker 镜像、Modal 应用名称、E2B 模板、超时和类似客户端特定设置。 |
+| `manifest` | 你想要一次性的全新会话工作区覆盖。 | 省略时回退到 `agent.default_manifest`。 |
+| `snapshot` | 全新沙盒会话应从快照提供种子。 | 对类似恢复的流程或远程快照客户端很有用。 |
+| `options` | 沙盒客户端需要创建时选项。 | 常见于 Docker 镜像、Modal 应用名称、E2B 模板、超时和类似的客户端专用设置。 |
### 物化控制
-`concurrency_limits` 控制可并行运行的沙盒物化工作量。当大型 manifests 或本地目录复制需要更严格的资源控制时，请使用 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`。将任一值设置为 `None` 可禁用该特定限制。
+`concurrency_limits` 控制可并行运行的沙盒物化工作量。当大型 manifest 或本地目录复制需要更严格资源控制时，请使用 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`。将任一值设为 `None` 可禁用对应限制。
-有几点影响值得注意：
+`archive_limits` 控制 SDK 侧归档解压资源检查。设置 `archive_limits=SandboxArchiveLimits()` 可启用 SDK 默认阈值；当归档需要更严格资源控制时，可传入显式值，如 `SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)`。保留 `archive_limits=None` 会保持无 SDK 归档资源限制的默认行为；或将单个字段设为 `None` 以仅禁用该限制。
+
+有几个影响值得注意：
- 全新会话：`manifest=` 和 `snapshot=` 仅在 runner 创建全新沙盒会话时适用。
-- 恢复 vs 快照：`session_state=` 重新连接到先前序列化的沙盒状态，而 `snapshot=` 从已保存的工作区内容为新沙盒会话播种。
-- 客户端特定选项：`options=` 取决于沙盒客户端；Docker 和许多托管客户端都需要它。
-- 注入的实时会话：如果传入正在运行的沙盒 `session`，能力驱动的 manifest 更新可以添加兼容的非挂载条目。它们不能更改 `manifest.root`、`manifest.environment`、`manifest.users` 或 `manifest.groups`；不能删除现有条目；不能替换条目类型；也不能添加或更改挂载条目。
-- Runner 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`；不能移除现有条目；不能替换条目类型；也不能添加或更改挂载条目。
+- Runner API：`SandboxAgent` 执行仍使用常规 `Runner.run()`、`Runner.run_sync()` 和 `Runner.run_streamed()` API。
## 完整示例：编码任务
-这个编码风格示例是一个良好的默认起点：
+这个编码风格示例是一个很好的默认起点：
```python
import asyncio
@@ -574,15 +576,15 @@ 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` 可以保持不变，只更改沙盒客户端、沙盒会话来源或工作区来源。
+从上面的完整示例开始。在许多情况下，同一个 `SandboxAgent` 可以保持不变，只改变沙盒客户端、沙盒会话来源或工作区来源。
### 切换沙盒客户端
-保持智能体定义不变，只更改运行配置。当需要容器隔离或镜像一致性时使用 Docker；当需要提供商管理的执行环境时使用托管提供商。有关示例和提供商选项，请参阅[沙盒客户端](clients.md)。
+保持智能体定义不变，只更改运行配置。当你需要容器隔离或镜像一致性时使用 Docker；当你需要由提供商管理的执行环境时使用托管提供商。示例和提供商选项请参阅 [沙盒客户端](clients.md)。
### 覆盖工作区
@@ -606,7 +608,7 @@ run_config = RunConfig(
)
```
-当同一个智能体角色应针对不同仓库、资料包或任务包运行，而无需重建智能体时，使用此模式。上面的已验证编码示例展示了相同模式，只是使用 `default_manifest` 而不是一次性覆盖。
+当同一智能体角色需要针对不同仓库、材料包或任务包运行，而无需重新构建智能体时，请使用此模式。上面经过验证的编码示例展示了相同模式，只是使用 `default_manifest` 而不是一次性覆盖。
### 注入沙盒会话
@@ -631,11 +633,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` 之外序列化了沙盒状态，请让 runner 从该状态重新连接：
+如果你已经在 `RunState` 外部序列化了沙盒状态，可让 runner 从该状态重新连接：
```python
from agents.run import RunConfig
@@ -652,11 +654,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
@@ -673,11 +675,11 @@ 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 加载 skills
+### 从 Git 加载技能
-将本地 skill 来源替换为仓库支持的来源：
+将本地技能来源替换为由仓库支持的来源：
```python
from agents.sandbox.capabilities import Capabilities, Skills
@@ -688,11 +690,11 @@ capabilities = Capabilities.default() + [
]
```
-当 skills 包有自己的发布节奏，或应在多个沙盒之间共享时，使用此模式。参见 [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)。
### 暴露为工具
-工具智能体既可以获得自己的沙盒边界，也可以复用父运行中的实时沙盒。复用对于快速只读探索智能体很有用：它可以检查父智能体正在使用的确切工作区，而无需为创建、补水或快照另一个沙盒付出成本。
+工具智能体可以拥有自己的沙盒边界，也可以复用父运行中的实时沙盒。复用对于快速只读探索者智能体很有用：它可以检查父级正在使用的确切工作区，而无需付出创建、水合或快照另一个沙盒的成本。
```python
from agents import Runner
@@ -774,7 +776,7 @@ async with sandbox:
)
```
-这里，父智能体以 `coordinator` 运行，explorer 工具智能体在同一个实时沙盒会话中以 `explorer` 运行。`pricing_packet/` 条目对 `other` 用户可读，因此 explorer 可以快速检查它们，但它没有写入位。`work/` 目录仅对 coordinator 的用户/组可用，因此父智能体可以写入最终产物，而 explorer 保持只读。
+这里父智能体以 `coordinator` 身份运行，探索者工具智能体在同一个实时沙盒会话中以 `explorer` 身份运行。`pricing_packet/` 条目可由 `other` 用户读取，因此探索者可以快速检查它们，但它没有写入位。`work/` 目录仅对协调者的用户/组可用，因此父级可以写入最终产物，而探索者保持只读。
当工具智能体需要真正隔离时，请为它提供自己的沙盒 `RunConfig`：
@@ -797,11 +799,11 @@ rollout_agent.as_tool(
)
```
-当工具智能体应自由变更内容、运行不受信任命令，或使用不同后端/镜像时，请使用单独沙盒。参见 [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 结合
-在保留沙盒工作区的同时，仍然在同一个智能体上使用普通工具：
+保留沙盒工作区，同时仍在同一个智能体上使用普通工具：
```python
from agents.sandbox import SandboxAgent
@@ -816,46 +818,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
+## 记忆
-当未来沙盒智能体运行应从先前运行中学习时，请使用 `Memory` 能力。Memory 独立于 SDK 的对话式 `Session` memory：它会将经验提炼为沙盒工作区内的文件，后续运行便可读取这些文件。
+当未来的沙盒智能体运行应从先前运行中学习时，请使用 `Memory` 能力。记忆与 SDK 的对话式 `Session` 记忆是分开的：它会将经验提炼为沙盒工作区内的文件，然后后续运行可以读取这些文件。
-有关设置、读取/生成行为、多轮对话和布局隔离，请参阅 [Agent memory](memory.md)。
+有关设置、读取/生成行为、多轮对话和布局隔离，请参阅 [智能体记忆](memory.md)。
## 组合模式
-一旦单智能体模式清晰，下一步设计问题就是在更大的系统中沙盒边界应位于哪里。
+当单智能体模式清晰后，下一个设计问题是在更大系统中沙盒边界应位于哪里。
-沙盒智能体仍然可以与 SDK 的其余部分组合：
+沙盒智能体仍可与 SDK 的其余部分组合：
-- [任务转移](../handoffs.md)：将大量文档工作从非沙盒接收智能体移交给沙盒审查者。
-- [Agents as tools](../tools.md#agents-as-tools)：将多个沙盒智能体暴露为工具，通常是在每次 `Agent.as_tool(...)` 调用时传入 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`，以便每个工具获得自己的沙盒边界。
-- [MCP](../mcp.md) 和普通工具调用：沙盒能力可以与 `mcp_servers` 和普通 Python 工具共存。
+- [任务转移](../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。
两种模式尤其常见：
- 非沙盒智能体仅在工作流中需要工作区隔离的部分任务转移给沙盒智能体
-- 编排器将多个沙盒智能体暴露为工具，通常为每个 `Agent.as_tool(...)` 调用提供单独的沙盒 `RunConfig`，以便每个工具拥有自己的隔离工作区
+- 编排器将多个沙盒智能体暴露为工具，通常为每个 `Agent.as_tool(...)` 调用配置单独的沙盒 `RunConfig`，以便每个工具拥有自己的隔离工作区
-### 轮次和沙盒运行
+### Turn 和沙盒运行
-分别解释任务转移和 agent-as-tool 调用会更有帮助。
+分别解释任务转移和 agent-as-tool 调用会更容易理解。
-对于任务转移，仍然只有一个顶层运行和一个顶层轮次循环。活跃智能体会改变，但运行不会变成嵌套。如果非沙盒接收智能体任务转移给沙盒审查者，那么同一次运行中的下一次模型调用会为沙盒智能体准备，该沙盒智能体会成为接下一个轮次的智能体。换句话说，任务转移会改变同一次运行中由哪个智能体拥有下一轮次。参见 [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(...)`，关系不同。外层编排器使用一个外层轮次来决定调用工具，而该工具调用会为沙盒智能体启动一个嵌套运行。嵌套运行有自己的轮次循环、`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 中完成，也可能需要多个。从外层编排器的角度看，所有这些工作仍位于一次工具调用之后，因此嵌套 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(...)`，沙盒工具智能体内部引发的审批仍会浮现在外层运行中，但它们来自已存储的嵌套运行状态，并在外层运行恢复时恢复嵌套沙盒运行
+- 使用任务转移时，审批留在同一个顶层运行中，因为沙盒智能体现在是该运行中的活动智能体
+- 使用 `Agent.as_tool(...)` 时，在沙盒工具智能体内部引发的审批仍会浮现在外层运行上，但它们来自已存储的嵌套运行状态，并在外层运行恢复时恢复嵌套沙盒运行
## 延伸阅读
- [快速入门](quickstart.md)：运行一个沙盒智能体。
- [沙盒客户端](clients.md)：选择本地、Docker、托管和挂载选项。
-- [Agent memory](memory.md)：保留并复用先前沙盒运行中的经验。
-- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)：可运行的本地、编码、memory、任务转移和智能体组合模式。
\ No newline at end of file
+- [智能体记忆](memory.md)：保留并复用先前沙盒运行中的经验。
+- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)：可运行的本地、编码、记忆、任务转移和智能体组合模式。
\ No newline at end of file