pydantic-deep 0.2.21

Deep Agent framework built on Pydantic-ai with planning, filesystem, and subagent capabilities

Pydantic Deep Agents

From framework to terminal — autonomous AI agents that plan, code, and ship

Docs · PyPI · CLI · DeepResearch · Examples

🔄 Unlimited Context  •  🤖 Subagent Delegation  •  🧠 Persistent Memory  •  🛡️ Lifecycle Hooks

---

Same Architecture as the Best

pydantic-deep implements the deep agent pattern — the same architecture powering:

	Product	What They Built
🤖	Claude Code	Anthropic's AI coding assistant
🦾	Manus AI	Autonomous task execution
👨‍💻	Devin	AI software engineer

Now you can build the same thing — or just use the CLI.

Inspired by: LangChain's Deep Agents research on autonomous agent architectures.

---

pydantic-deep is three things:

1. A Python framework for building Claude Code-style agents with planning, filesystem access, subagents, memory, and unlimited context
2. A CLI that gives you a terminal AI assistant out of the box
3. DeepResearch — a full-featured research agent with web UI, web search, diagrams, and sandboxed code execution

---

CLI — Terminal AI Assistant

pip install pydantic-deep[cli]
pydantic-deep chat

That's it. You get an interactive AI agent in your terminal with:

• File read/write/edit, shell execution, glob, grep
• Task planning and subagent delegation
• Persistent memory across sessions
• Context compression for unlimited conversations
• Git-aware project context
• Built-in commands: /commit, /pr, /review, /test, /fix, /explain
• Customizable skills, hooks, and output styles

# Interactive mode
pydantic-deep chat

# Run a single task
pydantic-deep run "Fix the failing tests in src/"

# Docker sandbox for isolated execution
pydantic-deep run "Build a web scraper" --sandbox

# Pick a model
pydantic-deep chat --model anthropic:claude-sonnet-4-20250514

# Manage config
pydantic-deep config set model openai:gpt-4.1

See CLI docs for the full reference.

---

Framework — Build Your Own Agent

pip install pydantic-deep

from pydantic_ai_backends import StateBackend
from pydantic_deep import create_deep_agent, create_default_deps

agent = create_deep_agent()
deps = create_default_deps(StateBackend())

result = await agent.run("Create a todo list for building a REST API", deps=deps)

One function call gives you an agent with planning, filesystem tools, subagents, skills, context management, and cost tracking. Everything is toggleable:

agent = create_deep_agent(
    model="openai:gpt-4.1",
    include_todo=True,          # Task planning
    include_filesystem=True,    # File read/write/edit/execute
    include_subagents=True,     # Delegate to subagents
    include_skills=True,        # Domain-specific skills from SKILL.md files
    include_memory=True,        # Persistent MEMORY.md across sessions
    include_plan=True,          # Structured planning before execution
    include_teams=True,         # Multi-agent teams with shared TODOs
    include_web=True,           # Web search and URL fetching
    context_manager=True,       # Auto-summarization for unlimited context
    cost_tracking=True,         # Token/USD budget enforcement
    include_checkpoints=True,   # Save, rewind, and fork conversations
)

Structured Output

from pydantic import BaseModel

class CodeReview(BaseModel):
    summary: str
    issues: list[str]
    score: int

agent = create_deep_agent(output_type=CodeReview)
result = await agent.run("Review the auth module", deps=deps)
print(result.output.score)  # Type-safe!

Context Management

from pydantic_deep import create_summarization_processor

processor = create_summarization_processor(
    trigger=("tokens", 100000),
    keep=("messages", 20),
)
agent = create_deep_agent(history_processors=[processor])

Hooks (Claude Code-Style)

from pydantic_deep import Hook, HookEvent

agent = create_deep_agent(
    hooks=[
        Hook(
            event=HookEvent.PRE_TOOL_USE,
            command="echo 'Tool called: $TOOL_NAME' >> /tmp/audit.log",
        ),
    ],
)

Cost Tracking

agent = create_deep_agent(
    cost_tracking=True,
    cost_budget_usd=5.0,
    on_cost_update=lambda info: print(f"Cost: ${info.total_usd:.4f}"),
)

Custom Subagents

agent = create_deep_agent(
    subagents=[
        {
            "name": "code-reviewer",
            "description": "Reviews code for quality issues",
            "instructions": "You are a senior code reviewer...",
            "preferred_mode": "sync",
        },
    ],
)

See the full API reference for all options.

---

DeepResearch — Reference App

A full-featured research agent with web UI, built entirely on pydantic-deep.

