Registry / llm-agents / pydantic-ai-backend

pydantic-ai-backend

library0.2.13pypypi✓ verified 87d ago

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.

llm-agents ai-ml devops

pip install pydantic-ai-backend

github ↗package ↗

INSTALL

IMPORT

SIG · PYDANTIC-AI-BACKEN

pydantic-ai-backend

llm-agentspythonv0.2.13

Install

6.6s avg

Import

712ms

Disk

87MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.13 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 8.25s

py 3.11

✓ —

✓ 7s

py 3.12

✓ —

✓ 5.5s

py 3.13

✓ —

✓ 5.8s

py 3.9

✕ build_error

87MB installed

● package 87MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LocalBackend

✓ from pydantic_ai_backends import LocalBackend

✗ from pydantic_ai_backend import LocalBackend

Package name uses plural 'backends'

DockerSandbox

✓ from pydantic_ai_backends import DockerSandbox

✗ from pydantic_ai_backends.sandbox 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

✓ from pydantic_ai_backends import SandboxProtocol

✗ from pydantic_ai_backends.protocol import SandboxProtocol

Not in a protocol module

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)

Debug

Known issues

breakingImports 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 ...'

affects: >=0.2.0

gotchaGlobstar 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.

affects: <0.2.5

gotchaBackendProtocol 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.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pydantic_ai_backends'

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

fix

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

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

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

pydantic_ai_backends.permissions.READONLY_RULESET

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

Upgrade

Version history

0.2.13latest on PyPI · released Jun 17, 2026

Audit

Dependencies

pydantic-ai-slimrequiredCore dependency for capabilities and toolsets

daytona-sdkoptionalCloud sandbox backend (DaytonaSandbox)

dockeroptionalDocker sandbox backend (DockerSandbox)

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vstorm-co/pydantic-ai-backend ↗

packagehttps://pypi.org/project/pydantic-ai-backend/ ↗