Skip to content

Pydantic Deep Agents

Build autonomous AI assistants in Python — file access, web search, memory, multi-agent teams, and unlimited context, out of the box.

CI Coverage PyPI Python License OpenSSF Best Practices

A language model can answer questions. It can't read your files, run code, search the web, remember things between sessions, or work on several tasks at once.

Pydantic Deep Agents gives it all of that. You call create_deep_agent() once, and the model gains a filesystem, a shell, web search and browsing, persistent memory, parallel sub-agents, and automatic handling of conversations longer than the context window. You describe what the agent should do — the library handles the how.

It's built on Pydantic AI, so it speaks the language you already know: type hints, async/await, and plain Python. It works with Claude, GPT, Gemini, and any other model Pydantic AI supports.

Think of it as a foundation

Pydantic Deep Agents is the open-source, self-hosted base for building your own Claude Code, Manus, or Devin-style assistant — without rebuilding the plumbing every time.

The key features

  • Batteries included. Filesystem, shell, web, memory, planning, and sub-agents are one keyword argument away — not a weekend of glue code.
  • Typed end to end. Strict Pyright + MyPy, 100% test coverage. If it type-checks, it tends to just work.
  • Modular. Use the whole framework, or cherry-pick a single package. Each capability is independently installable.
  • Safe by default. Docker sandboxing, per-tool approval gates, and human-in-the-loop workflows for anything risky.
  • Unlimited context. Long conversations are summarized and large tool outputs are evicted to files automatically — the agent keeps going.

Your first agent

Let's start with the smallest thing that works. An agent that can think, and write code:

Python
import asyncio
from pydantic_deep import create_deep_agent, DeepAgentDeps, StateBackend


async def main():
    agent = create_deep_agent(
        model="anthropic:claude-sonnet-4-6",
        instructions="You are a helpful coding assistant.",
    )

    # StateBackend keeps files in memory — perfect for trying things out.
    deps = DeepAgentDeps(backend=StateBackend())

    result = await agent.run(
        "Create a Python function that calculates Fibonacci numbers",
        deps=deps,
    )
    print(result.output)


asyncio.run(main())

That's it. The agent already has a filesystem, planning, web search, and more — all enabled by default.

Where did the file go?

The agent wrote to deps.backend. With StateBackend it lives in memory; swap in LocalBackend(root_dir="…") and the very same code writes to real files on disk. Your code doesn't change — only the backend does. More on that in Backends.

Adding your own tools

Your agent isn't limited to the built-in tools. Any async function with type hints becomes a tool — and it gets the agent's dependencies injected for free:

Python
from pydantic_ai import RunContext
from pydantic_deep import create_deep_agent, DeepAgentDeps


async def get_weather(ctx: RunContext[DeepAgentDeps], city: str) -> str:
    """Get the weather for a city."""
    # Everything in deps is available via ctx.deps.
    return f"Weather in {city}: Sunny, 22°C"


agent = create_deep_agent(
    tools=[get_weather],
    instructions="You can check the weather and work with files.",
)

The docstring becomes the tool's description, the type hints become its schema, and ctx.deps is your typed DeepAgentDeps. No decorators to learn, no registry to maintain.

What you get out of the box

Capability What it does
Planning A built-in todo list for breaking work down and tracking progress
Filesystem Read, write, and edit files, with grep and glob
Sub-agents Delegate focused tasks to isolated specialists
Skills Modular capability packages, loaded on demand
Backends StateBackend, LocalBackend, DockerSandbox, CompositeBackend
Context management Automatic summarization so long conversations never overflow

A modular ecosystem

Pydantic Deep Agents is assembled from standalone packages. Need just one piece? Take just one piece:

Package What it gives you
pydantic-ai-backend File storage, Docker sandbox, permission controls
pydantic-ai-todo Task planning with PostgreSQL and event streaming
subagents-pydantic-ai Multi-agent orchestration
summarization-pydantic-ai Context-management processors

Installation

Bash
pip install pydantic-deep

Want isolated code execution in a container? Add the sandbox extra:

Bash
pip install "pydantic-deep[sandbox]"

For LLMs and agents

The docs follow the llms.txt standard — point any tool at /llms.txt for an LLM-optimized version of this site.

Recap

You just saw the whole idea:

  1. create_deep_agent() gives a model real capabilities — files, web, memory, sub-agents — with sensible defaults.
  2. DeepAgentDeps + a backend decide where state lives; the same code runs in memory, on disk, or in a sandbox.
  3. Your own async functions become typed tools with dependency injection, no boilerplate.

Ready to go deeper?