pydantic-deep

What it is and what it does

Pydantic Deep Agents is a complete agent harness built on Pydantic AI that lets you build autonomous AI assistants in Python or run one as a self-hosted terminal TUI. It wraps an LLM with planning, tool-calling (file I/O, shell, web search, browser automation), persistent memory, multi-agent coordination, sandboxed execution, and unlimited context via auto-summarization. The framework is 100% type-safe and works with any model provider (Claude, GPT, Gemini, local).

The standout feature is live run forking: when an agent faces a decision (e.g., "refactor with a decorator or context manager?"), it can branch the run into parallel isolated copies, each trying a different approach. An AI judge or test-runner output picks the winner, and the winning branch's history becomes the parent run's continuation. This is unique to pydantic-deep—no other agent framework has it. You can use it as a library (one `create_deep_agent()` call) or as a CLI tool without Python setup.

Use it for:

• Build a self-hosted terminal coding assistant that plans, edits files, runs tests, and searches the web—on your choice of model.
• Spawn multi-agent teams with shared TODO lists and peer messaging to parallelize research, code review, or data processing tasks.
• Prototype agentic workflows with automatic fallback-model retry, persistent memory across sessions, and sandboxed Docker execution.
• Use live run forking to explore multiple solution branches in a single agent run and let test results or an AI judge pick the best approach.
• Build type-safe structured-output agents that connect to MCP servers (GitHub, Figma, custom) without rewiring the plumbing each time.
• Deploy headless agents with unlimited context that auto-summarize when approaching token limits, never hitting a context wall.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Python framework and terminal assistant for building autonomous AI agents with tool-calling, sandboxed execution, multi-agent coordination, and live run forking—all type-safe and model-agnostic.

Yes—if you want to build or run an autonomous AI agent in Python. The framework is actively maintained, MIT-licensed, has low install friction, and offers unique features (live run forking, multi-agent coordination, type safety) that other agent libraries don't. Beta status and rapid release cadence mean breaking changes are possible, but 1030 stars and 127515 monthly downloads suggest the community is already adopting it. Start with the terminal assistant to see if the model fits your workflow, then drop into the framework if you need to customize.

Install

pydantic-deep on PyPI

pip install pydantic-deep

uv add pydantic-deep

poetry add pydantic-deep

Installing pydantic-deep

Before you install

Low friction: pure Python wheel with no compiled dependencies. Active maintenance—released 9 days ago with recent commits. Early beta status (Development Status 4) but 1030 GitHub stars and 127515 monthly downloads suggest solid adoption for a young project (first release December 2025).

License in practice

MIT license (permissive) means you can use, modify, and redistribute freely in commercial or private projects with minimal restrictions—just include the license notice.

Quickstart

pip install pydantic-deep

from pydantic_deep import create_deep_agent

agent = await create_deep_agent(model="anthropic:claude-sonnet-4-6")
result = await agent.run("Build a REST API for auth")

Requires Python 3.10 or later. Needs a valid model provider API key (Anthropic, OpenAI, etc.) and an async runtime to execute agent.run().

Verify before relying

• Whether all 8 runtime dependencies (chardet, pydantic-ai-backend, pydantic-ai-shields, pydantic-ai-slim, pydantic-ai-todo, pydantic, subagents-pydantic-ai, summarization-pydantic-ai) are stable or also in beta.
• Actual resource overhead and latency of live run forking with copy-on-write filesystem overlays under typical workloads.
• Whether Docker sandbox execution is required or optional for the framework use case.
• Production readiness and breaking-change stability policy given the beta status and rapid release cadence.

Package facts

Evidence: pydantic_deep-0.3.43-py3-none-any.whl

Keywords: agent-framework, agentic, ai-agent, autonomous-agent, claude, cli, deep-agent, llm, mcp, multi-agent, openai, pydantic-ai, subagents, terminal-assistant, tool-calling

Tags

More Python Modules packages

Further reading