Pydantic Deep

0.3.17 verified Fri May 01 auth: no python

Batteries-included agent harness for Python built on Pydantic AI, providing tool-calling, sandboxed execution via Docker, multi-agent teams, and unlimited context. Current version 0.3.17, released monthly.

pip install pydantic-deep

Common errors

error pydantic_ai.exceptions.UserError: Unknown model: openai:gpt-4o ↓

cause Model string format is incorrect or missing provider registration.

fix

Use a supported model format like 'openai:gpt-4o' only if you have pydantic-ai >=0.0.22 with the openai extra installed. Ensure OPENAI_API_KEY env var is set.

error playwright._impl._errors.Error: It looks like you are using Playwright Sync API inside the async event loop. ↓

cause Playwright synchronous calls are used in an async context (e.g., using `sync_playwright` inside async agent run).

fix

Use async with async_playwright() as p: instead of with sync_playwright() as p:. Or switch to BrowserCapability which handles this internally.

error docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused')) ↓

cause Docker daemon is not running or the user does not have permissions to access the Docker socket.

fix

Start Docker Desktop or daemon, and ensure your user is in the 'docker' group (on Linux).

Warnings

breaking In 0.3.16, `instructions` now replaces `BASE_PROMPT` instead of appending to it. Previously, passing `instructions="..."` appended to the base prompt; now it becomes the full system prompt. Use `instructions=None` (default) to keep the default base prompt. ↓

fix Update code: if you previously relied on appending, manually include the base prompt prefix in your instructions string.

gotcha Tools passed via `tools=` parameter lost metadata (name, description, etc.) before 0.3.13. They were added via `agent.tool()` which hardcoded `takes_ctx=True` and discarded `Tool` metadata. ↓

fix Upgrade to >=0.3.13 or pass tools as list of `Tool` objects using the `tool` decorator with full metadata.

gotcha BrowserCapability opens Playwright browser eagerly on every agent run before 0.3.11. This caused a browser window to spawn even when no browser tool was used. ↓

fix Upgrade to >=0.3.11, which lazily initializes Playwright only on first browser tool call.

deprecated Subagent factory ignores parent `web_search`/`web_fetch` settings before 0.3.14, causing 400 errors on Bedrock/Vertex models that do not support the beta web tools. ↓

fix Upgrade to >=0.3.14, which propagates parent settings to subagents.

Install

pip install pydantic-deep[all]

Imports

create_deep_agent

wrong

from pydantic_deep.agent import create_deep_agent

correct

from pydantic_deep import create_deep_agent

Public API is at package root, not in submodule

BrowserCapability

wrong

from pydantic_deep import BrowserCapability

correct

from pydantic_deep.capabilities import BrowserCapability

Capabilities are in the capabilities subpackage

DockerSandbox

wrong

from pydantic_deep import DockerSandbox

correct

from pydantic_deep.sandbox import DockerSandbox

Sandbox classes are in the sandbox subpackage

Quickstart

Minimal agent creation with a single synchronous call.

import asyncio
from pydantic_deep import create_deep_agent

async def main():
    agent = create_deep_agent(
        model="openai:gpt-4o",
        api_key=os.environ.get("OPENAI_API_KEY", ""),
        instructions="You are a helpful assistant."
    )
    result = await agent.run("What is the capital of France?")
    print(result.data)

if __name__ == "__main__":
    import os
    asyncio.run(main())