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

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

async def read_todos() -> str

Read the current todo list state.

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

Tool: write_todos

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:

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

Returns: Confirmation message with status counts.

Types

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

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

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

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):

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

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

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

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

!!! note "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):

from pydantic_deep.features.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

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

List all available skills.

Returns: Formatted list of skills with metadata.

Tool: load_skill

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

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][pydantic_deep.features.skills.types.Skill] and the Types reference.

@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][pydantic_deep.features.skills.directory.SkillsDirectory].

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

from pydantic_deep.features.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

from pydantic_deep.features.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 and Memory API.

Memory is provided by the Memory capability from the external pydantic-ai-harness package (re-exported as pydantic_deep.Memory). Storage uses a pluggable MemoryStore (InMemoryStore default, FileStore, SqliteMemoryStore, PostgresMemoryStore), independent of deps.backend.

Tools

Tool	Description
`read_memory`	Read full memory content
`write_memory`	Write memory (optional `old_text` for a unique find-and-replace, `file` to target a specific memory file)
`delete_memory`	Delete memory content
`search_memory`	Search across memory

Enable via create_deep_agent(include_memory=True, memory_dir=..., memory_store=...). See create_deep_agent for the memory_dir / memory_store parameters.

!!! warning "Deprecated API" The homegrown AgentMemoryToolset(agent_name=..., memory_dir=..., max_lines=...) constructor, the update_memory tool, and the MemoryCapability class are deprecated (they still import but emit DeprecationWarning). Use the Memory capability and the MemoryStore classes instead — see Memory API. The update_memory tool has been removed; its replacement is write_memory(old_text=...).

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

from pydantic_deep.features.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.features.plan.create_plan_toolset options: show_source: false

ContextToolset

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

Constructor

from pydantic_deep.features.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][pydantic_deep.features.skills.directory.SkillsDirectory] and [BackendSkillsDirectory][pydantic_deep.features.skills.backend.BackendSkillsDirectory] classes (frontmatter parsing and directory traversal are internal implementation details). Pass these directly to SkillsToolset or to create_deep_agent via skill_directories:

from pydantic_deep.features.skills import SkillsDirectory, SkillsToolset

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

toolset = SkillsToolset(directories=[source])

Skill

::: pydantic_deep.features.skills.types.Skill options: show_source: false

SkillsDirectory

::: pydantic_deep.features.skills.directory.SkillsDirectory options: show_source: false

BackendSkillsDirectory

::: pydantic_deep.features.skills.backend.BackendSkillsDirectory options: show_source: false

LiteparseToolset

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

::: pydantic_deep.LiteparseToolset options: show_source: false

Uh oh!

FilesExpand file tree

toolsets.md

Latest commit

History

toolsets.md

File metadata and controls

Toolsets API

TodoToolset

Tools

Factory

Tool: read_todos

Tool: write_todos

Types

System Prompt

Standalone Usage

Console Toolset

Tools

Factory

Usage with pydantic-deep

SubAgentToolset

Tools

Factory

Tool: task

SubAgentConfig

SkillsToolset

Tools

Constructor

Tool: list_skills

Tool: load_skill

Tool: read_skill_resource

Type Definitions

Skill

SkillsDirectory

CheckpointToolset

Tools

Constructor

TeamToolset

Tools

Factory

MemoryToolset

Tools

PlanToolset

Tools

Factory

ContextToolset

Constructor

Skill Discovery

Skill

SkillsDirectory

BackendSkillsDirectory

LiteparseToolset