I've been working on pydantic-deepagents, a framework for creating deep AI agents that go beyond simple chatbots. It's built on top of pydantic-ai (which leverages Pydantic for structured data), but adds serious muscle: planning capabilities, filesystem access, subagent spawning, and more. Think of it as a toolkit for agents that can handle real-world tasks like file processing, task organization, and even human-in-the-loop decisions—all with type-safe outputs and streaming support.
Why this? I've built a ton of AI prototypes, and most frameworks fall short when you need agents to interact with files, manage long contexts, or break down complex problems into sub-tasks. This one aims to fix that, with a focus on extensibility and reliability (100% test coverage, MIT license).
Quick highlights: - Multiple backends: In-memory state, filesystem persistence, Docker sandbox for isolation, or mix them with composites. - Toolsets out of the box: TODO management, filesystem ops, subagents for delegation, and a skills system with markdown-based prompts. - File uploads: Agents can process uploaded files directly—e.g., analyze a CSV and spit out insights. - Structured responses: Use Pydantic models for guaranteed type-safe outputs, no more parsing JSON hacks. - Context smarts: Auto-summarizes long chats to stay under token limits. - Human confirmation: Built-in workflows for when you need a human to approve actions. - Streaming: Real-time responses for better UX.
Installation is dead simple: pip install pydantic-deep (or uv add for the cool kids). For Docker sandbox, add [sandbox] extras.
Here's a quickstart to get an agent organizing your tasks:
import asyncio from pydantic_deep import create_deep_agent, create_default_deps from pydantic_deep.backends import StateBackend
async def main(): backend = StateBackend() deps = create_default_deps(backend) agent = create_deep_agent() result = await agent.run("Help me organize my tasks", deps=deps) print(result.output)
asyncio.run(main())
Want structured output? Define a Pydantic model and pass it as output_type:
from pydantic import BaseModel
class TaskAnalysis(BaseModel): summary: str priority: str estimated_hours: float
agent = create_deep_agent(output_type=TaskAnalysis) # Then access result.output.priority safely.
File handling example: Upload a sales.csv and ask the agent to analyze it for top products. It mounts the file in /uploads and processes it seamlessly.
For long sessions, add a summarization processor to keep things efficient:
from pydantic_deep.processors import create_summarization_processor
processor = create_summarization_processor(trigger=("tokens", 100000), keep=("messages", 20)) agent = create_deep_agent(history_processors=[processor])
Check out the demo video here: https://drive.google.com/file/d/1hqgXkbAgUrsKOWpfWdF48cqaxRh...
And a full chat app example with file uploads and streaming: https://github.com/vstorm-co/pydantic-deepagents/tree/main/e...
Docs: https://vstorm-co.github.io/pydantic-deepagents/ PyPI: https://pypi.org/project/pydantic-deep/ Repo: https://github.com/vstorm-co/pydantic-deepagents (star it if you like!)
I'd love feedback—especially if you're building AI agents in Python. What features would make this indispensable? Bugs? Ideas for skills?
Thanks!
