Agent API¶

create_deep_agent¶

`pydantic_deep.agent.create_deep_agent(model=None, instructions=None, tools=None, toolsets=None, subagents=None, skills=None, skill_directories=None, backend=None, include_todo=True, include_filesystem=True, include_subagents=True, include_skills=True, include_general_purpose_subagent=True, include_execute=None, interrupt_on=None, output_type=None, history_processors=None, **agent_kwargs)` ¶

create_deep_agent(model: str | Model | None = None, instructions: str | None = None, tools: Sequence[Tool[DeepAgentDeps] | Any] | None = None, toolsets: Sequence[AbstractToolset[DeepAgentDeps]] | None = None, subagents: list[SubAgentConfig] | None = None, skills: list[Skill] | None = None, skill_directories: list[SkillDirectory] | None = None, backend: BackendProtocol | None = None, include_todo: bool = True, include_filesystem: bool = True, include_subagents: bool = True, include_skills: bool = True, include_general_purpose_subagent: bool = True, include_execute: bool | None = None, interrupt_on: dict[str, bool] | None = None, output_type: None = None, history_processors: Sequence[HistoryProcessor[DeepAgentDeps]] | None = None, **agent_kwargs: Any) -> Agent[DeepAgentDeps, str]

create_deep_agent(model: str | Model | None = None, instructions: str | None = None, tools: Sequence[Tool[DeepAgentDeps] | Any] | None = None, toolsets: Sequence[AbstractToolset[DeepAgentDeps]] | None = None, subagents: list[SubAgentConfig] | None = None, skills: list[Skill] | None = None, skill_directories: list[SkillDirectory] | None = None, backend: BackendProtocol | None = None, include_todo: bool = True, include_filesystem: bool = True, include_subagents: bool = True, include_skills: bool = True, include_general_purpose_subagent: bool = True, include_execute: bool | None = None, interrupt_on: dict[str, bool] | None = None, *, output_type: OutputSpec[OutputDataT], history_processors: Sequence[HistoryProcessor[DeepAgentDeps]] | None = None, **agent_kwargs: Any) -> Agent[DeepAgentDeps, OutputDataT]

Create a deep agent with planning, filesystem, subagent, and skills capabilities.

This factory function creates a fully-configured Agent with: - Todo toolset for task planning and tracking - Filesystem toolset for file operations - Subagent toolset for task delegation - Skills toolset for modular capability extension - Dynamic system prompts based on current state - Optional structured output via output_type - Optional history processing (e.g., summarization)

Parameters:

Name	Type	Description	Default
`model`	`str \| Model \| None`	Model to use (default: Claude Sonnet 4).	`None`
`instructions`	`str \| None`	Custom instructions for the agent.	`None`
`tools`	`Sequence[Tool[DeepAgentDeps] \| Any] \| None`	Additional tools to register.	`None`
`toolsets`	`Sequence[AbstractToolset[DeepAgentDeps]] \| None`	Additional toolsets to register.	`None`
`subagents`	`list[SubAgentConfig] \| None`	Subagent configurations for the task tool.	`None`
`skills`	`list[Skill] \| None`	Pre-loaded skills to make available.	`None`
`skill_directories`	`list[SkillDirectory] \| None`	Directories to discover skills from.	`None`
`backend`	`BackendProtocol \| None`	File storage backend (default: StateBackend).	`None`
`include_todo`	`bool`	Whether to include the todo toolset.	`True`
`include_filesystem`	`bool`	Whether to include the filesystem toolset.	`True`
`include_subagents`	`bool`	Whether to include the subagent toolset.	`True`
`include_skills`	`bool`	Whether to include the skills toolset.	`True`
`include_general_purpose_subagent`	`bool`	Whether to include a general-purpose subagent.	`True`
`include_execute`	`bool \| None`	Whether to include the execute tool. If None (default), automatically determined based on whether backend is a SandboxProtocol. Set to True to force include even when backend is None (useful when backend is provided via deps at runtime).	`None`
`interrupt_on`	`dict[str, bool] \| None`	Map of tool names to approval requirements. e.g., {"execute": True, "write_file": True}	`None`
`output_type`	`OutputSpec[OutputDataT] \| None`	Structured output type (Pydantic model, dataclass, TypedDict). When specified, the agent will return this type instead of str.	`None`
`history_processors`	`Sequence[HistoryProcessor[DeepAgentDeps]] \| None`	Sequence of history processors to apply to messages before sending to the model. Useful for summarization, filtering, etc.	`None`
`**agent_kwargs`	`Any`	Additional arguments passed to Agent constructor.	`{}`

Returns:

Type	Description
`Agent[DeepAgentDeps, OutputDataT] \| Agent[DeepAgentDeps, str]`	Configured Agent instance. Returns Agent[DeepAgentDeps, OutputDataT] if
`Agent[DeepAgentDeps, OutputDataT] \| Agent[DeepAgentDeps, str]`	output_type is specified, otherwise Agent[DeepAgentDeps, str].

