ag2-shell-tool

Shell 工具

适用场景

有两个不同的工具都叫“shell”——请根据需要谨慎选择：

需求	使用	原因
适用于任何模型提供商；完全掌控运行内容和运行位置	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 + 工具级筛选）

除一次性演示外，请限制 Agent 的操作权限。环境（LocalEnvironment）决定命令的运行位置，并携带后端配置（path、timeout、max_output、env_vars）；工具（SandboxShellTool）决定面向 Agent 的策略（allowed / blocked / ignore / readonly）。每次调用都会按以下顺序应用筛选：

1. allowed — 如果已设置，命令必须匹配至少一个前缀。在此受限模式下，Shell 运算符（>、>>、|、;、&&、||、`、$(）也会被拒绝。
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	每条命令的超时时间，单位为秒（返回 "Command timed out after Ns"，退出代码为 124）
max_output	100_000	返回的最大字符数（截断后的输出会附加 [truncated: …]）
env_vars	None	合并到每条命令中的额外环境变量

SandboxShellTool（工具——面向 Agent 的命令策略）：

参数	默认值	说明
environment	None	后端。None → LocalEnvironment()（本地 subprocess、临时目录）
allowed	None	命令前缀白名单。None → 允许所有命令
blocked	None	命令前缀黑名单（尽力而为，不构成安全边界）
ignore	None	Gitignore 风格的路径模式；匹配时会阻止命令执行
readonly	False	当设为 True 且未设置 allowed 时，限制为内置只读列表

有状态的多轮工作区

文件会在多次 ask() 调用之间保留在 workdir 中，因此 Agent 可以基于之前的工作继续操作：

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 会在服务端运行 shell。**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 的设置和环境配置。
• 如需在每次 shell 调用前要求人工审批，可添加 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。
• 使用其他进程也在操作的硬编码路径——多个 Agent 共用 /tmp/my_project 时会产生竞争。并行运行时请使用 tempfile.mkdtemp(prefix="...")。
• 期望 ShellTool 能访问本地文件——它不能；它运行在提供方的容器中。要访问文件系统中的内容，请使用 SandboxShellTool。
• 信任大模型使用 shell 的权限——即使处于沙盒隔离中，也应编写能够限定允许操作范围的 prompt，并考虑为破坏性操作配合使用 approval_required()。