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¶
Read the current todo list state.
Returns: Formatted list of todos with status icons and summary.
Tool: write_todos¶
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¶
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.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¶
List all available skills.
Returns: Formatted list of skills with metadata.
Tool: load_skill¶
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 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.
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.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¶
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¶
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¶
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: |
DEFAULT_PLANS_DIR
|
id
|
str | None
|
Toolset ID (default: |
None
|
descriptions
|
dict[str, str] | None
|
Optional mapping of tool name to custom description.
Supported keys: |
None
|
Returns:
| Type | Description |
|---|---|
FunctionToolset[Any]
|
FunctionToolset with |
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=["/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:
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
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
¶
__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
|
get_skills()
¶
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
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
|
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 documentscreenshot_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: |
None
|