Skip to main content
pydantic-deepagents is a Claude Code–style deep agent harness built on pydantic-ai. It uses pydantic-ai-backend’s SandboxProtocol for filesystem, shell, grep, and edit operations, Mirage’s PydanticAIWorkspace is a drop-in implementation of that protocol.

​
Install

uv add 'mirage-ai[pydantic-ai]'
This pulls in pydantic-ai>=1.35 and pydantic-ai-backend>=0.1.0. To use it with pydantic-deepagents: 
uv add pydantic-deep

​
Usage

from dataclasses import dataclass

from pydantic_ai import Agent
from pydantic_ai_backends import create_console_toolset

from mirage import MountMode, Workspace
from mirage.agents.pydantic_ai import PydanticAIWorkspace, build_system_prompt
from mirage.resource.ram import RAMResource

ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
backend = PydanticAIWorkspace(ws)


@dataclass
class Deps:
    backend: PydanticAIWorkspace


agent = Agent(
    "openai:gpt-4.1",
    system_prompt=build_system_prompt(
        mount_info={"/": "In-memory filesystem (read/write)"},
    ),
    deps_type=Deps,
    toolsets=[create_console_toolset()],
)

result = agent.run_sync(
    "Create /hello.txt with 'hi' and cat it.",
    deps=Deps(backend=backend),
)
print(result.output)

​
Exports

SymbolPurpose
PydanticAIWorkspaceSandboxProtocol implementation backed by a Mirage workspace.
build_system_promptGenerates a system prompt that describes mounted paths to the model.
PydanticAIWorkspace routes file operations through the Ops layer directly and shell operations through Workspace.execute() for full pipe and flag support. PDF reads are converted to images via pages_to_images so the agent can pass them as BinaryContent.

​
Examples