GitHub - vstorm-co/pydantic-deepagents: Python Deep Agent framework built on top of Pydantic-AI, designed to help you quickly build production-grade autonomous AI agents with planning, filesystem operations, subagent delegation, skills, and structured outputs—in just 10 lines of code.

Pydantic AI Deep Agents Framework

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

🔄 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

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.

Features

🧠 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.

🎯 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.

Use Cases

What You Want to Build	Key Components
AI Coding Assistant	Planning + Filesystem + Skills
Data Analysis Agent	File Uploads + Structured Output
Document Processor	Filesystem + Summarization
Research Agent	Subagents + Planning
Project Scaffolder	Planning + Filesystem
Test Generator	Filesystem + Docker Sandbox

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

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

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  │         │
│      └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘         │
│           │            │            │            │               │
│           └────────────┴─────┬──────┴────────────┘               │
│                              │                                   │
│                              ▼                                   │
│                    ┌──────────────────┐                          │
│  Summarization ──► │    Deep Agent    │                          │
│                    │   (pydantic-ai)  │                          │
│                    └────────┬─────────┘                          │
│                             │                                    │
│           ┌─────────────────┼─────────────────┐                  │
│           ▼                 ▼                 ▼                  │
│    ┌────────────┐    ┌────────────┐    ┌────────────┐            │
│    │   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
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}