Skip to content

Installation

Requirements

  • Python 3.10+
  • uv (recommended) or pip
Bash
uv add pydantic-ai-backend

Install with pip

Bash
pip install pydantic-ai-backend

Optional Dependencies

Console Toolset

For the ready-to-use pydantic-ai toolset:

Bash
uv add pydantic-ai-backend[console]
# or
pip install pydantic-ai-backend[console]

Docker Sandbox

For isolated code execution in Docker containers:

Bash
uv add pydantic-ai-backend[docker]
# or
pip install pydantic-ai-backend[docker]

All Dependencies

Bash
uv add pydantic-ai-backend[console,docker]
# or
pip install pydantic-ai-backend[console,docker]

Environment Setup

API Key (for console toolset)

If using the console toolset with pydantic-ai, set your model provider's API key:

Bash
export OPENAI_API_KEY=your-api-key
Bash
export ANTHROPIC_API_KEY=your-api-key

Docker (for DockerSandbox)

For using DockerSandbox:

  1. Install Docker: Get Docker
  2. Ensure Docker daemon is running
  3. Pull a base image:
Bash
docker pull python:3.12-slim

Verify Installation

Basic (LocalBackend)

Python
from pydantic_ai_backends import LocalBackend

backend = LocalBackend(root_dir=".")
backend.write("test.txt", "Hello from pydantic-ai-backend!")
print(backend.read("test.txt"))

With Console Toolset

Python
from dataclasses import dataclass
from pydantic_ai import Agent
from pydantic_ai_backends import LocalBackend, create_console_toolset

@dataclass
class Deps:
    backend: LocalBackend

backend = LocalBackend(root_dir=".", enable_execute=False)
toolset = create_console_toolset(include_execute=False)

agent = Agent("openai:gpt-4o-mini", deps_type=Deps)
agent = agent.with_toolset(toolset)

result = agent.run_sync("List files in current directory", deps=Deps(backend=backend))
print(result.output)

With Docker

Python
from pydantic_ai_backends import DockerSandbox

sandbox = DockerSandbox(image="python:3.12-slim")
sandbox.write("/workspace/hello.py", "print('Hello from Docker!')")
result = sandbox.execute("python /workspace/hello.py")
print(result.output)  # "Hello from Docker!"
sandbox.stop()

Troubleshooting

Import Errors

Ensure you have the correct Python version:

Bash
python --version  # Should be 3.10+

Docker Permission Denied

On Linux, add your user to the docker group:

Bash
sudo usermod -aG docker $USER

Then log out and back in.

pydantic-ai Not Found

If using console toolset, install with the [console] extra:

Bash
pip install pydantic-ai-backend[console]

Next Steps