Why AI Agents Need a Safe ‘execute’ Tool: Running Commands and Managing Risks

Writing code agents is less about the inability to code and more about the lack of verification after code is generated. Tests like pytest , builds like npm build , and linters like ruff must be checked; the model cannot rely on guesses. The execute tool enables closed‑loop verification for agents, but it is not a simple toggle.

Conclusion First

The value of execute is clear: it lets an agent run commands, inspect results, and then fix issues.

The risk is equally clear: any shell capability can access files, start processes, reach the network, install dependencies, or modify system state.

Therefore, execute is broken down into three concerns:

Can it execute? (Does the backend implement an execution protocol?)

Where does it execute? (Local shell, CI container, or remote sandbox?)

Who approves? (High‑risk commands require Human‑in‑the‑Loop approval.)

File permissions cannot control all shell commands; a proper sandbox, approval workflow, and logging must be designed together.

1. Position of execute in the Toolchain

Deep Agents includes execute in its tool description, but whether it can actually run commands depends on the backend.

Using the default StateBackend or a plain FilesystemBackend does not grant the agent a local shell.

To run commands, the backend must implement SandboxBackendProtocol. Common choices are: LocalShellBackend – suitable for local development or controlled CI environments. LangSmithSandbox – a hosted sandbox solution.

Other remote sandbox backends – for multi‑tenant or untrusted input scenarios.

Because shell commands can test, install dependencies, delete files, or access the network, execute deserves a dedicated discussion.

2. Using LocalShellBackend

Typical local‑development setup:

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

backend = LocalShellBackend(
    root_dir="/tmp/agent-workspace",
    virtual_mode=True,
    timeout=120,
    inherit_env=False,
)

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=backend,
    system_prompt="You are a development assistant; explain the purpose before executing a command.",
)

Key parameters: root_dir: working directory for shell commands and file tools. virtual_mode=True: changes file‑tool path semantics but does not restrict the shell. timeout=120: default 120 seconds, overridable per command. inherit_env=False: does not inherit parent environment variables, reducing key exposure. LocalShellBackend has no sandbox isolation; it runs commands directly on the host shell, inheriting the host user's permissions. Setting virtual_mode=True cannot limit the shell, only the file‑tool view.

3. Suitable Execution Closed‑Loop

execute

shines in a “modify‑then‑verify” loop, e.g., code‑fix tasks:

modify code
→ execute: pytest tests/ -v --tb=short
→ read failure output
→ fix code
→ execute again
→ read result

This workflow fits local development and temporary CI workspaces but should never be exposed directly to public users, as arbitrary scripts could perform network access, file scanning, dependency installation, or malicious actions.

4. Permissions Do Not Currently Guard execute

Earlier (Day 4) the article introduced FilesystemPermission, which only governs file‑tool operations, not shell commands.

In deepagents==0.5.3, if the backend supports command execution and ordinary file permissions are configured, the _PermissionMiddleware will warn that tool‑level permission for execute is not implemented. Do not claim that permissions can block a command like cat /etc/passwd.

More reliable control of execute involves:

Run locally only in temporary directories, containers, or CI runners.

In production, switch to a remote sandbox with file, network, and time limits.

Apply Human‑in‑the‑Loop (HITL) approval for execute.

Log command, arguments, exit code, duration, and truncation status.

5. HITL: Pause Dangerous Commands

Deep Agents’ interrupt_on integrates with LangChain’s HITL capability.

Simple configuration:

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=backend,
    interrupt_on={
        "execute": True,
        "edit_file": True,
    },
    checkpointer=True,
)

For richer approval decisions, use InterruptOnConfig:

from langchain.agents.middleware import InterruptOnConfig

interrupt_on = {
    "execute": InterruptOnConfig(
        allowed_decisions=["approve", "edit", "reject"],
        description="Human must confirm before executing a shell command.",
    )
}

Do not configure delete_file here; Deep Agents currently lacks a built‑in delete_file tool, and file deletion is typically performed via execute, falling under its risk scope.

HITL also depends on a recoverable state; in real projects, configure a clear checkpointer, otherwise paused approvals are hard to resume across requests.

6. Choosing Between Local and Remote Execution

Guidelines for different scenarios:

Personal local development – LocalShellBackend + temporary directory + HITL.

CI automatic test fixing – containerized runner + LocalShellBackend.

Multi‑tenant web service – use a remote sandbox instead of local shell.

Untrusted user code – remote sandbox with network/file/time limits.

File‑only retrieval – disable execute and use glob / grep only.

The sandbox choice is less critical than ensuring commands leave the host, resources are limited, logs are auditable, and failures are traceable.

7. Controlling Command Output

LocalShellBackend.execute()

returns a structured result containing output, exit_code, and truncated. Stdout and stderr are merged; excess output is truncated.

Best practices:

Append --tb=short and --maxfail=1 to test commands.

Set longer timeouts for build and install commands.

Show the agent only the essential log fragments.

First check exit_code, then inspect error details.

Explicitly inform the user when output is truncated.

The purpose of execute is not to let AI run anything arbitrarily, but to give agents a closed loop: modify code, run verification, see failures, and fix again.

My Assessment

I prefer a conservative stance on execute. It indeed turns an agent from “answer‑only” to “verification‑enabled”, but any shell capability pulls in CI/CD pipelines, container sandboxes, key management, audit logging, and cost control.

If your agent runs tests, builds images, or calls external APIs, start recording command, exit code, duration, and truncation status from day one; this data proves far more valuable than model‑generated summaries during later quality reviews.

Next Preview

The next article will dissect the task tool.

Complex tasks rarely need a single agent to handle everything; a primary agent can schedule sub‑agents that focus on analysis, fixing, or review, making boundaries much clearer.

Final Entry Point

If you are adding execute to your agent, reply “DeepAgents” to the public account to receive the code repository.

Leave a comment with the command you plan to run; I will later select typical scenarios and discuss isolation strategies.