ag2-shell-tool

Shell tools

When to use

Two distinct tools, both named "shell" — pick deliberately:

Need	Use	Why
Works with any model provider; full control over what runs and where	SandboxShellTool	Client-side subprocess (via LocalEnvironment). You own the sandbox.
Provider-managed sandbox (container, network policy) on OpenAI Responses	ShellTool	Server-side execution. No local subprocess.

SandboxShellTool is the workhorse. Reach for it unless you specifically need provider-managed isolation and you're on OpenAI Responses.

60-second recipe — 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 is provider-agnostic — swap AnthropicConfig for OpenAIConfig(model="gpt-4.1"), GeminiConfig(model="gemini-2.5-pro"), etc. Make sure you've installed the matching ag2[<provider>] extra and set the matching env var (see ag2-quickstart → Prerequisites).

With no arguments, SandboxShellTool defaults to a LocalEnvironment() that creates a temporary working directory (prefixed ag2_sandbox_) and cleans it up when the process exits. Pass a LocalEnvironment with a path to use a specific directory:

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

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

When a path is given, the directory is created if it does not exist and is not deleted on exit. Inspect the resolved working directory via tool.workdir.

Sandboxing (LocalEnvironment + tool-level filters)

For anything beyond a throwaway demo, lock down what the agent can do. The environment (LocalEnvironment) decides where commands run and carries backend config (path, timeout, max_output, env_vars); the tool (SandboxShellTool) decides the agent-facing policy (allowed / blocked / ignore / readonly). Filtering is applied in this order on every call: