Workspaces API¶

The workspace capabilities come from Pydantic AI (LocalWorkspace) and pydantic-ai-backend (the rest); pydantic-deep re-exports them. See Workspaces for how to choose one.

Full API Reference

For complete API documentation, see pydantic-ai-backend API Reference and Pydantic AI's workspaces.

Quick Import Reference¶

Python

from pydantic_deep import (
    # Workspace capabilities
    LocalWorkspace,
    StateWorkspace,
    DockerWorkspace,
    SandboxdWorkspace,
    KubernetesWorkspace,
    DaytonaWorkspace,
    # The document a StateWorkspace works in
    StateBackend,
    # Keeps file operations inside a workspace's working directory
    ConfinedWorkspace,
    # Docker runtimes
    RuntimeConfig,
    BUILTIN_RUNTIMES,
    get_runtime,
    # Console toolset
    create_console_toolset,
    get_console_system_prompt,
    # Types
    FileData,
    FileInfo,
)

Workspace capabilities¶

Capability	Where a run works	Docs
`LocalWorkspace(path)`	A directory on this machine	Link
`StateWorkspace()`	An in-memory `StateBackend` document, files only	Link
`DockerWorkspace(...)`	A Docker container on this host	Link
`SandboxdWorkspace(...)`	A `sandboxd` session	Link
`KubernetesWorkspace(...)`	A pod	Link
`DaytonaWorkspace(...)`	A Daytona sandbox	Link

Each sandbox capability creates its environment on first use and keeps it after the run; await capability.destroy(ref) removes it.

ConfinedWorkspace(workspace) wraps a workspace and refuses a file operation whose real path leaves its working directory; the console's glob and grep check their search root the same way. Commands are not confined. See Workspaces.

Console Toolset¶

create_deep_agent builds the console toolset for you. To give a plain Pydantic AI agent the same file and shell tools:

Python

from pydantic_ai import Agent, DeferredToolRequests
from pydantic_deep import LocalWorkspace, create_console_toolset

agent = Agent(
    "anthropic:claude-sonnet-4-6",
    capabilities=[LocalWorkspace(".")],
    toolsets=[create_console_toolset()],
    # `execute` asks for approval by default; or pass require_execute_approval=False
    output_type=[str, DeferredToolRequests],
)

See Console Toolset docs for details.