ag2-shell-tool 为 AG2 的 Agent 赋予运行 shell 命令的能力。它实际包含两个名称都叫 shell 的工具，机制与适用条件不同，需要按需选择。
两个工具的选择
SandboxShellTool 通过 LocalEnvironment 使用客户端 subprocess 执行命令，支持任意模型提供商，由使用者自行掌控沙箱，可完全控制运行什么、在哪里运行。ShellTool 是提供商托管的沙箱（容器、网络策略），基于 OpenAI Responses 在服务端执行，没有本地子进程。文档建议：除非你明确需要提供商托管的隔离且使用 OpenAI Responses，否则优先使用 SandboxShellTool。
基本用法
使用 SandboxShellTool 时需要从 ag2.tools 导入 SandboxShellTool（以及需要自定义时导入 LocalEnvironment），并配合模型配置（如 AnthropicConfig、OpenAIConfig、GeminiConfig 等）。SandboxShellTool 与提供商无关，可替换不同模型配置。使用前需要安装对应的 ag2[<provider>] extra 并设置相应环境变量。
不带参数时，SandboxShellTool 默认使用 LocalEnvironment()，会创建一个临时工作目录（前缀 ag2_sandbox_），并在进程退出时清理。若要使用指定目录，可传入带路径的 LocalEnvironment（字符串或 Path 均可）；给定路径时目录不存在会被创建，退出时不会删除。可通过 tool.workdir 查看解析后的工作目录。
沙箱与过滤（LocalEnvironment + 工具级过滤）
对于非临时演示的场景，需要限制 Agent 能做什么。环境（LocalEnvironment）决定命令在哪里运行并携带后端配置（path、timeout、max_output、env_vars）；工具（SandboxShellTool）决定面向 Agent 的命令策略（allowed / blocked / ignore / readonly）。每次调用按以下顺序应用过滤：
- allowed：若设置，命令必须匹配至少一个前缀；在此受限模式下，shell 操作符（>、>>、|、;、&&、||、`、$()）也会被拒绝。
- blocked：若设置，命令不得匹配任何前缀；仅为尽力而为（按头命令前缀匹配，链式命令可绕过）。
- ignore：对命令中的字面路径 token 按 gitignore 风格模式检查，匹配则返回 "Access denied: <path>"。
- 之后通过环境的 subprocess 执行。
只读模式
用于仅检查类访问（cat、head、tail、ls、grep、find、git log、git diff、git status 等）时，可设置 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()（本地子进程、临时目录）。
- allowed：默认 None。命令前缀白名单，None 表示允许全部命令。
- blocked：默认 None。命令前缀黑名单（尽力而为，不是安全边界）。
- ignore：默认 None。gitignore 风格路径模式，匹配则阻止该命令。
- readonly：默认 False。为 True 且未设置 allowed 时，限制为内置只读列表。
状态化多轮工作区
文件在 workdir 中跨 ask() 调用持久保留，因此 Agent 可以基于先前工作进行构建，实现多轮对话式文件操作（例如创建计数器文件、递增、再读取）。
提供商原生 ShellTool（仅 OpenAI Responses）
ShellTool 是提供商执行的能力标志。只有 OpenAI Responses API 在服务端运行 shell。Anthropic 的 bash 工具是客户端侧的，会被以 UnsupportedToolError 拒绝，此时应使用 SandboxShellTool。Gemini 也不受支持。
使用 ShellTool 时可配置 OpenAI 的执行环境，例如通过 ContainerAutoEnvironment 配合 NetworkPolicy 设置允许的域名。OpenAI 专属的环境选项包括：ContainerAutoEnvironment（提供商托管容器，可选 NetworkPolicy）和 ContainerReferenceEnvironment（按 ID 引用已有容器）。
两个工具的对比
执行方式：SandboxShellTool 为客户端 subprocess，ShellTool 为提供商侧容器。提供商支持：前者支持任意提供商，后者仅 OpenAI Responses。环境控制：前者完整（allowed、blocked、ignore、readonly 等），后者有限（取决于提供商）。本地文件系统访问：前者可以（由你决定暴露什么），后者不可以。网络控制：前者通过 blocked / allowed 模式，后者在 OpenAI 上通过 NetworkPolicy。导入方式：SandboxShellTool 与 LocalEnvironment 来自 ag2.tools，ShellTool 同样来自 ag2.tools。
深入与常见问题
参考文档包括 local_shell.mdx（SandboxShellTool / LocalEnvironment 的完整参考与命令过滤语义）和 builtin_tools.mdx#shell（提供商原生 ShellTool 的设置与环境配置）。若需在每次 shell 调用前加入人工审批，可叠加 approval_required() 中间件。
常见陷阱包括：生产环境忘记沙箱化（无过滤的 SandboxShellTool() 可在任何地方运行任何命令，默认超时 60 秒，非平凡用途应设置 allowed、blocked 或 readonly）；ignore 只检查命令字符串中的字面路径，变量替换、命令替换、动态 glob 展开不会被检查，若还要阻止读取器需叠加 blocked=["cat", "less"]；blocked 是尽力而为而非安全边界，只匹配头命令前缀，链式命令可绕过，真正隔离应使用 allowed / readonly 或隔离容器后端；在 Anthropic 或 Gemini 上使用 ShellTool 会抛出 UnsupportedToolError；硬编码路径可能与其他进程冲突，并行运行建议使用 tempfile.mkdtemp(prefix="...")；ShellTool 无法访问本地文件，需要访问文件系统应使用 SandboxShellTool；即使有沙箱，也应为破坏性操作编写限定范围的提示词并考虑配合 approval_required()。