468 Index C79e2c35

API Reference

Complete API documentation for pydantic-deep.

Modules

Quick Reference

Main Entry Points

from pydantic_deep import (
    # Agent
    create_deep_agent,
    create_default_deps,
    DeepAgentDeps,

    # Backends (from pydantic-ai-backend)
    BackendProtocol,
    SandboxProtocol,
    StateBackend,
    LocalBackend,
    CompositeBackend,
    BaseSandbox,
    DockerSandbox,

    # Processors
    SummarizationProcessor,
    create_summarization_processor,

    # Types
    FileData,
    FileInfo,
    WriteResult,
    EditResult,
    ExecuteResponse,
    GrepMatch,
    Todo,
    SubAgentConfig,
    CompiledSubAgent,
    Skill,
    SkillDirectory,
    SkillFrontmatter,
    ResponseFormat,
)

# Toolsets (from their respective packages)
from pydantic_ai_backends import create_console_toolset
from pydantic_ai_todo import create_todo_toolset
from pydantic_deep.toolsets import SubAgentToolset, SkillsToolset

Creating an Agent

agent = create_deep_agent(
    model="openai:gpt-4.1",
    instructions="You are a helpful assistant.",
    include_todo=True,
    include_filesystem=True,
    include_subagents=True,
    include_skills=True,
    subagents=[...],
    skills=[...],
    skill_directories=[...],
    interrupt_on={"execute": True},
)

Creating Dependencies

deps = DeepAgentDeps(
    backend=StateBackend(),
    todos=[],
    subagents={},
)

# Or use helper
deps = create_default_deps()

Running

# Basic run
result = await agent.run(prompt, deps=deps)

# With history
result = await agent.run(
    prompt,
    deps=deps,
    message_history=previous_result.all_messages(),
)

# Streaming
async with agent.iter(prompt, deps=deps) as run:
    async for node in run:
        ...
    result = run.result

Type Annotations

pydantic-deep is fully typed. The main agent type is:

Agent[DeepAgentDeps, str]

Where:

• DeepAgentDeps - Dependencies type
• str - Output type (agent returns strings)

Protocols

BackendProtocol

class BackendProtocol(Protocol):
    def ls_info(self, path: str) -> list[FileInfo]: ...
    def read(self, path: str, offset: int = 0, limit: int = 2000) -> str: ...
    def write(self, path: str, content: str) -> WriteResult: ...
    def edit(self, path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult: ...
    def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]: ...
    def grep_raw(self, pattern: str, path: str | None = None, glob: str | None = None) -> list[GrepMatch] | str: ...

SandboxProtocol

class SandboxProtocol(BackendProtocol, Protocol):
    def execute(self, command: str, timeout: int | None = None) -> ExecuteResponse: ...
    @property
    def id(self) -> str: ...

Exceptions

pydantic-deep uses standard Python exceptions:

Next Steps

• Agent API - Detailed agent documentation
• Backends API - Storage backend details
• Toolsets API - Tool collection details