Example

from pydantic import BaseModel
from pydantic_deep import create_deep_agent, DeepAgentDeps, StateBackend
from pydantic_deep.processors import create_summarization_processor

# Basic usage with string output
agent = create_deep_agent(
    model="openai:gpt-4.1",
    instructions="You are a coding assistant",
)

# With structured output
class CodeAnalysis(BaseModel):
    language: str
    issues: list[str]
    suggestions: list[str]

agent = create_deep_agent(
    output_type=CodeAnalysis,
)

# With summarization for long conversations
agent = create_deep_agent(
    history_processors=[
        create_summarization_processor(
            trigger=("tokens", 100000),
            keep=("messages", 20),
        )
    ],
)

deps = DeepAgentDeps(backend=StateBackend())
result = await agent.run("Analyze this code", deps=deps)

Signature¶

def create_deep_agent(
    model: str | None = None,
    instructions: str | None = None,
    tools: Sequence[Tool[DeepAgentDeps] | Any] | None = None,
    toolsets: Sequence[AbstractToolset[DeepAgentDeps]] | None = None,
    subagents: list[SubAgentConfig] | None = None,
    skills: list[Skill] | None = None,
    skill_directories: list[SkillDirectory] | None = None,
    backend: BackendProtocol | None = None,
    include_todo: bool = True,
    include_filesystem: bool = True,
    include_subagents: bool = True,
    include_skills: bool = True,
    include_general_purpose_subagent: bool = True,
    interrupt_on: dict[str, bool] | None = None,
    output_type: OutputSpec[OutputDataT] | None = None,
    history_processors: Sequence[HistoryProcessor[DeepAgentDeps]] | None = None,
    **agent_kwargs: Any,
) -> Agent[DeepAgentDeps, OutputDataT] | Agent[DeepAgentDeps, str]

Parameters¶

Parameter	Type	Default	Description
`model`	`str \\| None`	`"openai:gpt-4.1"`	LLM model identifier
`instructions`	`str \\| None`	Default instructions	System prompt for the agent
`tools`	`Sequence[Tool \\| Any] \\| None`	`None`	Additional custom tools
`toolsets`	`Sequence[AbstractToolset] \\| None`	`None`	Additional toolsets
`subagents`	`list[SubAgentConfig] \\| None`	`None`	Subagent configurations
`skills`	`list[Skill] \\| None`	`None`	Pre-loaded skills
`skill_directories`	`list[SkillDirectory] \\| None`	`None`	Directories to discover skills
`backend`	`BackendProtocol \\| None`	`StateBackend()`	File storage backend
`include_todo`	`bool`	`True`	Include TodoToolset
`include_filesystem`	`bool`	`True`	Include FilesystemToolset
`include_subagents`	`bool`	`True`	Include SubAgentToolset
`include_skills`	`bool`	`True`	Include SkillsToolset
`include_general_purpose_subagent`	`bool`	`True`	Include general-purpose subagent
`interrupt_on`	`dict[str, bool] \\| None`	`None`	Tools requiring approval
`output_type`	`OutputSpec \\| None`	`None`	Pydantic model for structured output
`history_processors`	`Sequence[HistoryProcessor] \\| None`	`None`	History processors (e.g., summarization)
`**agent_kwargs`	`Any`	-	Additional Agent constructor args

Returns¶

Agent[DeepAgentDeps, str] or Agent[DeepAgentDeps, OutputDataT] - Configured Pydantic AI agent.

When output_type is provided, returns an agent typed with the output model.

Example¶

from pydantic_deep import create_deep_agent, SubAgentConfig

agent = create_deep_agent(
    model="openai:gpt-4.1",
    instructions="You are a coding assistant.",
    subagents=[
        SubAgentConfig(
            name="reviewer",
            description="Reviews code",
            instructions="Review code for issues.",
        ),
    ],
    skill_directories=[
        {"path": "~/.pydantic-deep/skills", "recursive": True},
    ],
    interrupt_on={"execute": True},
)

create_default_deps¶

`pydantic_deep.agent.create_default_deps(backend=None)` ¶

Create default dependencies for a deep agent.

Parameters:

Name	Type	Description	Default
`backend`	`BackendProtocol \| None`	File storage backend (default: StateBackend).	`None`

Returns:

Type	Description
`DeepAgentDeps`	DeepAgentDeps instance.

Signature¶

def create_default_deps(
    backend: BackendProtocol | None = None,
) -> DeepAgentDeps

Parameters¶

Parameter	Type	Default	Description
`backend`	`BackendProtocol \\| None`	`StateBackend()`	File storage backend

Returns¶

DeepAgentDeps - Configured dependencies instance.

Example¶

from pydantic_deep import create_default_deps, FilesystemBackend

