Toolsets API

Toolsets API

TodoToolset

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

Tools

Factory

from pydantic_ai_todo import create_todo_toolset

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

Parameters:

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:

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("openai:gpt-4.1", toolsets=[create_todo_toolset()])

# With storage access
storage = TodoStorage()
agent = Agent("openai:gpt-4.1", 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

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

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:

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:

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

Factory

def create_skills_toolset(
    *,
    id: str = "skills",
    directories: list[SkillDirectory] | None = None,
    skills: list[Skill] | None = None,
) -> SkillsToolset

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

class Skill(TypedDict):
    name: str
    description: str
    path: str
    tags: list[str]
    version: str
    author: str
    frontmatter_loaded: bool
    instructions: NotRequired[str]
    resources: NotRequired[list[str]]

SkillDirectory

class SkillDirectory(TypedDict):
    path: str
    recursive: NotRequired[bool]

SkillFrontmatter

class SkillFrontmatter(TypedDict):
    name: str
    description: str
    tags: NotRequired[list[str]]
    version: NotRequired[str]
    author: NotRequired[str]

CheckpointToolset

Manual checkpoint controls. See Checkpointing.

Tools

Factory

Enabled via create_deep_agent(include_checkpoints=True).

TeamToolset

Multi-agent team management. See Teams.

Tools

Factory

from pydantic_deep.toolsets.teams import create_team_toolset

toolset = create_team_toolset(id="deep-team")

Or via create_deep_agent(include_teams=True).

MemoryToolset

Persistent agent memory. See Memory.

Tools

Constructor

from pydantic_deep.toolsets.memory import AgentMemoryToolset

toolset = AgentMemoryToolset(
    agent_name="main",
    memory_dir="/.deep/memory",
    max_lines=200,
)

Or via create_deep_agent(include_memory=True).

PlanToolset

Interactive planning with ask_user and save_plan. See Plan Mode.

Tools

Factory

from pydantic_deep.toolsets.plan import create_plan_toolset

toolset = create_plan_toolset(plans_dir="/plans")

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

ContextToolset

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

Constructor

from pydantic_deep.toolsets.context import ContextToolset

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

Helper Functions

discover_skills

def discover_skills(
    directories: list[SkillDirectory],
    backend: Any | None = None,
) -> list[Skill]

Discover skills from filesystem directories.

parse_skill_md

def parse_skill_md(content: str) -> tuple[dict[str, Any], str]

Parse SKILL.md into frontmatter and instructions.

load_skill_instructions

def load_skill_instructions(skill_path: str) -> str

Load full instructions from a skill directory.