Plan Mode — planner asks clarifying questions	Parallel Subagents — 5 agents researching simultaneously
Excalidraw Canvas — live diagrams synced with agent	File Browser — workspace files with inline preview

Web search (Tavily, Brave, Jina), sandboxed code execution, Excalidraw diagrams, subagents, plan mode, report export, and more.

cd apps/deepresearch
uv sync
cp .env.example .env  # Add your API keys
uv run deepresearch    # Open http://localhost:8080

See apps/deepresearch/README.md for full setup.

---

Architecture

pydantic-deep implements the deep agent pattern — the same architecture powering Claude Code, Devin, and Manus AI. Every component is modular and works standalone:

Component	Package	What It Does
Backends	pydantic-ai-backend	File storage, Docker/Daytona sandbox
Planning	pydantic-ai-todo	Task tracking with dependencies
Subagents	subagents-pydantic-ai	Sync/async delegation, cancellation
Summarization	summarization-pydantic-ai	LLM summaries or sliding window
Middleware	pydantic-ai-middleware	Lifecycle hooks, permissions

                              pydantic-deep
┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐   │
│   │ Planning │ │Filesystem│ │ Subagents│ │  Skills  │ │  Teams  │   │
│   └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘   │
│        │            │            │            │            │        │
│        └────────────┴─────┬──────┴────────────┴────────────┘        │
│                           │                                         │
│                           ▼                                         │
│  Summarization ──► ┌──────────────────┐ ◄── Middleware              │
│  Checkpointing ──► │    Deep Agent    │ ◄── Hooks                   │
│  Cost Tracking ──► │   (pydantic-ai)  │ ◄── Memory                  │
│                    └────────┬─────────┘                             │
│                             │                                       │
│           ┌─────────────────┼─────────────────┐                     │
│           ▼                 ▼                 ▼                     │
│    ┌────────────┐    ┌────────────┐    ┌────────────┐               │
│    │   State    │    │   Local    │    │   Docker   │               │
│    │  Backend   │    │  Backend   │    │  Sandbox   │               │
│    └────────────┘    └────────────┘    └────────────┘               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

---

All Features

Click to expand full feature list

Core Toolsets

• Planning — Task tracking with subtasks, dependencies, cycle detection. PostgreSQL storage. Event system.
• Filesystem — ls, read_file, write_file, edit_file, glob, grep, execute. Docker sandbox. Permission system.
• Subagents — Sync/async delegation. Background task management. Soft/hard cancellation.
• Summarization — LLM-based summaries or zero-cost sliding window. Trigger on tokens, messages, or fraction.
• Middleware — 7 lifecycle hooks. Composable chains. Permission handling.

Advanced

• Checkpointing — Save state at intervals. Rewind or fork sessions. In-memory and file-based stores.
• Agent Teams — Shared TODO lists with claiming and dependency tracking. Peer-to-peer message bus.
• Hooks — Claude Code-style lifecycle hooks. Shell commands on tool events. Audit logging, safety gates.
• Persistent Memory — MEMORY.md that persists across sessions. Auto-injected into system prompt.
• Context Files — Auto-discover and inject AGENT.md into the system prompt.
• Output Styles — Built-in (concise, explanatory, formal, conversational) or custom from files.
• Plan Mode — Dedicated planner subagent for structured planning before execution.
• Cost Tracking — Token/USD budgets with automatic enforcement and real-time callbacks.
• Eviction Processor — Evict large tool outputs to files. Keep context lean while preserving data.
• Patch Tool Calls — On resume, patch stale tool call results for clean history.
• Custom Tool Descriptions — Override any tool's description via descriptions parameter.
• Custom Commands — /commit, /pr, /review, /test, /fix, /explain. Three-scope discovery: built-in, user, project.
• Web Tools — Web search (Tavily) and URL fetching with automatic markdown conversion.
• Structured Output — Type-safe responses with Pydantic models via output_type.
• Human-in-the-Loop — Confirmation workflows for sensitive operations.
• Streaming — Full streaming support for real-time responses.
• Image Support — Multi-modal analysis with image inputs.

---

Contributing

git clone https://github.com/vstorm-co/pydantic-deepagents.git
cd pydantic-deepagents
make install
make test  # 100% coverage required
make all   # lint + typecheck + test

---

Star History

---

License

MIT — see LICENSE

---

Need help implementing this in your company?

We're Vstorm — an Applied Agentic AI Engineering Consultancy
with 30+ production AI agent implementations.

Made with ❤️ by Vstorm