ag2-shell-tool

シェルツール

使用する場面

名前がどちらも「shell」のツールが2つあります。用途に応じて選んでください。

必要なこと	使用するツール	理由
どのモデルプロバイダーでも動作し、実行内容と実行場所を完全に制御できる	SandboxShellTool	クライアント側の subprocess（LocalEnvironment 経由）です。サンドボックスは自分で管理します。
OpenAI Responses のプロバイダー管理サンドボックス（コンテナー、ネットワークポリシー）	ShellTool	サーバー側で実行します。ローカルの subprocess は使用しません。

SandboxShellTool は汎用的に使えるツールです。プロバイダー管理の分離が特に必要で、OpenAI Responses を使用している場合を除き、こちらを選んでください。

60秒でできるレシピ — SandboxShellTool

from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import SandboxShellTool

agent = Agent(
    "coder",
    "You write and run Python code.",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[SandboxShellTool()],
)

reply = await agent.ask("Write a hello world script and run it.")
print(await reply.content())

SandboxShellTool はプロバイダーに依存しません。AnthropicConfig を OpenAIConfig(model="gpt-4.1")、GeminiConfig(model="gemini-2.5-pro") などに置き換えられます。対応する ag2[<provider>] エクストラをインストールし、対応する環境変数を設定してください（ag2-quickstart → 前提条件を参照）。

引数を指定しない場合、SandboxShellTool はデフォルトで LocalEnvironment() を使用します。これは一時作業ディレクトリ（接頭辞 ag2_sandbox_）を作成し、プロセスの終了時に削除します。特定のディレクトリを使用するには、パスを指定した LocalEnvironment を渡してください。

from pathlib import Path
from ag2.tools import LocalEnvironment, SandboxShellTool

SandboxShellTool(LocalEnvironment("/tmp/my_project"))
SandboxShellTool(LocalEnvironment(Path("/tmp/my_project")))

パスを指定すると、ディレクトリが存在しない場合は作成され、終了時には削除されません。解決された作業ディレクトリは tool.workdir で確認できます。

サンドボックス化（LocalEnvironment とツールレベルのフィルター）

使い捨てのデモ以上の用途では、エージェントに許可する操作を制限してください。環境（LocalEnvironment）はコマンドの実行場所を決め、バックエンドの設定（path、timeout、max_output、env_vars）を保持します。ツール（SandboxShellTool）は、エージェントに適用するポリシー（allowed / blocked / ignore / readonly）を決めます。呼び出しごとに、次の順序でフィルタリングが適用されます。

