Pydantic Deep Agents
A self-hosted terminal assistant and Python harness for tool-calling agents on supported models.
Per-dimension scores and reasoning
Evidence shows: tool approval dialogs (approve/auto-approve/deny), default security hook blocks destructive commands, Docker sandbox isolation, budget limits, type-safe inputs. Deductions: data flow transparency insufficient, no detailed logging/audit of tool calls; source attribution only via author field, publisher identity unverified.
Evidence shows: extensive test coverage, CI includes lint, typecheck, tests, security scan, dependency version constraints. Deductions: no specific failure message examples, dependency availability not verified (static review).
Evidence shows: targets developers and end-users, provides CLI and framework usage, supports multiple models and providers, broad scenarios. Deductions: capability boundaries not precisely described, trigger conditions (e.g., forking) not detailed.
Evidence shows: README well-structured, install instructions detailed, MIT license clear, CHANGELOG and versioning present. Deductions: known limitations not explicitly listed, maintenance responsibility unclear (publisher unverified).
Evidence shows: type-safe outputs, structured output, high marginal value (unique features like forking). Deductions: cost-benefit not quantified, actual runtime performance not verified.
Evidence shows: README claims partially correspond to code and tests, test files verify some functionality. Deductions: insufficient cross-source corroboration, relies solely on single repository evidence.
- Publisher identity unverified, treat source with caution.
- Data flow transparency insufficient, tool call audit logs not explicit.
- Known limitations not listed, potential issues may be hidden.
What does this agent do, and when should you use it?
Pydantic Deep Agents combines a terminal TUI assistant with a Python agent framework built on Pydantic AI. It can run interactively, headlessly through pydantic-deep run for scripts and CI/CD, or as an agent created with create_deep_agent(). Configurable capabilities include filesystem and shell tools, planning, subagents, teams, memory, context compression, checkpoints, MCP, cost controls, and typed output. Execution can use local or Docker-backed environments; Docker supports named workspaces and mounts the project at /workspace. Its Live Run Forking feature branches an in-progress run into isolated alternatives and resolves them through manual, automatic, fallback, or vote-based selection.
An agent created with create_deep_agent() can work on a task using ls, read_file, write_file, edit_file, glob, grep, and execute against its workspace, with optional web search, web fetch, and Playwright browser automation. include_todo, include_plan, include_subagents, and include_teams enable task organization and delegation; MEMORY.md can persist memory, while context_manager summarizes or slides context as it approaches its budget. With forking=True, the agent receives fork_run, inspect_branches, merge_or_select, terminate_branch, diff_branches, and fork_cost; branches use copy-on-write BranchOverlay isolation, and LiveForkCapability(test_command="pytest -q") can use test exit codes in selection. Results are presented as streaming chats, tool calls, and diffs in the Textual TUI, returned as Pydantic-typed values through output_type, or emitted for automation with pydantic-deep run --json.
- A Python team that wants a local terminal coding assistant to inspect a repository, edit files, and run tests.
- An engineering lead running tasks such as fixing a failing test_auth.py test from CI/CD or a script.
- A Python developer adding filesystem, shell, planning, and budget-governed agent behavior to an internal developer tool with create_deep_agent().
- A refactoring team that wants to run pytest -q across competing implementations before selecting a branch.
- An application team coordinating parallel research or code-review work through subagents, shared TODOs, and a message bus.
- An engineering group that needs MCP connections to GitHub, Figma, Context7, DeepWiki, or a custom server.
What are this agent's strengths and limitations?
- It provides an interactive terminal TUI, a headless runner, and the create_deep_agent() library API in one project, spanning direct use and embedded applications.
- Live Run Forking supplies copy-on-write isolated branches, branch budgets, a test-command hook, and four merge modes for comparing verifiable approaches.
- It is built on Pydantic AI and explicitly documents paths for Anthropic, OpenAI, OpenRouter, Gemini, Ollama, and OpenAI-compatible endpoints.
- output_type can return Pydantic models rather than requiring callers to parse JSON, alongside token/USD tracking and budget enforcement.
- Named Docker workspaces, MCP, lifecycle hooks, and default_security_hook() address controlled execution and external-tool integration.
- Its core behavior requires a model that supports tool calling, while model APIs, network access, and credentials are the deployer's responsibility.
- The supplied material explicitly requires Python 3.10+; Docker sandboxing and Playwright browser automation add Docker and browser-related dependencies.
- Live Run Forking executes parallel branches and can assign each a budget, so adoption requires planning for additional model-call and test-execution cost.
- The default security hook is documented to block destructive shell commands, path traversal, and secret leaks, but its fit with an organization's security policy must be validated.
- The material provides installation and usage examples but does not specify a production deployment topology, long-term support policy, or a complete provider-authentication matrix.
How do you install or deploy this agent?
On macOS or Linux, run: curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deep/main/install.sh | bash. For Windows or manual CLI installation, run: pip install "pydantic-deep[cli]"; for framework use, run: pip install pydantic-deep. The README states a Python 3.10+ requirement. Before using the documented Anthropic example, set credentials with: export ANTHROPIC_API_KEY=sk-ant-....
How do you use this agent?
Start the interactive terminal assistant with: pydantic-deep. To choose a model: pydantic-deep tui --model openrouter:anthropic/claude-opus-4-6. For headless use: pydantic-deep run "Fix the failing test in test_auth.py"; add --json for JSON output. In Python: from pydantic_deep import create_deep_agent; agent = create_deep_agent(model="anthropic:claude-sonnet-4-6"); result = await agent.run("Build a REST API for auth"). Use pydantic-deep tui --sandbox docker for the Docker sandbox; browser automation requires pydantic-deep[browser] and pydantic-deep tui --browser.
How does this agent compare with similar options?
The README compares the project with Claude Code, Aider, LangGraph, and CrewAI, positioning it as a combination of terminal assistant, Python framework, model choice, and Live Run Forking. Claude Code has a terminal experience and MCP in that comparison, while the README presents run branching and a Python framework as Pydantic Deep differentiators; LangGraph and CrewAI are positioned more as frameworks. Choose based on the need for a TUI, branch resolution, and Pydantic AI integration rather than treating cross-project feature markings as independently verified.