Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,12 @@ strands-agents/
│ │ ├── repository_session_manager.py # Repository pattern
│ │ └── session_repository.py # Storage interface
│ │
│ │
│ ├── sandbox/ # Sandbox abstraction for code execution
│ │ ├── base.py # Sandbox ABC, ExecutionResult, FileInfo, OutputFile
│ │ ├── host.py # HostSandbox (native Python, default)
│ │ ├── shell_based.py # ShellBasedSandbox (for remote/container envs)
│ │ └── noop.py # NoOpSandbox (raises NotImplementedError for all ops)
│ ├── telemetry/ # Observability (OpenTelemetry)
│ │ ├── tracer.py # Tracing
│ │ ├── metrics.py # Metrics collection
Expand Down Expand Up @@ -183,6 +189,7 @@ strands-agents/
│ ├── types/
│ ├── session/
│ ├── telemetry/
│ ├── sandbox/
│ ├── hooks/
│ ├── plugins/
│ ├── handlers/
Expand Down
16 changes: 15 additions & 1 deletion src/strands/__init__.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
"""A framework for building, deploying, and managing AI agents."""

from . import agent, models, telemetry, types
from . import agent, models, sandbox, telemetry, types
from .agent.agent import Agent
from .agent.base import AgentBase
from .event_loop._retry import ModelRetryStrategy
from .plugins import Plugin
from .sandbox.base import ExecutionResult, FileInfo, OutputFile, Sandbox, StreamChunk, StreamType
from .sandbox.host import HostSandbox
from .sandbox.noop import NoOpSandbox
from .sandbox.shell_based import ShellBasedSandbox
from .tools.decorator import tool
from .types._snapshot import Snapshot
from .types.tools import ToolContext
Expand All @@ -15,11 +19,21 @@
"AgentBase",
"AgentSkills",
"agent",
"ExecutionResult",
"FileInfo",
"HostSandbox",
"models",
"ModelRetryStrategy",
"Plugin",
"OutputFile",
"sandbox",
"Sandbox",
"NoOpSandbox",
"ShellBasedSandbox",
"Skill",
"Snapshot",
"StreamChunk",
"StreamType",
"tool",
"ToolContext",
"types",
Expand Down
16 changes: 16 additions & 0 deletions src/strands/agent/agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
from .._async import run_async
from ..event_loop._retry import ModelRetryStrategy
from ..event_loop.event_loop import INITIAL_DELAY, MAX_ATTEMPTS, MAX_DELAY, event_loop_cycle
from ..sandbox.base import Sandbox
from ..tools._tool_helpers import generate_missing_tool_result_content
from ..types._snapshot import (
SNAPSHOT_SCHEMA_VERSION,
Expand Down Expand Up @@ -146,6 +147,7 @@ def __init__(
tool_executor: ToolExecutor | None = None,
retry_strategy: ModelRetryStrategy | _DefaultRetryStrategySentinel | None = _DEFAULT_RETRY_STRATEGY,
concurrent_invocation_mode: ConcurrentInvocationMode = ConcurrentInvocationMode.THROW,
sandbox: Sandbox | None = None,
):
"""Initialize the Agent with the specified configuration.

Expand Down Expand Up @@ -214,6 +216,9 @@ def __init__(
Set to "unsafe_reentrant" to skip lock acquisition entirely, allowing concurrent invocations.
Warning: "unsafe_reentrant" makes no guarantees about resulting behavior and is provided
only for advanced use cases where the caller understands the risks.
sandbox: Execution environment for agent tools. Tools access the sandbox
via tool_context.agent.sandbox to execute commands, code, and filesystem operations.
Defaults to HostSandbox() for host execution when not specified.

Raises:
ValueError: If agent id contains path separators.
Expand Down Expand Up @@ -298,6 +303,17 @@ def __init__(

self.tool_caller = _ToolCaller(self)

# Initialize sandbox for tool execution environment
# Default to HostSandbox() for backwards compatibility — any code that
# accesses agent.sandbox gets a working local execution environment.
# Import is deferred to avoid unconditional coupling to HostSandbox.
if sandbox is not None:
self.sandbox: Sandbox = sandbox
else:
from ..sandbox.host import HostSandbox

self.sandbox = HostSandbox()

self.hooks = HookRegistry()

self._plugin_registry = _PluginRegistry(self)
Expand Down
30 changes: 30 additions & 0 deletions src/strands/sandbox/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
"""Sandbox abstraction for agent code execution environments.

This module provides the Sandbox interface that decouples tool logic from where code runs.
Tools that need to execute code or access a filesystem receive a Sandbox instead of managing
their own execution, enabling portability across local and cloud environments.

Class hierarchy::

Sandbox (ABC, all abstract + helpers)
├── HostSandbox — native Python methods for host execution (default)
├── ShellBasedSandbox (ABC, only execute_streaming() abstract — shell-based file ops + execute_code)
└── NoOpSandbox — no-op implementation that disables all sandbox functionality
"""

from .base import ExecutionResult, FileInfo, OutputFile, Sandbox, StreamChunk, StreamType
from .host import HostSandbox
from .noop import NoOpSandbox
from .shell_based import ShellBasedSandbox

__all__ = [
"ExecutionResult",
"FileInfo",
"HostSandbox",
"NoOpSandbox",
"OutputFile",
"Sandbox",
"ShellBasedSandbox",
"StreamChunk",
"StreamType",
]
Loading