Filesystem

Filesystem

Bases: Capability

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

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

    def tools(self) -> list[Tool]:
        if self.session is None:
            raise ValueError("Filesystem capability is not bound to a SandboxSession")

        toolset = FilesystemToolSet(
            view_image=ViewImageTool(session=self.session, user=self.run_as),
            apply_patch=SandboxApplyPatchTool(session=self.session, user=self.run_as),
        )
        if self.configure_tools is not None:
            self.configure_tools(toolset)

        return [toolset.view_image, toolset.apply_patch]

configure_tools class-attribute instance-attribute

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

Optional callback that can customize or replace bundled filesystem 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()

instructions async

instructions(manifest: Manifest) -> str | None

Return a deterministic instruction fragment appended during run preparation.

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

async def instructions(self, manifest: Manifest) -> str | None:
    """Return a deterministic instruction fragment appended during run preparation."""
    _ = manifest
    return None

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

FilesystemToolSet dataclass

Mutable bundle of tools exposed by the filesystem capability.

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

@dataclass
class FilesystemToolSet:
    """Mutable bundle of tools exposed by the filesystem capability."""

    view_image: ViewImageTool
    apply_patch: SandboxApplyPatchTool