From 2faf34a140e865ea339dd5d3b4afbacdf716a69b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 22 Apr 2026 01:34:48 +0000 Subject: [PATCH] Update all translated document pages --- docs/ja/sandbox/guide.md | 356 +++++++++++++++++----------------- docs/ja/sandbox_agents.md | 34 ++-- docs/ko/sandbox/guide.md | 350 +++++++++++++++++----------------- docs/ko/sandbox_agents.md | 38 ++-- docs/zh/sandbox/guide.md | 388 +++++++++++++++++++------------------- docs/zh/sandbox_agents.md | 36 ++-- 6 files changed, 610 insertions(+), 592 deletions(-) diff --git a/docs/ja/sandbox/guide.md b/docs/ja/sandbox/guide.md index ff49b22b60..9e71e5218e 100644 --- a/docs/ja/sandbox/guide.md +++ b/docs/ja/sandbox/guide.md @@ -6,35 +6,35 @@ search: !!! warning "ベータ機能" - Sandbox Agents はベータ版です。一般提供までに API の詳細、デフォルト値、サポートされる機能は変更される可能性があり、また今後より高度な機能が追加されていく予定です。 + SandboxAgent はベータ版です。一般提供までに API 、デフォルト、対応機能の詳細は変更される可能性があり、時間とともにより高度な機能が追加される見込みです。 -現代のエージェントは、ファイルシステム上の実際のファイルを操作できるときに最も効果を発揮します。**Sandbox Agents** は、専用ツールやシェルコマンドを利用して、大規模なドキュメント集合の検索や操作、ファイル編集、成果物の生成、コマンド実行を行えます。サンドボックスは、モデルに永続的なワークスペースを提供し、エージェントがユーザーに代わって作業できるようにします。Agents SDK の Sandbox Agents は、サンドボックス環境と組み合わせたエージェントを簡単に実行できるようにし、ファイルシステム上に適切なファイルを配置しやすくするとともに、サンドボックスの開始、停止、再開を大規模に容易にするためのエージェントオーケストレーションを支援します。 +現代のエージェントは、ファイルシステム上の実ファイルを扱えるときに最も効果的に動作します。 **Sandbox Agents** は、特化したツールやシェルコマンドを利用して、大規模なドキュメント集合の検索や操作、ファイル編集、成果物の生成、コマンド実行を行えます。サンドボックスは、モデルに永続的なワークスペースを提供し、エージェントがユーザーに代わって作業できるようにします。Agents SDK の Sandbox Agents は、サンドボックス環境と組み合わせたエージェントの実行を容易にし、ファイルシステム上に適切なファイルを配置しやすくするとともに、サンドボックスの開始、停止、再開を大規模に簡単にオーケストレーションできるようにします。 -ワークスペースは、エージェントが必要とするデータを中心に定義します。GitHub リポジトリ、ローカルのファイルやディレクトリ、合成タスクファイル、S3 や Azure Blob Storage などのリモートファイルシステム、およびユーザーが提供するその他のサンドボックス入力から開始できます。 +ワークスペースは、エージェントが必要とするデータを中心に定義します。GitHub リポジトリ、ローカルファイルやディレクトリ、合成タスクファイル、 S3 や Azure Blob Storage などのリモートファイルシステム、その他ユーザーが提供するサンドボックス入力から開始できます。
-![計算機能付き Sandbox agent harness](../assets/images/harness_with_compute.png) +![Sandbox agent harness with compute](../assets/images/harness_with_compute.png)
-`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` のようなサンドボックス固有のデフォルトや、ファイルシステムツール、シェルアクセス、スキル、メモリ、コンパクションといった機能を含みます。 +- `SandboxAgent` はエージェント自体を定義します。通常のエージェント設定に加え、`default_manifest` 、 `base_instructions` 、 `run_as` などのサンドボックス固有のデフォルトや、ファイルシステムツール、シェルアクセス、スキル、メモリ、コンパクションなどの機能を含みます。 - `Manifest` は、新しいサンドボックスワークスペースの望ましい初期内容とレイアウトを宣言します。これには、ファイル、リポジトリ、マウント、環境が含まれます。 -- サンドボックスセッションは、コマンドが実行され、ファイルが変更される、隔離されたライブ環境です。 -- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、その実行がどのようにサンドボックスセッションを取得するかを決定します。たとえば、直接注入する、シリアライズ済みのサンドボックスセッション状態から再接続する、またはサンドボックスクライアント経由で新しいサンドボックスセッションを作成する、といった方法です。 -- 保存済みサンドボックス状態とスナップショットにより、後続の実行で以前の作業に再接続したり、保存済み内容から新しいサンドボックスセッションを初期化したりできます。 +- サンドボックスセッションは、コマンドが実行されファイルが変更される、稼働中の分離環境です。 +- [`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,43 +50,43 @@ flowchart LR sandbox --> saved ``` -サンドボックス固有のデフォルトは `SandboxAgent` に保持されます。実行ごとのサンドボックスセッション選択は `SandboxRunConfig` に保持されます。 +サンドボックス固有のデフォルトは `SandboxAgent` に残ります。実行ごとのサンドボックスセッション選択は `SandboxRunConfig` に残ります。 -ライフサイクルは 3 つの段階で考えるとよいでしょう。 +ライフサイクルは 3 つのフェーズで考えるとよいです。 -1. `SandboxAgent`、`Manifest`、および各種機能によって、エージェントと新規ワークスペース契約を定義します。 -2. サンドボックスセッションを注入、再開、または作成する `SandboxRunConfig` を `Runner` に渡して実行します。 -3. ランナーが管理する `RunState`、明示的なサンドボックス `session_state`、または保存済みワークスペーススナップショットから後で継続します。 +1. `SandboxAgent` 、 `Manifest` 、機能を使って、エージェントと新規ワークスペース契約を定義します。 +2. `SandboxRunConfig` を `Runner` に渡して、サンドボックスセッションを注入、再開、または作成して実行します。 +3. ランナー管理の `RunState` 、明示的なサンドボックス `session_state` 、または保存済みワークスペーススナップショットから後で続行します。 -シェルアクセスが単なる補助的なツールの 1 つにすぎないなら、まずは [tools guide](../tools.md) の hosted shell を使ってください。ワークスペース分離、サンドボックスクライアントの選択、またはサンドボックスセッションの再開挙動が設計の一部である場合に、sandbox agents を使います。 +シェルアクセスが単なる補助的なツールの 1 つにすぎない場合は、まず [tools guide](../tools.md) のホスト型シェルから始めてください。ワークスペース分離、サンドボックスクライアントの選択、またはサンドボックスセッションの再開動作が設計の一部である場合に、サンドボックスエージェントを使ってください。 ## 利用場面 -sandbox agents は、ワークスペース中心のワークフローに適しています。たとえば次のようなものです。 +サンドボックスエージェントは、たとえば次のようなワークスペース中心のワークフローに適しています。 -- コーディングとデバッグ。たとえば GitHub リポジトリ内の issue レポートに対する自動修正をエージェントオーケストレーションし、対象を絞ったテストを実行する -- ドキュメント処理と編集。たとえばユーザーの財務書類から情報を抽出し、記入済みの納税フォーム草案を作成する -- ファイルに基づくレビューや分析。たとえば回答前に onboarding packet、生成されたレポート、または成果物バンドルを確認する -- 分離されたマルチエージェントパターン。たとえば各レビュアーやコーディング用サブエージェントに専用ワークスペースを与える -- 複数段階のワークスペースタスク。たとえばある実行でバグを修正し、後で回帰テストを追加する、あるいはスナップショットやサンドボックスセッション状態から再開する +- コーディングとデバッグ。たとえば、 GitHub リポジトリの issue レポートに対する自動修正をエージェントオーケストレーションし、対象を絞ったテストを実行する場合 +- ドキュメント処理と編集。たとえば、ユーザーの財務書類から情報を抽出し、記入済みの税務フォーム下書きを作成する場合 +- ファイルに基づくレビューや分析。たとえば、オンボーディングパケット、生成レポート、成果物バンドルを確認してから回答する場合 +- 分離されたマルチエージェントパターン。たとえば、各レビュアーやコーディング用サブエージェントにそれぞれ専用ワークスペースを与える場合 +- 複数ステップのワークスペースタスク。たとえば、ある実行でバグを修正し、後で回帰テストを追加する場合、またはスナップショットやサンドボックスセッション状態から再開する場合 -ファイルや生きたファイルシステムへのアクセスが不要であれば、引き続き `Agent` を使用してください。シェルアクセスが単に時々必要な機能であれば hosted shell を追加し、ワークスペース境界そのものが機能の一部であれば sandbox agents を使用します。 +ファイルや生きたファイルシステムへのアクセスが不要であれば、引き続き `Agent` を使用してください。シェルアクセスが単発的な機能にすぎないならホスト型シェルを追加し、ワークスペース境界自体が機能の一部ならサンドボックスエージェントを使用してください。 ## サンドボックスクライアントの選択 -ローカル開発では `UnixLocalSandboxClient` から始めてください。コンテナ分離やイメージの同一性が必要になったら `DockerSandboxClient` に移行します。プロバイダー管理の実行が必要なら hosted provider に移行してください。 +ローカル開発では `UnixLocalSandboxClient` から始めてください。コンテナ分離やイメージの同一性が必要になったら `DockerSandboxClient` に移行します。プロバイダー管理の実行が必要ならホスト型プロバイダーに移行します。 -多くの場合、`SandboxAgent` の定義はそのままで、サンドボックスクライアントとそのオプションだけが [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] で変わります。ローカル、 Docker 、 hosted 、リモートマウントのオプションについては [Sandbox clients](clients.md) を参照してください。 +多くの場合、`SandboxAgent` の定義自体は変わらず、[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 内のサンドボックスクライアントとそのオプションだけが変わります。ローカル、 Docker 、ホスト型、リモートマウントの各選択肢については [Sandbox clients](clients.md) を参照してください。 -## コア要素 +## 中核要素
-| レイヤー | 主な SDK 要素 | 何に答えるか | +| レイヤー | 主な SDK 要素 | 答える内容 | | --- | --- | --- | -| エージェント定義 | `SandboxAgent`、`Manifest`、各種機能 | どのエージェントが動作し、どのような新規セッションワークスペース契約から開始すべきですか。 | -| サンドボックス実行 | `SandboxRunConfig`、サンドボックスクライアント、ライブサンドボックスセッション | この実行はどのようにライブサンドボックスセッションを取得し、作業はどこで実行されますか。 | -| 保存済みサンドボックス状態 | `RunState` のサンドボックスペイロード、`session_state`、スナップショット | このワークフローは以前のサンドボックス作業にどう再接続するか、または保存済み内容から新しいサンドボックスセッションをどう初期化するか。 | +| エージェント定義 | `SandboxAgent` 、 `Manifest` 、機能 | どのエージェントが実行されるべきか、またどのような新規セッション用ワークスペース契約から開始すべきか。 | +| サンドボックス実行 | `SandboxRunConfig` 、サンドボックスクライアント、稼働中のサンドボックスセッション | この実行はどのように稼働中のサンドボックスセッションを取得し、作業はどこで実行されるのか。 | +| 保存済みサンドボックス状態 | `RunState` のサンドボックスペイロード、 `session_state` 、スナップショット | このワークフローはどのように以前のサンドボックス作業に再接続するか、または保存済み内容から新しいサンドボックスセッションを初期化するか。 |
@@ -94,154 +94,157 @@ sandbox agents は、ワークスペース中心のワークフローに適し
-| 要素 | 管理対象 | この質問をする | +| 要素 | 管理対象 | 確認すべき質問 | | --- | --- | --- | -| [`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] | 新しいサンドボックスセッション用の保存済みワークスペース内容 | 新しいサンドボックスセッションを保存済みファイルや成果物から開始すべきですか。 | +| [`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(...))` でサンドボックスセッションを取得するかを決めます。 +3. 組み込みまたはカスタム機能を追加します。 +4. `RunConfig(sandbox=SandboxRunConfig(...))` で、各実行がどのようにサンドボックスセッションを取得するか決めます。 ## サンドボックス実行の準備方法 -実行時に、ランナーはその定義を具体的なサンドボックス対応実行へ変換します。 +実行時には、ランナーがその定義を具体的なサンドボックス対応実行に変換します。 -1. `SandboxRunConfig` からサンドボックスセッションを解決します。 - `session=...` を渡した場合、そのライブサンドボックスセッションを再利用します。 - そうでない場合は `client=...` を使用して作成または再開します。 -2. 実行の実効ワークスペース入力を決定します。 - 実行がサンドボックスセッションを注入または再開する場合、その既存のサンドボックス状態が優先されます。 - そうでない場合、ランナーは 1 回限りの manifest オーバーライドまたは `agent.default_manifest` から開始します。 - そのため、`Manifest` だけでは各実行の最終的なライブワークスペースは定義されません。 -3. 各種機能が結果の manifest を処理できるようにします。 - これにより、各種機能は最終的なエージェント準備前に、ファイル、マウント、またはその他のワークスペース範囲の挙動を追加できます。 -4. 最終的な instructions を固定順序で構築します。 - SDK のデフォルトサンドボックスプロンプト、または明示的に上書きした場合は `base_instructions`、その後に `instructions`、さらに機能による命令断片、次にリモートマウントポリシーのテキスト、最後にレンダリングされたファイルシステムツリーです。 -5. 機能ツールをライブサンドボックスセッションに結び付け、準備済みエージェントを通常の `Runner` API で実行します。 +1. `SandboxRunConfig` からサンドボックスセッションを解決します。 + `session=...` を渡した場合は、その稼働中サンドボックスセッションを再利用します。 + それ以外の場合は `client=...` を使って作成または再開します。 +2. 実行に対する実効ワークスペース入力を決定します。 + 実行がサンドボックスセッションを注入または再開する場合、その既存のサンドボックス状態が優先されます。 + そうでなければ、ランナーは一時的な manifest 上書きまたは `agent.default_manifest` から開始します。 + これが、`Manifest` 単体ではすべての実行における最終的な稼働中ワークスペースを定義しない理由です。 +3. 機能に対して、結果の manifest を処理させます。 + これにより、最終的なエージェント準備の前に、機能がファイル、マウント、その他ワークスペーススコープの挙動を追加できます。 +4. 最終的な指示を固定順序で構築します。 + SDK のデフォルトサンドボックスプロンプト、または明示的に上書きした場合は `base_instructions` 、その後に `instructions` 、機能による指示断片、リモートマウントポリシー文言、最後にレンダリングされたファイルシステムツリーです。 +5. 機能ツールを稼働中サンドボックスセッションにバインドし、準備済みエージェントを通常の `Runner` API で実行します。 -サンドボックス化によってターンの意味は変わりません。ターンは依然としてモデルの 1 ステップであり、単一のシェルコマンドやサンドボックス操作ではありません。サンドボックス側の操作とターンの間に固定の 1:1 対応はありません。一部の作業はサンドボックス実行レイヤー内に留まり、別のアクションではツール結果、承認、またはその他の状態が返ってきて、別のモデルステップが必要になることがあります。実務上のルールとしては、サンドボックス作業の後にエージェントランタイムが別のモデル応答を必要とする場合にのみ、次のターンが消費されます。 +サンドボックス化は 1 ターンの意味を変えません。ターンは依然としてモデルの 1 ステップであり、単一のシェルコマンドやサンドボックス操作ではありません。サンドボックス側の操作とターンの間に固定の 1 対 1 対応はありません。作業の一部はサンドボックス実行レイヤー内に留まり、他の操作はツール結果、承認、または別のモデルステップを必要とする状態を返すことがあります。実務上の目安としては、サンドボックス作業の後にエージェントランタイムが別のモデル応答を必要とするときにのみ、次のターンが消費されます。 -こうした準備手順があるため、`default_manifest`、`instructions`、`base_instructions`、`capabilities`、`run_as` が、`SandboxAgent` を設計するときに考慮すべき主なサンドボックス固有オプションになります。 +これらの準備ステップがあるため、`default_manifest` 、 `instructions` 、 `base_instructions` 、 `capabilities` 、 `run_as` は、`SandboxAgent` を設計する際に主に検討すべきサンドボックス固有のオプションです。 ## `SandboxAgent` オプション -通常の `Agent` フィールドに加えて、次のサンドボックス固有オプションがあります。 +これらは通常の `Agent` フィールドに加わるサンドボックス固有のオプションです。
| オプション | 最適な用途 | | --- | --- | -| `default_manifest` | ランナーが作成する新しいサンドボックスセッション用のデフォルトワークスペース。 | -| `instructions` | SDK のサンドボックスプロンプトの後に追加される、追加の役割、ワークフロー、成功条件。 | -| `base_instructions` | SDK のサンドボックスプロンプトを置き換える高度なエスケープハッチ。 | -| `capabilities` | このエージェントと一緒に持ち運ぶべき、サンドボックスネイティブなツールと挙動。 | -| `run_as` | シェルコマンド、ファイル読み取り、パッチなど、モデル向けサンドボックスツールのユーザー ID 。 | +| `default_manifest` | ランナーが作成する新しいサンドボックスセッションのデフォルトワークスペース。 | +| `instructions` | SDK サンドボックスプロンプトの後に追加される、役割、ワークフロー、成功条件。 | +| `base_instructions` | SDK サンドボックスプロンプトを置き換える高度なエスケープハッチ。 | +| `capabilities` | このエージェントとともに持ち運ぶべき、サンドボックスネイティブなツールと挙動。 | +| `run_as` | シェルコマンド、ファイル読み取り、パッチなどのモデル向けサンドボックスツールに使うユーザー ID 。 |
-サンドボックスクライアントの選択、サンドボックスセッションの再利用、 manifest オーバーライド、スナップショット選択は、エージェントではなく [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] に属します。 +サンドボックスクライアントの選択、サンドボックスセッションの再利用、 manifest の上書き、スナップショットの選択は、エージェント上ではなく [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] に属します。 ### `default_manifest` -`default_manifest` は、このエージェント用にランナーが新しいサンドボックスセッションを作成する際に使われるデフォルトの [`Manifest`][agents.sandbox.manifest.Manifest] です。通常エージェントが開始時に持つべきファイル、リポジトリ、補助資料、出力ディレクトリ、マウントに使用します。 +`default_manifest` は、このエージェント用にランナーが新しいサンドボックスセッションを作成するときに使うデフォルトの [`Manifest`][agents.sandbox.manifest.Manifest] です。エージェントが通常開始時に持つべきファイル、リポジトリ、補助資料、出力ディレクトリ、マウントに使います。 -これはあくまでデフォルトです。実行ごとに `SandboxRunConfig(manifest=...)` で上書きでき、再利用または再開されたサンドボックスセッションは既存のワークスペース状態を維持します。 +これはあくまでデフォルトです。実行ごとに `SandboxRunConfig(manifest=...)` で上書きでき、再利用または再開されたサンドボックスセッションは既存のワークスペース状態を保持します。 ### `instructions` と `base_instructions` -`instructions` は、異なるプロンプト間でも維持したい短いルールに使います。`SandboxAgent` では、これらの instructions は SDK のサンドボックス基本プロンプトの後に追加されるため、組み込みのサンドボックスガイダンスを保ちながら、独自の役割、ワークフロー、成功条件を追加できます。 +`instructions` は、異なるプロンプトでも維持したい短いルールに使います。`SandboxAgent` では、これらの指示は SDK のサンドボックスベースプロンプトの後に追加されるため、組み込みのサンドボックスガイダンスを維持しつつ、独自の役割、ワークフロー、成功条件を追加できます。 -`base_instructions` は、SDK のサンドボックス基本プロンプトを置き換えたい場合にのみ使ってください。ほとんどのエージェントでは設定不要です。 +`base_instructions` は、SDK のサンドボックスベースプロンプトを置き換えたい場合にのみ使用してください。ほとんどのエージェントでは設定不要です。
-| 置く場所 | 用途 | 例 | +| 入れる場所 | 用途 | 例 | | --- | --- | --- | -| `instructions` | エージェント向けの安定した役割、ワークフロールール、成功条件。 | 「 onboarding documents を確認してから hand off する。」「最終ファイルを `output/` に書き込む。」 | -| `base_instructions` | SDK のサンドボックス基本プロンプト全体の置き換え。 | カスタムの低レベルサンドボックスラッパープロンプト。 | +| `instructions` | エージェントの安定した役割、ワークフロールール、成功条件。 | 「オンボーディング文書を確認してからハンドオフする。」、 「最終ファイルを `output/` に書き込む。」 | +| `base_instructions` | SDK サンドボックスベースプロンプトの完全な置き換え。 | カスタムの低レベルなサンドボックスラッパープロンプト。 | | ユーザープロンプト | この実行だけの単発リクエスト。 | 「このワークスペースを要約してください。」 | -| manifest 内のワークスペースファイル | より長いタスク仕様、リポジトリローカル instructions 、または範囲の限られた参照資料。 | `repo/task.md`、ドキュメントバンドル、サンプル packet 。 | +| 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 状態が重要なときにエージェントを 1 つの対話プロセス内に維持します。 +- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) では、 PTY 状態が重要な場合に、エージェントを 1 つの対話型プロセス内に維持します。 - [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/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` | エージェントにシェルアクセスが必要な場合。 | `exec_command` を追加し、サンドボックスクライアントが PTY 対話をサポートする場合は `write_stdin` も追加します。 | -| `Filesystem` | エージェントがファイル編集やローカル画像の確認を行う場合。 | `apply_patch` と `view_image` を追加します。パッチパスはワークスペースルート相対です。 | -| `Skills` | サンドボックス内でスキル検出と実体化を行いたい場合。 | サンドボックスローカルな `SKILL.md` スキルについては、`.agents` や `.agents/skills` を手動でマウントするよりこちらを推奨します。 | -| `Memory` | 後続実行でメモリ成果物を読み取る、または生成したい場合。 | `Shell` が必要です。ライブ更新には `Filesystem` も必要です。 | -| `Compaction` | 長時間実行フローで、コンパクション項目の後にコンテキストの切り詰めが必要な場合。 | モデルのサンプリングと入力処理を調整します。 | +| `Filesystem` | エージェントがファイル編集やローカル画像確認を行う必要がある場合。 | `apply_patch` と `view_image` を追加します。パッチパスはワークスペースルート相対です。 | +| `Skills` | サンドボックス内でスキルの検出と実体化を行いたい場合。 | `.agents` や `.agents/skills` を手動でマウントするよりこちらを推奨します。`Skills` はスキルをインデックス化し、サンドボックス内に実体化します。 | +| `Memory` | 後続の実行でメモリ成果物を読み取ったり生成したりする必要がある場合。 | `Shell` が必要です。ライブ更新には `Filesystem` も必要です。 | +| `Compaction` | 長時間実行フローで compaction 項目の後にコンテキストの切り詰めが必要な場合。 | モデルサンプリングと入力処理を調整します。 |
-デフォルトでは、`SandboxAgent.capabilities` は `Capabilities.default()` を使用し、これには `Filesystem()`、`Shell()`、`Compaction()` が含まれます。`capabilities=[...]` を渡すと、そのリストがデフォルトを置き換えるため、引き続き必要なデフォルト機能は明示的に含めてください。 +デフォルトでは、`SandboxAgent.capabilities` は `Capabilities.default()` を使い、`Filesystem()` 、 `Shell()` 、 `Compaction()` を含みます。`capabilities=[...]` を渡すとそのリストがデフォルトを置き換えるため、必要なデフォルト機能を引き続き含めてください。 スキルについては、どのように実体化したいかに応じてソースを選びます。 -- `Skills(lazy_from=LocalDirLazySkillSource(...))` は、大きなローカルスキルディレクトリのよいデフォルトです。モデルが最初にインデックスを発見し、必要なものだけを読み込めるためです。 +- `Skills(lazy_from=LocalDirLazySkillSource(...))` は、大規模なローカルスキルディレクトリのよいデフォルトです。モデルはまずインデックスを確認し、必要なものだけを読み込めます。 +- `LocalDirLazySkillSource(source=LocalDir(src=...))` は、SDK プロセスが実行されているファイルシステムから読み取ります。サンドボックスイメージやワークスペース内にしか存在しないパスではなく、元のホスト側スキルディレクトリを渡してください。 - `Skills(from_=LocalDir(src=...))` は、事前に配置したい小さなローカルバンドルに適しています。 -- `Skills(from_=GitRepo(repo=..., ref=...))` は、スキル自体をリポジトリから取得したい場合に適しています。 +- `Skills(from_=GitRepo(repo=..., ref=...))` は、スキル自体をリポジトリから取得すべき場合に適しています。 -スキルがすでに `.agents/skills//SKILL.md` のような形でディスク上にある場合は、`LocalDir(...)` をそのソースルートに向けたうえで、引き続き `Skills(...)` を使って公開してください。既存のワークスペース契約が別のサンドボックス内レイアウトに依存していない限り、デフォルトの `skills_path=".agents"` を維持してください。 +`LocalDir.src` は SDK ホスト上のソースパスです。`skills_path` は、`load_skill` 呼び出し時にスキルが配置されるサンドボックスワークスペース内の相対的な宛先パスです。 -適合する場合は組み込み機能を優先してください。組み込み機能でカバーされないサンドボックス固有のツールや命令の表面が必要な場合にのみ、カスタム機能を書いてください。 +スキルが既に `.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 、 hosted client 間で移植可能に保たれます。 +Manifest のエントリパスはワークスペース相対です。絶対パスにはできず、`..` でワークスペース外へ出ることもできません。これにより、ワークスペース契約はローカル、 Docker 、ホスト型クライアント間で移植可能に保たれます。 -manifest エントリは、作業開始前にエージェントが必要とする資料に使います。 +manifest エントリは、作業開始前にエージェントが必要とする素材に使ってください。
| Manifest エントリ | 用途 | | --- | --- | -| `File`、`Dir` | 小さな合成入力、補助ファイル、または出力ディレクトリ。 | -| `LocalFile`、`LocalDir` | サンドボックス内に実体化すべきホストファイルまたはディレクトリ。 | -| `GitRepo` | ワークスペースへ取得すべきリポジトリ。 | -| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` などのマウント | サンドボックス内に現れるべき外部ストレージ。 | +| `File` 、 `Dir` | 小さな合成入力、補助ファイル、または出力ディレクトリ。 | +| `LocalFile` 、 `LocalDir` | サンドボックス内に実体化すべきホストファイルまたはディレクトリ。 | +| `GitRepo` | ワークスペースに取得すべきリポジトリ。 | +| `S3Mount` 、 `GCSMount` 、 `R2Mount` 、 `AzureBlobMount` 、 `BoxMount` 、 `S3FilesMount` などのマウント | サンドボックス内に見えるようにすべき外部ストレージ。 |
-マウントエントリは、どのストレージを公開するかを記述します。マウント戦略は、サンドボックスバックエンドがそのストレージをどのように接続するかを記述します。マウントオプションとプロバイダーサポートについては [Sandbox clients](clients.md#mounts-and-remote-storage) を参照してください。 +マウントエントリは公開するストレージを記述し、マウント戦略はサンドボックスバックエンドがそのストレージをどう接続するかを記述します。マウントオプションとプロバイダー対応については [Sandbox clients](clients.md#mounts-and-remote-storage) を参照してください。 -よい manifest 設計とは通常、ワークスペース契約を狭く保ち、長いタスク手順を `repo/task.md` のようなワークスペースファイルに置き、 instructions では `repo/task.md` や `output/report.md` のように相対ワークスペースパスを使うことです。エージェントが `Filesystem` 機能の `apply_patch` ツールでファイルを編集する場合、パッチパスはシェルの `workdir` ではなく、サンドボックスワークスペースルート相対であることを忘れないでください。 +よい manifest 設計とは通常、ワークスペース契約を狭く保ち、長いタスク手順は `repo/task.md` のようなワークスペースファイルに置き、指示では `repo/task.md` や `output/report.md` のような相対ワークスペースパスを使うことを意味します。エージェントが `Filesystem` 機能の `apply_patch` ツールでファイル編集する場合は、パッチパスがシェルの `workdir` ではなくサンドボックスワークスペースルート相対であることに注意してください。 -`extra_path_grants` は、エージェントがワークスペース外の具体的な絶対パスを必要とする場合にのみ使用してください。たとえば、一時的なツール出力のための `/tmp` や、読み取り専用ランタイムのための `/opt/toolchain` です。付与は、バックエンドがファイルシステムポリシーを強制できる場合、SDK のファイル API とシェル実行の両方に適用されます。 +`extra_path_grants` は、エージェントがワークスペース外の具体的な絶対パスを必要とする場合にのみ使用してください。たとえば、一時ツール出力用の `/tmp` や、読み取り専用ランタイム用の `/opt/toolchain` です。付与は、バックエンドがファイルシステムポリシーを適用できる限り、SDK ファイル API とシェル実行の両方に適用されます。 ```python from agents.sandbox import Manifest, SandboxPathGrant @@ -258,9 +261,9 @@ manifest = Manifest( ### 権限 -`Permissions` は manifest エントリのファイルシステム権限を制御します。これはサンドボックスが実体化するファイルに関するものであり、モデル権限、承認ポリシー、 API 資格情報に関するものではありません。 +`Permissions` は、 manifest エントリのファイルシステム権限を制御します。これはサンドボックスが実体化するファイルに関するものであり、モデル権限、承認ポリシー、 API 資格情報に関するものではありません。 -デフォルトでは、 manifest エントリは所有者に対して読み取り、書き込み、実行が可能で、グループとその他に対して読み取りと実行が可能です。配置されたファイルを非公開、読み取り専用、または実行可能にすべき場合はこれを上書きします。 +デフォルトでは、 manifest エントリは所有者に対して読み取り、書き込み、実行を許可し、グループとその他には読み取りと実行を許可します。配置されるファイルを非公開、読み取り専用、または実行可能にしたい場合はこれを上書きしてください。 ```python from agents.sandbox import FileMode, Permissions @@ -276,9 +279,9 @@ private_notes = File( ) ``` -`Permissions` は、所有者、グループ、その他それぞれのビットと、そのエントリがディレクトリかどうかを別々に保持します。直接構築することも、`Permissions.from_str(...)` でモード文字列から解析することも、`Permissions.from_mode(...)` で OS モードから導出することもできます。 +`Permissions` は、所有者、グループ、その他の各ビットと、そのエントリがディレクトリかどうかを個別に保持します。直接構築することも、`Permissions.from_str(...)` でモード文字列から解析することも、`Permissions.from_mode(...)` で OS モードから導出することもできます。 -ユーザーは、作業を実行できるサンドボックス内の ID です。その ID をサンドボックス内に存在させたい場合は、 manifest に `User` を追加し、シェルコマンド、ファイル読み取り、パッチなどのモデル向けサンドボックスツールをそのユーザーとして実行したい場合は `SandboxAgent.run_as` を設定します。`run_as` が manifest 内にまだ存在しないユーザーを指している場合、ランナーはそのユーザーを実効 manifest に追加します。 +ユーザーは、作業を実行できるサンドボックス内の ID です。その ID をサンドボックス内に存在させたい場合は、 manifest に `User` を追加し、シェルコマンド、ファイル読み取り、パッチなどのモデル向けサンドボックスツールをそのユーザーとして実行したい場合は `SandboxAgent.run_as` を設定してください。`run_as` が manifest にまだ存在しないユーザーを指している場合、ランナーがそのユーザーを実効 manifest に追加します。 ```python from agents import Runner @@ -330,13 +333,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 @@ -353,13 +356,13 @@ run_config = RunConfig( ) ``` -ランナーが新しいサンドボックスセッションを作成すると、そのセッション用にサンドボックスクライアントがスナップショットインスタンスを構築します。開始時にスナップショットが復元可能であれば、実行を続行する前にサンドボックスが保存済みワークスペース内容を復元します。クリーンアップ時には、ランナー所有のサンドボックスセッションがワークスペースをアーカイブし、スナップショット経由で再度永続化します。 +ランナーが新しいサンドボックスセッションを作成するとき、サンドボックスクライアントはそのセッション用のスナップショットインスタンスを構築します。開始時に、スナップショットが復元可能であれば、実行継続前に保存済みワークスペース内容を復元します。クリーンアップ時には、ランナー所有のサンドボックスセッションがワークスペースをアーカイブし、スナップショットを通じて永続化し直します。 -`snapshot` を省略すると、ランタイムは可能な場合にデフォルトのローカルスナップショット保存先を使おうとします。設定できない場合は no-op スナップショットにフォールバックします。マウントされたパスや一時パスは、永続的なワークスペース内容としてスナップショットにコピーされません。 +`snapshot` を省略すると、ランタイムは可能な場合にデフォルトのローカルスナップショット保存場所を使おうとします。設定できない場合は no-op スナップショットにフォールバックします。マウント済みパスや一時パスは、永続的なワークスペース内容としてスナップショットにはコピーされません。 ### サンドボックスライフサイクル -ライフサイクルモードは **SDK 所有** と **開発者所有** の 2 種類です。 +ライフサイクルモードは **SDK 所有** と **開発者所有** の 2 つです。
@@ -387,7 +390,7 @@ sequenceDiagram
-サンドボックスを 1 回の実行だけ生かせばよい場合は、SDK 所有ライフサイクルを使用します。`client`、任意の `manifest`、任意の `snapshot`、および client `options` を渡すと、ランナーがサンドボックスを作成または再開し、開始し、エージェントを実行し、スナップショット対応ワークスペース状態を永続化し、サンドボックスを停止し、ランナー所有リソースを client にクリーンアップさせます。 +サンドボックスが 1 回の実行だけ生きればよい場合は、SDK 所有ライフサイクルを使用します。`client` 、任意の `manifest` 、任意の `snapshot` 、クライアント `options` を渡すと、ランナーがサンドボックスを作成または再開し、開始し、エージェントを実行し、スナップショット対応のワークスペース状態を永続化し、サンドボックスを停止し、ランナー所有リソースをクライアントにクリーンアップさせます。 ```python result = await Runner.run( @@ -399,7 +402,7 @@ result = await Runner.run( ) ``` -サンドボックスを事前に作成したい場合、1 つのライブサンドボックスを複数回の実行で再利用したい場合、実行後にファイルを確認したい場合、自分で作成したサンドボックス上でストリーミングしたい場合、またはクリーンアップのタイミングを厳密に制御したい場合は、開発者所有ライフサイクルを使用します。`session=...` を渡すと、ランナーはそのライブサンドボックスを使用しますが、ユーザーの代わりに閉じることはしません。 +サンドボックスを事前に作成したい場合、1 つの稼働中サンドボックスを複数実行で再利用したい場合、実行後にファイルを確認したい場合、自分で作成したサンドボックスに対してストリーミングしたい場合、またはクリーンアップのタイミングを厳密に制御したい場合は、開発者所有ライフサイクルを使用します。`session=...` を渡すと、その稼働中サンドボックスをランナーが使いますが、閉じるのはランナーではありません。 ```python sandbox = await client.create(manifest=agent.default_manifest) @@ -410,7 +413,7 @@ async with sandbox: await Runner.run(agent, "Write the final report.", run_config=run_config) ``` -コンテキストマネージャーが通常の形です。エントリ時にサンドボックスを開始し、終了時にセッションのクリーンアップライフサイクルを実行します。アプリでコンテキストマネージャーを使えない場合は、ライフサイクルメソッドを直接呼び出してください。 +コンテキストマネージャーが通常の形です。入場時にサンドボックスを開始し、終了時にセッションクリーンアップライフサイクルを実行します。アプリでコンテキストマネージャーを使えない場合は、ライフサイクルメソッドを直接呼び出してください。 ```python sandbox = await client.create( @@ -431,32 +434,32 @@ finally: await sandbox.aclose() ``` -`stop()` はスナップショット対応ワークスペース内容を永続化するだけで、サンドボックス自体は破棄しません。`aclose()` は完全なセッションクリーンアップ経路です。停止前フックを実行し、`stop()` を呼び出し、サンドボックスリソースをシャットダウンし、セッションスコープ依存関係を閉じます。 +`stop()` はスナップショット対応のワークスペース内容だけを永続化し、サンドボックス自体は破棄しません。`aclose()` は完全なセッションクリーンアップ経路です。停止前フックを実行し、`stop()` を呼び出し、サンドボックスリソースをシャットダウンし、セッションスコープの依存関係を閉じます。 ## `SandboxRunConfig` オプション -[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、サンドボックスセッションの取得元と、新しいセッションをどのように初期化するかを決定する実行ごとのオプションを保持します。 +[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、サンドボックスセッションの取得元と、新しいセッションの初期化方法を決定する実行ごとのオプションを保持します。 ### サンドボックス取得元 -これらのオプションは、ランナーがサンドボックスセッションを再利用、再開、または作成すべきかを決定します。 +これらのオプションは、ランナーがサンドボックスセッションを再利用、再開、作成のどれにするかを決めます。
-| オプション | 使用場面 | 注記 | +| オプション | 使う場面 | 注記 | | --- | --- | --- | -| `client` | ランナーにサンドボックスセッションの作成、再開、クリーンアップを任せたい場合。 | ライブサンドボックス `session` を提供しない限り必須です。 | -| `session` | すでに自分でライブサンドボックスセッションを作成している場合。 | ライフサイクルは呼び出し元が所有します。ランナーはそのライブサンドボックスセッションを再利用します。 | -| `session_state` | サンドボックスセッション状態はシリアライズ済みだが、ライブサンドボックスセッションオブジェクトはない場合。 | `client` が必要です。ランナーはその明示的な状態から所有セッションとして再開します。 | +| `client` | ランナーにサンドボックスセッションの作成、再開、クリーンアップを任せたい場合。 | 稼働中のサンドボックス `session` を渡さない限り必須です。 | +| `session` | 稼働中のサンドボックスセッションを自分で既に作成している場合。 | ライフサイクルは呼び出し側が所有し、ランナーはその稼働中サンドボックスセッションを再利用します。 | +| `session_state` | サンドボックスセッション状態は直列化済みだが、稼働中のサンドボックスセッションオブジェクトはない場合。 | `client` が必要で、ランナーはその明示的な状態から所有セッションとして再開します。 |
実際には、ランナーは次の順序でサンドボックスセッションを解決します。 -1. `run_config.sandbox.session` を注入した場合、そのライブサンドボックスセッションを直接再利用します。 -2. それ以外で、実行が `RunState` から再開されている場合は、保存済みサンドボックスセッション状態を再開します。 -3. それ以外で、`run_config.sandbox.session_state` を渡した場合、ランナーはその明示的なシリアライズ済みサンドボックスセッション状態から再開します。 -4. それ以外の場合、ランナーは新しいサンドボックスセッションを作成します。その新しいセッションには、`run_config.sandbox.manifest` が指定されていればそれを、なければ `agent.default_manifest` を使用します。 +1. `run_config.sandbox.session` を注入した場合、その稼働中サンドボックスセッションを直接再利用します。 +2. そうでなく、実行が `RunState` から再開されている場合は、保存されたサンドボックスセッション状態を再開します。 +3. そうでなく、`run_config.sandbox.session_state` を渡した場合は、ランナーがその明示的に直列化されたサンドボックスセッション状態から再開します。 +4. それ以外の場合、ランナーは新しいサンドボックスセッションを作成します。その新規セッションには、提供されていれば `run_config.sandbox.manifest` を、なければ `agent.default_manifest` を使います。 ### 新規セッション入力 @@ -464,25 +467,25 @@ finally:
-| オプション | 使用場面 | 注記 | +| オプション | 使う場面 | 注記 | | --- | --- | --- | | `manifest` | 1 回限りの新規セッションワークスペース上書きを行いたい場合。 | 省略時は `agent.default_manifest` にフォールバックします。 | -| `snapshot` | 新しいサンドボックスセッションをスナップショットから初期化したい場合。 | 再開に近いフローやリモートスナップショットクライアントに有用です。 | -| `options` | サンドボックスクライアントが作成時オプションを必要とする場合。 | Docker イメージ、 Modal アプリ名、 E2B テンプレート、タイムアウトなど、 client 固有設定で一般的です。 | +| `snapshot` | 新しいサンドボックスセッションをスナップショットから初期化したい場合。 | 再開に近いフローやリモートスナップショットクライアントで有用です。 | +| `options` | サンドボックスクライアントに作成時オプションが必要な場合。 | Docker イメージ、 Modal アプリ名、 E2B テンプレート、タイムアウトなど、クライアント固有設定でよく使います。 |
### 実体化制御 -`concurrency_limits` は、どれだけのサンドボックス実体化作業を並列実行できるかを制御します。大きな manifest やローカルディレクトリコピーでリソース制御をより厳密にしたい場合は、`SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` を使用してください。どちらかの値を `None` にすると、その特定の制限は無効になります。 +`concurrency_limits` は、並列実行できるサンドボックス実体化作業の量を制御します。大きな manifest やローカルディレクトリコピーでより厳密なリソース制御が必要な場合は、`SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` を使ってください。いずれかの値を `None` にすると、その特定の制限は無効になります。 -覚えておくべき影響をいくつか挙げます。 +いくつか覚えておくべき含意があります。 -- 新規セッション: `manifest=` と `snapshot=` は、ランナーが新しいサンドボックスセッションを作成する場合にのみ適用されます。 -- 再開とスナップショット: `session_state=` は以前にシリアライズしたサンドボックス状態へ再接続し、`snapshot=` は保存済みワークスペース内容から新しいサンドボックスセッションを初期化します。 -- client 固有オプション: `options=` はサンドボックスクライアントに依存します。Docker と多くの hosted client では必須です。 -- 注入されたライブセッション: 実行中のサンドボックス `session` を渡した場合、機能主導の manifest 更新では互換性のある非マウントエントリを追加できます。ただし、`manifest.root`、`manifest.environment`、`manifest.users`、`manifest.groups` の変更、既存エントリの削除、エントリ型の置換、マウントエントリの追加や変更はできません。 -- ランナー API: `SandboxAgent` の実行でも、通常の `Runner.run()`、`Runner.run_sync()`、`Runner.run_streamed()` API をそのまま使用します。 +- 新規セッション: `manifest=` と `snapshot=` が適用されるのは、ランナーが新しいサンドボックスセッションを作成する場合のみです。 +- 再開とスナップショット: `session_state=` は以前に直列化されたサンドボックス状態へ再接続するのに対し、`snapshot=` は保存済みワークスペース内容から新しいサンドボックスセッションを初期化します。 +- クライアント固有オプション: `options=` はサンドボックスクライアントに依存します。Docker や多くのホスト型クライアントではこれが必要です。 +- 注入された稼働中セッション: 稼働中のサンドボックス `session` を渡した場合、機能主導の manifest 更新では互換性のある非マウントエントリを追加できます。ただし、`manifest.root` 、 `manifest.environment` 、 `manifest.users` 、 `manifest.groups` の変更、既存エントリの削除、エントリ型の置き換え、マウントエントリの追加や変更はできません。 +- ランナー API : `SandboxAgent` の実行には、引き続き通常の `Runner.run()` 、 `Runner.run_sync()` 、 `Runner.run_streamed()` API を使います。 ## 完全な例: コーディングタスク @@ -529,9 +532,10 @@ def build_agent(model: str) -> SandboxAgent[None]: } ), capabilities=Capabilities.default() + [ - # Let Skills(...) stage and index sandbox-local skills for you. Skills( lazy_from=LocalDirLazySkillSource( + # This is a host path read by the SDK process. + # Requested skills are copied into `skills_path` in the sandbox. source=LocalDir(src=HOST_SKILLS_DIR), ) ), @@ -564,19 +568,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 を使い、プロバイダー管理の実行が必要なら hosted provider を使ってください。例とプロバイダーオプションについては [Sandbox clients](clients.md) を参照してください。 +エージェント定義はそのままにして、実行設定だけを変更します。コンテナ分離やイメージの同一性が必要なら Docker を、プロバイダー管理の実行が必要ならホスト型プロバイダーを使ってください。例とプロバイダーオプションについては [Sandbox clients](clients.md) を参照してください。 ### ワークスペースの上書き -エージェント定義はそのままにして、新規セッション manifest だけを差し替えます。 +エージェント定義はそのままにし、新規セッション manifest だけを差し替えます。 ```python from agents.run import RunConfig @@ -596,11 +600,11 @@ run_config = RunConfig( ) ``` -これは、同じエージェントの役割を異なるリポジトリ、 packet 、またはタスクバンドルに対して実行したいが、エージェントを再構築したくない場合に使います。上の検証可能なコーディング例では、1 回限りの上書きではなく `default_manifest` で同じパターンを示しています。 +これは、同じエージェントの役割を、エージェントを作り直さずに異なるリポジトリ、パケット、タスクバンドルに対して実行したい場合に使います。上の検証可能なコーディング例は、単発の上書きではなく `default_manifest` を使って同じパターンを示しています。 ### サンドボックスセッションの注入 -明示的なライフサイクル制御、実行後の確認、または出力コピーが必要な場合は、ライブサンドボックスセッションを注入します。 +明示的なライフサイクル制御、実行後の確認、または出力コピーが必要な場合は、稼働中のサンドボックスセッションを注入します。 ```python from agents import Runner @@ -621,11 +625,11 @@ async with sandbox: ) ``` -これは、実行後にワークスペースを確認したい場合や、すでに開始済みのサンドボックスセッション上でストリーミングしたい場合に使います。[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) と [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。 +これは、実行後にワークスペースを確認したい場合や、既に開始済みのサンドボックスセッションに対してストリーミングしたい場合に使います。[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) と [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。 ### セッション状態からの再開 -`RunState` の外でサンドボックス状態をすでにシリアライズしている場合は、ランナーにその状態から再接続させます。 +`RunState` の外で既にサンドボックス状態を直列化している場合は、その状態からランナーに再接続させます。 ```python from agents.run import RunConfig @@ -642,11 +646,11 @@ run_config = RunConfig( ) ``` -これは、サンドボックス状態が独自のストレージやジョブシステムに保存されていて、`Runner` にそこから直接再開させたい場合に使います。シリアライズ / デシリアライズの流れについては [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) を参照してください。 +これは、サンドボックス状態が独自のストレージやジョブシステムにあり、`Runner` にそれを直接再開させたい場合に使います。直列化と逆直列化の流れについては [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) を参照してください。 -### スナップショットから開始 +### スナップショットからの開始 -保存済みファイルと成果物から新しいサンドボックスを初期化します。 +保存済みファイルや成果物から新しいサンドボックスを初期化します。 ```python from pathlib import Path @@ -663,11 +667,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 @@ -678,11 +682,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) を参照してください。 -### ツールとして公開 +### ツールとしての公開 -ツールエージェントは、独自のサンドボックス境界を持つことも、親実行のライブサンドボックスを再利用することもできます。再利用は、高速な読み取り専用 explorer エージェントに便利です。別のサンドボックスを作成、ハイドレート、スナップショット化するコストを払わずに、親が使っている正確なワークスペースを確認できます。 +ツールエージェントには、独自のサンドボックス境界を与えることも、親実行の稼働中サンドボックスを再利用させることもできます。再利用は、高速な読み取り専用エクスプローラーエージェントに有用です。別のサンドボックスを作成、ハイドレート、スナップショットするコストを払わずに、親が使っている正確なワークスペースを確認できます。 ```python from agents import Runner @@ -764,9 +768,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 @@ -787,9 +791,9 @@ 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 との組み合わせ 同じエージェント上で通常のツールを使いつつ、サンドボックスワークスペースも維持します。 @@ -810,42 +814,42 @@ agent = SandboxAgent( ## メモリ -将来の sandbox-agent 実行が過去の実行から学習すべき場合は、`Memory` 機能を使用してください。メモリは SDK の会話用 `Session` メモリとは別物です。教訓をサンドボックスワークスペース内のファイルに抽出し、後続の実行がそれらのファイルを読み取れるようにします。 +将来のサンドボックスエージェント実行が過去の実行から学習すべき場合は、`Memory` 機能を使用してください。メモリは SDK の会話用 `Session` メモリとは別です。学びをサンドボックスワークスペース内のファイルに要約し、その後の実行でそれらのファイルを読み取れるようにします。 -セットアップ、読み取り / 生成挙動、複数ターン会話、レイアウト分離については [Agent memory](memory.md) を参照してください。 +セットアップ、読み取り / 生成動作、マルチターン会話、レイアウト分離については [Agent memory](memory.md) を参照してください。 ## 構成パターン -単一エージェントパターンが明確になったら、次の設計上の問いは、より大きなシステムの中でどこにサンドボックス境界を置くかです。 +単一エージェントパターンが明確になったら、次の設計上の問いは、より大きなシステムのどこにサンドボックス境界を置くかです。 -sandbox agents は引き続き SDK の他の部分と組み合わせられます。 +サンドボックスエージェントは引き続き SDK の他の部分と組み合わせられます。 -- [Handoffs](../handoffs.md): サンドボックスではない intake エージェントから、ドキュメント中心の作業をサンドボックスレビュアーへ hand off します。 -- [Agents as tools](../tools.md#agents-as-tools): 複数の sandbox agents をツールとして公開します。通常は各 `Agent.as_tool(...)` 呼び出しで `run_config=RunConfig(sandbox=SandboxRunConfig(...))` を渡し、各ツールが独自のサンドボックス境界を持つようにします。 +- [Handoffs](../handoffs.md): サンドボックスなしの受付エージェントから、ドキュメント量の多い作業をサンドボックスレビュアーへハンドオフします。 +- [Agents as tools](../tools.md#agents-as-tools): 複数のサンドボックスエージェントをツールとして公開します。通常は各 `Agent.as_tool(...)` 呼び出しに `run_config=RunConfig(sandbox=SandboxRunConfig(...))` を渡して、各ツールが独自のサンドボックス境界を持つようにします。 - [MCP](../mcp.md) と通常の関数ツール: サンドボックス機能は `mcp_servers` や通常の Python ツールと共存できます。 -- [Running agents](../running_agents.md): サンドボックス実行でも通常の `Runner` API を使います。 +- [Running agents](../running_agents.md): サンドボックス実行でも、引き続き通常の `Runner` API を使います。 -特によくあるパターンは 2 つあります。 +特によくあるパターンは 2 つです。 -- サンドボックスではないエージェントが、ワークスペース分離を必要とする部分だけを sandbox agent に hand off する -- オーケストレーターが複数の sandbox agents をツールとして公開し、通常は各 `Agent.as_tool(...)` 呼び出しごとに別々のサンドボックス `RunConfig` を使って、各ツールが独自の分離ワークスペースを持つようにする +- ワークスペース分離が必要な部分だけで、サンドボックスなしエージェントがサンドボックスエージェントへハンドオフする +- オーケストレーターが複数のサンドボックスエージェントをツールとして公開し、通常は各 `Agent.as_tool(...)` 呼び出しごとに別々のサンドボックス `RunConfig` を使って、各ツールに独立したワークスペースを与える ### ターンとサンドボックス実行 -handoff と agent-as-tool 呼び出しは分けて説明すると理解しやすくなります。 +ハンドオフと agent-as-tool 呼び出しは別々に説明するとわかりやすいです。 -handoff では、依然として 1 つのトップレベル実行と 1 つのトップレベルターンループがあります。アクティブエージェントは変わりますが、実行がネストされるわけではありません。サンドボックスではない intake エージェントがサンドボックスレビュアーへ hand off すると、その同じ実行内の次のモデル呼び出しはサンドボックスエージェント向けに準備され、そのサンドボックスエージェントが次のターンを担当します。つまり、handoff は同じ実行の次のターンをどのエージェントが担当するかを変えます。[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 つの外側ターンを使ってツール呼び出しを決定し、そのツール呼び出しが sandbox agent のネストされた実行を開始します。ネストされた実行には独自のターンループ、`max_turns`、承認、そして通常は独自のサンドボックス `RunConfig` があります。1 回のネストされたターンで終わることもあれば、複数回かかることもあります。外側のオーケストレーターから見ると、そのすべての作業は依然として 1 回のツール呼び出しの背後にあるため、ネストされたターンは外側実行のターンカウンターを増やしません。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。 +`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) を参照してください。 承認の挙動も同じ分割に従います。 -- handoff の場合、サンドボックスエージェントがその実行内でアクティブエージェントになるため、承認は同じトップレベル実行に留まります -- `Agent.as_tool(...)` の場合、サンドボックスツールエージェント内で発生した承認も外側の実行に表れますが、それらは保存されたネスト実行状態から来るものであり、外側の実行が再開されるとネストされたサンドボックス実行も再開されます +- ハンドオフでは、サンドボックスエージェントがその実行のアクティブエージェントになるため、承認は同じトップレベル実行上に留まります +- `Agent.as_tool(...)` では、サンドボックスツールエージェント内で発生した承認も外側実行に現れますが、それらは保存されたネスト実行状態に由来し、外側実行が再開されるとネストされたサンドボックス実行を再開します -## 参考情報 +## 参考資料 -- [Quickstart](quickstart.md): 1 つの sandbox agent を動かします。 -- [Sandbox clients](clients.md): ローカル、 Docker 、 hosted 、マウントオプションを選びます。 -- [Agent memory](memory.md): 以前のサンドボックス実行から得た教訓を保持し、再利用します。 -- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 実行可能なローカル、コーディング、メモリ、 handoff 、エージェント構成パターンです。 \ No newline at end of file +- [Quickstart](quickstart.md): 1 つのサンドボックスエージェントを動かします。 +- [Sandbox clients](clients.md): ローカル、 Docker 、ホスト型、マウントの選択肢を選びます。 +- [Agent memory](memory.md): 過去のサンドボックス実行から得た学びを保存して再利用します。 +- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 実行可能なローカル、コーディング、メモリ、ハンドオフ、エージェント構成パターンです。 \ No newline at end of file diff --git a/docs/ja/sandbox_agents.md b/docs/ja/sandbox_agents.md index 90bbf8a70f..1c2314564e 100644 --- a/docs/ja/sandbox_agents.md +++ b/docs/ja/sandbox_agents.md @@ -6,27 +6,27 @@ search: !!! warning "ベータ機能" - Sandbox Agents はベータ版です。一般提供までの間に API の詳細、デフォルト値、対応機能は変更される可能性があり、また時間の経過とともにより高度な機能が追加される予定です。 + Sandbox Agents はベータ版です。一般提供までに API の詳細、デフォルト設定、対応機能は変更される可能性があり、また時間とともにより高度な機能が追加される予定です。 -現代的なエージェントは、ファイルシステム内の実際のファイルを操作できるときに最も効果的に動作します。Agents SDK の **Sandbox Agents** は、モデルに永続的なワークスペースを提供し、そこでは大規模なドキュメント群の検索、ファイル編集、コマンド実行、成果物の生成、保存された sandbox 状態からの作業再開が可能です。 +モダンなエージェントは、ファイルシステム内の実際のファイルを操作できるときに最も効果を発揮します。Agents SDK の **Sandbox Agents** は、モデルに永続的なワークスペースを提供し、そこで大規模なドキュメント集合を検索し、ファイルを編集し、コマンドを実行し、成果物を生成し、保存された sandbox state から作業を再開できます。 -SDK は、ファイルのステージング、ファイルシステムツール、シェルアクセス、sandbox のライフサイクル、スナップショット、プロバイダー固有の接続処理を自分で組み合わせることなく、その実行ハーネスを提供します。通常の `Agent` と `Runner` のフローはそのまま維持しつつ、ワークスペース用の `Manifest` 、 sandbox ネイティブツール用の capabilities 、そして作業の実行場所を指定する `SandboxRunConfig` を追加できます。 +SDK は、ファイルのステージング、ファイルシステムツール、シェルアクセス、sandbox のライフサイクル、スナップショット、プロバイダー固有の接続処理を自分で組み合わせることなく、その実行ハーネスを提供します。通常の `Agent` と `Runner` のフローはそのままに、ワークスペース用の `Manifest`、sandbox ネイティブツール用の capabilities、作業の実行場所を指定する `SandboxRunConfig` を追加するだけです。 ## 前提条件 - Python 3.10 以上 -- OpenAI Agents SDK の基本的な知識 -- sandbox クライアント。ローカル開発では、まず `UnixLocalSandboxClient` から始めてください。 +- OpenAI Agents SDK の基本的な理解 +- sandbox クライアント。ローカル開発では、まず `UnixLocalSandboxClient` を使用してください。 ## インストール -まだ SDK をインストールしていない場合は、次を実行してください。 +まだ SDK をインストールしていない場合は、次を実行します。 ```bash pip install openai-agents ``` -Docker ベースの sandbox の場合: +Docker ベースの sandbox の場合は、次を実行します。 ```bash pip install "openai-agents[docker]" @@ -34,7 +34,7 @@ pip install "openai-agents[docker]" ## ローカル sandbox エージェントの作成 -この例では、ローカルのリポジトリを `repo/` 配下にステージングし、ローカル skills を遅延読み込みし、 runner が実行時に Unix ローカル sandbox セッションを作成できるようにします。 +この例では、`repo/` 配下にローカルリポジトリをステージングし、ローカル skills を遅延読み込みし、runner が実行時に Unix ローカル sandbox セッションを作成できるようにします。 ```python import asyncio @@ -69,6 +69,8 @@ def build_agent(model: str) -> SandboxAgent[None]: capabilities=Capabilities.default() + [ Skills( lazy_from=LocalDirLazySkillSource( + # This is a host path read by the SDK process. + # Requested skills are copied into `skills_path` in the sandbox. source=LocalDir(src=HOST_SKILLS_DIR), ) ), @@ -99,17 +101,17 @@ if __name__ == "__main__": 基本的な実行が動作したら、次に多くの人が選ぶ項目は以下です。 - `default_manifest`: 新しい sandbox セッション用のファイル、リポジトリ、ディレクトリ、マウント -- `instructions`: プロンプト全体に適用される短いワークフロールール +- `instructions`: プロンプト全体にわたって適用される短いワークフロールール - `base_instructions`: SDK の sandbox プロンプトを置き換えるための高度なエスケープハッチ -- `capabilities`: ファイルシステム編集 / 画像検査、シェル、 skills 、メモリ、 compaction などの sandbox ネイティブツール -- `run_as`: モデル向けツールにおける sandbox ユーザー ID +- `capabilities`: ファイルシステム編集 / 画像検査、シェル、skills、メモリ、コンパクションなどの sandbox ネイティブツール +- `run_as`: モデル向けツールに対する sandbox ユーザー ID - `SandboxRunConfig.client`: sandbox バックエンド -- `SandboxRunConfig.session` 、 `session_state` 、または `snapshot`: 後続の実行を以前の作業に再接続する方法 +- `SandboxRunConfig.session`、`session_state`、または `snapshot`: 後続の実行を以前の作業に再接続する方法 ## 次の参照先 -- [概念](sandbox/guide.md): manifests 、 capabilities 、 permissions 、 snapshots 、 run config 、構成パターンを理解します。 -- [Sandbox クライアント](sandbox/clients.md): Unix ローカル、 Docker 、ホスト型プロバイダー、マウント戦略を選びます。 -- [エージェントメモリ](sandbox/memory.md): 以前の sandbox 実行から得た学びを保持し、再利用します。 +- [概念](sandbox/guide.md): manifest、capabilities、権限、スナップショット、run config、構成パターンを理解します。 +- [sandbox クライアント](sandbox/clients.md): Unix ローカル、Docker、ホスト型プロバイダー、マウント戦略を選択します。 +- [エージェントメモリ](sandbox/memory.md): 以前の sandbox 実行から得た知見を保持し、再利用します。 -シェルアクセスが時々使うツールの 1 つにすぎない場合は、[ツールガイド](tools.md) のホスト型シェルから始めてください。ワークスペースの分離、sandbox クライアントの選択、または sandbox セッションの再開動作が設計の一部である場合は、sandbox エージェントを使用してください。 \ No newline at end of file +シェルアクセスが単発でたまに使うツールの 1 つにすぎない場合は、[tools ガイド](tools.md) の hosted shell から始めてください。ワークスペース分離、sandbox クライアントの選択、または sandbox セッションの再開動作が設計の一部である場合は、sandbox エージェントを使用してください。 \ No newline at end of file diff --git a/docs/ko/sandbox/guide.md b/docs/ko/sandbox/guide.md index 727ab59479..719dabd26a 100644 --- a/docs/ko/sandbox/guide.md +++ b/docs/ko/sandbox/guide.md @@ -6,35 +6,35 @@ search: !!! warning "베타 기능" - Sandbox Agents는 베타입니다. 정식 출시 전에 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다. + Sandbox Agents는 베타입니다. 정식 출시 전까지 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다. -최신 에이전트는 파일시스템의 실제 파일에서 작업할 수 있을 때 가장 잘 동작합니다. **Sandbox Agents**는 특화된 도구와 셸 명령을 사용해 대규모 문서 세트를 검색하고 조작하며, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 모델에 지속적인 워크스페이스를 제공하며, 에이전트는 이를 사용해 사용자를 대신해 작업을 수행할 수 있습니다. Agents SDK의 Sandbox Agents는 샌드박스 환경과 연결된 에이전트를 쉽게 실행할 수 있도록 도와주며, 파일시스템에 올바른 파일을 쉽게 배치하고, 대규모로 작업을 시작, 중지, 재개하기 쉽도록 샌드박스를 오케스트레이션할 수 있게 해줍니다. +현대적인 에이전트는 파일시스템의 실제 파일에서 작업할 수 있을 때 가장 잘 동작합니다. **Sandbox Agents**는 특화된 도구와 셸 명령을 활용해 대규모 문서 집합을 검색하고 조작하며, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 모델에 지속적인 워크스페이스를 제공하며, 에이전트는 이를 사용해 사용자를 대신해 작업할 수 있습니다. Agents SDK의 Sandbox Agents는 샌드박스 환경과 연결된 에이전트를 쉽게 실행할 수 있게 해주며, 파일시스템에 올바른 파일을 배치하고 샌드박스를 오케스트레이션해 대규모로 작업을 쉽게 시작, 중지, 재개할 수 있도록 도와줍니다. -워크스페이스는 에이전트가 필요로 하는 데이터를 중심으로 정의합니다. GitHub 리포지토리, 로컬 파일 및 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일시스템, 그리고 사용자가 제공하는 기타 샌드박스 입력에서 시작할 수 있습니다. +워크스페이스는 에이전트에 필요한 데이터를 중심으로 정의합니다. GitHub 리포지토리, 로컬 파일 및 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일시스템, 그리고 사용자가 제공하는 기타 샌드박스 입력에서 시작할 수 있습니다.
-![컴퓨트가 포함된 Sandbox agent harness](../assets/images/harness_with_compute.png) +![Sandbox agent harness with compute](../assets/images/harness_with_compute.png)
-`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`, 가드레일, 훅 같은 일반적인 에이전트 표면을 그대로 유지하며, 여전히 일반 `Runner` API를 통해 실행됩니다. 달라지는 것은 실행 경계입니다. -- `SandboxAgent`는 에이전트 자체를 정의합니다. 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스 전용 기본값과 파일시스템 도구, 셸 접근, 스킬, 메모리, 컴팩션 같은 기능을 포함합니다. -- `Manifest`는 새 샌드박스 워크스페이스의 원하는 초기 콘텐츠와 레이아웃을 선언하며, 파일, 리포지토리, 마운트, 환경을 포함합니다. -- 샌드박스 세션은 명령이 실행되고 파일이 변경되는 라이브 격리 환경입니다. -- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 실행이 해당 샌드박스 세션을 어떻게 얻는지 결정합니다. 예를 들어 세션을 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 다시 연결하거나, 샌드박스 클라이언트를 통해 새로운 샌드박스 세션을 생성할 수 있습니다. -- 저장된 샌드박스 상태와 스냅샷을 사용하면 이후 실행에서 이전 작업에 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 초기화할 수 있습니다. +- `SandboxAgent`는 에이전트 자체를 정의합니다. 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스 전용 기본값과 파일시스템 도구, 셸 접근, 스킬, 메모리, 컴팩션 같은 기능을 포함합니다 +- `Manifest`는 파일, 리포지토리, 마운트, 환경을 포함해 새 샌드박스 워크스페이스의 원하는 시작 콘텐츠와 레이아웃을 선언합니다 +- 샌드박스 세션은 명령이 실행되고 파일이 변경되는 실제 격리 환경입니다 +- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 실행이 샌드박스 세션을 어떻게 얻는지 결정합니다. 예를 들어 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 재연결하거나, 샌드박스 클라이언트를 통해 새로운 샌드박스 세션을 생성할 수 있습니다 +- 저장된 샌드박스 상태와 스냅샷을 사용하면 이후 실행에서 이전 작업에 재연결하거나 저장된 콘텐츠로 새로운 샌드박스 세션을 시드할 수 있습니다 -`Manifest`는 새 세션 워크스페이스 계약이지, 모든 라이브 샌드박스의 전체 단일 진실 공급원은 아닙니다. 실행의 실제 워크스페이스는 재사용된 샌드박스 세션, 직렬화된 샌드박스 세션 상태, 또는 실행 시점에 선택된 스냅샷에서 대신 올 수 있습니다. +`Manifest`는 새 세션 워크스페이스 계약이지, 모든 실제 샌드박스의 완전한 단일 진실 공급원은 아닙니다. 실행의 실효 워크스페이스는 대신 재사용된 샌드박스 세션, 직렬화된 샌드박스 세션 상태, 또는 실행 시점에 선택된 스냅샷에서 올 수 있습니다. -이 페이지 전체에서 "샌드박스 세션"은 샌드박스 클라이언트가 관리하는 라이브 실행 환경을 의미합니다. 이는 [Sessions](../sessions/index.md)에서 설명하는 SDK의 대화형 [`Session`][agents.memory.session.Session] 인터페이스와는 다릅니다. +이 페이지 전반에서 "샌드박스 세션"은 샌드박스 클라이언트가 관리하는 실제 실행 환경을 의미합니다. 이는 [Sessions](../sessions/index.md)에서 설명하는 SDK의 대화형 [`Session`][agents.memory.session.Session] 인터페이스와는 다릅니다. -바깥쪽 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 bookkeeping을 담당합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 담당합니다. 이러한 분리는 모델의 핵심 요소입니다. +바깥 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 기록 관리를 담당합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 담당합니다. 이러한 분리는 모델의 핵심 부분입니다. ### 구성 요소의 결합 방식 -샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. 러너는 에이전트를 준비하고, 이를 라이브 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다. +샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. 러너는 에이전트를 준비하고, 이를 실제 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다. ```mermaid flowchart LR @@ -52,31 +52,31 @@ flowchart LR 샌드박스 전용 기본값은 `SandboxAgent`에 유지됩니다. 실행별 샌드박스 세션 선택은 `SandboxRunConfig`에 유지됩니다. -수명 주기는 세 단계로 생각하면 됩니다. +수명주기를 세 단계로 생각해 보세요. -1. `SandboxAgent`, `Manifest`, 기능을 사용해 에이전트와 새 워크스페이스 계약을 정의합니다. -2. 샌드박스 세션을 주입, 재개 또는 생성하는 `SandboxRunConfig`를 `Runner`에 제공하여 실행합니다. -3. 러너가 관리하는 `RunState`, 명시적 샌드박스 `session_state`, 또는 저장된 워크스페이스 스냅샷에서 나중에 이어서 작업합니다. +1. `SandboxAgent`, `Manifest`, 기능을 사용해 에이전트와 새 워크스페이스 계약을 정의합니다 +2. 샌드박스 세션을 주입, 재개 또는 생성하는 `SandboxRunConfig`를 `Runner`에 제공해 실행합니다 +3. 러너가 관리하는 `RunState`, 명시적인 샌드박스 `session_state`, 또는 저장된 워크스페이스 스냅샷에서 나중에 이어갑니다 -셸 접근이 가끔 사용하는 단일 도구일 뿐이라면 [tools guide](../tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요. +셸 접근이 가끔 필요한 도구 하나에 불과하다면 [도구 가이드](../tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요. ## 사용 시점 샌드박스 에이전트는 워크스페이스 중심 워크플로에 적합합니다. 예를 들면 다음과 같습니다. -- 코딩과 디버깅, 예를 들어 GitHub 리포지토리의 이슈 리포트에 대한 자동 수정 작업을 에이전트 오케스트레이션하고 대상 테스트를 실행하는 경우 -- 문서 처리 및 편집, 예를 들어 사용자의 금융 문서에서 정보를 추출하고 작성 완료된 세금 양식 초안을 생성하는 경우 -- 파일 기반 검토 또는 분석, 예를 들어 온보딩 패킷, 생성된 보고서, 또는 아티팩트 번들을 확인한 후 응답하는 경우 -- 격리된 멀티 에이전트 패턴, 예를 들어 각 검토자 또는 코딩 하위 에이전트에 자체 워크스페이스를 제공하는 경우 -- 다단계 워크스페이스 작업, 예를 들어 한 번의 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개하는 경우 +- 코딩 및 디버깅. 예를 들어 GitHub 리포지토리의 이슈 보고서에 대한 자동 수정 작업을 오케스트레이션하고 대상 테스트를 실행하는 경우 +- 문서 처리 및 편집. 예를 들어 사용자의 금융 문서에서 정보를 추출하고 작성 완료된 세금 양식 초안을 만드는 경우 +- 파일 기반 검토 또는 분석. 예를 들어 온보딩 패킷, 생성된 보고서, 또는 아티팩트 번들을 확인한 뒤 응답하는 경우 +- 격리된 다중 에이전트 패턴. 예를 들어 각 리뷰어 또는 코딩 하위 에이전트에 자체 워크스페이스를 제공하는 경우 +- 다단계 워크스페이스 작업. 예를 들어 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개하는 경우 -파일이나 살아 있는 파일시스템에 접근할 필요가 없다면 계속 `Agent`를 사용하세요. 셸 접근이 가끔 필요한 기능일 뿐이라면 호스티드 셸을 추가하고, 워크스페이스 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요. +파일이나 실제 파일시스템에 대한 접근이 필요하지 않다면 계속 `Agent`를 사용하세요. 셸 접근이 가끔 필요한 기능일 뿐이라면 호스티드 셸을 추가하고, 워크스페이스 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요. ## 샌드박스 클라이언트 선택 -로컬 개발은 `UnixLocalSandboxClient`로 시작하세요. 컨테이너 격리 또는 이미지 일치가 필요하면 `DockerSandboxClient`로 전환하세요. 공급자 관리 실행이 필요하면 호스티드 공급자로 전환하세요. +로컬 개발에는 `UnixLocalSandboxClient`로 시작하세요. 컨테이너 격리나 이미지 일치성이 필요하면 `DockerSandboxClient`로 이동하세요. 제공업체가 관리하는 실행이 필요하면 호스티드 제공업체로 이동하세요. -대부분의 경우 `SandboxAgent` 정의는 그대로 유지되고, 샌드박스 클라이언트와 그 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경됩니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [Sandbox clients](clients.md)를 참고하세요. +대부분의 경우 `SandboxAgent` 정의는 그대로 유지되고, 샌드박스 클라이언트와 해당 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경됩니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [Sandbox clients](clients.md)를 참고하세요. ## 핵심 구성 요소 @@ -84,145 +84,148 @@ flowchart LR | 계층 | 주요 SDK 구성 요소 | 답하는 질문 | | --- | --- | --- | -| 에이전트 정의 | `SandboxAgent`, `Manifest`, 기능 | 어떤 에이전트가 실행되며, 어떤 새 세션 워크스페이스 계약에서 시작해야 하는가? | -| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 라이브 샌드박스 세션 | 이 실행은 라이브 샌드박스 세션을 어떻게 얻고, 작업은 어디서 실행되는가? | -| 저장된 샌드박스 상태 | `RunState` 샌드박스 payload, `session_state`, 스냅샷 | 이 워크플로는 이전 샌드박스 작업에 어떻게 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 초기화하는가? | +| 에이전트 정의 | `SandboxAgent`, `Manifest`, capabilities | 어떤 에이전트가 실행되며, 어떤 새 세션 워크스페이스 계약에서 시작해야 하는가? | +| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 실제 샌드박스 세션 | 이 실행은 실제 샌드박스 세션을 어떻게 얻으며, 작업은 어디에서 실행되는가? | +| 저장된 샌드박스 상태 | `RunState` 샌드박스 페이로드, `session_state`, 스냅샷 | 이 워크플로는 이전 샌드박스 작업에 어떻게 재연결하거나 저장된 콘텐츠로 새로운 샌드박스 세션을 어떻게 시드하는가? | -주요 SDK 구성 요소는 다음과 같이 이 계층에 매핑됩니다. +주요 SDK 구성 요소는 다음과 같이 해당 계층에 매핑됩니다.
-| 구성 요소 | 담당 범위 | 스스로에게 물어볼 질문 | +| 구성 요소 | 소유 대상 | 확인할 질문 | | --- | --- | --- | -| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 에이전트 정의 | 이 에이전트는 무엇을 해야 하며, 어떤 기본값이 함께 따라가야 하는가? | -| [`Manifest`][agents.sandbox.manifest.Manifest] | 새 세션 워크스페이스 파일 및 폴더 | 실행이 시작될 때 파일시스템에 어떤 파일과 폴더가 있어야 하는가? | -| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 샌드박스 고유 동작 | 어떤 도구, 지시문 조각, 또는 런타임 동작을 이 에이전트에 연결해야 하는가? | +| [`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] | 새 샌드박스 세션용 저장된 워크스페이스 콘텐츠 | 새 샌드박스 세션을 저장된 파일과 아티팩트에서 시작해야 하는가? | +| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 명시적인 직렬화된 샌드박스 세션 상태 | 이미 `RunState` 외부에서 직렬화한 샌드박스 상태로 재개하고 싶은가? | +| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 새로운 샌드박스 세션을 위한 저장된 워크스페이스 콘텐츠 | 새 샌드박스 세션이 저장된 파일과 아티팩트에서 시작해야 하는가? |
실용적인 설계 순서는 다음과 같습니다. -1. `Manifest`로 새 세션 워크스페이스 계약을 정의합니다. -2. `SandboxAgent`로 에이전트를 정의합니다. -3. 내장 또는 사용자 정의 기능을 추가합니다. -4. 각 실행이 샌드박스 세션을 어떻게 얻을지 `RunConfig(sandbox=SandboxRunConfig(...))`에서 결정합니다. +1. `Manifest`로 새 세션 워크스페이스 계약을 정의합니다 +2. `SandboxAgent`로 에이전트를 정의합니다 +3. 내장 또는 커스텀 기능을 추가합니다 +4. `RunConfig(sandbox=SandboxRunConfig(...))`에서 각 실행이 샌드박스 세션을 어떻게 얻을지 결정합니다 ## 샌드박스 실행 준비 방식 -실행 시점에 러너는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다. +실행 시 러너는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다. -1. `SandboxRunConfig`에서 샌드박스 세션을 확인합니다. - `session=...`를 전달하면 해당 라이브 샌드박스 세션을 재사용합니다. - 그렇지 않으면 `client=...`를 사용해 세션을 생성하거나 재개합니다. -2. 실행에 대한 실제 워크스페이스 입력을 결정합니다. - 실행이 샌드박스 세션을 주입하거나 재개하면 기존 샌드박스 상태가 우선합니다. - 그렇지 않으면 러너는 일회성 manifest override 또는 `agent.default_manifest`에서 시작합니다. - 따라서 `Manifest`만으로는 모든 실행의 최종 라이브 워크스페이스를 정의하지 않습니다. -3. 기능이 결과 manifest를 처리하도록 합니다. - 이를 통해 기능은 최종 에이전트가 준비되기 전에 파일, 마운트 또는 기타 워크스페이스 범위 동작을 추가할 수 있습니다. -4. 최종 instructions를 고정된 순서로 구성합니다. - SDK의 기본 샌드박스 프롬프트 또는 명시적으로 재정의한 경우 `base_instructions`, 그다음 `instructions`, 그다음 기능 지시문 조각, 그다음 원격 마운트 정책 텍스트, 마지막으로 렌더링된 파일시스템 트리 순서입니다. -5. 기능 도구를 라이브 샌드박스 세션에 바인딩하고, 일반적인 `Runner` API를 통해 준비된 에이전트를 실행합니다. +1. `SandboxRunConfig`에서 샌드박스 세션을 확인합니다 + `session=...`을 전달하면 해당 실제 샌드박스 세션을 재사용합니다 + 그렇지 않으면 `client=...`를 사용해 생성하거나 재개합니다 +2. 실행의 실효 워크스페이스 입력을 결정합니다 + 실행이 샌드박스 세션을 주입하거나 재개하는 경우, 기존 샌드박스 상태가 우선합니다 + 그렇지 않으면 러너는 일회성 manifest 재정의 또는 `agent.default_manifest`에서 시작합니다 + 그래서 `Manifest`만으로는 모든 실행의 최종 실제 워크스페이스를 정의하지 않습니다 +3. 기능이 결과 manifest를 처리하도록 합니다 + 이를 통해 기능은 최종 에이전트가 준비되기 전에 파일, 마운트, 또는 기타 워크스페이스 범위 동작을 추가할 수 있습니다 +4. 고정된 순서로 최종 instructions를 구성합니다 + SDK의 기본 샌드박스 프롬프트 또는 명시적으로 재정의한 `base_instructions`, 그 다음 `instructions`, 그 다음 기능 지시문 조각, 그 다음 원격 마운트 정책 텍스트, 마지막으로 렌더링된 파일시스템 트리 순입니다 +5. 기능 도구를 실제 샌드박스 세션에 바인딩하고 준비된 에이전트를 일반 `Runner` API를 통해 실행합니다 -샌드박싱은 turn의 의미를 바꾸지 않습니다. turn은 여전히 모델 단계이며, 단일 셸 명령이나 샌드박스 작업이 아닙니다. 샌드박스 측 작업과 turn 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 내부에 머물 수 있고, 다른 작업은 도구 결과, 승인 또는 또 다른 모델 단계가 필요한 기타 상태를 반환할 수 있습니다. 실질적으로는 샌드박스 작업이 발생한 후 에이전트 런타임이 또 다른 모델 응답을 필요로 할 때만 추가 turn이 소비됩니다. +샌드박싱은 턴의 의미를 바꾸지 않습니다. 턴은 여전히 단일 셸 명령이나 샌드박스 작업이 아니라 모델 단계입니다. 샌드박스 측 작업과 턴 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 안에 머무를 수 있고, 다른 작업은 도구 결과, 승인, 또는 또 다른 모델 단계가 필요한 기타 상태를 반환할 수 있습니다. 실용적으로 말하면, 샌드박스 작업이 발생한 뒤 에이전트 런타임이 또 다른 모델 응답을 필요로 할 때만 추가 턴이 소비됩니다. -이러한 준비 단계 때문에 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`가 `SandboxAgent`를 설계할 때 고려해야 할 주요 샌드박스 전용 옵션입니다. +이러한 준비 단계 때문에 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`가 `SandboxAgent`를 설계할 때 생각해야 할 주요 샌드박스 전용 옵션입니다. ## `SandboxAgent` 옵션 -일반적인 `Agent` 필드에 더해 있는 샌드박스 전용 옵션은 다음과 같습니다. +다음은 일반적인 `Agent` 필드에 더해지는 샌드박스 전용 옵션입니다.
-| 옵션 | 가장 적합한 용도 | +| 옵션 | 적절한 사용처 | | --- | --- | -| `default_manifest` | 러너가 생성하는 새 샌드박스 세션의 기본 워크스페이스 | +| `default_manifest` | 러너가 생성하는 새로운 샌드박스 세션의 기본 워크스페이스 | | `instructions` | SDK 샌드박스 프롬프트 뒤에 추가되는 역할, 워크플로, 성공 기준 | -| `base_instructions` | SDK 샌드박스 프롬프트를 대체하는 고급 escape hatch | -| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 고유 도구 및 동작 | +| `base_instructions` | SDK 샌드박스 프롬프트를 대체하는 고급 탈출구 | +| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 네이티브 도구 및 동작 | | `run_as` | 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구의 사용자 ID |
-샌드박스 클라이언트 선택, 샌드박스 세션 재사용, manifest override, 스냅샷 선택은 에이전트가 아니라 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에 속합니다. +샌드박스 클라이언트 선택, 샌드박스 세션 재사용, manifest 재정의, 스냅샷 선택은 에이전트가 아니라 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에 속합니다. ### `default_manifest` -`default_manifest`는 러너가 이 에이전트용 새 샌드박스 세션을 생성할 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 일반적으로 시작해야 하는 파일, 리포지토리, 보조 자료, 출력 디렉터리, 마운트에 사용하세요. +`default_manifest`는 러너가 이 에이전트를 위해 새로운 샌드박스 세션을 만들 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 보통 시작할 파일, 리포지토리, 도우미 자료, 출력 디렉터리, 마운트에 사용하세요. -이것은 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 재정의할 수 있으며, 재사용되거나 재개된 샌드박스 세션은 기존 워크스페이스 상태를 유지합니다. +이것은 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 재정의할 수 있고, 재사용되거나 재개된 샌드박스 세션은 기존 워크스페이스 상태를 유지합니다. ### `instructions`와 `base_instructions` -서로 다른 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 내장 샌드박스 가이드를 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다. +다양한 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 내장 샌드박스 가이드를 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다. SDK 샌드박스 기본 프롬프트를 대체하려는 경우에만 `base_instructions`를 사용하세요. 대부분의 에이전트는 이를 설정할 필요가 없습니다.
-| 다음 위치에 둘 것 | 용도 | 예시 | +| 다음에 넣기... | 용도 | 예시 | | --- | --- | --- | -| `instructions` | 에이전트의 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검토한 뒤 핸드오프합니다.", "최종 파일은 `output/`에 작성합니다." | -| `base_instructions` | SDK 샌드박스 기본 프롬프트를 완전히 대체 | 사용자 정의 저수준 샌드박스 래퍼 프롬프트 | -| 사용자 프롬프트 | 이 실행에 대한 일회성 요청 | "이 워크스페이스를 요약하세요." | -| manifest의 워크스페이스 파일 | 더 긴 작업 사양, 리포지토리 로컬 instructions, 또는 범위가 제한된 참고 자료 | `repo/task.md`, 문서 번들, 샘플 패킷 | +| `instructions` | 에이전트의 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검토한 뒤 핸드오프하세요.", "최종 파일을 `output/`에 작성하세요." | +| `base_instructions` | SDK 샌드박스 기본 프롬프트의 완전한 대체 | 커스텀 저수준 샌드박스 래퍼 프롬프트 | +| 사용자 프롬프트 | 이번 실행을 위한 일회성 요청 | "이 워크스페이스를 요약하세요." | +| manifest의 워크스페이스 파일 | 더 긴 작업 명세, 리포지토리 로컬 instructions, 또는 범위가 제한된 참조 자료 | `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`에 복사해 넣거나, manifest에 들어가야 할 긴 참고 자료를 포함하거나, 내장 기능이 이미 주입하는 도구 문서를 반복하거나, 모델이 실행 시점에 필요로 하지 않는 로컬 설치 메모를 섞는 것은 피하세요. +사용자의 일회성 작업을 `instructions`에 복사하거나, manifest에 들어가야 할 긴 참조 자료를 포함하거나, 내장 기능이 이미 주입하는 도구 문서를 반복하거나, 모델이 실행 시점에 필요로 하지 않는 로컬 설치 메모를 섞어 넣는 것은 피하세요. -`instructions`를 생략해도 SDK는 여전히 기본 샌드박스 프롬프트를 포함합니다. 이는 저수준 래퍼에는 충분하지만, 대부분의 사용자 대상 에이전트는 여전히 명시적인 `instructions`를 제공해야 합니다. +`instructions`를 생략해도 SDK는 기본 샌드박스 프롬프트를 포함합니다. 저수준 래퍼에는 이것만으로 충분하지만, 대부분의 사용자 대상 에이전트는 여전히 명시적인 `instructions`를 제공하는 것이 좋습니다. ### `capabilities` -기능은 샌드박스 고유 동작을 `SandboxAgent`에 연결합니다. 실행 시작 전에 워크스페이스를 구성하고, 샌드박스 전용 instructions를 추가하고, 라이브 샌드박스 세션에 바인딩되는 도구를 노출하며, 해당 에이전트의 모델 동작이나 입력 처리를 조정할 수 있습니다. +Capabilities는 샌드박스 네이티브 동작을 `SandboxAgent`에 부착합니다. 실행 시작 전 워크스페이스를 구성하고, 샌드박스 전용 instructions를 추가하며, 실제 샌드박스 세션에 바인딩되는 도구를 노출하고, 해당 에이전트의 모델 동작이나 입력 처리를 조정할 수 있습니다. 내장 기능에는 다음이 포함됩니다.
-| 기능 | 추가할 시점 | 참고 | +| Capability | 추가할 시점 | 참고 | | --- | --- | --- | | `Shell` | 에이전트에 셸 접근이 필요할 때 | `exec_command`를 추가하며, 샌드박스 클라이언트가 PTY 상호작용을 지원하면 `write_stdin`도 추가합니다 | -| `Filesystem` | 에이전트가 파일을 편집하거나 로컬 이미지를 검사해야 할 때 | `apply_patch`와 `view_image`를 추가합니다. 패치 경로는 워크스페이스 루트 기준 상대 경로입니다 | -| `Skills` | 샌드박스에서 스킬 검색과 materialization이 필요할 때 | 샌드박스 로컬 `SKILL.md` 스킬에는 `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 것보다 이 방식을 권장합니다 | -| `Memory` | 후속 실행에서 메모리 아티팩트를 읽거나 생성해야 할 때 | `Shell`이 필요하며, 라이브 업데이트에는 `Filesystem`도 필요합니다 | -| `Compaction` | 장기 실행 흐름에서 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=[...]`를 전달하면 그 목록이 기본값을 대체하므로, 여전히 원하는 기본 기능이 있다면 함께 포함해야 합니다. -스킬의 경우, materialization 방식을 기준으로 소스를 선택하세요. +스킬의 경우, 구체화 방식을 기준으로 소스를 선택하세요. -- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 모델이 먼저 인덱스를 탐색하고 필요한 것만 로드할 수 있으므로 큰 로컬 스킬 디렉터리에 적합한 기본 선택입니다. -- `Skills(from_=LocalDir(src=...))`는 작고 로컬인 번들을 미리 스테이징하고 싶을 때 더 적합합니다. -- `Skills(from_=GitRepo(repo=..., ref=...))`는 스킬 자체를 리포지토리에서 가져와야 할 때 적합합니다. +- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 더 큰 로컬 스킬 디렉터리에 적합한 기본 선택입니다. 모델이 먼저 인덱스를 탐색하고 필요한 것만 로드할 수 있기 때문입니다 +- `LocalDirLazySkillSource(source=LocalDir(src=...))`는 SDK 프로세스가 실행 중인 파일시스템에서 읽습니다. 샌드박스 이미지나 워크스페이스 내부에만 존재하는 경로가 아니라 원래 호스트 측 스킬 디렉터리를 전달하세요 +- `Skills(from_=LocalDir(src=...))`는 미리 단계적으로 올려두고 싶은 작은 로컬 번들에 더 적합합니다 +- `Skills(from_=GitRepo(repo=..., ref=...))`는 스킬 자체가 리포지토리에서 와야 할 때 적합합니다 -스킬이 이미 `.agents/skills//SKILL.md` 같은 경로 아래 디스크에 있다면, `LocalDir(...)`를 해당 소스 루트로 지정하고 여전히 `Skills(...)`를 사용해 이를 노출하세요. 샌드박스 내부 레이아웃이 다른 기존 워크스페이스 계약에 의존하지 않는 한, 기본 `skills_path=".agents"`를 유지하세요. +`LocalDir.src`는 SDK 호스트의 소스 경로입니다. `skills_path`는 `load_skill`이 호출될 때 스킬이 배치되는 샌드박스 워크스페이스 내부의 상대 대상 경로입니다. -적합하다면 내장 기능을 우선 사용하세요. 내장 기능으로 다루지 못하는 샌드박스 전용 도구 또는 instructions 표면이 필요할 때만 사용자 정의 기능을 작성하세요. +스킬이 이미 `.agents/skills//SKILL.md` 같은 형태로 디스크에 있다면, `LocalDir(...)`는 해당 소스 루트를 가리키게 하고, 노출에는 여전히 `Skills(...)`를 사용하세요. 기존 워크스페이스 계약이 다른 샌드박스 내부 레이아웃에 의존하지 않는 한 기본 `skills_path=".agents"`를 유지하세요. + +적합하다면 내장 기능을 우선 사용하세요. 내장 기능으로 다루지 못하는 샌드박스 전용 도구나 지시문 표면이 필요할 때만 커스텀 capability를 작성하세요. ## 개념 ### Manifest -[`Manifest`][agents.sandbox.manifest.Manifest]는 새 샌드박스 세션의 워크스페이스를 설명합니다. 워크스페이스 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사해 넣고, Git 리포지토리를 복제하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자나 그룹을 정의하고, 워크스페이스 외부의 특정 절대 경로에 대한 접근 권한을 부여할 수 있습니다. +[`Manifest`][agents.sandbox.manifest.Manifest]는 새로운 샌드박스 세션의 워크스페이스를 설명합니다. 워크스페이스 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사하고, Git 리포지토리를 클론하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자나 그룹을 정의하고, 워크스페이스 외부의 특정 절대 경로에 대한 접근을 부여할 수 있습니다. -Manifest 항목 경로는 워크스페이스 기준 상대 경로입니다. 절대 경로일 수 없고 `..`를 사용해 워크스페이스를 벗어날 수도 없습니다. 이를 통해 워크스페이스 계약은 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다. +Manifest 항목 경로는 워크스페이스 상대 경로입니다. 절대 경로일 수 없고 `..`로 워크스페이스를 벗어날 수도 없으므로, 워크스페이스 계약은 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다. 작업 시작 전에 에이전트가 필요로 하는 자료에는 manifest 항목을 사용하세요. @@ -230,18 +233,18 @@ Manifest 항목 경로는 워크스페이스 기준 상대 경로입니다. 절 | Manifest 항목 | 용도 | | --- | --- | -| `File`, `Dir` | 작은 합성 입력, 보조 파일, 또는 출력 디렉터리 | -| `LocalFile`, `LocalDir` | 샌드박스 안으로 materialization되어야 하는 호스트 파일 또는 디렉터리 | +| `File`, `Dir` | 작은 합성 입력, 도우미 파일, 또는 출력 디렉터리 | +| `LocalFile`, `LocalDir` | 샌드박스에 구체화되어야 하는 호스트 파일 또는 디렉터리 | | `GitRepo` | 워크스페이스로 가져와야 하는 리포지토리 | | `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount` 같은 mounts | 샌드박스 내부에 나타나야 하는 외부 스토리지 | -마운트 항목은 어떤 스토리지를 노출할지 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 어떻게 연결할지 설명합니다. 마운트 옵션과 공급자 지원은 [Sandbox clients](clients.md#mounts-and-remote-storage)를 참고하세요. +Mount 항목은 노출할 스토리지를 설명하고, mount 전략은 샌드박스 백엔드가 해당 스토리지를 어떻게 연결할지 설명합니다. 마운트 옵션과 제공업체 지원은 [Sandbox clients](clients.md#mounts-and-remote-storage)를 참고하세요. -좋은 manifest 설계는 보통 워크스페이스 계약을 좁게 유지하고, 긴 작업 지침은 `repo/task.md` 같은 워크스페이스 파일에 넣고, instructions에서는 예를 들어 `repo/task.md` 또는 `output/report.md`처럼 워크스페이스 기준 상대 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` 기능의 `apply_patch` 도구로 파일을 편집하는 경우, 패치 경로는 셸 `workdir`가 아니라 샌드박스 워크스페이스 루트 기준 상대 경로라는 점을 기억하세요. +좋은 manifest 설계는 보통 워크스페이스 계약을 좁게 유지하고, 긴 작업 절차는 `repo/task.md` 같은 워크스페이스 파일에 넣고, instructions에서는 `repo/task.md`나 `output/report.md`처럼 상대 워크스페이스 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` capability의 `apply_patch` 도구로 파일을 편집한다면, 패치 경로는 셸 `workdir`이 아니라 샌드박스 워크스페이스 루트 기준 상대 경로임을 기억하세요. -에이전트가 워크스페이스 밖의 구체적인 절대 경로가 필요할 때만 `extra_path_grants`를 사용하세요. 예를 들어 임시 도구 출력용 `/tmp`나 읽기 전용 런타임용 `/opt/toolchain` 등이 해당합니다. grant는 백엔드가 파일시스템 정책을 강제할 수 있는 경우 SDK 파일 API와 셸 실행 모두에 적용됩니다. +에이전트가 워크스페이스 외부의 구체적인 절대 경로가 필요할 때만 `extra_path_grants`를 사용하세요. 예를 들어 임시 도구 출력을 위한 `/tmp`나 읽기 전용 런타임을 위한 `/opt/toolchain` 등이 있습니다. 권한 부여는 백엔드가 파일시스템 정책을 강제할 수 있는 SDK 파일 API와 셸 실행 모두에 적용됩니다. ```python from agents.sandbox import Manifest, SandboxPathGrant @@ -254,13 +257,13 @@ manifest = Manifest( ) ``` -스냅샷과 `persist_workspace()`는 여전히 워크스페이스 루트만 포함합니다. 추가로 부여된 경로는 런타임 접근 권한일 뿐, 영구적인 워크스페이스 상태가 아닙니다. +스냅샷과 `persist_workspace()`는 여전히 워크스페이스 루트만 포함합니다. 추가로 부여된 경로는 런타임 접근이지, 지속되는 워크스페이스 상태가 아닙니다. ### 권한 -`Permissions`는 manifest 항목의 파일시스템 권한을 제어합니다. 이는 샌드박스가 materialization하는 파일에 관한 것이며, 모델 권한, 승인 정책, API 자격 증명에 관한 것이 아닙니다. +`Permissions`는 manifest 항목의 파일시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 대한 것이며, 모델 권한, 승인 정책, API 자격 증명에 대한 것이 아닙니다. -기본적으로 manifest 항목은 소유자에게 읽기/쓰기/실행 권한이 있고, 그룹과 기타 사용자에게 읽기/실행 권한이 있습니다. 스테이징된 파일을 비공개, 읽기 전용, 또는 실행 가능하게 해야 한다면 이를 재정의하세요. +기본적으로 manifest 항목은 소유자 읽기/쓰기/실행 가능, 그룹과 기타 사용자 읽기/실행 가능입니다. 단계적으로 올린 파일을 비공개, 읽기 전용, 또는 실행 가능으로 해야 할 때 이를 재정의하세요. ```python from agents.sandbox import FileMode, Permissions @@ -276,9 +279,9 @@ private_notes = File( ) ``` -`Permissions`는 소유자, 그룹, 기타 사용자별 비트와 해당 항목이 디렉터리인지 여부를 별도로 저장합니다. 직접 구성할 수도 있고, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나 `Permissions.from_mode(...)`로 OS 모드에서 파생할 수도 있습니다. +`Permissions`는 소유자, 그룹, 기타에 대한 개별 비트와 해당 항목이 디렉터리인지 여부를 저장합니다. 직접 구성할 수도 있고, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나, `Permissions.from_mode(...)`로 OS 모드에서 파생할 수도 있습니다. -사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 해당 ID가 샌드박스 안에 존재해야 한다면 manifest에 `User`를 추가한 뒤, 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구가 그 사용자로 실행되도록 `SandboxAgent.run_as`를 설정하세요. `run_as`가 manifest에 아직 없는 사용자를 가리키면 러너가 이를 자동으로 실제 manifest에 추가합니다. +사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 해당 ID가 샌드박스에 존재하도록 하려면 manifest에 `User`를 추가하고, 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구를 해당 사용자로 실행하려면 `SandboxAgent.run_as`를 설정하세요. `run_as`가 manifest에 아직 없는 사용자를 가리키면 러너가 이를 실효 manifest에 자동으로 추가합니다. ```python from agents import Runner @@ -330,13 +333,13 @@ result = await Runner.run( ) ``` -파일 수준 공유 규칙도 필요하다면, 사용자를 manifest 그룹 및 항목의 `group` 메타데이터와 함께 결합하세요. `run_as` 사용자는 샌드박스 고유 작업을 누가 실행하는지를 제어하고, `Permissions`는 샌드박스가 워크스페이스를 materialization한 뒤 해당 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지를 제어합니다. +파일 수준 공유 규칙도 필요하다면, 사용자와 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 @@ -353,13 +356,13 @@ run_config = RunConfig( ) ``` -러너가 새 샌드박스 세션을 생성하면 샌드박스 클라이언트는 해당 세션용 스냅샷 인스턴스를 생성합니다. 시작 시 스냅샷을 복원할 수 있으면 실행이 계속되기 전에 저장된 워크스페이스 콘텐츠를 복원합니다. 정리 시 러너가 소유한 샌드박스 세션은 워크스페이스를 아카이브하고 스냅샷을 통해 다시 영속화합니다. +러너가 새로운 샌드박스 세션을 만들면 샌드박스 클라이언트는 해당 세션을 위한 스냅샷 인스턴스를 생성합니다. 시작 시 스냅샷이 복원 가능하면, 샌드박스는 실행이 계속되기 전에 저장된 워크스페이스 콘텐츠를 복원합니다. 정리 시 러너가 소유한 샌드박스 세션은 워크스페이스를 아카이브하고 스냅샷을 통해 다시 저장합니다. -`snapshot`을 생략하면 런타임은 가능할 경우 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 이를 설정할 수 없으면 no-op 스냅샷으로 대체합니다. 마운트된 경로와 임시 경로는 영구 워크스페이스 콘텐츠로 스냅샷에 복사되지 않습니다. +`snapshot`을 생략하면 런타임은 가능할 경우 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 이를 설정할 수 없으면 no-op 스냅샷으로 대체됩니다. 마운트된 경로와 임시 경로는 지속 워크스페이스 콘텐츠로 스냅샷에 복사되지 않습니다. -### 샌드박스 수명 주기 +### 샌드박스 수명주기 -수명 주기 모드는 두 가지입니다. **SDK 소유**와 **개발자 소유**입니다. +수명주기 모드는 두 가지입니다. **SDK 소유**와 **개발자 소유**입니다.
@@ -387,7 +390,7 @@ sequenceDiagram
-샌드박스가 한 번의 실행 동안만 살아 있으면 SDK 소유 수명 주기를 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 러너가 샌드박스를 생성하거나 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 워크스페이스 상태를 영속화하고, 샌드박스를 종료하고, 클라이언트가 러너 소유 리소스를 정리하도록 합니다. +샌드박스가 한 번의 실행 동안만 살아 있으면 SDK 소유 수명주기를 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 러너가 샌드박스를 생성 또는 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 워크스페이스 상태를 저장하고, 샌드박스를 종료하고, 클라이언트가 러너 소유 리소스를 정리하도록 합니다. ```python result = await Runner.run( @@ -399,7 +402,7 @@ result = await Runner.run( ) ``` -샌드박스를 미리 생성하거나, 하나의 라이브 샌드박스를 여러 실행에서 재사용하거나, 실행 후 파일을 검사하거나, 직접 만든 샌드박스에서 스트리밍하거나, 정리 시점을 정확히 제어하고 싶다면 개발자 소유 수명 주기를 사용하세요. `session=...`를 전달하면 러너는 해당 라이브 샌드박스를 사용하지만, 이를 대신 닫아주지는 않습니다. +샌드박스를 미리 생성하거나, 여러 실행에 걸쳐 하나의 실제 샌드박스를 재사용하거나, 실행 후 파일을 검사하거나, 직접 생성한 샌드박스에 대해 스트리밍하거나, 정리 시점을 정확히 제어하려면 개발자 소유 수명주기를 사용하세요. `session=...`을 전달하면 러너가 해당 실제 샌드박스를 사용하지만, 이를 대신 닫지는 않습니다. ```python sandbox = await client.create(manifest=agent.default_manifest) @@ -410,7 +413,7 @@ async with sandbox: await Runner.run(agent, "Write the final report.", run_config=run_config) ``` -컨텍스트 매니저가 일반적인 형태입니다. 진입 시 샌드박스를 시작하고 종료 시 세션 정리 수명 주기를 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 수명 주기 메서드를 직접 호출하세요. +컨텍스트 매니저가 일반적인 형태입니다. 진입 시 샌드박스를 시작하고 종료 시 세션 정리 수명주기를 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 수명주기 메서드를 직접 호출하세요. ```python sandbox = await client.create( @@ -431,62 +434,62 @@ finally: await sandbox.aclose() ``` -`stop()`은 스냅샷 기반 워크스페이스 콘텐츠만 영속화하며, 샌드박스를 해제하지는 않습니다. `aclose()`는 전체 세션 정리 경로입니다. pre-stop hooks를 실행하고, `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` | 일회성 새 세션 워크스페이스 override가 필요할 때 | 생략 시 `agent.default_manifest`로 대체됩니다 | -| `snapshot` | 새 샌드박스 세션을 스냅샷에서 초기화해야 할 때 | 재개와 유사한 흐름이나 원격 스냅샷 클라이언트에 유용합니다 | +| `manifest` | 일회성 새 세션 워크스페이스 재정의가 필요할 때 | 생략 시 `agent.default_manifest`로 대체됩니다 | +| `snapshot` | 새 샌드박스 세션이 스냅샷에서 시드되어야 할 때 | 재개 유사 흐름이나 원격 스냅샷 클라이언트에 유용합니다 | | `options` | 샌드박스 클라이언트에 생성 시점 옵션이 필요할 때 | Docker 이미지, Modal 앱 이름, E2B 템플릿, 타임아웃 등 클라이언트별 설정에 흔히 사용됩니다 |
-### materialization 제어 +### 구체화 제어 -`concurrency_limits`는 얼마나 많은 샌드박스 materialization 작업을 병렬로 실행할 수 있을지 제어합니다. 큰 manifest나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요하다면 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요. +`concurrency_limits`는 얼마나 많은 샌드박스 구체화 작업을 병렬로 실행할 수 있는지 제어합니다. 큰 manifest나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요할 때 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요. -유념할 만한 몇 가지 사항은 다음과 같습니다. +기억해 둘 만한 몇 가지 의미는 다음과 같습니다. -- 새 세션: `manifest=`와 `snapshot=`은 러너가 새 샌드박스 세션을 생성할 때만 적용됩니다 -- 재개와 스냅샷: `session_state=`는 이전에 직렬화한 샌드박스 상태에 다시 연결하고, `snapshot=`은 저장된 워크스페이스 콘텐츠에서 새 샌드박스 세션을 초기화합니다 +- 새로운 세션: `manifest=`와 `snapshot=`은 러너가 새로운 샌드박스 세션을 만들 때만 적용됩니다 +- 재개 vs 스냅샷: `session_state=`는 이전에 직렬화된 샌드박스 상태에 재연결하고, `snapshot=`은 저장된 워크스페이스 콘텐츠에서 새로운 샌드박스 세션을 시드합니다 - 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 다르며, Docker와 많은 호스티드 클라이언트는 이를 요구합니다 -- 주입된 라이브 세션: 실행 중인 샌드박스 `session`을 전달하면 기능 기반 manifest 업데이트는 호환되는 비마운트 항목을 추가할 수 있습니다. 하지만 `manifest.root`, `manifest.environment`, `manifest.users`, `manifest.groups`를 변경하거나, 기존 항목을 제거하거나, 항목 유형을 교체하거나, 마운트 항목을 추가 또는 변경할 수는 없습니다 -- 러너 API: `SandboxAgent` 실행은 여전히 일반적인 `Runner.run()`, `Runner.run_sync()`, `Runner.run_streamed()` API를 사용합니다 +- 주입된 실제 세션: 실행 중인 샌드박스 `session`을 전달하면 capability 기반 manifest 업데이트는 호환 가능한 비마운트 항목을 추가할 수 있습니다. 하지만 `manifest.root`, `manifest.environment`, `manifest.users`, `manifest.groups`를 변경하거나, 기존 항목을 제거하거나, 항목 유형을 교체하거나, 마운트 항목을 추가 또는 변경할 수는 없습니다 +- 러너 API: `SandboxAgent` 실행은 여전히 일반 `Runner.run()`, `Runner.run_sync()`, `Runner.run_streamed()` API를 사용합니다 -## 전체 예제: 코딩 작업 +## 전체 예시: 코딩 작업 -이 코딩 스타일 예제는 기본 시작점으로 적합합니다. +이 코딩 스타일 예시는 시작점으로 적합한 기본 예시입니다. ```python import asyncio @@ -529,9 +532,10 @@ def build_agent(model: str) -> SandboxAgent[None]: } ), capabilities=Capabilities.default() + [ - # Let Skills(...) stage and index sandbox-local skills for you. Skills( lazy_from=LocalDirLazySkillSource( + # This is a host path read by the SDK process. + # Requested skills are copied into `skills_path` in the sandbox. source=LocalDir(src=HOST_SKILLS_DIR), ) ), @@ -564,19 +568,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를 사용하고, 공급자 관리 실행이 필요하면 호스티드 공급자를 사용하세요. 예시와 공급자 옵션은 [Sandbox clients](clients.md)를 참고하세요. +에이전트 정의는 그대로 두고 실행 구성만 변경하세요. 컨테이너 격리나 이미지 일치성이 필요하면 Docker를 사용하고, 제공업체 관리 실행이 필요하면 호스티드 제공업체를 사용하세요. 예시와 제공업체 옵션은 [Sandbox clients](clients.md)를 참고하세요. ### 워크스페이스 재정의 -에이전트 정의는 그대로 두고 새 세션 manifest만 교체하세요. +에이전트 정의는 그대로 두고 새로운 세션 manifest만 교체하세요. ```python from agents.run import RunConfig @@ -596,11 +600,11 @@ run_config = RunConfig( ) ``` -동일한 에이전트 역할을 서로 다른 리포지토리, 패킷 또는 작업 번들에 대해 에이전트를 다시 만들지 않고 실행해야 할 때 사용하세요. 위의 검증된 코딩 예제는 일회성 override 대신 `default_manifest`를 사용하는 동일한 패턴을 보여줍니다. +동일한 에이전트 역할을 다른 리포지토리, 패킷, 또는 작업 번들에 대해 실행하되 에이전트를 다시 만들고 싶지 않을 때 사용하세요. 위의 검증된 코딩 예시는 일회성 재정의 대신 `default_manifest`로 같은 패턴을 보여줍니다. ### 샌드박스 세션 주입 -명시적인 수명 주기 제어, 실행 후 검사, 또는 출력 복사가 필요하다면 라이브 샌드박스 세션을 주입하세요. +명시적인 수명주기 제어, 실행 후 검사, 또는 출력 복사가 필요할 때 실제 샌드박스 세션을 주입하세요. ```python from agents import Runner @@ -621,11 +625,11 @@ async with sandbox: ) ``` -실행 후 워크스페이스를 검사하거나 이미 시작된 샌드박스 세션에서 스트리밍하고 싶을 때 사용하세요. [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 및 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요. +실행 후 워크스페이스를 검사하거나 이미 시작된 샌드박스 세션에 대해 스트리밍하고 싶을 때 사용하세요. [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)와 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요. ### 세션 상태에서 재개 -이미 `RunState` 외부에서 샌드박스 상태를 직렬화했다면 러너가 해당 상태에서 다시 연결하도록 하세요. +이미 `RunState` 외부에서 샌드박스 상태를 직렬화했다면, 러너가 해당 상태에서 재연결하도록 하세요. ```python from agents.run import RunConfig @@ -642,11 +646,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`가 그 상태에서 직접 재개하기를 원할 때 사용하세요. serialize/deserialize 흐름은 [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 @@ -667,7 +671,7 @@ run_config = RunConfig( ### Git에서 스킬 로드 -로컬 스킬 소스를 리포지토리 기반 소스로 교체합니다. +로컬 스킬 소스를 리포지토리 기반 소스로 교체하세요. ```python from agents.sandbox.capabilities import Capabilities, Skills @@ -678,11 +682,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)를 참고하세요. ### 도구로 노출 -도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고 부모 실행의 라이브 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색 에이전트에 유용합니다. 별도의 샌드박스를 생성, hydration, 스냅샷하는 비용 없이 부모가 사용하는 정확한 워크스페이스를 검사할 수 있기 때문입니다. +도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고, 부모 실행의 실제 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색 에이전트에 유용합니다. 다른 샌드박스를 생성, 구체화, 스냅샷하는 비용 없이 부모가 사용하는 정확한 워크스페이스를 검사할 수 있기 때문입니다. ```python from agents import Runner @@ -764,9 +768,9 @@ async with sandbox: ) ``` -여기서 부모 에이전트는 `coordinator`로 실행되고, 탐색기 도구 에이전트는 동일한 라이브 샌드박스 세션 안에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색기가 이를 빠르게 검사할 수 있지만 쓰기 비트는 없습니다. `work/` 디렉터리는 coordinator의 사용자/그룹만 사용할 수 있으므로 부모는 최종 아티팩트를 쓸 수 있고 탐색기는 읽기 전용으로 유지됩니다. +여기서 부모 에이전트는 `coordinator`로 실행되고, 탐색기 도구 에이전트는 동일한 실제 샌드박스 세션 내부에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색기는 이를 빠르게 검사할 수 있지만 쓰기 비트는 없습니다. `work/` 디렉터리는 coordinator의 사용자/그룹에만 제공되므로 부모는 최종 아티팩트를 쓸 수 있고 탐색기는 읽기 전용으로 유지됩니다. -대신 도구 에이전트에 실제 격리가 필요하다면 자체 샌드박스 `RunConfig`를 제공하세요. +도구 에이전트에 실제 격리가 필요하다면 대신 자체 샌드박스 `RunConfig`를 제공하세요. ```python from docker import from_env as docker_from_env @@ -791,7 +795,7 @@ rollout_agent.as_tool( ### 로컬 도구 및 MCP와 결합 -동일한 에이전트에서 일반 도구를 계속 사용하면서 샌드박스 워크스페이스도 유지할 수 있습니다. +동일한 에이전트에서 일반 도구를 계속 사용하면서 샌드박스 워크스페이스를 유지하세요. ```python from agents.sandbox import SandboxAgent @@ -806,46 +810,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` capability를 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와는 별개입니다. 샌드박스 워크스페이스 내부의 파일로 교훈을 추출하고, 이후 실행에서 해당 파일을 읽을 수 있습니다. -설정, 읽기/생성 동작, 멀티턴 대화, 레이아웃 격리는 [Agent memory](memory.md)를 참고하세요. +설정, 읽기/생성 동작, 다중 턴 대화, 레이아웃 격리는 [Agent memory](memory.md)를 참고하세요. ## 구성 패턴 -단일 에이전트 패턴이 명확해지면, 다음 설계 질문은 더 큰 시스템에서 샌드박스 경계를 어디에 둘 것인가입니다. +단일 에이전트 패턴이 명확해지면, 다음 설계 질문은 더 큰 시스템에서 샌드박스 경계를 어디에 둘지입니다. 샌드박스 에이전트는 여전히 SDK의 나머지 부분과 조합할 수 있습니다. -- [Handoffs](../handoffs.md): 샌드박스가 아닌 intake 에이전트에서 문서 중심 작업을 샌드박스 리뷰어로 핸드오프합니다 -- [Agents as tools](../tools.md#agents-as-tools): 여러 샌드박스 에이전트를 도구로 노출합니다. 일반적으로 각 도구가 자체 샌드박스 경계를 갖도록 각 `Agent.as_tool(...)` 호출에 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`를 전달합니다 -- [MCP](../mcp.md) 및 일반 함수 도구: 샌드박스 기능은 `mcp_servers` 및 일반 Python 도구와 공존할 수 있습니다 -- [Running agents](../running_agents.md): 샌드박스 실행도 여전히 일반적인 `Runner` API를 사용합니다 +- [Handoffs](../handoffs.md): 샌드박스가 아닌 접수 에이전트에서 문서 중심 작업을 샌드박스 리뷰어로 넘깁니다 +- [Agents as tools](../tools.md#agents-as-tools): 여러 샌드박스 에이전트를 도구로 노출합니다. 보통 각 `Agent.as_tool(...)` 호출에 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`를 전달해 각 도구가 자체 샌드박스 경계를 갖도록 합니다 +- [MCP](../mcp.md) 및 일반 함수 도구: 샌드박스 capability는 `mcp_servers` 및 일반 Python 도구와 공존할 수 있습니다 +- [Running agents](../running_agents.md): 샌드박스 실행도 여전히 일반 `Runner` API를 사용합니다 특히 흔한 패턴은 두 가지입니다. -- 워크스페이스 격리가 필요한 워크플로의 일부에 대해서만 샌드박스가 아닌 에이전트가 샌드박스 에이전트로 핸드오프하는 패턴 -- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출하는 패턴으로, 보통 각 도구가 자체 격리 워크스페이스를 갖도록 각 `Agent.as_tool(...)` 호출마다 별도의 샌드박스 `RunConfig`를 사용합니다 +- 샌드박스가 아닌 에이전트가 워크스페이스 격리가 필요한 워크플로의 일부에 대해서만 샌드박스 에이전트로 핸드오프하는 패턴 +- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출하는 패턴. 보통 각 `Agent.as_tool(...)` 호출에 별도의 샌드박스 `RunConfig`를 두어 각 도구가 자체 격리 워크스페이스를 갖게 합니다 -### Turns와 샌드박스 실행 +### 턴과 샌드박스 실행 핸드오프와 agent-as-tool 호출은 별도로 설명하는 것이 도움이 됩니다. -핸드오프에서는 여전히 하나의 최상위 실행과 하나의 최상위 turn 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 샌드박스가 아닌 intake 에이전트가 샌드박스 리뷰어로 핸드오프하면, 같은 실행에서 다음 모델 호출은 샌드박스 에이전트에 맞게 준비되고, 그 샌드박스 에이전트가 다음 turn을 수행하는 주체가 됩니다. 즉, 핸드오프는 같은 실행의 다음 turn을 어떤 에이전트가 담당할지 바꿉니다. [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(...)`에서는 관계가 다릅니다. 바깥쪽 오케스트레이터는 하나의 바깥쪽 turn을 사용해 도구 호출을 결정하고, 그 도구 호출은 샌드박스 에이전트에 대한 중첩 실행을 시작합니다. 중첩 실행은 자체 turn 루프, `max_turns`, 승인, 그리고 보통 자체 샌드박스 `RunConfig`를 가집니다. 한 번의 중첩 turn으로 끝날 수도 있고 여러 번 걸릴 수도 있습니다. 바깥쪽 오케스트레이터 관점에서는 이 모든 작업이 여전히 하나의 도구 호출 뒤에 있으므로, 중첩된 turns는 바깥쪽 실행의 turn 카운터를 증가시키지 않습니다. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참고하세요. +`Agent.as_tool(...)`에서는 관계가 다릅니다. 외부 오케스트레이터는 하나의 외부 턴을 사용해 도구 호출을 결정하고, 그 도구 호출은 샌드박스 에이전트에 대한 중첩 실행을 시작합니다. 중첩 실행은 자체 턴 루프, `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](quickstart.md): 하나의 샌드박스 에이전트를 실행합니다 -- [Sandbox clients](clients.md): 로컬, Docker, 호스티드, 마운트 옵션을 선택합니다 -- [Agent memory](memory.md): 이전 샌드박스 실행의 교훈을 보존하고 재사용합니다 -- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 실행 가능한 로컬, 코딩, 메모리, 핸드오프, 에이전트 구성 패턴 \ No newline at end of file +- [Quickstart](quickstart.md): 샌드박스 에이전트 하나를 실행해 보기 +- [Sandbox clients](clients.md): 로컬, Docker, 호스티드, 마운트 옵션 선택 +- [Agent memory](memory.md): 이전 샌드박스 실행의 교훈을 보존하고 재사용하기 +- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 실행 가능한 로컬, 코딩, 메모리, 핸드오프, 에이전트 조합 패턴 \ No newline at end of file diff --git a/docs/ko/sandbox_agents.md b/docs/ko/sandbox_agents.md index c0141dc2b7..2382de1bfa 100644 --- a/docs/ko/sandbox_agents.md +++ b/docs/ko/sandbox_agents.md @@ -6,27 +6,27 @@ search: !!! warning "베타 기능" - 샌드박스 에이전트는 베타입니다. 정식 출시 전까지 API의 세부 사항, 기본값, 지원 기능은 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 예정입니다. + 샌드박스 에이전트는 베타입니다. 정식 출시 전에 API 의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다. -현대적인 에이전트는 파일시스템의 실제 파일에서 작업할 수 있을 때 가장 잘 작동합니다. Agents SDK의 **Sandbox Agents**는 모델에 지속적인 작업공간을 제공하여 대규모 문서 집합 검색, 파일 편집, 명령 실행, 아티팩트 생성, 저장된 샌드박스 상태에서 작업 재개를 가능하게 합니다. +현대적인 에이전트는 파일시스템의 실제 파일에서 작업할 수 있을 때 가장 잘 동작합니다. Agents SDK 의 **Sandbox Agents** 는 모델에 지속적인 작업 공간을 제공하여, 대규모 문서 집합을 검색하고, 파일을 편집하고, 명령을 실행하고, 아티팩트를 생성하고, 저장된 샌드박스 상태에서 작업을 다시 이어갈 수 있게 합니다. -SDK는 파일 스테이징, 파일시스템 도구, 셸 접근, 샌드박스 수명 주기, 스냅샷, 제공자별 연결 코드를 직접 구성하지 않아도 이 실행 환경을 제공합니다. 일반적인 `Agent` 및 `Runner` 흐름을 유지하면서, 작업공간용 `Manifest`, 샌드박스 네이티브 도구용 기능, 그리고 작업 실행 위치를 지정하는 `SandboxRunConfig`를 추가하면 됩니다. +SDK 는 파일 스테이징, 파일시스템 도구, 셸 접근, 샌드박스 수명 주기, 스냅샷, 공급자별 연결 코드를 직접 조합하지 않아도 되는 실행 하네스를 제공합니다. 일반적인 `Agent` 및 `Runner` 흐름은 그대로 유지하면서, 작업 공간용 `Manifest`, 샌드박스 네이티브 도구를 위한 capabilities, 그리고 작업 실행 위치를 지정하는 `SandboxRunConfig` 를 추가하면 됩니다. -## 사전 요구 사항 +## 사전 준비 - Python 3.10 이상 -- OpenAI Agents SDK에 대한 기본적인 이해 -- 샌드박스 클라이언트. 로컬 개발의 경우 `UnixLocalSandboxClient`로 시작하세요. +- OpenAI Agents SDK 에 대한 기본적인 이해 +- 샌드박스 클라이언트. 로컬 개발에는 `UnixLocalSandboxClient` 로 시작하세요. ## 설치 -아직 SDK를 설치하지 않았다면 다음을 실행하세요. +아직 SDK 를 설치하지 않았다면: ```bash pip install openai-agents ``` -Docker 기반 샌드박스의 경우 다음을 실행하세요. +Docker 기반 샌드박스의 경우: ```bash pip install "openai-agents[docker]" @@ -34,7 +34,7 @@ pip install "openai-agents[docker]" ## 로컬 샌드박스 에이전트 생성 -이 예제는 `repo/` 아래에 로컬 리포지토리를 스테이징하고, 로컬 스킬을 지연 로드하며, 실행 시 러너가 Unix 로컬 샌드박스 세션을 생성하도록 합니다. +이 예제는 로컬 리포지토리를 `repo/` 아래에 스테이징하고, 로컬 스킬을 지연 로드하며, 러너가 실행을 위해 Unix 로컬 샌드박스 세션을 생성하도록 합니다. ```python import asyncio @@ -69,6 +69,8 @@ def build_agent(model: str) -> SandboxAgent[None]: capabilities=Capabilities.default() + [ Skills( lazy_from=LocalDirLazySkillSource( + # This is a host path read by the SDK process. + # Requested skills are copied into `skills_path` in the sandbox. source=LocalDir(src=HOST_SKILLS_DIR), ) ), @@ -92,24 +94,24 @@ if __name__ == "__main__": asyncio.run(main()) ``` -[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참고하세요. 이 예제는 작은 셸 기반 리포지토리를 사용하므로 Unix 로컬 실행 전반에서 예제를 결정적으로 검증할 수 있습니다. +[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참조하세요. 이 예제는 작은 셸 기반 리포지토리를 사용하므로, Unix 로컬 실행 전반에서 예제를 결정적으로 검증할 수 있습니다. ## 주요 선택 사항 -기본 실행이 작동하면, 다음으로 가장 많이 선택하는 항목은 다음과 같습니다. +기본 실행이 동작하기 시작하면, 대부분의 사용자가 다음으로 고려하는 선택지는 다음과 같습니다: - `default_manifest`: 새 샌드박스 세션을 위한 파일, 리포지토리, 디렉터리 및 마운트 - `instructions`: 프롬프트 전반에 적용되어야 하는 짧은 워크플로 규칙 -- `base_instructions`: SDK 샌드박스 프롬프트를 교체하기 위한 고급 이스케이프 해치 -- `capabilities`: 파일시스템 편집/이미지 검사, 셸, 스킬, 메모리, 압축(compaction) 같은 샌드박스 네이티브 도구 -- `run_as`: 모델 대응 도구를 위한 샌드박스 사용자 ID +- `base_instructions`: SDK 샌드박스 프롬프트를 대체하기 위한 고급 이스케이프 해치 +- `capabilities`: 파일시스템 편집/이미지 검사, 셸, 스킬, 메모리, 압축(compaction)과 같은 샌드박스 네이티브 도구 +- `run_as`: 모델 대면 도구에 대한 샌드박스 사용자 ID - `SandboxRunConfig.client`: 샌드박스 백엔드 - `SandboxRunConfig.session`, `session_state`, 또는 `snapshot`: 이후 실행이 이전 작업에 다시 연결되는 방식 ## 다음 단계 -- [개념](sandbox/guide.md): 매니페스트, 기능, 권한, 스냅샷, 실행 구성, 조합 패턴을 이해합니다 -- [샌드박스 클라이언트](sandbox/clients.md): Unix 로컬, Docker, 호스티드 제공자, 마운트 전략 중에서 선택합니다 -- [에이전트 메모리](sandbox/memory.md): 이전 샌드박스 실행의 학습 내용을 보존하고 재사용합니다 +- [개념](sandbox/guide.md): 매니페스트, capabilities, 권한, 스냅샷, 실행 구성, 조합 패턴을 이해합니다 +- [샌드박스 클라이언트](sandbox/clients.md): Unix 로컬, Docker, 호스티드 공급자, 마운트 전략 중에서 선택합니다 +- [에이전트 메모리](sandbox/memory.md): 이전 샌드박스 실행의 교훈을 보존하고 재사용합니다 -셸 접근이 가끔 사용하는 도구 하나일 뿐이라면 [도구 가이드](tools.md)의 호스티드 셸부터 시작하세요. 작업공간 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요. \ No newline at end of file +셸 접근이 가끔 사용하는 도구 중 하나일 뿐이라면, [도구 가이드](tools.md)의 호스티드 셸부터 시작하세요. 작업 공간 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요. \ No newline at end of file diff --git a/docs/zh/sandbox/guide.md b/docs/zh/sandbox/guide.md index cc39db6cb0..3532a82a42 100644 --- a/docs/zh/sandbox/guide.md +++ b/docs/zh/sandbox/guide.md @@ -6,35 +6,35 @@ search: !!! warning "Beta 功能" - 沙盒智能体目前处于 beta 阶段。API 的细节、默认值和支持的能力在正式可用前都可能发生变化，并且功能会随着时间推移变得更高级。 + Sandbox 智能体目前处于 beta 阶段。预计 API 的细节、默认值和支持的能力在正式可用之前都会发生变化，并且功能也会随着时间推移变得更高级。 -现代智能体在能够操作文件系统中的真实文件时效果最佳。**Sandbox Agents** 可以使用专门的工具和 shell 命令来搜索和处理大型文档集、编辑文件、生成产物以及运行命令。沙盒为模型提供了一个持久化工作区，智能体可以用它来代你完成工作。Agents SDK 中的沙盒智能体帮助你轻松运行与沙盒环境配对的智能体，使正确的文件进入文件系统变得简单，并对沙盒进行智能体编排，从而便于大规模启动、停止和恢复任务。 +现代智能体在能够对文件系统中的真实文件进行操作时效果最佳。**Sandbox 智能体**可以使用专门的工具和 shell 命令，在大型文档集合上执行检索和操作、编辑文件、生成产物以及运行命令。sandbox 为模型提供了一个持久化工作区，智能体可以利用它代表你执行工作。Agents SDK 中的 Sandbox 智能体可帮助你轻松运行与 sandbox 环境配对的智能体，从而更方便地将正确的文件放入文件系统，并编排 sandboxes，以便大规模地轻松启动、停止和恢复任务。 -你可以围绕智能体所需的数据定义工作区。它可以从 GitHub 仓库、本地文件和目录、合成任务文件、S3 或 Azure Blob Storage 等远程文件系统，以及你提供的其他沙盒输入开始。 +你可以围绕智能体所需的数据来定义工作区。它可以从 GitHub 仓库、本地文件和目录、合成任务文件、诸如 S3 或 Azure Blob Storage 之类的远程文件系统，以及你提供的其他 sandbox 输入开始。
-![带计算能力的沙盒智能体控制框架](../assets/images/harness_with_compute.png) +![带计算能力的 Sandbox 智能体运行框架](../assets/images/harness_with_compute.png)
-`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、内存或压缩等能力。 -- `Manifest` 声明全新沙盒工作区所需的初始内容和布局，包括文件、仓库、挂载和环境。 -- 沙盒会话是命令运行和文件变更发生的实时隔离环境。 -- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 决定此次运行如何获得该沙盒会话，例如直接注入一个沙盒会话、从序列化的沙盒会话状态重新连接，或通过沙盒客户端创建一个全新的沙盒会话。 -- 已保存的沙盒状态和快照使后续运行能够重新连接到先前的工作，或用保存的内容为新的沙盒会话提供初始数据。 +- `SandboxAgent` 定义智能体本身：常规的智能体配置，加上 sandbox 专属默认值，例如 `default_manifest`、`base_instructions`、`run_as`，以及文件系统工具、shell 访问、skills、memory 或 compaction 等能力。 +- `Manifest` 声明一个全新 sandbox 工作区所需的初始内容和布局，包括文件、仓库、挂载和环境。 +- sandbox session 是命令运行和文件发生变化的实时隔离环境。 +- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 决定该次运行如何获得该 sandbox session，例如直接注入一个 session、从序列化的 sandbox session 状态重连，或通过 sandbox client 创建一个新的 sandbox session。 +- 已保存的 sandbox 状态和快照允许后续运行重新连接到先前的工作，或用保存的内容为新的 sandbox session 提供初始内容。 -`Manifest` 是全新会话工作区的契约，而不是每个实时沙盒的完整事实来源。一次运行的实际工作区也可以来自复用的沙盒会话、序列化的沙盒会话状态，或在运行时选定的快照。 +`Manifest` 是全新 session 工作区的契约，而不是每个实时 sandbox 的完整事实来源。一次运行的实际工作区也可能来自复用的 sandbox session、序列化的 sandbox session 状态，或在运行时选择的快照。 -在本页中，“沙盒会话”指由沙盒客户端管理的实时执行环境。它不同于 [Sessions](../sessions/index.md) 中描述的 SDK 会话式 [`Session`][agents.memory.session.Session] 接口。 +在本页中，“sandbox session”指的是由 sandbox client 管理的实时执行环境。它不同于 [Sessions](../sessions/index.md) 中描述的 SDK 对话式 [`Session`][agents.memory.session.Session] 接口。 -外层运行时仍负责审批、追踪、任务转移和恢复记录。沙盒会话负责命令、文件变更和环境隔离。这种划分是该模型的核心组成部分。 +外层运行时仍然负责 approvals、追踪、任务转移和恢复记录。sandbox session 负责命令、文件变更和环境隔离。这种划分是该模型的核心部分。 -### 组件配合方式 +### 组件协作方式 -一次沙盒运行会将智能体定义与每次运行的沙盒配置组合起来。运行器会准备智能体，将其绑定到一个实时沙盒会话，并可为后续运行保存状态。 +一次 sandbox 运行将智能体定义与每次运行的 sandbox 配置结合起来。runner 会准备智能体，将其绑定到一个实时 sandbox session，并且可以为后续运行保存状态。 ```mermaid flowchart LR @@ -50,43 +50,43 @@ flowchart LR sandbox --> saved ``` -沙盒专属默认值保留在 `SandboxAgent` 上。每次运行的沙盒会话选择保留在 `SandboxRunConfig` 中。 +sandbox 专属默认值保留在 `SandboxAgent` 上。每次运行的 sandbox-session 选择保留在 `SandboxRunConfig` 中。 可以将生命周期理解为三个阶段： -1. 使用 `SandboxAgent`、`Manifest` 和能力定义智能体以及全新工作区契约。 -2. 通过向 `Runner` 提供一个 `SandboxRunConfig` 来执行运行，该配置用于注入、恢复或创建沙盒会话。 -3. 之后可从由运行器管理的 `RunState`、显式的沙盒 `session_state`，或已保存的工作区快照继续。 +1. 使用 `SandboxAgent`、`Manifest` 和能力来定义智能体及全新工作区契约。 +2. 通过向 `Runner` 提供一个 `SandboxRunConfig` 来执行运行，以注入、恢复或创建 sandbox session。 +3. 稍后从 runner 管理的 `RunState`、显式的 sandbox `session_state` 或已保存的工作区快照继续。 -如果 shell 访问只是偶尔使用的工具，请先从[工具指南](../tools.md)中的托管 shell 开始。只有当工作区隔离、沙盒客户端选择或沙盒会话恢复行为是设计的一部分时，再使用沙盒智能体。 +如果 shell 访问只是一个偶尔使用的工具，请从 [工具指南](../tools.md) 中的 hosted shell 开始。当工作区隔离、sandbox client 选择或 sandbox-session 恢复行为本身就是设计的一部分时，再使用 sandbox 智能体。 ## 适用场景 -沙盒智能体非常适合以工作区为中心的工作流，例如： +Sandbox 智能体非常适合以工作区为中心的工作流，例如： -- 编码与调试，例如在 GitHub 仓库中对 issue 报告进行自动修复编排并运行定向测试 -- 文档处理与编辑，例如从用户的财务文件中提取信息并创建已填写的报税表草稿 -- 基于文件的审查或分析，例如在回答前检查入职材料包、生成的报告或产物包 -- 隔离的多智能体模式，例如为每个审查者或编码子智能体提供其独立工作区 -- 多步骤工作区任务，例如一次运行中修复 bug，之后再添加回归测试，或从快照或沙盒会话状态恢复 +- 编码和调试，例如在 GitHub 仓库中编排针对 issue 报告的自动修复并运行有针对性的测试 +- 文档处理与编辑，例如从用户的财务文件中提取信息并创建一份填写完成的税表草稿 +- 基于文件的审查或分析，例如在回答之前检查入职材料包、生成的报告或产物包 +- 隔离的多智能体模式，例如为每个审查员或编码子智能体分配各自的工作区 +- 多步骤工作区任务，例如在一次运行中修复 bug，稍后再添加回归测试，或从快照或 sandbox session 状态恢复 -如果你不需要访问文件或一个活跃的文件系统，请继续使用 `Agent`。如果 shell 访问只是偶尔需要的能力，则添加托管 shell；如果工作区边界本身就是功能的一部分，则使用沙盒智能体。 +如果你不需要访问文件或一个活动中的文件系统，请继续使用 `Agent`。如果 shell 访问只是偶尔需要的一项能力，请添加 hosted shell；如果工作区边界本身就是功能的一部分，请使用 sandbox 智能体。 -## 沙盒客户端选择 +## sandbox client 选择 -本地开发时从 `UnixLocalSandboxClient` 开始。需要容器隔离或镜像一致性时，转到 `DockerSandboxClient`。需要由提供方托管执行时，转到托管提供方。 +本地开发时从 `UnixLocalSandboxClient` 开始。当你需要容器隔离或镜像一致性时，切换到 `DockerSandboxClient`。当你需要由提供方管理执行环境时，切换到托管提供方。 -在大多数情况下，`SandboxAgent` 定义保持不变，而沙盒客户端及其选项在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中变化。有关本地、Docker、托管和远程挂载选项，请参见[沙盒客户端](clients.md)。 +在大多数情况下，`SandboxAgent` 定义保持不变，而 sandbox client 及其选项在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中变化。有关本地、Docker、托管和远程挂载选项，请参见 [Sandbox clients](clients.md)。 ## 核心组件
-| 层级 | 主要 SDK 组件 | 它回答的问题 | +| 层级 | 主要 SDK 组件 | 回答的问题 | | --- | --- | --- | -| 智能体定义 | `SandboxAgent`、`Manifest`、能力 | 将运行什么智能体，它应从什么样的全新会话工作区契约开始？ | -| 沙盒执行 | `SandboxRunConfig`、沙盒客户端和实时沙盒会话 | 此次运行如何获得一个实时沙盒会话，工作将在何处执行？ | -| 已保存的沙盒状态 | `RunState` 沙盒负载、`session_state` 和快照 | 此工作流如何重新连接到先前的沙盒工作，或用保存的内容为新的沙盒会话提供初始数据？ | +| 智能体定义 | `SandboxAgent`、`Manifest`、capabilities | 将运行什么智能体，以及它应从什么样的全新 session 工作区契约开始？ | +| Sandbox 执行 | `SandboxRunConfig`、sandbox client 和实时 sandbox session | 此次运行如何获得一个实时 sandbox session，工作在哪里执行？ | +| 已保存的 sandbox 状态 | `RunState` sandbox payload、`session_state` 和 snapshots | 此工作流如何重新连接到之前的 sandbox 工作，或从已保存内容为新的 sandbox session 提供初始内容？ |
@@ -94,154 +94,157 @@ flowchart LR
-| 组件 | 它负责的内容 | 请问这个问题 | +| 组件 | 负责内容 | 请问这个问题 | | --- | --- | --- | -| [`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] | 为新的沙盒会话保存的工作区内容 | 新的沙盒会话是否应从保存的文件和产物开始？ | +| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 智能体定义 | 这个智能体应该做什么，哪些默认值应随其一同携带？ | +| [`Manifest`][agents.sandbox.manifest.Manifest] | 全新 session 工作区文件和文件夹 | 运行开始时，文件系统中应存在哪些文件和文件夹？ | +| [`Capability`][agents.sandbox.capabilities.capability.Capability] | sandbox 原生行为 | 哪些工具、instruction 片段或运行时行为应附加到此智能体？ | +| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 每次运行的 sandbox client 和 sandbox-session 来源 | 此次运行应注入、恢复，还是创建一个 sandbox session？ | +| [`RunState`][agents.run_state.RunState] | runner 管理的已保存 sandbox 状态 | 我是否正在恢复一个先前由 runner 管理的工作流，并自动延续其 sandbox 状态？ | +| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 显式序列化的 sandbox session 状态 | 我是否希望从已经在 `RunState` 之外序列化的 sandbox 状态恢复？ | +| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 用于全新 sandbox sessions 的已保存工作区内容 | 新的 sandbox session 是否应从已保存文件和产物开始？ |
一个实用的设计顺序是： -1. 使用 `Manifest` 定义全新会话工作区契约。 -2. 使用 `SandboxAgent` 定义智能体。 +1. 用 `Manifest` 定义全新 session 工作区契约。 +2. 用 `SandboxAgent` 定义智能体。 3. 添加内置或自定义能力。 -4. 在 `RunConfig(sandbox=SandboxRunConfig(...))` 中决定每次运行应如何获取其沙盒会话。 +4. 在 `RunConfig(sandbox=SandboxRunConfig(...))` 中决定每次运行应如何获取其 sandbox session。 -## 沙盒运行准备方式 +## sandbox 运行的准备方式 -在运行时，运行器会将该定义转换为一次具体的、由沙盒支持的运行： +在运行时，runner 会将该定义转换为一次具体的、由 sandbox 支持的运行： -1. 它从 `SandboxRunConfig` 解析沙盒会话。 - 如果你传入 `session=...`，它会复用该实时沙盒会话。 - 否则它会使用 `client=...` 来创建或恢复一个会话。 -2. 它确定此次运行的实际工作区输入。 - 如果运行注入或恢复了一个沙盒会话，则现有沙盒状态优先。 - 否则，运行器从一次性 manifest 覆盖或 `agent.default_manifest` 开始。 - 这就是为什么仅有 `Manifest` 并不能定义每次运行最终的实时工作区。 -3. 它让能力处理生成的 manifest。 - 这样能力就可以在最终智能体准备完成前，添加文件、挂载或其他工作区范围的行为。 -4. 它按固定顺序构建最终指令： - SDK 的默认沙盒提示词，或者如果你显式覆盖了则使用 `base_instructions`，然后是 `instructions`，接着是能力指令片段，然后是任何远程挂载策略文本，最后是渲染后的文件系统树。 -5. 它将能力工具绑定到实时沙盒会话，并通过常规 `Runner` API 运行已准备好的智能体。 +1. 它从 `SandboxRunConfig` 解析 sandbox session。 + 如果你传入 `session=...`，它会复用该实时 sandbox session。 + 否则，它会使用 `client=...` 来创建或恢复一个。 +2. 它确定该次运行的实际工作区输入。 + 如果运行注入或恢复了一个 sandbox session，则现有的 sandbox 状态优先生效。 + 否则，runner 会从一次性的 manifest 覆盖或 `agent.default_manifest` 开始。 + 这就是为什么仅有 `Manifest` 并不能定义每次运行的最终实时工作区。 +3. 它让 capabilities 处理生成的 manifest。 + 这样 capabilities 就可以在最终智能体准备完成之前，添加文件、挂载或其他作用于工作区范围的行为。 +4. 它按固定顺序构建最终 instructions： + SDK 的默认 sandbox 提示词，或如果你显式覆盖则使用 `base_instructions`，然后是 `instructions`，接着是 capability instruction 片段，再是任何远程挂载策略文本，最后是渲染后的文件系统树。 +5. 它将 capability 工具绑定到实时 sandbox session，并通过常规 `Runner` API 运行已准备好的智能体。 -沙盒化不会改变一个 turn 的含义。turn 仍然是模型的一步，而不是单个 shell 命令或单次沙盒操作。沙盒侧操作与 turn 之间不存在固定的 1:1 映射：某些工作可能停留在沙盒执行层内部，而其他操作会返回工具结果、审批或其他需要模型再次响应的状态。实际规则是，只有当智能体运行时在沙盒工作发生后还需要模型再次响应时，才会消耗另一个 turn。 +Sandboxing 不会改变一个 turn 的含义。turn 仍然是一个模型步骤，而不是单个 shell 命令或 sandbox 动作。sandbox 侧操作与 turn 之间并不存在固定的一对一映射：有些工作可能停留在 sandbox 执行层内部，而其他动作会返回工具结果、approvals 或其他需要再进行一次模型步骤的状态。实践上，只有当智能体运行时在 sandbox 工作发生后还需要另一个模型响应时，才会消耗另一个 turn。 -这些准备步骤也是为什么在设计 `SandboxAgent` 时，`default_manifest`、`instructions`、`base_instructions`、`capabilities` 和 `run_as` 是主要需要考虑的沙盒专属选项。 +这些准备步骤说明了为什么在设计 `SandboxAgent` 时，`default_manifest`、`instructions`、`base_instructions`、`capabilities` 和 `run_as` 是主要需要考虑的 sandbox 专属选项。 ## `SandboxAgent` 选项 -这些是在常规 `Agent` 字段基础上的沙盒专属选项： +这些是在常规 `Agent` 字段之外的 sandbox 专属选项：
| 选项 | 最佳用途 | | --- | --- | -| `default_manifest` | 由运行器创建的新沙盒会话的默认工作区。 | -| `instructions` | 追加在 SDK 沙盒提示词之后的额外角色、工作流和成功标准。 | -| `base_instructions` | 用于替换 SDK 沙盒提示词的高级逃生口。 | -| `capabilities` | 应随该智能体一起传递的沙盒原生工具和行为。 | -| `run_as` | 面向模型的沙盒工具（如 shell 命令、文件读取和补丁）的用户身份。 | +| `default_manifest` | 由 runner 创建的全新 sandbox sessions 的默认工作区。 | +| `instructions` | 追加在 SDK sandbox 提示词之后的额外角色、工作流和成功标准。 | +| `base_instructions` | 用于替换 SDK sandbox 提示词的高级逃生舱口。 | +| `capabilities` | 应随此智能体携带的 sandbox 原生工具和行为。 | +| `run_as` | 面向模型的 sandbox 工具（如 shell 命令、文件读取和 patch）所使用的用户身份。 |
-沙盒客户端选择、沙盒会话复用、manifest 覆盖和快照选择应放在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中，而不是放在智能体上。 +sandbox client 选择、sandbox-session 复用、manifest 覆盖和快照选择属于 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]，而不是智能体本身。 ### `default_manifest` -`default_manifest` 是当运行器为该智能体创建新的沙盒会话时使用的默认 [`Manifest`][agents.sandbox.manifest.Manifest]。用它来定义智能体通常应具备的初始文件、仓库、辅助材料、输出目录和挂载。 +`default_manifest` 是当 runner 为此智能体创建一个全新 sandbox session 时使用的默认 [`Manifest`][agents.sandbox.manifest.Manifest]。应将它用于智能体通常应具备的文件、仓库、辅助材料、输出目录和挂载。 -这只是默认值。一次运行可以通过 `SandboxRunConfig(manifest=...)` 覆盖它，而复用或恢复的沙盒会话会保留其现有工作区状态。 +这只是默认值。一次运行可以通过 `SandboxRunConfig(manifest=...)` 覆盖它，而一个复用或恢复的 sandbox session 会保留其现有工作区状态。 ### `instructions` 和 `base_instructions` -使用 `instructions` 来放置那些应跨不同提示词保留的简短规则。在 `SandboxAgent` 中，这些指令会追加在 SDK 的沙盒基础提示词之后，因此你既保留了内置沙盒指导，也可以添加自己的角色、工作流和成功标准。 +将 `instructions` 用于应跨不同提示词保留的简短规则。在 `SandboxAgent` 中，这些 instructions 会追加在 SDK 的 sandbox 基础提示词之后，因此你可以保留内置的 sandbox 指引，并添加自己的角色、工作流和成功标准。 -仅当你想替换 SDK 沙盒基础提示词时才使用 `base_instructions`。大多数智能体都不应设置它。 +只有当你想替换 SDK sandbox 基础提示词时，才使用 `base_instructions`。大多数智能体都不应设置它。
| 放在...中 | 用途 | 示例 | | --- | --- | --- | -| `instructions` | 智能体的稳定角色、工作流规则和成功标准。 | “检查入职文档，然后任务转移。”、“将最终文件写入 `output/`。” | -| `base_instructions` | 对 SDK 沙盒基础提示词的完整替换。 | 自定义的底层沙盒包装提示词。 | +| `instructions` | 智能体的稳定角色、工作流规则和成功标准。 | “检查入职文档，然后执行任务转移。”, “将最终文件写入 `output/`。” | +| `base_instructions` | 完整替换 SDK sandbox 基础提示词。 | 自定义的底层 sandbox 包装提示词。 | | 用户提示词 | 此次运行的一次性请求。 | “总结这个工作区。” | -| manifest 中的工作区文件 | 更长的任务规范、仓库本地说明或受限参考资料。 | `repo/task.md`、文档包、示例材料包。 | +| manifest 中的工作区文件 | 更长的任务规范、仓库本地 instructions 或有界的参考材料。 | `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) 禁止 sandbox 审查智能体在检查后直接回答用户。 +- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) 要求最终填写完成的文件实际落在 `output/` 中。 +- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 固定了精确的验证命令，并澄清了相对于工作区根目录的 patch 路径。 -避免将用户的一次性任务复制到 `instructions` 中，避免嵌入应属于 manifest 的长参考材料，避免重复内置能力已经注入的工具文档，也不要混入模型在运行时并不需要的本地安装说明。 +避免将用户的一次性任务复制到 `instructions` 中、嵌入应放在 manifest 中的长参考材料、重复内置 capabilities 已经注入的工具文档，或混入模型在运行时并不需要的本地安装说明。 -如果你省略 `instructions`，SDK 仍会包含默认的沙盒提示词。对于底层包装器来说这已经足够，但大多数面向用户的智能体仍应提供明确的 `instructions`。 +如果你省略 `instructions`，SDK 仍会包含默认 sandbox 提示词。对于低层封装器来说这已经足够，但大多数面向用户的智能体仍应提供明确的 `instructions`。 ### `capabilities` -能力会将沙盒原生行为附加到 `SandboxAgent`。它们可以在运行开始前塑造工作区，追加沙盒专属说明，暴露绑定到实时沙盒会话的工具，并调整该智能体的模型行为或输入处理。 +Capabilities 会将 sandbox 原生行为附加到 `SandboxAgent`。它们可以在运行开始前塑造工作区、追加 sandbox 专属 instructions、暴露绑定到实时 sandbox session 的工具，并为该智能体调整模型行为或输入处理方式。 -内置能力包括： +内置 capabilities 包括：
-| 能力 | 在何时添加 | 说明 | +| Capability | 适用场景 | 说明 | | --- | --- | --- | -| `Shell` | 智能体需要 shell 访问时。 | 添加 `exec_command`，当沙盒客户端支持 PTY 交互时还会添加 `write_stdin`。 | -| `Filesystem` | 智能体需要编辑文件或检查本地图像时。 | 添加 `apply_patch` 和 `view_image`；补丁路径相对于工作区根目录。 | -| `Skills` | 你希望在沙盒中进行 skill 发现和实例化时。 | 对于沙盒本地的 `SKILL.md` skills，优先使用它，而不是手动挂载 `.agents` 或 `.agents/skills`。 | -| `Memory` | 后续运行应读取或生成内存产物时。 | 需要 `Shell`；实时更新还需要 `Filesystem`。 | -| `Compaction` | 长时间运行的流程在压缩项之后需要裁剪上下文时。 | 会调整模型采样和输入处理。 | +| `Shell` | 智能体需要 shell 访问。 | 添加 `exec_command`，并在 sandbox client 支持 PTY 交互时添加 `write_stdin`。 | +| `Filesystem` | 智能体需要编辑文件或检查本地图片。 | 添加 `apply_patch` 和 `view_image`；patch 路径相对于工作区根目录。 | +| `Skills` | 你希望在 sandbox 中进行 skill 发现和具体化。 | 优先使用它，而不是手动挂载 `.agents` 或 `.agents/skills`；`Skills` 会为你在 sandbox 中索引并具体化 skills。 | +| `Memory` | 后续运行应读取或生成 memory 产物。 | 需要 `Shell`；实时更新还需要 `Filesystem`。 | +| `Compaction` | 长时间运行的流程需要在 compaction 项之后裁剪上下文。 | 会调整模型采样和输入处理。 |
-默认情况下，`SandboxAgent.capabilities` 使用 `Capabilities.default()`，其中包括 `Filesystem()`、`Shell()` 和 `Compaction()`。如果你传入 `capabilities=[...]`，该列表会替换默认值，因此请包含你仍然需要的默认能力。 +默认情况下，`SandboxAgent.capabilities` 使用 `Capabilities.default()`，其中包括 `Filesystem()`、`Shell()` 和 `Compaction()`。如果你传入 `capabilities=[...]`，该列表会替换默认值，因此请包含你仍然需要的任何默认 capability。 -对于 skills，请根据你希望它们如何实例化来选择来源： +对于 skills，请根据你希望其被具体化的方式选择来源： -- `Skills(lazy_from=LocalDirLazySkillSource(...))` 适合作为较大本地 skill 目录的默认选项，因为模型可以先发现索引，只加载其需要的部分。 -- `Skills(from_=LocalDir(src=...))` 更适合较小的本地 bundle，并且你希望它们一开始就被准备好。 -- `Skills(from_=GitRepo(repo=..., ref=...))` 适用于 skills 本身应来自某个仓库的情况。 +- `Skills(lazy_from=LocalDirLazySkillSource(...))` 是较大的本地 skill 目录的一个良好默认选项，因为模型可以先发现索引，再仅加载所需内容。 +- `LocalDirLazySkillSource(source=LocalDir(src=...))` 会从运行 SDK 进程的文件系统中读取。请传入宿主机侧原始 skills 目录，而不是只存在于 sandbox 镜像或工作区中的路径。 +- `Skills(from_=LocalDir(src=...))` 更适合你希望预先准备好的小型本地 bundle。 +- `Skills(from_=GitRepo(repo=..., ref=...))` 适用于 skills 本身应来自某个仓库的场景。 -如果你的 skills 已经以 `.agents/skills//SKILL.md` 之类的形式位于磁盘上，请将 `LocalDir(...)` 指向该源根目录，并仍然使用 `Skills(...)` 来暴露它们。除非你已有的工作区契约依赖于不同的沙盒内布局，否则请保留默认的 `skills_path=".agents"`。 +`LocalDir.src` 是 SDK 宿主机上的源路径。`skills_path` 是调用 `load_skill` 时，skills 在 sandbox 工作区内准备到的相对目标路径。 -当内置能力适用时，优先使用它们。只有当你需要内置能力未覆盖的沙盒专属工具或指令接口时，才编写自定义能力。 +如果你的 skills 已经以类似 `.agents/skills//SKILL.md` 的结构存在于磁盘上，请将 `LocalDir(...)` 指向该源根目录，并仍然使用 `Skills(...)` 来暴露它们。保留默认的 `skills_path=".agents"`，除非你已有依赖不同 sandbox 内布局的现有工作区契约。 + +在适用时优先使用内置 capabilities。只有当你需要内置项未覆盖的 sandbox 专属工具或 instruction 接口时，才编写自定义 capability。 ## 概念 ### Manifest -[`Manifest`][agents.sandbox.manifest.Manifest] 描述一个全新沙盒会话的工作区。它可以设置工作区 `root`，声明文件和目录，复制本地文件，克隆 Git 仓库，附加远程存储挂载，设置环境变量，定义用户或组，并授予对工作区外特定绝对路径的访问权限。 +[`Manifest`][agents.sandbox.manifest.Manifest] 描述一个全新 sandbox session 的工作区。它可以设置工作区 `root`、声明文件和目录、复制本地文件、克隆 Git 仓库、附加远程存储挂载、设置环境变量、定义用户或组，并授予对工作区外特定绝对路径的访问权限。 -Manifest 条目的路径是相对于工作区的。它们不能是绝对路径，也不能通过 `..` 逃离工作区，这使工作区契约能够在本地、Docker 和托管客户端之间保持可移植性。 +Manifest 条目的路径是相对于工作区的。它们不能是绝对路径，也不能通过 `..` 逃离工作区，这使工作区契约可以在本地、Docker 和托管 client 之间保持可移植性。 -对智能体在工作开始前所需的材料，请使用 manifest 条目： +将 manifest 条目用于智能体在开始工作前所需的材料：
| Manifest 条目 | 用途 | | --- | --- | | `File`、`Dir` | 小型合成输入、辅助文件或输出目录。 | -| `LocalFile`、`LocalDir` | 应实例化到沙盒中的主机文件或目录。 | -| `GitRepo` | 应拉取到工作区中的仓库。 | -| 挂载，如 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` | 应出现在沙盒中的外部存储。 | +| `LocalFile`、`LocalDir` | 应在 sandbox 中具体化的宿主机文件或目录。 | +| `GitRepo` | 应获取到工作区中的仓库。 | +| 挂载，如 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` | 应出现在 sandbox 内的外部存储。 |
-挂载条目描述要暴露哪些存储；挂载策略描述沙盒后端如何附加这些存储。有关挂载选项和提供方支持，请参见[沙盒客户端](clients.md#mounts-and-remote-storage)。 +挂载条目描述要暴露什么存储；挂载策略描述 sandbox 后端如何附加该存储。有关挂载选项和提供方支持，请参见 [Sandbox clients](clients.md#mounts-and-remote-storage)。 -良好的 manifest 设计通常意味着保持工作区契约精简，将较长的任务说明放在工作区文件中，例如 `repo/task.md`，并在说明中使用相对工作区路径，例如 `repo/task.md` 或 `output/report.md`。如果智能体使用 `Filesystem` 能力的 `apply_patch` 工具编辑文件，请记住补丁路径是相对于沙盒工作区根目录，而不是 shell 的 `workdir`。 +良好的 manifest 设计通常意味着保持工作区契约精简，将较长的任务说明放在工作区文件中，例如 `repo/task.md`，并在 instructions 中使用相对工作区路径，例如 `repo/task.md` 或 `output/report.md`。如果智能体使用 `Filesystem` capability 的 `apply_patch` 工具编辑文件，请记住 patch 路径相对于 sandbox 工作区根目录，而不是 shell 的 `workdir`。 -仅当智能体需要访问工作区之外的具体绝对路径时才使用 `extra_path_grants`，例如用于临时工具输出的 `/tmp`，或作为只读运行时环境的 `/opt/toolchain`。在后端能够执行文件系统策略的情况下，授权同时适用于 SDK 文件 API 和 shell 执行： +仅当智能体需要访问工作区外的具体绝对路径时，才使用 `extra_path_grants`，例如用于临时工具输出的 `/tmp` 或用于只读运行时的 `/opt/toolchain`。在后端可以实施文件系统策略的情况下，授权同时适用于 SDK 文件 API 和 shell 执行： ```python from agents.sandbox import Manifest, SandboxPathGrant @@ -254,13 +257,13 @@ manifest = Manifest( ) ``` -快照和 `persist_workspace()` 仍然只包含工作区根目录。额外授予的路径是运行时访问权限，而不是持久化工作区状态。 +快照和 `persist_workspace()` 仍然只包含工作区根目录。额外授权的路径属于运行时访问，而不是持久化工作区状态。 ### 权限 -`Permissions` 控制 manifest 条目的文件系统权限。它针对的是沙盒实例化出来的文件，而不是模型权限、审批策略或 API 凭据。 +`Permissions` 控制 manifest 条目的文件系统权限。它针对的是 sandbox 具体化出来的文件，而不是模型权限、approval 策略或 API 凭证。 -默认情况下，manifest 条目对所有者可读/可写/可执行，对组和其他用户可读/可执行。当预置的文件应为私有、只读或可执行时，请覆盖此设置： +默认情况下，manifest 条目对所有者可读/可写/可执行，对组和其他用户可读/可执行。当准备的文件应为私有、只读或可执行时，请覆盖此设置： ```python from agents.sandbox import FileMode, Permissions @@ -276,9 +279,9 @@ private_notes = File( ) ``` -`Permissions` 存储单独的所有者、组和其他用户位，以及该条目是否为目录。你可以直接构建它，用 `Permissions.from_str(...)` 从 mode 字符串解析，或用 `Permissions.from_mode(...)` 从操作系统 mode 派生。 +`Permissions` 存储独立的 owner、group 和 other 位，以及该条目是否为目录。你可以直接构建它，也可以通过 `Permissions.from_str(...)` 从 mode 字符串解析，或通过 `Permissions.from_mode(...)` 从操作系统 mode 派生。 -用户是可以执行工作的沙盒身份。当你希望某个身份存在于沙盒中时，请向 manifest 添加一个 `User`，然后在希望 shell 命令、文件读取和补丁等面向模型的沙盒工具以该用户身份运行时设置 `SandboxAgent.run_as`。如果 `run_as` 指向的用户尚未在 manifest 中，运行器会为你将其添加到实际 manifest 中。 +Users 是可以执行工作的 sandbox 身份。当你希望某个身份存在于 sandbox 中时，请向 manifest 添加一个 `User`；然后，当面向模型的 sandbox 工具（如 shell 命令、文件读取和 patch）应以该用户身份运行时，设置 `SandboxAgent.run_as`。如果 `run_as` 指向一个尚未存在于 manifest 中的用户，runner 会自动将其添加到实际 manifest 中。 ```python from agents import Runner @@ -330,13 +333,13 @@ result = await Runner.run( ) ``` -如果你还需要文件级共享规则，请将用户与 manifest 组以及条目的 `group` 元数据结合使用。`run_as` 用户控制谁执行沙盒原生操作；`Permissions` 控制在沙盒实例化工作区之后，该用户可以读取、写入或执行哪些文件。 +如果你还需要文件级别的共享规则，请将 users 与 manifest groups 以及条目的 `group` 元数据结合使用。`run_as` 用户控制谁执行 sandbox 原生动作；`Permissions` 控制一旦 sandbox 具体化工作区后，该用户可以读取、写入或执行哪些文件。 ### SnapshotSpec -`SnapshotSpec` 告诉一个全新的沙盒会话应从哪里恢复已保存的工作区内容，以及将其持久化回哪里。它是沙盒工作区的快照策略，而 `session_state` 是用于恢复特定沙盒后端的序列化连接状态。 +`SnapshotSpec` 告诉一个全新 sandbox session，应从哪里恢复已保存的工作区内容，以及持久化回哪里。它是 sandbox 工作区的快照策略，而 `session_state` 是用于恢复特定 sandbox 后端的序列化连接状态。 -本地持久快照使用 `LocalSnapshotSpec`；当你的应用提供远程快照客户端时使用 `RemoteSnapshotSpec`。当本地快照设置不可用时，会退回使用无操作快照；高级调用方也可以在不希望工作区快照持久化时显式使用它。 +当你需要本地持久快照时，使用 `LocalSnapshotSpec`；当你的应用提供远程快照 client 时，使用 `RemoteSnapshotSpec`。当本地快照设置不可用时，会回退使用 no-op 快照；高级调用方也可以在不希望工作区快照持久化时显式使用它。 ```python from pathlib import Path @@ -353,13 +356,13 @@ run_config = RunConfig( ) ``` -当运行器创建一个全新的沙盒会话时，沙盒客户端会为该会话构建一个快照实例。启动时，如果快照可恢复，沙盒会在运行继续前恢复已保存的工作区内容。清理时，由运行器拥有的沙盒会话会归档工作区，并通过快照将其持久化回去。 +当 runner 创建一个全新 sandbox session 时，sandbox client 会为该 session 构建一个快照实例。启动时，如果快照可恢复，sandbox 会在运行继续前恢复已保存的工作区内容。清理时，由 runner 拥有的 sandbox sessions 会归档工作区，并通过快照将其持久化回去。 -如果你省略 `snapshot`，运行时会在可行时尝试使用默认的本地快照位置。如果无法设置，则退回到无操作快照。挂载路径和临时路径不会作为持久工作区内容复制进快照中。 +如果你省略 `snapshot`，运行时会在可行时尝试使用默认的本地快照位置。如果无法设置，则会回退为 no-op 快照。已挂载路径和临时路径不会作为持久工作区内容复制进快照。 -### 沙盒生命周期 +### Sandbox 生命周期 -有两种生命周期模式：**SDK 拥有**和**开发者拥有**。 +有两种生命周期模式：**SDK-owned** 和 **developer-owned**。
@@ -387,7 +390,7 @@ sequenceDiagram
-当沙盒只需要存活一个运行周期时，使用 SDK 拥有的生命周期。传入 `client`、可选的 `manifest`、可选的 `snapshot` 和客户端 `options`；运行器会创建或恢复沙盒、启动它、运行智能体、持久化由快照支持的工作区状态、关闭沙盒，并让客户端清理由运行器拥有的资源。 +当 sandbox 只需存活一次运行时，使用 SDK-owned 生命周期。传入 `client`、可选的 `manifest`、可选的 `snapshot` 和 client `options`；runner 会创建或恢复 sandbox，启动它，运行智能体，持久化由快照支持的工作区状态，关闭 sandbox，并让 client 清理由 runner 拥有的资源。 ```python result = await Runner.run( @@ -399,7 +402,7 @@ result = await Runner.run( ) ``` -当你希望预先创建沙盒、在多次运行中复用一个实时沙盒、在运行后检查文件、对你自己创建的沙盒进行流式处理，或精确决定何时清理时，请使用开发者拥有的生命周期。传入 `session=...` 会告诉运行器使用该实时沙盒，但不会替你关闭它。 +当你想要提前创建一个 sandbox、在多次运行间复用同一个实时 sandbox、在运行后检查文件、对你自己创建的 sandbox 进行流式处理，或精确决定何时清理时，请使用 developer-owned 生命周期。传入 `session=...` 会告诉 runner 使用该实时 sandbox，但不会替你关闭它。 ```python sandbox = await client.create(manifest=agent.default_manifest) @@ -410,7 +413,7 @@ async with sandbox: await Runner.run(agent, "Write the final report.", run_config=run_config) ``` -上下文管理器是常见形式：进入时启动沙盒，退出时执行会话清理生命周期。如果你的应用无法使用上下文管理器，请直接调用生命周期方法： +上下文管理器是常见形式：进入时启动 sandbox，退出时运行 session 清理生命周期。如果你的应用无法使用上下文管理器，请直接调用生命周期方法： ```python sandbox = await client.create( @@ -431,62 +434,62 @@ finally: await sandbox.aclose() ``` -`stop()` 只持久化由快照支持的工作区内容；它不会拆除沙盒。`aclose()` 是完整的会话清理路径：它会运行停止前 hook，调用 `stop()`，关闭沙盒资源，并关闭会话范围的依赖项。 +`stop()` 只会持久化由快照支持的工作区内容；它不会拆除 sandbox。`aclose()` 是完整的 session 清理路径：它会运行 pre-stop hooks、调用 `stop()`、关闭 sandbox 资源，并关闭 session 范围的依赖项。 ## `SandboxRunConfig` 选项 -[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 保存每次运行的选项，用于决定沙盒会话来自何处，以及全新会话应如何初始化。 +[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 包含每次运行的选项，用于决定 sandbox session 来自哪里，以及全新 session 应如何初始化。 -### 沙盒来源 +### Sandbox 来源 -这些选项决定运行器应复用、恢复还是创建沙盒会话： +这些选项决定 runner 应复用、恢复还是创建 sandbox session：
| 选项 | 适用场景 | 说明 | | --- | --- | --- | -| `client` | 你希望运行器为你创建、恢复和清理沙盒会话。 | 除非你提供一个实时沙盒 `session`，否则必需。 | -| `session` | 你已经自己创建了一个实时沙盒会话。 | 生命周期由调用方负责；运行器会复用该实时沙盒会话。 | -| `session_state` | 你有已序列化的沙盒会话状态，但没有实时沙盒会话对象。 | 需要 `client`；运行器会从该显式状态恢复，并作为拥有者会话管理它。 | +| `client` | 你希望 runner 为你创建、恢复并清理 sandbox sessions。 | 除非你提供一个实时 sandbox `session`，否则必填。 | +| `session` | 你已经自行创建了一个实时 sandbox session。 | 生命周期由调用方负责；runner 会复用该实时 sandbox session。 | +| `session_state` | 你拥有序列化的 sandbox session 状态，但没有实时 sandbox session 对象。 | 需要 `client`；runner 会以拥有型 session 的方式从该显式状态恢复。 |
-在实践中，运行器按以下顺序解析沙盒会话： +在实践中，runner 会按以下顺序解析 sandbox session： -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`，则直接复用该实时 sandbox session。 +2. 否则，如果该运行是从 `RunState` 恢复的，则恢复存储的 sandbox session 状态。 +3. 否则，如果你传入 `run_config.sandbox.session_state`，runner 会从该显式序列化的 sandbox session 状态恢复。 +4. 否则，runner 会创建一个全新的 sandbox session。对于该全新 session，若提供了 `run_config.sandbox.manifest` 就使用它，否则使用 `agent.default_manifest`。 -### 全新会话输入 +### 全新 session 输入 -这些选项仅在运行器创建全新沙盒会话时才有意义： +这些选项仅在 runner 正在创建一个全新 sandbox session 时才有意义：
| 选项 | 适用场景 | 说明 | | --- | --- | --- | -| `manifest` | 你希望一次性覆盖全新会话工作区。 | 省略时回退到 `agent.default_manifest`。 | -| `snapshot` | 全新的沙盒会话应从快照提供初始数据。 | 适用于类似恢复的流程或远程快照客户端。 | -| `options` | 沙盒客户端需要创建时选项。 | 常见于 Docker 镜像、Modal 应用名、E2B 模板、超时等类似的客户端专属设置。 | +| `manifest` | 你希望一次性覆盖全新 session 工作区。 | 省略时回退到 `agent.default_manifest`。 | +| `snapshot` | 全新的 sandbox session 应从快照中获得初始内容。 | 适用于类似恢复的流程或远程快照 client。 | +| `options` | sandbox client 需要创建时选项。 | 常见于 Docker 镜像、Modal 应用名、E2B 模板、超时以及类似的 client 专属设置。 |
-### 实例化控制 +### 具体化控制 -`concurrency_limits` 控制有多少沙盒实例化工作可以并行运行。当大型 manifest 或本地目录复制需要更严格的资源控制时，请使用 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`。将任一值设为 `None` 可禁用对应的限制。 +`concurrency_limits` 控制有多少 sandbox 具体化工作可以并行运行。当大型 manifest 或本地目录复制需要更严格的资源控制时，使用 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`。将任一值设为 `None` 可禁用该特定限制。 -有几个值得记住的影响： +有几点值得注意： -- 全新会话：`manifest=` 和 `snapshot=` 仅在运行器创建全新沙盒会话时生效。 -- 恢复与快照：`session_state=` 重新连接到先前序列化的沙盒状态，而 `snapshot=` 则是从保存的工作区内容为一个新的沙盒会话提供初始数据。 -- 客户端专属选项：`options=` 取决于沙盒客户端；Docker 和许多托管客户端都需要它。 -- 注入的实时会话：如果你传入一个正在运行的沙盒 `session`，由能力驱动的 manifest 更新可以添加兼容的非挂载条目。它们不能更改 `manifest.root`、`manifest.environment`、`manifest.users` 或 `manifest.groups`；不能删除现有条目；不能替换条目类型；也不能添加或修改挂载条目。 -- 运行器 API：`SandboxAgent` 执行仍使用常规的 `Runner.run()`、`Runner.run_sync()` 和 `Runner.run_streamed()` API。 +- 全新 sessions：`manifest=` 和 `snapshot=` 仅在 runner 创建全新 sandbox session 时生效。 +- 恢复 vs 快照：`session_state=` 会重新连接到先前序列化的 sandbox 状态，而 `snapshot=` 会从已保存的工作区内容为新的 sandbox session 提供初始内容。 +- client 专属选项：`options=` 依赖于 sandbox client；Docker 和许多托管 client 都需要它。 +- 注入的实时 sessions：如果你传入一个正在运行的 sandbox `session`，由 capability 驱动的 manifest 更新可以添加兼容的非挂载条目。它们不能更改 `manifest.root`、`manifest.environment`、`manifest.users` 或 `manifest.groups`；不能移除现有条目；不能替换条目类型；也不能添加或更改挂载条目。 +- Runner API：`SandboxAgent` 执行仍使用常规的 `Runner.run()`、`Runner.run_sync()` 和 `Runner.run_streamed()` API。 ## 完整示例：编码任务 -这个编码风格示例是一个很好的默认起点： +这个编码风格的示例是一个很好的默认起点： ```python import asyncio @@ -529,9 +532,10 @@ def build_agent(model: str) -> SandboxAgent[None]: } ), capabilities=Capabilities.default() + [ - # Let Skills(...) stage and index sandbox-local skills for you. Skills( lazy_from=LocalDirLazySkillSource( + # This is a host path read by the SDK process. + # Requested skills are copied into `skills_path` in the sandbox. source=LocalDir(src=HOST_SKILLS_DIR), ) ), @@ -564,19 +568,19 @@ if __name__ == "__main__": ) ``` -参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用了一个很小的基于 shell 的仓库，以便该示例可以在 Unix 本地运行中被确定性验证。当然，你的真实任务仓库也可以是 Python、JavaScript 或其他任何内容。 +参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用了一个基于 shell 的微型仓库，以便该示例可以在 Unix 本地运行中被确定性验证。当然，你的真实任务仓库可以是 Python、JavaScript 或任何其他类型。 ## 常见模式 -从上面的完整示例开始。在很多情况下，同一个 `SandboxAgent` 可以保持不变，只改变沙盒客户端、沙盒会话来源或工作区来源。 +从上面的完整示例开始。在许多情况下，同一个 `SandboxAgent` 可以保持不变，而只更改 sandbox client、sandbox-session 来源或工作区来源。 -### 切换沙盒客户端 +### 切换 sandbox clients -保持智能体定义不变，只修改运行配置。当你需要容器隔离或镜像一致性时使用 Docker；当你需要提供方托管执行时使用托管提供方。示例和提供方选项请参见[沙盒客户端](clients.md)。 +保持智能体定义不变，只更改 run config。当你需要容器隔离或镜像一致性时使用 Docker；当你希望由提供方管理执行环境时使用托管提供方。示例和提供方选项请参见 [Sandbox clients](clients.md)。 ### 覆盖工作区 -保持智能体定义不变，只替换全新会话 manifest： +保持智能体定义不变，仅替换全新 session 的 manifest： ```python from agents.run import RunConfig @@ -596,11 +600,11 @@ run_config = RunConfig( ) ``` -当同一个智能体角色需要针对不同仓库、材料包或任务包运行，而无需重建智能体时，请使用此方式。上面的已验证编码示例展示了使用 `default_manifest` 而非一次性覆盖的相同模式。 +当同一智能体角色应面向不同仓库、材料包或任务包运行，而无需重建智能体时，可使用此方式。上面的已验证编码示例展示了使用 `default_manifest` 而不是一次性覆盖的相同模式。 -### 注入沙盒会话 +### 注入 sandbox session -当你需要显式生命周期控制、运行后检查或复制输出时，注入一个实时沙盒会话： +当你需要显式生命周期控制、运行后检查或输出复制时，注入一个实时 sandbox session： ```python from agents import Runner @@ -621,11 +625,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)。 +当你希望在运行后检查工作区，或对一个已经启动的 sandbox session 进行流式处理时，可使用此方式。参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 和 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。 -### 从会话状态恢复 +### 从 session 状态恢复 -如果你已经在 `RunState` 之外序列化了沙盒状态，让运行器从该状态重新连接： +如果你已经在 `RunState` 之外序列化了 sandbox 状态，让 runner 从该状态重新连接： ```python from agents.run import RunConfig @@ -642,11 +646,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)。 +当 sandbox 状态保存在你自己的存储或作业系统中，并且你希望 `Runner` 直接从中恢复时，可使用此方式。序列化/反序列化流程请参见 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)。 ### 从快照开始 -使用已保存的文件和产物为新的沙盒提供初始数据： +从已保存的文件和产物为新的 sandbox 提供初始内容： ```python from pathlib import Path @@ -663,11 +667,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)，远程快照 client 请参见 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)。 ### 从 Git 加载 skills -将本地 skill 来源替换为基于仓库的来源： +将本地 skill 来源替换为仓库支持的来源： ```python from agents.sandbox.capabilities import Capabilities, Skills @@ -678,11 +682,11 @@ capabilities = Capabilities.default() + [ ] ``` -当 skills bundle 有其自己的发布节奏，或应在多个沙盒之间共享时，请使用此方式。参见 [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)。 +当 skills bundle 有其自身的发布节奏，或应在多个 sandboxes 之间共享时，可使用此方式。参见 [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)。 ### 作为工具暴露 -工具智能体既可以拥有自己的沙盒边界，也可以复用父运行中的实时沙盒。复用对于一个快速的只读探索智能体很有用：它可以检查父智能体正在使用的确切工作区，而无需为创建、填充或快照另一个沙盒付出成本。 +工具智能体可以拥有自己的 sandbox 边界，也可以复用父运行中的实时 sandbox。复用对于一个快速的只读探索智能体很有用：它可以检查父级正在使用的精确工作区，而无需付出创建、填充或快照另一个 sandbox 的成本。 ```python from agents import Runner @@ -764,9 +768,9 @@ async with sandbox: ) ``` -这里父智能体以 `coordinator` 身份运行，而探索工具智能体则以 `explorer` 身份在同一个实时沙盒会话中运行。`pricing_packet/` 条目对 `other` 用户可读，因此探索者可以快速检查它们，但没有写入位。`work/` 目录仅对协调者的用户/组可用，因此父智能体可以写入最终产物，而探索者保持只读。 +这里父智能体以 `coordinator` 身份运行，而探索工具智能体在同一个实时 sandbox session 中以 `explorer` 身份运行。`pricing_packet/` 条目对 `other` 用户可读，因此 explorer 可以快速检查它们，但它没有写权限。`work/` 目录仅对 coordinator 的用户/组可用，因此父级可以写入最终产物，而 explorer 保持只读。 -当工具智能体确实需要真正的隔离时，请给它自己的沙盒 `RunConfig`： +当工具智能体确实需要真正的隔离时，请为它提供自己的 sandbox `RunConfig`： ```python from docker import from_env as docker_from_env @@ -787,11 +791,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)。 +当工具智能体应能自由修改、运行不受信任的命令，或使用不同的后端/镜像时，请使用单独的 sandbox。参见 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。 -### 与本地工具和 MCP 结合 +### 结合本地工具和 MCP -在保留沙盒工作区的同时，仍在同一个智能体上使用普通工具： +在保留 sandbox 工作区的同时，仍在同一个智能体上使用普通工具： ```python from agents.sandbox import SandboxAgent @@ -806,46 +810,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` 能力。内存不同于 SDK 的会话式 `Session` 内存：它将经验提炼为沙盒工作区中的文件，之后的运行便可以读取这些文件。 +当未来的 sandbox-agent 运行应从先前运行中学习时，使用 `Memory` capability。Memory 与 SDK 的对话式 `Session` memory 分离：它会将经验提炼为 sandbox 工作区内的文件，之后的运行即可读取这些文件。 -有关设置、读取/生成行为、多轮对话和布局隔离，请参见[智能体内存](memory.md)。 +有关设置、读取/生成行为、多轮对话和布局隔离，请参见 [Agent memory](memory.md)。 ## 组合模式 -当单智能体模式清晰后，下一个设计问题就是在更大的系统中应将沙盒边界放在哪里。 +当单智能体模式已经清晰后，下一个设计问题就是在更大的系统中应将 sandbox 边界放在哪里。 -沙盒智能体仍然可以与 SDK 的其他部分组合： +Sandbox 智能体仍可与 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 工具共存。 -- [运行智能体](../running_agents.md)：沙盒运行仍使用常规 `Runner` API。 +- [Handoffs](../handoffs.md)：将文档密集型工作从非 sandbox 的接入智能体转移给 sandbox 审查智能体。 +- [Agents as tools](../tools.md#agents-as-tools)：将多个 sandbox 智能体作为工具暴露，通常是在每次 `Agent.as_tool(...)` 调用时传入 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`，以便每个工具获得自己的 sandbox 边界。 +- [MCP](../mcp.md) 和普通工具调用：sandbox capabilities 可以与 `mcp_servers` 和常规 Python 工具共存。 +- [Running agents](../running_agents.md)：sandbox 运行仍使用常规的 `Runner` API。 有两种模式尤其常见： -- 非沙盒智能体仅在工作流中需要工作区隔离的部分任务转移到沙盒智能体 -- 一个编排器将多个沙盒智能体作为工具暴露，通常为每次 `Agent.as_tool(...)` 调用提供单独的沙盒 `RunConfig`，以便每个工具都有各自隔离的工作区 +- 非 sandbox 智能体仅在工作流中需要工作区隔离的部分才转移给 sandbox 智能体 +- 一个编排器将多个 sandbox 智能体作为工具暴露，通常每次 `Agent.as_tool(...)` 调用都使用单独的 sandbox `RunConfig`，从而让每个工具获得各自隔离的工作区 -### Turns 与沙盒运行 +### Turns 和 sandbox 运行 -分别解释任务转移和作为工具的智能体调用会更容易理解。 +分别解释 handoff 与 agent-as-tool 调用会更容易理解。 -对于任务转移，仍然只有一个顶层运行和一个顶层 turn 循环。活跃智能体会变化，但运行不会变成嵌套。如果一个非沙盒接入智能体将任务转移给一个沙盒审查智能体，那么在同一运行中的下一次模型调用会为该沙盒智能体进行准备，而该沙盒智能体将成为执行下一个 turn 的智能体。换句话说，任务转移改变的是同一运行中由哪个智能体拥有下一个 turn。参见 [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)。 +对于 handoff，仍然只有一个顶层运行和一个顶层 turn 循环。活动智能体会变化，但运行不会变成嵌套。如果一个非 sandbox 的接入智能体转移给 sandbox 审查智能体，那么该同一次运行中的下一次模型调用就会为 sandbox 智能体准备，而该 sandbox 智能体将成为执行下一个 turn 的智能体。换句话说，handoff 改变的是同一次运行中下一个 turn 由哪个智能体负责。参见 [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)。 -对于 `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(...)`，关系则不同。外层编排器会在一个外层 turn 中决定调用该工具，而该工具调用会为 sandbox 智能体启动一次嵌套运行。嵌套运行有自己的 turn 循环、`max_turns`、approvals，以及通常也有自己的 sandbox `RunConfig`。它可能在一个嵌套 turn 内完成，也可能需要多个。从外层编排器的角度看，这些工作仍然都隐藏在一次工具调用之后，因此嵌套 turn 不会增加外层运行的 turn 计数。参见 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。 -审批行为遵循相同的划分： +approval 行为也遵循相同的划分： -- 对于任务转移，审批仍保留在同一个顶层运行中，因为沙盒智能体现在是该运行中的活跃智能体 -- 对于 `Agent.as_tool(...)`，在沙盒工具智能体内部触发的审批仍会出现在外层运行上，但它们来自已存储的嵌套运行状态，并会在外层运行恢复时恢复嵌套的沙盒运行 +- 对于 handoff，approvals 保持在同一个顶层运行上，因为 sandbox 智能体现在是该运行中的活动智能体 +- 对于 `Agent.as_tool(...)`，在 sandbox 工具智能体内部产生的 approvals 仍会显示在外层运行上，但它们来自已存储的嵌套运行状态，并会在外层运行恢复时恢复嵌套的 sandbox 运行 ## 延伸阅读 -- [快速开始](quickstart.md)：运行一个沙盒智能体。 -- [沙盒客户端](clients.md)：选择本地、Docker、托管和挂载选项。 -- [智能体内存](memory.md)：保留并复用先前沙盒运行中的经验。 -- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)：可运行的本地、编码、内存、任务转移和智能体组合模式。 \ No newline at end of file +- [Quickstart](quickstart.md)：运行一个 sandbox 智能体。 +- [Sandbox clients](clients.md)：选择本地、Docker、托管和挂载选项。 +- [Agent memory](memory.md)：保留并复用先前 sandbox 运行中的经验。 +- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)：可运行的本地、编码、memory、handoff 和智能体组合模式。 \ No newline at end of file diff --git a/docs/zh/sandbox_agents.md b/docs/zh/sandbox_agents.md index 480b3b4eb7..4c76ddd1f4 100644 --- a/docs/zh/sandbox_agents.md +++ b/docs/zh/sandbox_agents.md @@ -2,31 +2,31 @@ search: exclude: true --- -# 快速入门 +# 快速开始 !!! warning "Beta 功能" - Sandbox 智能体目前处于 beta 阶段。预计 API 的细节、默认值以及支持的能力会在正式可用前发生变化，并且功能也会随着时间推移变得更高级。 + Sandbox 智能体目前处于 beta 阶段。预计 API 的细节、默认设置和支持的能力会在正式可用前发生变化，并且功能也会随着时间推移变得更高级。 -现代智能体在能够对文件系统中的真实文件进行操作时效果最佳。Agents SDK 中的 **Sandbox 智能体** 为模型提供了一个持久化工作区，模型可以在其中检索大型文档集、编辑文件、运行命令、生成产物，并从已保存的 sandbox 状态恢复工作。 +现代智能体在能够对文件系统中的真实文件进行操作时效果最佳。Agents SDK 中的 **Sandbox Agents** 为模型提供了一个持久化工作区，模型可以在其中检索大型文档集、编辑文件、运行命令、生成产物，并从已保存的 sandbox 状态中继续工作。 -SDK 为你提供了这一执行框架，无需你自己拼接文件预置、文件系统工具、shell 访问、sandbox 生命周期、快照以及特定提供方的胶水代码。你可以继续使用常规的 `Agent` 和 `Runner` 流程，然后为工作区添加 `Manifest`，为 sandbox 原生工具添加 capabilities，并通过 `SandboxRunConfig` 指定工作运行的位置。 +SDK 为你提供了这一执行框架，无需你自己去拼接文件暂存、文件系统工具、shell 访问、sandbox 生命周期、快照以及特定提供方的胶水代码。你可以保留常规的 `Agent` 和 `Runner` 流程，然后再为工作区添加 `Manifest`、用于 sandbox 原生工具的 capabilities，以及用于指定工作运行位置的 `SandboxRunConfig`。 ## 前提条件 - Python 3.10 或更高版本 - 对 OpenAI Agents SDK 有基本了解 -- 一个 sandbox 客户端。对于本地开发，可从 `UnixLocalSandboxClient` 开始。 +- 一个 sandbox 客户端。对于本地开发，建议从 `UnixLocalSandboxClient` 开始。 ## 安装 -如果你还没有安装 SDK： +如果你尚未安装 SDK： ```bash pip install openai-agents ``` -对于基于 Docker 的 sandbox： +对于由 Docker 支持的 sandboxes： ```bash pip install "openai-agents[docker]" @@ -34,7 +34,7 @@ pip install "openai-agents[docker]" ## 创建本地 sandbox 智能体 -此示例会将本地仓库预置到 `repo/` 下，按需懒加载本地技能，并让 runner 为此次运行创建一个 Unix 本地 sandbox 会话。 +此示例会将本地仓库暂存到 `repo/` 下，按需延迟加载本地 skills，并让 runner 为本次运行创建一个 Unix 本地 sandbox 会话。 ```python import asyncio @@ -69,6 +69,8 @@ def build_agent(model: str) -> SandboxAgent[None]: capabilities=Capabilities.default() + [ Skills( lazy_from=LocalDirLazySkillSource( + # This is a host path read by the SDK process. + # Requested skills are copied into `skills_path` in the sandbox. source=LocalDir(src=HOST_SKILLS_DIR), ) ), @@ -92,24 +94,24 @@ if __name__ == "__main__": asyncio.run(main()) ``` -参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用了一个非常小的基于 shell 的仓库，因此该示例可以在 Unix 本地运行中以确定性的方式进行验证。 +参见[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用了一个基于 shell 的小型仓库，因此该示例可以在 Unix 本地运行中以确定性方式进行验证。 ## 关键选择 -当基础运行成功后，大多数人接下来会关注这些选择： +当基础运行正常后，大多数人接下来会关注这些选择： - `default_manifest`：用于全新 sandbox 会话的文件、仓库、目录和挂载 -- `instructions`：应在各个提示词之间通用的简短工作流规则 -- `base_instructions`：用于替换 SDK sandbox 提示词的高级兜底机制 -- `capabilities`：sandbox 原生工具，例如文件系统编辑/图像检查、shell、技能、memory 和压缩 +- `instructions`：应在各个提示词中统一适用的简短工作流规则 +- `base_instructions`：一种高级兜底方式，用于替换 SDK 的 sandbox 提示词 +- `capabilities`：sandbox 原生工具，例如文件系统编辑/图像检查、shell、skills、memory 和 compaction - `run_as`：面向模型的工具所使用的 sandbox 用户身份 - `SandboxRunConfig.client`：sandbox 后端 -- `SandboxRunConfig.session`、`session_state` 或 `snapshot`：后续运行如何重新连接到先前的工作 +- `SandboxRunConfig.session`、`session_state` 或 `snapshot`：后续运行如何重新连接到先前工作 -## 后续方向 +## 后续内容 -- [概念](sandbox/guide.md)：了解清单、能力、权限、快照、运行配置和组合模式。 +- [概念](sandbox/guide.md)：了解 manifest、capabilities、权限、快照、运行配置和组合模式。 - [Sandbox 客户端](sandbox/clients.md)：选择 Unix 本地、Docker、托管提供方以及挂载策略。 - [智能体 memory](sandbox/memory.md)：保留并复用先前 sandbox 运行中的经验。 -如果 shell 访问只是一个偶尔使用的工具，请先从[工具指南](tools.md)中的托管 shell 开始。当工作区隔离、sandbox 客户端选择或 sandbox 会话恢复行为是设计的一部分时，再使用 sandbox 智能体。 \ No newline at end of file +如果 shell 访问只是偶尔使用的工具之一，请先查看[tools 指南](tools.md)中的托管 shell。若工作区隔离、sandbox 客户端选择或 sandbox 会话恢复行为是设计的一部分，则应使用 sandbox 智能体。 \ No newline at end of file