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
|
|
pip install pydantic-deepfrom 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
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 |
🧠 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
taskin 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.
💾 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.
🎯 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.
| 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.
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
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!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())],
)from pydantic_deep import create_summarization_processor
processor = create_summarization_processor(
trigger=("tokens", 100000),
keep=("messages", 20),
)
agent = create_deep_agent(history_processors=[processor])agent = create_deep_agent(
subagents=[
{
"name": "code-reviewer",
"description": "Reviews code for quality issues",
"instructions": "You are a senior code reviewer...",
"preferred_mode": "sync",
},
],
)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_toagent = create_deep_agent(include_teams=True)
# Agent gets tools: spawn_team, assign_task, check_teammates,
# message_teammate, dissolve_teamfrom 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",
),
],
)agent = create_deep_agent(include_memory=True, memory_dir="./agent-data")
# Agent reads MEMORY.md on start, can write_memory to persist factsagent = 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}"),
)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])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")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
)agent = create_deep_agent(include_plan=True, plans_dir="./plans")
# Agent gets a dedicated plan mode subagent for structured planning## Combines token tracking + auto-compression in a single middleware
agent = create_deep_agent(
context_manager=True,
context_manager_max_tokens=100000,
)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 handlingagent = create_deep_agent(
skill_directories=[{"path": "~/.pydantic-deep/skills", "recursive": True}],
) pydantic-deep
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │ Planning │ │Filesystem│ │ Subagents│ │ Skills │ │ Teams │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘ │
│ │ │ │ │ │ │
│ └────────────┴─────┬──────┴────────────┴────────────┘ │
│ │ │
│ ▼ │
│ Summarization ──► ┌──────────────────┐ ◄── Middleware │
│ Checkpointing ──► │ Deep Agent │ ◄── Hooks │
│ Cost Tracking ──► │ (pydantic-ai) │ ◄── Memory │
│ └────────┬─────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ State │ │ Local │ │ Docker │ │
│ │ Backend │ │ Backend │ │ Sandbox │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
- 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)
git clone https://github.com/vstorm-co/pydantic-deepagents.git
cd pydantic-deepagents
make install
make test # 100% coverage required
make all # lint + typecheck + testSee CONTRIBUTING.md for full guidelines.
MIT — see LICENSE
Built with ❤️ by vstorm-co
