pydantic-deep 0.2.17

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

Pydantic AI Deep Agents Framework

Build Claude Code-Style AI Agents — In 10 Lines of Python

Docs • Examples • PyPI • DeepResearch

🔄 Unlimited Context via summarization  •  🤖 Subagent Delegation sync & async  •  🧩 Modular use only what you need  •  🎯 Fully Type-Safe

---

See It In Action

---

Get Started in 60 Seconds

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)

That's it. Your agent can now:

• ✅ Plan tasks — break down complex work into steps
• ✅ Read & write files — navigate and modify codebases
• ✅ Delegate to subagents — spawn specialists for specific tasks
• ✅ Load skills — use domain-specific instructions
• ✅ Manage context — handle unlimited conversation length
• ✅ Checkpoint & rewind — save conversation state, rewind, or fork sessions
• ✅ Agent teams — shared TODO lists and peer-to-peer messaging
• ✅ Persistent memory — remember facts across sessions via MEMORY.md
• ✅ Lifecycle hooks — Claude Code-style hooks for audit, safety gates, and custom logic
• ✅ Output styles — built-in or custom response formatting
• ✅ Cost tracking — token/USD budgets with automatic enforcement
• ✅ Middleware — composable before/after hooks with permission handling
• ✅ Context files — auto-inject DEEP.md, AGENTS.md, CLAUDE.md into system prompt
• ✅ Context manager — hybrid summarization + sliding window middleware

---

Same Architecture as the Best

pydantic-deep implements the deep agent architecture — the same patterns 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.

Inspired by: This framework is also inspired by LangChain's Deep Agents research on autonomous agent architectures.

---

DeepResearch — Full-Featured Reference App

Plan Mode — planner asks clarifying questions before research

Parallel Subagents — 5 agents researching simultaneously

---

Features

Core Toolsets

🧠 Planning — pydantic-ai-todo

Task tracking with read_todos / write_todos. Subtasks & dependencies with cycle detection. PostgreSQL storage. Event system for webhooks.

📁 Filesystem — pydantic-ai-backend

Full access: ls, read_file, write_file, edit_file, glob, grep, execute. Docker sandbox for isolation. Permission system (allow/deny/ask). Session manager for multi-user apps.

🤖 Subagents — subagents-pydantic-ai

Delegate with task in sync or async mode. Background task management. Dynamic agent creation at runtime. Soft/hard cancellation.

💬 Summarization — summarization-pydantic-ai

Two modes: LLM-based intelligent summaries or zero-cost sliding window. Trigger on tokens, messages, or context fraction. Custom prompts.

🛡️ Middleware — pydantic-ai-middleware

7 lifecycle hooks: before_run, after_run, before_model_request, before_tool_call, after_tool_call, on_tool_error, on_error. Composable chains. Permission handling.

Advanced Features

💾 Checkpointing — Save conversation state at intervals. Rewind to any checkpoint, or fork into a new session from a past state. In-memory and file-based stores.

👥 Agent Teams — Shared TODO lists with claiming and dependency tracking. Peer-to-peer message bus between team members. Spawn, assign, and dissolve teams via tools.

🪝 Hooks — Claude Code-style lifecycle hooks. Run shell commands or scripts on events like before_tool_call or after_run. Use for audit logging, safety gates, or custom side effects.

🧠 Persistent Memory — Agents read/write a MEMORY.md file that persists across sessions. Automatic injection into system prompt. Tools: read_memory, write_memory.

📄 Context Files — Auto-discover and inject DEEP.md, AGENTS.md, CLAUDE.md, and SOUL.md from the working directory into the system prompt.

🎨 Output Styles — Built-in styles (concise, detailed, markdown, etc.) or load custom styles from files. Control response formatting via output_style.

📋 Plan Mode — Dedicated plan mode subagent for structured planning before execution. Separate toolset with plan-specific instructions.

💰 Cost Tracking — Track token usage and USD costs per run. Set budgets with automatic enforcement. Callbacks for real-time cost updates.

📦 Eviction Processor — Automatically evict large tool outputs to files when they exceed token limits. Keeps conversation lean while preserving data access.

🔧 Patch Tool Calls — On session resume, patch stale tool call results so the model sees clean history without re-executing tools.

Built-in Capabilities

🎯 Skills — Load domain instructions from markdown files with YAML frontmatter.

📊 Structured Output — Type-safe responses with Pydantic models via output_type.

👤 Human-in-the-Loop — Built-in confirmation workflows for sensitive operations.

⚡ Streaming — Full streaming support for real-time responses.

