Skip to content

Toolsets API

TodoToolset

Task planning and tracking tools. Provided by pydantic-ai-todo.

Tools

Tool Description
read_todos Read the current todo list state
write_todos Update the todo list

Factory

Python
from pydantic_ai_todo import create_todo_toolset

def create_todo_toolset(
    storage: TodoStorageProtocol | None = None,
    *,
    id: str | None = None,
) -> FunctionToolset[Any]

Parameters:

Parameter Type Default Description
storage TodoStorageProtocol \| None None Storage backend (defaults to in-memory)
id str \| None None Optional unique ID for the toolset

Tool: read_todos

Python
async def read_todos() -> str

Read the current todo list state.

Returns: Formatted list of todos with status icons and summary.

Tool: write_todos

Python
async def write_todos(todos: list[TodoItem]) -> str

Update the todo list with new items.

Parameters:

Parameter Type Description
todos list[TodoItem] List of todo items

Each todo item:

Python
{
    "content": str,      # Task description
    "status": str,       # "pending", "in_progress", "completed"
    "active_form": str,  # Present continuous form
}

Returns: Confirmation message with status counts.

Types

Python
from pydantic_ai_todo import Todo, TodoItem, TodoStorage, TodoStorageProtocol

class Todo(BaseModel):
    content: str
    status: Literal["pending", "in_progress", "completed"]
    active_form: str

class TodoStorage:
    """Default in-memory storage."""
    todos: list[Todo]

System Prompt

Python
from pydantic_ai_todo import get_todo_system_prompt

def get_todo_system_prompt(storage: TodoStorageProtocol | None = None) -> str

Generates dynamic system prompt showing current todos.

Standalone Usage

Python
from pydantic_ai import Agent
from pydantic_ai_todo import create_todo_toolset, TodoStorage

# Simple usage
agent = Agent("anthropic:claude-sonnet-4-6", toolsets=[create_todo_toolset()])

# With storage access
storage = TodoStorage()
agent = Agent("anthropic:claude-sonnet-4-6", toolsets=[create_todo_toolset(storage)])
result = await agent.run("Create 3 tasks")
print(storage.todos)  # Access todos directly

Console Toolset

File operation tools. Provided by pydantic-ai-backend.

For full documentation, see pydantic-ai-backend Console Toolset.

Tools

Tool Description
ls List directory contents
read_file Read file with line numbers
write_file Create or overwrite file
edit_file Replace strings in file
glob Find files by pattern
grep Search file contents
execute Run shell command (sandbox only)

Factory

Python
from pydantic_ai_backends import create_console_toolset

toolset = create_console_toolset(
    id="console",
    include_execute=False,
    require_write_approval=False,
    require_execute_approval=True,
)

Usage with pydantic-deep

The console toolset is automatically included when you create a deep agent with include_filesystem=True (the default):

Python
from pydantic_deep import create_deep_agent

# Console toolset is included by default
agent = create_deep_agent()

# Or explicitly disable it
agent = create_deep_agent(include_filesystem=False)

SubAgentToolset

Task delegation tools. Provided by subagents-pydantic-ai.

Tools

Tool Description
task Spawn a subagent for a task (sync or async mode)
check_task Check status of a background task
list_active_tasks List all running/pending tasks
soft_cancel_task Request graceful task cancellation
hard_cancel_task Force immediate task cancellation

Factory

Python
from subagents_pydantic_ai import create_subagent_toolset

def create_subagent_toolset(
    *,
    id: str = "subagents",
    subagents: list[SubAgentConfig] | None = None,
    default_model: str | None = None,
    include_general_purpose: bool = True,
    toolsets_factory: ToolsetFactory | None = None,
) -> FunctionToolset[Any]

Parameters:

Parameter Type Default Description
id str "subagents" Unique toolset identifier
subagents list[SubAgentConfig] \| None None Custom subagent configurations
default_model str \| None None Default model for subagents
include_general_purpose bool True Include general-purpose subagent
toolsets_factory ToolsetFactory \| None None Factory to create toolsets for subagents

Tool: task

Python
async def task(
    ctx: RunContext[SubAgentDepsProtocol],
    description: str,
    subagent_type: str = "general-purpose",
    mode: ExecutionMode = "sync",
    priority: TaskPriority = TaskPriority.NORMAL,
    complexity: Literal["simple", "moderate", "complex"] | None = None,
    requires_user_context: bool = False,
    may_need_clarification: bool = False,
) -> str

