pydantic-deep¶
Deep Agent Framework, the Pydantic AI way
pydantic-deep is a Python deep agent framework built on top of Pydantic AI designed to help you quickly build production-grade autonomous agents with planning, filesystem operations, subagent delegation, and skills.
Why use pydantic-deep?¶
Building autonomous agents that can plan, execute multi-step tasks, and work with files is complex. pydantic-deep provides:
📋 Planning
Built-in todo list for task decomposition. Agents break down complex tasks and track progress automatically.
📁 Filesystem
Virtual and real filesystem operations. Read, write, edit files with grep and glob support.
🤖 Subagents
Delegate specialized tasks to isolated subagents. Code review, testing, documentation - each with focused context.
🎯 Skills
Modular capability packages loaded on-demand. Extend agent abilities without bloating context.
Hello World Example¶
import asyncio
from pydantic_deep import create_deep_agent, DeepAgentDeps, StateBackend
async def main():
# Create a deep agent with all capabilities
agent = create_deep_agent(
model="openai:gpt-4.1",
instructions="You are a helpful coding assistant.",
)
# Create dependencies with in-memory storage
deps = DeepAgentDeps(backend=StateBackend())
# Run the agent
result = await agent.run(
"Create a Python function that calculates fibonacci numbers",
deps=deps,
)
print(result.output)
asyncio.run(main())
Tools & Dependency Injection Example¶
from pydantic_ai import RunContext
from pydantic_deep import create_deep_agent, DeepAgentDeps
# Define a custom tool
async def get_weather(
ctx: RunContext[DeepAgentDeps],
city: str,
) -> str:
"""Get weather for a city."""
# Access dependencies via ctx.deps
return f"Weather in {city}: Sunny, 22°C"
# Create agent with custom tools
agent = create_deep_agent(
tools=[get_weather],
instructions="You can check weather and work with files.",
)
Key Features¶
| Feature | Description |
|---|---|
| Planning | Todo toolset for task decomposition and tracking |
| Filesystem | Read, write, edit, glob, grep operations |
| Subagents | Context-isolated task delegation |
| Skills | Modular capability packages with progressive disclosure |
| Backends | StateBackend, FilesystemBackend, DockerSandbox, CompositeBackend |
| Structured Output | Type-safe responses with Pydantic models via output_type |
| Context Management | Automatic conversation summarization for long sessions |
| HITL | Human-in-the-loop approval workflows |
llms.txt¶
pydantic-deep supports the llms.txt standard. Access documentation at /llms.txt for LLM-optimized content.