6.9 KiB
| search | ||
|---|---|---|
|
クイックスタート
最新のエージェントは、ファイルシステム内の実際のファイルを操作できる場合に最も効果を発揮します。Agents SDK の サンドボックスエージェント は、大規模なドキュメント群の検索、ファイルの編集、コマンドの実行、成果物の生成、保存済みのサンドボックス状態からの作業再開が可能な永続ワークスペースをモデルに提供します。
SDK は、ファイルのステージング、ファイルシステムツール、シェルアクセス、サンドボックスのライフサイクル、スナップショット、プロバイダー固有の連携処理を自分で接続することなく、この実行基盤を提供します。通常の Agent と Runner のフローを維持したまま、ワークスペース用の Manifest、サンドボックスネイティブツール用の機能、作業の実行場所を指定する SandboxRunConfig を追加できます。
前提条件
- Python 3.10 以上
- OpenAI Agents SDK に関する基本的な知識
- サンドボックスクライアント。信頼できるローカル開発では、まず
UnixLocalSandboxClientを使用します。
インストール
SDK をまだインストールしていない場合は、次を実行します。
pip install openai-agents
Docker ベースのサンドボックスの場合は、次を実行します。
pip install "openai-agents[docker]"
ローカルサンドボックスエージェントの作成
この例では、ローカルリポジトリを repo/ 配下にステージングし、ローカルスキルを遅延読み込みして、ランナーに実行用の Unix ローカルサンドボックスセッションを作成させます。
!!! warning "ローカルコマンドによるホスト権限の使用"
Linux では、`UnixLocalSandboxClient` はコマンドに OS レベルの隔離を追加しません。macOS では、`sandbox-exec` を介してファイルシステムの制限を適用しますが、ネットワークの隔離は提供しません。この例は、信頼できるローカル開発、または外部で隔離された環境内で使用してください。信頼できない入力の影響を受けるコマンドを含む、信頼できないコマンドを実行する場合は、適切に構成された Docker サンドボックスまたはホステッドサンドボックスを選択するか、外部の隔離環境を用意してください。[Unix ローカル実行の制限](sandbox/clients.md#decision-guide)を参照してください。
import asyncio
from pathlib import Path
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Capabilities, LocalDirLazySkillSource, Skills
from agents.sandbox.entries import LocalDir
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient
EXAMPLE_DIR = Path(__file__).resolve().parent
HOST_REPO_DIR = EXAMPLE_DIR / "repo"
HOST_SKILLS_DIR = EXAMPLE_DIR / "skills"
def build_agent(model: str) -> SandboxAgent[None]:
return SandboxAgent(
name="Sandbox engineer",
model=model,
instructions=(
"Read `repo/task.md` before editing files. Stay grounded in the repository, preserve "
"existing behavior, and mention the exact verification command you ran. "
"If you edit files with apply_patch, paths are relative to the sandbox workspace root."
),
default_manifest=Manifest(
entries={
"repo": LocalDir(src=HOST_REPO_DIR),
}
),
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),
)
),
],
)
async def main() -> None:
result = await Runner.run(
build_agent("gpt-5.6-sol"),
"Open `repo/task.md`, fix the issue, run the targeted test, and summarize the change.",
run_config=RunConfig(
sandbox=SandboxRunConfig(client=UnixLocalSandboxClient()),
workflow_name="Sandbox coding example",
),
)
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())
examples/sandbox/docs/coding_task.pyを参照してください。このコード例では小規模なシェルベースのリポジトリを使用しているため、Unix ローカルでの実行において決定論的に検証できます。
主な選択項目
基本的な実行が動作した後、多くの場合に次に選択する項目は以下のとおりです。
default_manifest: 新規サンドボックスセッション用のファイル、リポジトリ、ディレクトリ、マウントinstructions: 複数のプロンプトに共通して適用する短いワークフロールールbase_instructions: SDK のサンドボックスプロンプトを置き換えるための高度なエスケープハッチcapabilities: ファイルシステムの編集/画像検査、シェル、スキル、メモリ、SDK の圧縮メカニズムなどのサンドボックスネイティブツールrun_as: モデル向けツールを実行するサンドボックスのユーザーアカウントSandboxRunConfig.client: サンドボックスのバックエンドSandboxRunConfig.session、session_state、またはsnapshot: 後続の実行で以前の作業に再接続する方法
次のステップ
- 概念: マニフェスト、機能、権限、スナップショット、実行設定、構成パターンについて説明します。
- サンドボックスクライアント: Unix ローカル、Docker、ホステッドプロバイダー、マウント戦略を選択します。
- エージェントメモリ: 以前のサンドボックス実行で得た知見を保存し、再利用します。
シェルアクセスが、ときどき使用するツールの一つにすぎない場合は、ツールガイドのホステッドシェルから始めてください。ワークスペースの隔離、サンドボックスクライアントの選択、サンドボックスセッションの再開動作が設計の一部となる場合は、サンドボックスエージェントを使用してください。