Spawn a subagent to handle a task.

Parameters:

Parameter Type Default Description
description str Required Task description
subagent_type str "general-purpose" Subagent name
mode ExecutionMode "sync" Execution mode: "sync", "async", or "auto"
priority TaskPriority NORMAL Task priority for async tasks
complexity str \| None None Hint for auto-mode: "simple", "moderate", "complex"
requires_user_context bool False Hint for auto-mode
may_need_clarification bool False Hint for auto-mode

Returns: Subagent's output (sync mode) or task handle info (async mode).

SubAgentConfig

Python
class SubAgentConfig(TypedDict, total=False):
    name: str                      # Required: Unique identifier
    description: str               # Required: When to use this subagent
    instructions: str              # Required: System prompt
    model: NotRequired[str]        # Custom model
    can_ask_questions: NotRequired[bool]  # Enable ask_parent tool
    max_questions: NotRequired[int]       # Limit questions per task
    preferred_mode: NotRequired[Literal["sync", "async", "auto"]]
    typical_complexity: NotRequired[Literal["simple", "moderate", "complex"]]
    typically_needs_context: NotRequired[bool]
    toolsets: NotRequired[list[Any]]      # Additional toolsets
    agent_kwargs: NotRequired[dict[str, Any]]  # Additional Agent kwargs (e.g., builtin_tools)

SkillsToolset

Future Migration

This implementation will be removed when skills support is added to pydantic-ai core. See pydantic-ai#3780 for progress.

Modular capability tools.

Tools

Tool Description
list_skills List available skills
load_skill Load skill instructions
read_skill_resource Read skill resource file

Constructor

SkillsToolset is constructed directly (there is no separate factory function):

Python
from pydantic_deep.toolsets.skills import SkillsToolset

toolset = SkillsToolset(
    skills=[...],
    directories=[...],
    descriptions={
        "list_skills": "Show all available agent capabilities",
        "load_skill": "Load instructions for a specific capability",
    },
)

Parameters:

Parameter Type Default Description
skills list[Skill] \| None None Pre-loaded Skill objects
directories list[...] \| None None Directories to discover skills from
validate bool True Validate skill structure during discovery
max_depth int \| None 3 Maximum depth for skill discovery
id str \| None None Unique identifier for this toolset
instruction_template str \| None None Custom instruction template (must include {skills_list})
exclude_tools set[str] \| list[str] \| None None Tool names to exclude from registration
descriptions dict[str, str] \| None None Custom tool descriptions (keys: list_skills, load_skill, read_skill_resource, run_skill_script)

Tool: list_skills

Python
async def list_skills(
    ctx: RunContext[DeepAgentDeps],
) -> str

List all available skills.

Returns: Formatted list of skills with metadata.

Tool: load_skill

Python
async def load_skill(
    ctx: RunContext[DeepAgentDeps],
    skill_name: str,
) -> str

Load full instructions for a skill.

Returns: Complete skill instructions.

Tool: read_skill_resource

Python
async def read_skill_resource(
    ctx: RunContext[DeepAgentDeps],
    skill_name: str,
    resource_name: str,
) -> str

Read a resource file from a skill.

Returns: Resource file content.

Type Definitions

Skill

Skill is a dataclass (accessed via attributes, not dict keys). See Skill and the Types reference.

Python
@dataclass
class Skill:
    name: str
    description: str
    content: str
    license: str | None = None
    compatibility: str | None = None
    resources: list[SkillResource] = []
    scripts: list[SkillScript] = []
    uri: str | None = None
    metadata: dict[str, Any] | None = None

SkillsDirectory

A filesystem skill source. See SkillsDirectory.

Python
class SkillsDirectory:
    def __init__(
        self,
        *,
        path: str | Path,
        validate: bool = True,
        max_depth: int | None = 3,
        script_executor: LocalSkillScriptExecutor | CallableSkillScriptExecutor | None = None,
    ) -> None: ...

CheckpointToolset

Manual checkpoint controls. See Checkpointing.

Tools

