Skip to content

Pydantic AI Backend

Pydantic AI Backend

Sandboxed execution & file tools for agents.

PyPI version PyPI Downloads GitHub Stars Python 3.10+ License: MIT Coverage Status CI Pydantic AI

Part of Pydantic Deep Agents

Pydantic AI Backend is one library in Pydantic Deep Agents — the open-source Claude Code alternative & Python agent framework. Use it standalone, or get every library wired together in a single create_deep_agent() call.

pydantic-ai-backend gives pydantic-ai agents somewhere to work and the tools to work there: workspaces Pydantic AI does not ship — a Docker container, a sandboxd session, a Kubernetes pod, a Daytona sandbox, a JSON document — and file and shell tools that run in whichever workspace the run has.

  • Self-hosted sandboxes

    A container on this host, or behind sandboxd so your app never holds the Docker socket

  • Console tools

    ls, read, write, edit, glob, grep, execute — in any Pydantic AI workspace

  • Permission system

    Per-path and per-command rules, approvals and presets

  • Checked against the contract

    Pydantic AI's own workspace conformance suite, on a real Docker daemon

Quick Start

Python
from pydantic_ai import Agent

from pydantic_ai_backends import ConsoleCapability, DockerWorkspace

agent = Agent(
    "anthropic:claude-opus-5-5",
    capabilities=[DockerWorkspace(image="python:3.12-slim"), ConsoleCapability()],
)
result = agent.run_sync("Write fizzbuzz.py and run it.")

The container is created on the first tool call and kept after the run; pass the message history to the next run and it works in the same container.

With Permissions

Python
from pydantic_ai_backends import ConsoleCapability
from pydantic_ai_backends.permissions import READONLY_RULESET

# Read-only agent — write/edit/execute tools hidden from the model
capability = ConsoleCapability(permissions=READONLY_RULESET)

Choose Your Workspace

Same tools, different environments:

Python
from pydantic_ai.capabilities import LocalWorkspace

workspace = LocalWorkspace("./workspace")  # Pydantic AI's own; isolates nothing
Python
from pydantic_ai_backends import StateWorkspace

workspace = StateWorkspace()  # a JSON document, no side effects
Python
from pydantic_ai_backends import DockerWorkspace

workspace = DockerWorkspace(runtime="python-datascience")
Python
from pydantic_ai_backends import SandboxdWorkspace

workspace = SandboxdWorkspace(service_url="http://sandboxd:8080", token="...")

Available Tools

Tool Description
ls List files in a directory
read_file Read file content with line numbers, or an image or PDF the model can see
write_file Create or overwrite a file
edit_file Replace strings in a file
glob Find files matching a pattern
grep Search for patterns in files
execute Run shell commands (optional)

Workspace Comparison

Workspace Kept between runs Commands Best For
StateWorkspace In your store No Tests, files kept in a database
DockerWorkspace Until destroyed Yes Safe execution on one host
SandboxdWorkspace Until destroyed, or the service's TTL Yes Containerised apps, many users
KubernetesWorkspace Until destroyed Yes Cluster-scheduled sandboxes
DaytonaWorkspace Until destroyed, or Daytona's auto-delete Yes Hosted sandboxes
Package Description
Pydantic Deep Agents Full agent framework (uses this library)
pydantic-ai-todo Task planning toolset
subagents-pydantic-ai Multi-agent orchestration
summarization-pydantic-ai Context management
pydantic-ai The foundation — agent framework by Pydantic

Next Steps