Pydantic Deep Agents

Pydantic Deep Agents is an MIT-licensed project from Vstorm that ships both a terminal AI assistant and a Python framework built on Pydantic AI. A single create_deep_agent() call gives a model a filesystem, shell, planning, web search, persistent memory, sub-agents, and automatic context management. It works with Claude, GPT, Gemini, local models via Ollama, and other models Pydantic AI supports.

What It Is

The project is an agent harness: the model supplies the reasoning, and the harness supplies tools, memory, sandboxed execution, and long-conversation handling. It can be used in two ways. The first is a Claude Code-style terminal UI (pydantic-deep) that runs on a model of your choice. The second is a Python library, installed with pip install pydantic-deep, for building your own assistant, research agent, or coding tool. Any async, type-hinted Python function can be added as a custom tool, with the agent's typed dependencies injected.

How the Agent Works

Built-in capabilities include file read/write/edit, grep and glob, shell execution, web search and fetch, and browser automation through Playwright. Planning uses a todo list, with an optional plan mode in which a planner subagent asks clarifying questions before execution. Sub-agents handle delegated tasks, and agent teams share TODO lists and a message bus. Skills load on demand from SKILL.md files. Memory persists across sessions in MEMORY.md. Long conversations are summarized, and large tool outputs are evicted to files.

Live Run Forking

The README presents live run forking as its signature feature. An in-flight run splits into parallel branches, each with a copy-on-write filesystem overlay, its own steering message, and its own budget cap. The branches are then merged in one of four modes: manual, auto, auto_with_fallback, or vote. An AI judge can weigh quality, test results, and consistency. Forking is enabled with forking=True or via /fork and /merge in the CLI.

Safety, Control, and Integrations

Docker sandboxing with named workspaces, per-tool approval dialogs, and human-in-the-loop workflows are documented. Lifecycle hooks include a security preset that blocks destructive commands. Cost tracking enforces token and USD budgets, and fallback models retry on API errors. MCP servers such as GitHub, Figma, and Context7 can be connected, and LiteParse parses PDFs, Office documents, and images locally. The repo also includes a DeepResearch reference web app and an ACP adapter for Zed.