Tool Description
save_checkpoint Label the most recent auto-checkpoint
list_checkpoints Show all saved checkpoints
rewind_to Rewind to a checkpoint (raises RewindRequested)

Constructor

Python
from pydantic_deep.toolsets.checkpointing import CheckpointToolset

toolset = CheckpointToolset(
    descriptions={
        "save_checkpoint": "Bookmark the current conversation state",
        "rewind_to": "Roll back conversation to a previous bookmark",
    },
)

Parameters:

Parameter Type Default Description
store CheckpointStore \| None None Fallback checkpoint store (used if deps has no store)
id str "deep-checkpoints" Toolset identifier
descriptions dict[str, str] \| None None Custom tool descriptions (keys: save_checkpoint, list_checkpoints, rewind_to)

Or enabled via create_deep_agent(include_checkpoints=True).


TeamToolset

Multi-agent team management. See Teams.

Tools

Tool Description
spawn_team Create a team and register members
assign_task Assign a task to a team member
check_teammates Show team status and shared tasks
message_teammate Send a message to a team member
dissolve_team Shut down the team

Factory

Python
from pydantic_deep.toolsets.teams import create_team_toolset

toolset = create_team_toolset(
    id="deep-team",
    descriptions={
        "spawn_team": "Create a new team of specialized agents",
        "assign_task": "Delegate a task to a specific team member",
    },
)

Parameters:

Parameter Type Default Description
id str \| None "deep-team" Toolset identifier
descriptions dict[str, str] \| None None Custom tool descriptions (keys: spawn_team, assign_task, check_teammates, message_teammate, dissolve_team)

Or via create_deep_agent(include_teams=True).


MemoryToolset

Persistent agent memory. See Memory.

Tools

Tool Description
read_memory Read full memory content
write_memory Append new content to memory
update_memory Find and replace text in memory

Constructor

Python
from pydantic_deep.toolsets.memory import AgentMemoryToolset

toolset = AgentMemoryToolset(
    agent_name="main",
    memory_dir="/.deep/memory",
    max_lines=200,
    descriptions={
        "write_memory": "Save important findings to persistent memory",
    },
)

Parameters:

Parameter Type Default Description
agent_name str "main" Agent name (used for path and prompt label)
memory_dir str "/.deep/memory" Base directory for memory files
max_lines int 200 Max lines to inject into system prompt
descriptions dict[str, str] \| None None Custom tool descriptions (keys: read_memory, write_memory, update_memory)

Or via create_deep_agent(include_memory=True).


PlanToolset

Interactive planning with ask_user and save_plan. See Plan Mode.

Tools

Tool Description
ask_user Ask user a question with options
save_plan Save implementation plan to markdown file

Factory

Python
from pydantic_deep.toolsets.plan import create_plan_toolset

toolset = create_plan_toolset(
    plans_dir="/plans",
    descriptions={
        "ask_user": "Pose a question to the user with predefined choices",
    },
)

Parameters:

Parameter Type Default Description
plans_dir str "/plans" Directory to save plan files
id str \| None "deep-plan" Toolset identifier
descriptions dict[str, str] \| None None Custom tool descriptions (keys: ask_user, save_plan)

Or via create_deep_agent(include_plan=True) (default).

pydantic_deep.toolsets.plan.create_plan_toolset(plans_dir=DEFAULT_PLANS_DIR, *, id=None, descriptions=None)

Create a plan toolset with ask_user and save_plan tools.