🖼️ Image Support — Pass images to the agent for multi-modal analysis.

---

Use Cases

What You Want to Build	Key Components
AI Coding Assistant	Planning + Filesystem + Skills + Memory + Hooks
Data Analysis Agent	File Uploads + Structured Output + Teams
Document Processor	Filesystem + Summarization + Eviction
Research Agent	Subagents + Planning + Checkpointing — see DeepResearch
Project Scaffolder	Planning + Filesystem + Output Styles
Test Generator	Filesystem + Docker Sandbox + Cost Tracking
Multi-Agent Workflow	Teams + Subagents + Middleware
Audited Enterprise Agent	Hooks + Middleware + Cost Tracking

Reference app: DeepResearch is a full-featured research agent built with pydantic-deep. It includes a web UI, MCP-powered web search, Excalidraw diagrams, code execution in Docker, and more. See deepresearch/README.md for setup instructions.

---

Modular — Use What You Need

Every component works standalone:

Component	Package	Use It For
Backends	pydantic-ai-backend	File storage, Docker sandbox
Planning	pydantic-ai-todo	Task tracking
Subagents	subagents-pydantic-ai	Task delegation
Summarization	summarization-pydantic-ai	Context management
Middleware	pydantic-ai-middleware	Lifecycle hooks, permissions

Full-stack template? fastapi-fullstack — Production-ready with FastAPI + Next.js

---

Go Deeper

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!

File Uploads

from pydantic_deep import run_with_files

with open("data.csv", "rb") as f:
    result = await run_with_files(
        agent,
        "Analyze this data and find trends",
        deps,
        files=[("data.csv", f.read())],
    )

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])

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",
        },
    ],
)

Checkpointing & Rewind

from pydantic_deep import create_deep_agent

agent = create_deep_agent(
    include_checkpoints=True,
    checkpoint_frequency="every_tool",  # "every_tool", "every_turn", or "manual_only"
    max_checkpoints=20,
)
# Agent gets tools: save_checkpoint, list_checkpoints, rewind_to

Agent Teams

agent = create_deep_agent(include_teams=True)
# Agent gets tools: spawn_team, assign_task, check_teammates,
#                   message_teammate, dissolve_team

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",
        ),
    ],
)

Persistent Memory

agent = create_deep_agent(include_memory=True, memory_dir="./agent-data")
# Agent reads MEMORY.md on start, can write_memory to persist facts

Cost Tracking

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

Middleware

from pydantic_ai_middleware import before_tool_call, ToolDecision

@before_tool_call
async def audit(ctx, tool_name, tool_args):
    print(f"Calling {tool_name}")
    return ToolDecision.ALLOW

agent = create_deep_agent(middleware=[audit])

Output Styles

agent = create_deep_agent(output_style="concise")  # Built-in: concise, explanatory, formal, conversational

# Or load custom styles from a directory
agent = create_deep_agent(output_style="my-style", styles_dir="./styles")

Context Files

agent = create_deep_agent(
    context_files=["DEEP.md", "AGENTS.md"],  # Explicit files
    context_discovery=True,  # Auto-discover DEEP.md, CLAUDE.md, SOUL.md in working dir
)

Plan Mode

agent = create_deep_agent(include_plan=True, plans_dir="./plans")
# Agent gets a dedicated plan mode subagent for structured planning

Context Manager (Hybrid)

## Combines token tracking + auto-compression in a single middleware
agent = create_deep_agent(
    context_manager=True,
    context_manager_max_tokens=100000,
)

Skills

Create ~/.pydantic-deep/skills/review/SKILL.md:

---
name: code-review
description: Review Python code for quality
---

# Code Review Skill

Check for:
- [ ] Security issues
- [ ] Type hints
- [ ] Error handling

agent = create_deep_agent(
    skill_directories=[{"path": "~/.pydantic-deep/skills", "recursive": True}],
)

---

Architecture

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

---

Related Projects

• pydantic-ai - The foundation: Agent framework by Pydantic
• pydantic-ai-backend - File storage and sandbox backends
• pydantic-ai-todo - Task planning toolset
• subagents-pydantic-ai - Multi-agent orchestration
• summarization-pydantic-ai - Context management
• pydantic-ai-middleware - Middleware system with lifecycle hooks
• DeepResearch - Full-featured research agent built with pydantic-deep (included in this repo)
• fastapi-fullstack - Full-stack AI app template
• deepagents - Deep Agent implementation by LangChain (inspiration)

---

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

See CONTRIBUTING.md for full guidelines.

---

Star History

---

License

MIT — see LICENSE

_{Built with ❤️ by vstorm-co}