Skip to main content
Toolsets group tools under a single name so you can give an agent a curated capability set without listing every tool. 
from praisonaiagents import Agent

agent = Agent(name="researcher", toolsets=["research"])
agent.start("Summarise the latest in AI agent frameworks")

​
Quick Start

1

Pick a prebuilt toolset

Use one of the prebuilt toolsets for common scenarios:
from praisonaiagents import Agent

# Research workflow with web search and file tools
agent = Agent(name="researcher", toolsets=["research"])

# Safe environment with minimal tools
agent = Agent(name="assistant", toolsets=["safe"])

# Development with code execution and system access
agent = Agent(name="developer", toolsets=["development"])
2

Register a custom toolset

Create your own toolset by combining tools and other toolsets:
from praisonaiagents import Agent, register_toolset

register_toolset(
    "data_analysis",
    tools=["read_file", "write_file"],
    includes=["safe"],
    description="Tools for data analysis workflows"
)

agent = Agent(name="analyst", toolsets=["data_analysis"])
3

YAML configuration

Use toolsets in YAML workflows:
agents:
  researcher:
    role: Senior Research Analyst
    goal: Research topics thoroughly
    toolsets: [research]
  
  analyst:
    role: Data Analyst
    goal: Analyse data files
    tools: [write_file]
    toolsets: [safe]
4

CLI usage

Use toolsets directly from command line:
praisonai run "Research this topic" --toolset research
praisonai chat --toolset web,files

​
How It Works

ComponentPurpose
ToolsetRegistryMaps toolset names to tool lists with recursive resolution
Tool ResolutionExpands toolset names to flat lists, handles cycles and includes
TTL Cache30-second cache for tool availability checks to improve performance
DeduplicationEnsures no duplicate tools when mixing explicit tools and toolsets

​
Configuration Reference

Toolsets API Reference

TypeScript configuration options

Toolsets Rust Reference

Rust configuration options

​
Prebuilt Toolsets

NameDirect toolsIncludesDescription
webinternet_search, duckduckgo, searxng_search, tavily_search, exa_search—Web search and crawling tools
filesread_file, write_file, list_files, get_file_info, copy_file, move_file, delete_file—File system operations
codeexecute_code, analyze_code, format_code, lint_code—Python code execution and analysis
systemexecute_command, list_processes, kill_process, get_system_info—System administration and shell operations
scrapingscrape_page, extract_links, crawl, extract_text—Web page scraping and content extraction
research(none)web, files, scrapingComplete research workflow
safeinternet_search, read_file, tavily_search—Minimal safe toolset for restricted environments
development(none)code, files, systemComplete development workflow

​
ToolsetSpec Fields

FieldTypeDefaultDescription
namestr(required)Unique name for the toolset
toolsList[str][]Tool names included directly in this toolset
includesList[str][]Other toolset names to include (recursive composition)
descriptionstr""Optional description of the toolset’s purpose

​
Common Patterns

​
Mixing Explicit Tools and Toolsets

from praisonaiagents import Agent

agent = Agent(
    name="hybrid",
    tools=["write_file"],  # Explicit tool
    toolsets=["safe"],     # Toolset
)
# Agent gets tools from both sources with automatic deduplication

​
Composition with Includes

from praisonaiagents import register_toolset

# Build up capabilities progressively
register_toolset("basic", tools=["read_file", "write_file"])
register_toolset("enhanced", includes=["basic"], tools=["internet_search"])
register_toolset("complete", includes=["enhanced"], tools=["execute_code"])

​
Environment-Specific Toolsets

import os
from praisonaiagents import Agent

# Choose toolset based on environment
if os.getenv("PRODUCTION"):
    toolsets = ["safe"]
else:
    toolsets = ["development"]

agent = Agent(name="assistant", toolsets=toolsets)

​
CLI Usage

Use toolsets with praisonai run and praisonai chat commands: 
# Single toolset
praisonai run "Research renewable energy" --toolset research

# Multiple toolsets (comma-separated)
praisonai chat --toolset web,files

# Safe environment
praisonai run "Help me write a report" --toolset safe

​
YAML Usage

Add toolsets: key under each agent definition: 
agents:
  researcher:
    role: Senior Research Analyst
    goal: Research topics thoroughly
    toolsets: [research]  # research = web + files + scraping
    
  writer:
    role: Content Writer
    goal: Write based on research
    tools: [write_file]   # explicit tool
    toolsets: [safe]      # safe toolset
    
  developer:
    role: Software Developer
    goal: Build applications
    toolsets: [development]  # development = code + files + system

tasks:
  research_task:
    description: Research AI frameworks
    agent: researcher

​
Custom Toolsets

​
Register Function

from praisonaiagents import register_toolset

register_toolset(
    name: str,
    tools: Optional[List[str]] = None,
    includes: Optional[List[str]] = None,
    description: str = "",
    overwrite: bool = False
)

​
Overwrite Behavior

By default, register_toolset is a silent no-op if the name already exists. Set overwrite=True to replace: 
register_toolset("my_toolset", tools=["tool1"], overwrite=True)

​
Recursive Includes

Toolsets can include other toolsets with automatic cycle detection: 
register_toolset("base", tools=["read_file"])
register_toolset("extended", includes=["base"], tools=["write_file"])
register_toolset("complete", includes=["extended"], tools=["internet_search"])
# complete resolves to: ["read_file", "write_file", "internet_search"]
Circular dependencies raise ValueError: 
register_toolset("a", includes=["b"])
register_toolset("b", includes=["a"])  # Raises ValueError on resolution

​
Performance Note

Tool availability is cached for 30 seconds by default. The list_available_tools() function uses TTL caching to avoid expensive availability checks on every agent initialization, improving performance when creating many agents.

​
Best Practices

Use the safe toolset in production environments where you need to restrict tool capabilities. It includes only read-only operations like internet_search and read_file.
# Production agent with minimal attack surface
agent = Agent(name="prod_assistant", toolsets=["safe"])
Use the includes parameter to build on existing toolsets instead of duplicating tool lists:
# Good: Compose with includes
register_toolset("analysis", includes=["safe"], tools=["analyze_data"])

# Avoid: Copying tool lists
register_toolset("analysis", tools=["read_file", "internet_search", "analyze_data"])
Register toolsets once during application initialization, not in request handlers:
# Good: Register once at startup
def setup_toolsets():
    register_toolset("custom", tools=["my_tool"])

# Avoid: Registering per request
def handle_request():
    register_toolset("custom", tools=["my_tool"])  # Inefficient
Use both parameters when you need a toolset plus one additional tool:
agent = Agent(
    name="researcher",
    tools=["special_analysis_tool"],  # One extra tool
    toolsets=["research"]             # Base capability set
)

Allowed Tools

Environment variable whitelist for tool restriction

Bot Default Tools

Default tools for bot agents

Load MCP Tools

Model Context Protocol tool loading

Tools Concepts

Core concepts of the tool system