Pydantic AI Backend

0.2.5 verified Fri May 01 auth: no python

File storage and sandbox backends for AI agents built with pydantic-ai. Provides backends (LocalBackend, DockerSandbox, DaytonaSandbox) and console tools (ls, read, write, glob, grep, execute) bundled as pydantic-ai capabilities. Current version 0.2.5. Release cadence: weekly.

pip install pydantic-ai-backend

Common errors

error ModuleNotFoundError: No module named 'pydantic_ai_backends' ↓

cause Installed old version (<0.2.0) where package was named 'pydantic_ai_backend' (singular).

fix

Upgrade: pip install --upgrade pydantic-ai-backend

error AttributeError: module 'pydantic_ai_backends' has no attribute 'DockerSandbox' ↓

cause Missing docker extra or old version before DockerSandbox was added (v0.1.12).

fix

Install with docker extra: pip install pydantic-ai-backend[docker] and ensure version >=0.1.12

error pydantic_ai_backends.permissions.READONLY_RULESET ↓

cause Import path changed after v0.2.0; previously might have been in a different location.

fix

Use: from pydantic_ai_backends.permissions import READONLY_RULESET

Warnings

breaking Imports changed from 'pydantic_ai_backend' (singular) to 'pydantic_ai_backends' (plural) after v0.1.x. ↓

fix Use 'from pydantic_ai_backends import ...' instead of 'from pydantic_ai_backend import ...'

gotcha Globstar patterns (e.g., '**/*.md') in glob_info and glob tools did not match nested files before v0.2.5. Only now fixed to use find -path. ↓

fix Upgrade to >=0.2.5 for correct recursive glob support.

gotcha BackendProtocol methods are synchronous. When using them inside async agent tools (e.g., ConsoleCapability), ensure calls are wrapped in asyncio.to_thread() to avoid blocking the event loop. The built-in toolset from >=0.2.3 already wraps them; custom tools must handle this. ↓

fix Wrap backend calls in asyncio.to_thread() if called from async context.

Install

pip install pydantic-ai-backend[daytona]

Imports

LocalBackend

wrong

from pydantic_ai_backend import LocalBackend

correct

from pydantic_ai_backends import LocalBackend

Package name uses plural 'backends'

DockerSandbox

wrong

from pydantic_ai_backends.sandbox import DockerSandbox

correct

from pydantic_ai_backends import DockerSandbox

Top-level import, not nested

ConsoleCapability

from pydantic_ai_backends import ConsoleCapability

READONLY_RULESET

from pydantic_ai_backends.permissions import READONLY_RULESET

SandboxProtocol

wrong

from pydantic_ai_backends.protocol import SandboxProtocol

correct

from pydantic_ai_backends import SandboxProtocol

Not in a protocol module

Quickstart

Create an agent with console capability, using LocalBackend to read/write files.

from pydantic_ai import Agent
from pydantic_ai_backends import LocalBackend, ConsoleCapability
from pydantic_ai_backends.permissions import READONLY_RULESET

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[ConsoleCapability(permissions=READONLY_RULESET)],
    system_prompt="You can read files in the current directory.",
)
backend = LocalBackend(work_dir="/tmp/demo")
with backend as b:
    b.write("hello.txt", b"Hello, world!")
    result = agent.run_sync("Read hello.txt", deps=b)
    print(result.data)