API Reference

Complete API documentation for pydantic-ai-backend.

Quick Example

Python

from pydantic_ai import Agent

from pydantic_ai_backends import ConsoleCapability, DockerWorkspace

agent = Agent(
    "anthropic:claude-opus-5-5",
    capabilities=[DockerWorkspace(runtime="python-minimal"), ConsoleCapability()],
)

result = agent.run_sync("Create hello.py and run it")

Modules

Module	Description
Capability	ConsoleCapability: the console tools as one capability
Workspaces	Docker, sandboxd, Kubernetes, Daytona and state-document workspaces
Permissions	Rulesets, presets and the permission checker
Docker	DockerSandbox, SessionManager, built-in runtimes
Kubernetes	KubernetesPodSandbox
sandboxd	The sandbox service, its configuration, wire protocol and archive
Toolsets	create_console_toolset and the tool text
Types	Type definitions, StateBackend

Import Reference

Python

# Console tools (requires the [console] extra)
from pydantic_ai_backends import (
    ConsoleCapability,
    create_console_toolset,
    get_console_system_prompt,
)

# Workspaces (requires the [workspaces] extra, plus the provider's own)
from pydantic_ai_backends import (
    DaytonaWorkspace,
    DockerWorkspace,
    KubernetesWorkspace,
    SandboxdWorkspace,
    StateWorkspace,
)

# Sandboxes the workspaces run on
from pydantic_ai_backends import (
    BUILTIN_RUNTIMES,
    DockerSandbox,
    KubernetesPodSandbox,
    RuntimeConfig,
    SessionManager,
)

# A filesystem kept as a JSON document
from pydantic_ai_backends import StateBackend

# Types
from pydantic_ai_backends import (
    CommandOutcome,
    EditResult,
    ExecuteResponse,
    FileInfo,
    GrepMatch,
    WriteResult,
)

Protocols

CommandRunner

What a sandbox implements for the container workspaces and sandboxd to run commands in it under the workspace contract.

pydantic_ai_backends.protocol.CommandRunner

Bases: Protocol

Commands under a workspace's failure contract.

Raises rather than folding a failure into the output, keeps stdout and stderr apart, and can be stopped from elsewhere by the run_id its caller chose. Implemented by DockerSandbox and KubernetesPodSandbox, and what both sandboxd's /run and the Pydantic AI workspaces in :mod:pydantic_ai_backends.workspaces are built on.

Source code in src/pydantic_ai_backends/protocol.py

@runtime_checkable
class CommandRunner(Protocol):
    """Commands under a workspace's failure contract.

    Raises rather than folding a failure into the output, keeps stdout and
    stderr apart, and can be stopped from elsewhere by the `run_id` its caller
    chose. Implemented by `DockerSandbox` and `KubernetesPodSandbox`, and what
    both `sandboxd`'s `/run` and the Pydantic AI workspaces in
    :mod:`pydantic_ai_backends.workspaces` are built on.
    """

    async def run_command(
        self,
        argv: Sequence[str],
        *,
        run_id: str,
        env: Mapping[str, str] | None = None,
        timeout: float | None = None,
        output_limit: int | None = None,
    ) -> CommandOutcome:
        """Run `argv` with stdin at EOF and wait for it.

        Args:
            argv: The program and its arguments, passed through literally.
            run_id: Names the run, so :meth:`stop_command` can stop it.
            env: Variables layered over the sandbox's environment.
            timeout: Seconds before the command is stopped; none when `None`.
            output_limit: Combined output bytes before it is stopped; the
                implementation's default when `None`.

        Raises:
            SandboxUnavailableError: The sandbox is gone or not running.
        """
        ...

    async def stop_command(self, run_id: str) -> None:
        """Stop the command started under `run_id` and everything it started.

        A run that already finished, or never started, has nothing to stop.
        """
        ...

run_command(argv, *, run_id, env=None, timeout=None, output_limit=None) async

Run argv with stdin at EOF and wait for it.

Parameters:

Name	Type	Description	Default
argv	Sequence[str]	The program and its arguments, passed through literally.	required
run_id	str	Names the run, so :meth:stop_command can stop it.	required
env	Mapping[str, str] | None	Variables layered over the sandbox's environment.	None
timeout	float | None	Seconds before the command is stopped; none when None.	None
output_limit	int | None	Combined output bytes before it is stopped; the implementation's default when None.	None

Raises:

Type	Description
SandboxUnavailableError	The sandbox is gone or not running.

Source code in src/pydantic_ai_backends/protocol.py

async def run_command(
    self,
    argv: Sequence[str],
    *,
    run_id: str,
    env: Mapping[str, str] | None = None,
    timeout: float | None = None,
    output_limit: int | None = None,
) -> CommandOutcome:
    """Run `argv` with stdin at EOF and wait for it.

    Args:
        argv: The program and its arguments, passed through literally.
        run_id: Names the run, so :meth:`stop_command` can stop it.
        env: Variables layered over the sandbox's environment.
        timeout: Seconds before the command is stopped; none when `None`.
        output_limit: Combined output bytes before it is stopped; the
            implementation's default when `None`.

    Raises:
        SandboxUnavailableError: The sandbox is gone or not running.
    """
    ...

stop_command(run_id) async

Stop the command started under run_id and everything it started.

A run that already finished, or never started, has nothing to stop.

Source code in src/pydantic_ai_backends/protocol.py

async def stop_command(self, run_id: str) -> None:
    """Stop the command started under `run_id` and everything it started.

    A run that already finished, or never started, has nothing to stop.
    """
    ...

SandboxUnavailableError

pydantic_ai_backends.protocol.SandboxUnavailableError

Bases: RuntimeError

The sandbox is gone or no longer running, so no command can reach it.

Source code in src/pydantic_ai_backends/protocol.py

class SandboxUnavailableError(RuntimeError):
    """The sandbox is gone or no longer running, so no command can reach it."""