Backends API¶

Backends are provided by pydantic-ai-backend.

Full API Reference

For complete API documentation, see pydantic-ai-backend API Reference.

Quick Import Reference¶

Python

from pydantic_deep import (
    # Backends
    LocalBackend,
    StateBackend,
    CompositeBackend,
    DockerSandbox,
    BaseSandbox,
    AsyncBaseSandbox,
    # Protocols
    BackendProtocol,
    SandboxProtocol,
    # Session Management
    SessionManager,
    # Runtimes
    RuntimeConfig,
    BUILTIN_RUNTIMES,
    get_runtime,
    # Console Toolset
    create_console_toolset,
    get_console_system_prompt,
    ConsoleDeps,
    # Types
    FileInfo,
    FileData,
    WriteResult,
    EditResult,
    ExecuteResponse,
    GrepMatch,
)

Available Backends¶

Backend	Description	Docs
`LocalBackend`	Local filesystem with shell execution	Link
`StateBackend`	In-memory storage for testing	Link
`DockerSandbox`	Docker container execution	Link
`CompositeBackend`	Route by path prefix	Link

Writing your own backend¶

Subclass one of the two bases rather than implementing BackendProtocol by hand: each derives every file operation from shell commands, so you implement execute and edit and get the rest.

Base	For a sandbox reached	Notes
`BaseSandbox`	synchronously — a socket, a subprocess
`AsyncBaseSandbox`	over an async transport — `asyncssh`, an async HTTP SDK	Implement `execute` and `edit` as coroutines

Pick AsyncBaseSandbox for a natively async sandbox rather than wrapping it in a synchronous facade: ensure_async cannot see through a facade, so it thread-wraps it and every call then occupies a worker thread that has to hop back onto the event loop. A sandbox whose own recovery path also needs a thread deadlocks against its own pool. is_async_backend is the check ensure_async uses, exposed so a host can ask the same question.

See Writing your own backend.

Console Toolset¶

The console toolset provides file operation tools for pydantic-ai agents:

Python

from pydantic_deep import create_console_toolset, LocalBackend, DeepAgentDeps

toolset = create_console_toolset()
backend = LocalBackend(root_dir=".")
deps = DeepAgentDeps(backend=backend)

See Console Toolset docs for details.

SessionManager¶

For multi-user applications with isolated Docker sandboxes:

Python

from pydantic_deep import SessionManager

manager = SessionManager(
    default_runtime="python-datascience",
    workspace_root="/app/workspaces",
)

sandbox = await manager.get_or_create(user_id="alice")

See Docker docs for details.