1. allowed — 設定されている場合、コマンドは少なくとも1つのプレフィックスに一致する必要があります。この制限モードでは、シェル演算子（>、>>、|、;、&&、||、`、$(）も拒否されます。
2. blocked — 設定されている場合、コマンドはいずれのプレフィックスにも一致してはなりません。ベストエフォートの制限です（先頭コマンドのプレフィックスのみを照合するため、コマンドの連結で回避できます）。
3. ignore — コマンド内のリテラルなパスのトークンを gitignore 形式のパターンと照合します。一致した場合は "Access denied: <path>" を返します。
4. 環境の subprocess を使用して実行します。

from ag2.tools import LocalEnvironment, SandboxShellTool

sh = SandboxShellTool(
    LocalEnvironment(
        path="/tmp/my_project",
        timeout=30,
        max_output=50_000,
    ),
    allowed=["python", "uv run", "git"],
    blocked=["rm -rf", "curl", "wget"],
    ignore=["**/.env", "*.key", "secrets/**"],
)

読み取り専用モード

確認のみのアクセス（cat、head、tail、ls、grep、find、git log、git diff、git status など）には、次を使用します。

from ag2.tools import LocalEnvironment, SandboxShellTool

sh = SandboxShellTool(LocalEnvironment(path="/my/codebase"), readonly=True)

組み込みの読み取り専用許可リストを上書きするには、明示的に allowed=[...] を渡してください。

パラメーターのリファレンス

LocalEnvironment（環境 — コマンドの実行場所と実行方法）：

パラメーター	デフォルト	説明
path	None	作業ディレクトリ。None → 一時ディレクトリ（接頭辞 ag2_sandbox_）。終了時に削除されます
cleanup	None	None → 自動設定（path=None の場合は True、それ以外は False）。終了時に path を削除します
timeout	60	コマンドごとのタイムアウト（秒）。タイムアウトすると終了コード 124 とともに "Command timed out after Ns" を返します
max_output	100_000	返される最大文字数（切り詰められた出力には末尾に [truncated: …] が付加されます）
env_vars	None	各コマンドに追加で設定される環境変数

SandboxShellTool（ツール — エージェントに適用するコマンドポリシー）：

パラメーター	デフォルト	説明
environment	None	バックエンド。None → LocalEnvironment()（ローカルの subprocess、一時ディレクトリ）
allowed	None	コマンドプレフィックスの許可リスト。None → すべてのコマンドを許可
blocked	None	コマンドプレフィックスの拒否リスト（ベストエフォートであり、セキュリティ境界ではありません）
ignore	None	gitignore 形式のパスパターン。一致した場合、コマンドを拒否します
readonly	False	True かつ allowed が未設定の場合、組み込みの読み取り専用リストに制限します

状態を保持する複数ターンのワークスペース

ファイルは ask() の呼び出し間も workdir に保持されるため、エージェントは前回の作業を引き継いで進められます。

from ag2.tools import LocalEnvironment, SandboxShellTool

sh = SandboxShellTool(LocalEnvironment(path="/tmp/counter_demo"))
agent = Agent("coder", "You manage files.", config=config, tools=[sh])

reply1 = await agent.ask("Create counter.txt with value 0")
reply2 = await reply1.ask("Increment the counter by 1")
reply3 = await reply2.ask("Read the counter and tell me the value")

プロバイダー標準の ShellTool（OpenAI Responses のみ）

ShellTool はプロバイダーが実行する機能フラグです。サーバー側でシェルを実行するのは OpenAI Responses API のみです。 Anthropic の bash ツールはクライアント側で実行され、UnsupportedToolError で拒否されます。代わりに SandboxShellTool を使用してください。Gemini もサポートされていません。

from ag2.config import OpenAIResponsesConfig
from ag2.tools import ShellTool

agent = Agent("devops", config=OpenAIResponsesConfig(model="gpt-4.1"), tools=[ShellTool()])

OpenAI では、実行環境を設定できます。

from ag2.config import OpenAIResponsesConfig
from ag2.tools import ContainerAutoEnvironment, NetworkPolicy, ShellTool

agent = Agent(
    "devops",
    config=OpenAIResponsesConfig(model="gpt-4.1"),
    tools=[
        ShellTool(
            environment=ContainerAutoEnvironment(
                network_policy=NetworkPolicy(allowed_domains=["pypi.org"]),
            ),
        ),
    ],
)

環境オプション（OpenAI 専用）：

環境	説明
ContainerAutoEnvironment	オプションの NetworkPolicy を設定できる、プロバイダー管理のコンテナ
ContainerReferenceEnvironment	ID を指定して既存のコンテナを参照します

SandboxShellTool と ShellTool の比較

	SandboxShellTool	ShellTool
実行方式	クライアント側の subprocess	プロバイダー側のコンテナ
プロバイダーのサポート	すべてのプロバイダー	OpenAI Responses のみ
環境の制御	完全（allowed、blocked、ignore、readonly など）	限定的（プロバイダーによって異なります）
ローカルファイルシステムへのアクセス	可能（公開する対象を選択できます）	不可
ネットワークの制御	blocked / allowed パターンで制御	OpenAI：NetworkPolicy
インポート	from ag2.tools import SandboxShellTool, LocalEnvironment	from ag2.tools import ShellTool

詳細

• website/docs/user-guide/tools/local_shell.mdx — SandboxShellTool / LocalEnvironment の詳細なリファレンスと、コマンドフィルタリングの仕様。
• website/docs/user-guide/tools/builtin_tools.mdx#shell — プロバイダー標準の ShellTool の設定と、環境設定。
• シェル呼び出しの前に毎回人間による承認を求めるには、approval_required() ミドルウェアを追加してください（ag2-hitl を参照）。

よくある落とし穴

• 本番環境でサンドボックス化を忘れる — フィルターなしの SandboxShellTool() は、60 秒のタイムアウト内であらゆる場所のあらゆるコマンドを実行します。重要な用途では、allowed、blocked、または readonly を設定してください。
• ignore が確認するのはコマンド文字列内のリテラルなパスのみ — 変数の置換、コマンド置換（`cat secrets.key`）、動的な glob 展開は検査されません。読み取りコマンドもブロックする場合は、blocked=["cat", "less"] も設定してください。
• blocked はベストエフォートであり、セキュリティ境界ではない — 先頭のコマンドのプレフィックスとのみ照合するため、コマンドの連結（echo x; rm -rf ~）で blocked=["rm"] を回避できます。実際に分離するには、allowed / readonly または分離されたコンテナバックエンドを使用してください。
• Anthropic または Gemini で ShellTool を使おうとする — サポートされていないため、UnsupportedToolError が発生します。代わりに SandboxShellTool を使用してください。
• 別のプロセスも使用しているハードコードされたパスを使う — /tmp/my_project を複数のエージェントで共有すると、競合が発生します。並列実行では tempfile.mkdtemp(prefix="...") を使用してください。
• ShellTool がローカルファイルにアクセスできると想定する — ローカルファイルにはアクセスできません。プロバイダーのコンテナ内で実行されます。ファイルシステム上のデータを扱う場合は、SandboxShellTool を使用してください。
• LLM にシェルアクセスを許可しても安全だと考える — サンドボックス内であっても、許可する範囲を限定する prompt を作成し、破壊的な操作には approval_required() を併用することを検討してください。