Toolsets

Attach a named group of tools to an agent in one line

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

The user sends a research task; the research toolset supplies curated web and file tools automatically.

graph TB
    Start[Which toolset should I use?]
    Start --> Restricted{Restricted environment?}
    Restricted -->|Yes| Safe[🔒 safe]
    Restricted -->|No| Purpose{What's your purpose?}

    Purpose --> Single{Single capability?}
    Single -->|Yes| SingleChoice[🌐 web / 📁 files / 💻 code / ⚙️ system / 🕷️ scraping]
    Single -->|No| Workflow{Complete workflow?}

    Workflow -->|Research| Research[📊 research]
    Workflow -->|Development| Development[🛠️ development]
    Workflow -->|Coding| Coding[💻 coding]
    Workflow -->|Custom| Custom[📝 register_toolset(...)]

    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef toolset fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef custom fill:#6366F1,stroke:#7C90A0,color:#fff

    class Start,Restricted,Purpose,Single,Workflow decision
    class Safe,SingleChoice,Research,Development,Coding toolset
    class Custom custom

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"])
   
   # Coding workflow — diff-based file edits + code search + shell + todos
   agent = Agent(name="coder", toolsets=["coding"])
   agent.start("Refactor UserService to AccountService across src/")

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]
   
     coder:
       role: Coding Assistant
       goal: Safe, diff-based code edits
       toolsets: [coding]

4. CLI usage

   Use toolsets directly from command line:

   praisonai run "Research this topic" --toolset research
   praisonai chat --toolset web,files
   praisonai run "Fix the auth bug in src/user.py" --toolset coding

How It Works

Configuration Reference

Prebuilt Toolsets

ToolsetSpec Fields

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

# Coding workflow
praisonai run "Fix the auth bug in src/user.py" --toolset coding

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

  coder:
    role: Coding Assistant
    goal: Safe, diff-based code edits
    toolsets: [coding]  # coding = diff-based edits + code search + shell + todos

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

When to use coding vs development

Both toolsets are useful for code-related tasks but target different workflows.

Choose coding when the agent makes targeted edits to source files; choose development for broader scripting and dev-tooling tasks.

Model-family-aware edit order

When an agent has a string llm= model id, the coding toolset advertises the family’s preferred edit primitive first (Claude → apply_patch; GPT → edit_file). Both primitives stay available — only their order changes, matching the guidance the Model Harness prepends to the system prompt.

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

# Production agent with minimal attack surface
agent = Agent(name="prod_assistant", toolsets=["safe"])

# 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"])

# 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

agent = Agent(
    name="researcher",
    tools=["special_analysis_tool"],  # One extra tool
    toolsets=["research"]             # Base capability set
)

Related