Shell

Shell

Bases: Capability

Source code in src/agents/sandbox/capabilities/shell.py

class Shell(Capability):
    type: Literal["shell"] = "shell"
    configure_tools: ShellToolConfigurator | None = Field(default=None, exclude=True)
    """Optional callback that can customize or replace bundled shell tools."""

    def tools(self) -> list[Tool]:
        if self.session is None:
            raise ValueError("Shell capability is not bound to a SandboxSession")
        toolset = ShellToolSet(
            exec_command=ExecCommandTool(session=self.session, user=self.run_as),
            write_stdin=WriteStdinTool(session=self.session)
            if self.session.supports_pty()
            else None,
        )
        if self.configure_tools is not None:
            self.configure_tools(toolset)
        tools: list[Tool] = [toolset.exec_command]
        if toolset.write_stdin is not None:
            tools.append(toolset.write_stdin)
        return tools

    async def instructions(self, manifest: Manifest) -> str | None:
        _ = manifest
        return _SHELL_INSTRUCTIONS

configure_tools class-attribute instance-attribute

configure_tools: ShellToolConfigurator | None = Field(
    default=None, exclude=True
)

Optional callback that can customize or replace bundled shell tools.

clone

clone() -> Capability

Return a per-run copy of this capability.

Source code in src/agents/sandbox/capabilities/capability.py

def clone(self) -> "Capability":
    """Return a per-run copy of this capability."""
    cloned = self.model_copy(deep=False)
    for name, value in self.__dict__.items():
        cloned.__dict__[name] = _clone_capability_value(value)
    return cloned

bind

bind(session: BaseSandboxSession) -> None

Bind a live session to this plugin (default no-op).

Source code in src/agents/sandbox/capabilities/capability.py

def bind(self, session: BaseSandboxSession) -> None:
    """Bind a live session to this plugin (default no-op)."""
    self.session = session

bind_run_as

bind_run_as(user: User | None) -> None

Bind the sandbox user identity for model-facing operations.

Source code in src/agents/sandbox/capabilities/capability.py

def bind_run_as(self, user: User | None) -> None:
    """Bind the sandbox user identity for model-facing operations."""
    self.run_as = user

required_capability_types

required_capability_types() -> set[str]

Return capability types that must be present alongside this capability.

Source code in src/agents/sandbox/capabilities/capability.py

def required_capability_types(self) -> set[str]:
    """Return capability types that must be present alongside this capability."""
    return set()

sampling_params

sampling_params(
    sampling_params: dict[str, Any],
) -> dict[str, Any]

Return additional model request parameters needed for this capability.

Source code in src/agents/sandbox/capabilities/capability.py

def sampling_params(self, sampling_params: dict[str, Any]) -> dict[str, Any]:
    """Return additional model request parameters needed for this capability."""
    _ = sampling_params
    return {}

process_context

process_context(
    context: list[TResponseInputItem],
) -> list[TResponseInputItem]

Transform the model input context before sampling.

Source code in src/agents/sandbox/capabilities/capability.py

def process_context(self, context: list[TResponseInputItem]) -> list[TResponseInputItem]:
    """Transform the model input context before sampling."""
    return context

ShellToolSet dataclass

Mutable bundle of tools exposed by the shell capability.

Source code in src/agents/sandbox/capabilities/shell.py

@dataclass
class ShellToolSet:
    """Mutable bundle of tools exposed by the shell capability."""

    exec_command: ExecCommandTool
    write_stdin: WriteStdinTool | None