# With default StateBackend
deps = create_default_deps()

# With custom backend
deps = create_default_deps(backend=FilesystemBackend("/workspace"))

DeepAgentDeps¶

`pydantic_deep.deps.DeepAgentDeps` `dataclass` ¶

Dependencies for deep agents.

This container holds all the state and resources needed by the agent and its tools during execution.

Attributes:

Name	Type	Description
`backend`	`BackendProtocol`	File storage backend (StateBackend, FilesystemBackend, etc.)
`files`	`dict[str, FileData]`	In-memory file cache (used with StateBackend)
`todos`	`list[Todo]`	Task list for planning
`subagents`	`dict[str, Any]`	Pre-configured subagents available for delegation

`__post_init__()` ¶

Initialize backend with files if using StateBackend.

`get_todo_prompt()` ¶

Generate system prompt section for todos.

`get_files_summary()` ¶

Generate summary of files in memory.

`get_subagents_summary()` ¶

Generate summary of available subagents.

`upload_file(name, content, *, upload_dir='/uploads')` ¶

Upload a file to the backend and track it.

The file is written to the backend and its metadata is stored for display in the system prompt.

Parameters:

Name	Type	Description	Default
`name`	`str`	Original filename (e.g., "sales.csv")	required
`content`	`bytes`	File content as bytes	required
`upload_dir`	`str`	Directory to store uploads (default: "/uploads")	`'/uploads'`

Returns:

Type	Description
`str`	The path where the file was stored (e.g., "/uploads/sales.csv")

Example

deps = DeepAgentDeps(backend=StateBackend())
path = deps.upload_file("data.csv", csv_bytes)
# Agent can now access the file at /uploads/data.csv

`get_uploads_summary()` ¶

Generate summary of uploaded files for system prompt.

`clone_for_subagent()` ¶

Create a new deps instance for a subagent.

Subagents get: - Same backend (shared) - Empty todos (isolated) - Empty subagents (no nested delegation) - Same files (shared) - Same uploads (shared)

Definition¶

@dataclass
class DeepAgentDeps:
    backend: BackendProtocol = field(default_factory=StateBackend)
    files: dict[str, FileData] = field(default_factory=dict)
    todos: list[Todo] = field(default_factory=list)
    subagents: dict[str, Any] = field(default_factory=dict)

Attributes¶

Attribute	Type	Description
`backend`	`BackendProtocol`	File storage backend
`files`	`dict[str, FileData]`	In-memory file cache
`todos`	`list[Todo]`	Task list
`subagents`	`dict[str, Any]`	Pre-configured subagent instances

Methods¶

get_todo_prompt¶

def get_todo_prompt(self) -> str

Generate system prompt section for current todos.

get_files_summary¶

def get_files_summary(self) -> str

Generate summary of files in memory.

get_subagents_summary¶

def get_subagents_summary(self) -> str

Generate summary of available subagents.

clone_for_subagent¶

def clone_for_subagent(self) -> DeepAgentDeps

Create isolated dependencies for a subagent.

Same backend (shared)
Empty todos (isolated)
Empty subagents (no nested delegation)
Same files (shared reference)

Example¶

from pydantic_deep import DeepAgentDeps, StateBackend, Todo

deps = DeepAgentDeps(
    backend=StateBackend(),
    todos=[
        Todo(
            content="Review code",
            status="pending",
            active_form="Reviewing code",
        ),
    ],
)

# Access todo prompt
print(deps.get_todo_prompt())

# Clone for subagent
subagent_deps = deps.clone_for_subagent()
assert subagent_deps.todos == []  # Isolated
assert subagent_deps.backend is deps.backend  # Shared

Agent API¶

create_deep_agent¶

Signature¶

Parameters¶

Returns¶

Example¶

create_default_deps¶

pydantic_deep.agent.create_default_deps(backend=None) ¶

Signature¶

Parameters¶

Returns¶

Example¶

DeepAgentDeps¶

pydantic_deep.deps.DeepAgentDeps dataclass ¶

__post_init__() ¶

get_todo_prompt() ¶

get_files_summary() ¶

get_subagents_summary() ¶

upload_file(name, content, *, upload_dir='/uploads') ¶

get_uploads_summary() ¶

clone_for_subagent() ¶

Definition¶

Attributes¶

Methods¶

get_todo_prompt¶

get_files_summary¶

get_subagents_summary¶

clone_for_subagent¶

Example¶

`pydantic_deep.agent.create_default_deps(backend=None)` ¶

`pydantic_deep.deps.DeepAgentDeps` `dataclass` ¶

`__post_init__()` ¶

`get_todo_prompt()` ¶

`get_files_summary()` ¶

`get_subagents_summary()` ¶

`upload_file(name, content, *, upload_dir='/uploads')` ¶

`get_uploads_summary()` ¶

`clone_for_subagent()` ¶