The ask_user tool pauses execution and asks the human user a question with predefined options (like Claude Code's AskUserQuestion). It relies on a callback at ctx.deps.ask_user. When no callback is set (headless mode), it auto-selects the recommended option.

The save_plan tool writes the plan to a markdown file in the backend.

Parameters:

Name Type Description Default
plans_dir str

Directory to save plan files (default: /plans).

DEFAULT_PLANS_DIR
id str | None

Toolset ID (default: deep-plan).

None
descriptions dict[str, str] | None

Optional mapping of tool name to custom description. Supported keys: ask_user, save_plan. When a key is absent the built-in default is used.

None

Returns:

Type Description
FunctionToolset[Any]

FunctionToolset with ask_user and save_plan tools.


ContextToolset

Injects project context files into system prompt. See Context Files. Has no tools — only provides instructions via get_instructions().

Constructor

Python
from pydantic_deep.toolsets.context import ContextToolset

toolset = ContextToolset(
    context_files=["/AGENTS.md", "/SOUL.md"],
    context_discovery=False,
    is_subagent=False,
    max_chars=20_000,
)

Skill Discovery

Skill discovery is handled by the SkillsDirectory and BackendSkillsDirectory classes (frontmatter parsing and directory traversal are internal implementation details). Pass these directly to SkillsToolset or to create_deep_agent via skill_directories:

Python
from pydantic_deep.toolsets.skills import SkillsDirectory, SkillsToolset

source = SkillsDirectory(path="~/.pydantic-deep/skills")
skills = source.get_skills()  # dict[str, Skill]

toolset = SkillsToolset(directories=[source])

Skill

pydantic_deep.toolsets.skills.types.Skill dataclass

A skill instance with metadata, content, resources, and scripts.

Can be created programmatically or loaded from filesystem directories.

Example - Programmatic skill with decorators
Python
from pydantic_ai import RunContext
from pydantic_deep.toolsets.skills import Skill, SkillResource

my_skill = Skill(
    name='hr-analytics-skill',
    description='Skill for HR analytics',
    content='Use this skill for HR data analysis...',
    resources=[
        SkillResource(name='table-schemas', content='Schema definitions...')
    ]
)

@my_skill.resource
def get_db_context() -> str:
    return "Dynamic database context."

@my_skill.resource
async def get_samples(ctx: RunContext[MyDeps]) -> str:
    return await ctx.deps.get_samples()

@my_skill.script
async def load_dataset(ctx: RunContext[MyDeps]) -> str:
    await ctx.deps.load_data()
    return 'Dataset loaded.'

Attributes:

Name Type Description
name str

Skill name.

description str

Brief description of what the skill does.

content str

Main instructional content.

license str | None

Optional license information.

compatibility str | None

Optional environment requirements (max 500 chars).

resources list[SkillResource]

List of resources (files or callables).

scripts list[SkillScript]

List of scripts (functions or file-based).

uri str | None

Optional URI for skill's base location (internal use).

metadata dict[str, Any] | None

Additional metadata fields.

resource(func=None, *, name=None, description=None, takes_ctx=None, docstring_format='auto', schema_generator=None)

Decorator to register a callable as a skill resource.

The decorated function can optionally take RunContext as its first argument for accessing dependencies. This is auto-detected if not specified.

Parameters:

Name Type Description Default
func Callable[..., Any] | None

The function to register as a resource.

None
name str | None

Resource name (defaults to function name).

None
description str | None

Resource description (inferred from docstring if not provided).

None
takes_ctx bool | None

Whether function takes RunContext (auto-detected if None).

None
docstring_format DocstringFormat

Format of the docstring ('auto', 'google', 'numpy', 'sphinx').

'auto'
schema_generator type[GenerateJsonSchema] | None

Custom JSON schema generator class.

None

Returns:

Type Description
Callable[..., Any] | Callable[[Callable[..., Any]], Callable[..., Any]]

The original function (allows use as decorator).

script(func=None, *, name=None, description=None, takes_ctx=None, docstring_format='auto', schema_generator=None)

Decorator to register a callable as a skill script.

The decorated function can optionally take RunContext as its first argument for accessing dependencies. This is auto-detected if not specified.

Parameters:

Name Type Description Default
func Callable[..., Any] | None

The function to register as a script.

None
name str | None

Script name (defaults to function name).

None
description str | None

Script description (inferred from docstring if not provided).

None
takes_ctx bool | None

Whether function takes RunContext (auto-detected if None).

None
docstring_format DocstringFormat

Format of the docstring ('auto', 'google', 'numpy', 'sphinx').

'auto'
schema_generator type[GenerateJsonSchema] | None

Custom JSON schema generator class.

None

Returns:

Type Description
Callable[..., Any]

The original function (allows use as decorator).

SkillsDirectory

pydantic_deep.toolsets.skills.directory.SkillsDirectory

Skill source for a single filesystem directory.

Discovers and loads skills from a local directory by finding SKILL.md files and automatically discovering associated resources and scripts.

File-based scripts are executed using the configured script executor (LocalSkillScriptExecutor or CallableSkillScriptExecutor).

skills property

Get the dictionary of loaded skills.

Returns:

Type Description
dict[str, Skill]

Dictionary mapping skill URI to Skill objects.

__init__(*, path, validate=True, max_depth=3, script_executor=None)

Initialize the skills directory source.

Parameters:

Name Type Description Default
path str | Path

Directory path to search for skills.

required
validate bool

Validate skill structure on discovery.

True
max_depth int | None

Maximum depth for skill discovery (None for unlimited).

3
script_executor LocalSkillScriptExecutor | CallableSkillScriptExecutor | None

Optional custom script executor for file-based scripts. If None, uses LocalSkillScriptExecutor with default settings.

None
Example
Python
source = SkillsDirectory(path="./skills")

# With custom executor
from pydantic_deep.toolsets.skills import LocalSkillScriptExecutor

executor = LocalSkillScriptExecutor(timeout=60)
source = SkillsDirectory(path="./skills", script_executor=executor)

get_skills()

Get all skills from this source.

Returns:

Type Description
dict[str, Skill]

Dictionary of skill URI to Skill object.

load_skill(skill_uri)

Load full instructions for a skill.

Parameters:

Name Type Description Default
skill_uri str

URI of the skill to load.

required

Returns:

Type Description
Skill

Loaded Skill object.

Raises:

Type Description
SkillNotFoundError

If skill is not found.

BackendSkillsDirectory

pydantic_deep.toolsets.skills.backend.BackendSkillsDirectory

Discover and load skills from a backend filesystem.

Uses BackendProtocol methods (glob_info, read_bytes) for skill discovery and resource loading. Script execution requires SandboxProtocol (with execute()).

Example
Python
from pydantic_ai_backends import StateBackend
from pydantic_deep.toolsets.skills import BackendSkillsDirectory, SkillsToolset

backend = StateBackend()
# Write skill files to backend...
backend.write("/skills/my-skill/SKILL.md", skill_content)

# Discover skills from backend
directory = BackendSkillsDirectory(backend=backend, path="/skills")
toolset = SkillsToolset(directories=[directory])

skills property

Get the dictionary of loaded skills.

__init__(*, backend, path='/skills', validate=True, max_depth=3, script_timeout=30)

Initialize the backend skills directory.

Parameters:

Name Type Description Default
backend BackendProtocol

Backend to discover skills from.

required
path str

Base path to search for skills within the backend.

'/skills'
validate bool

Validate skill structure on discovery.

True
max_depth int | None

Maximum depth for skill discovery (None for unlimited).

3
script_timeout int

Timeout for script execution in seconds.

30

get_skills()

Discover and load all skills from the backend.

Returns:

Type Description
dict[str, Skill]

Dictionary mapping skill name to Skill objects.


LiteparseToolset

Document parsing tools (PDF, DOCX, and more) backed by LiteParse. See LiteParse. Enable via create_deep_agent(include_liteparse=True).

pydantic_deep.LiteparseToolset

Bases: FunctionToolset[Any]

Toolset for parsing documents with LiteParse.

Provides tools to extract text and generate screenshots from PDFs, DOCX, and other document formats using the LiteParse Node.js CLI.

Requirements
  • Node.js >= 18 on the system
  • LiteParse CLI (auto-installed via npm on first use if install_if_not_available=True)
  • pip install pydantic-deep[liteparse]
Tools
  • parse_document: Extract text content from a document
  • screenshot_document: Generate page screenshots saved to the backend

__init__(*, ocr_enabled=True, ocr_language='en', ocr_server_url=None, dpi=150, max_pages=10000, install_if_not_available=True, descriptions=None)

Initialize LiteparseToolset.

Parameters:

Name Type Description Default
ocr_enabled bool

Enable OCR for scanned documents. Defaults to True.

True
ocr_language str

OCR language code (e.g. "en", "fr", "de"). Defaults to "en".

'en'
ocr_server_url str | None

URL of HTTP OCR server. Uses built-in Tesseract if not set.

None
dpi int

Rendering DPI - higher gives better OCR quality but is slower. Defaults to 150.

150
max_pages int

Maximum pages to parse per document. Defaults to 10,000.

10000
install_if_not_available bool

Auto-install CLI via npm on first use. Defaults to True.

True
descriptions dict[str, str] | None

Optional dict to override tool descriptions. Keys: parse_document, screenshot_document.

None