Add Tools

Add tools from files or GitHub to PraisonAI

Understanding Tool Discovery

PraisonAI automatically discovers tools from ~/.praisonai/tools/ (user-global) and .praisonai/tools/ in your project (walk-up) on every praisonai run. Any .py file you place there will be loaded and its functions become available as tools.

• praisonai init scaffolds .praisonai/tools/example.py for you.

See Project-Local Tools for the full discovery rules and precedence.

How to Add Tools from Local Files (Recommended)

1. Create Your Tools File

   # my_pandas_tools.py
   import pandas as pd
   from io import StringIO
   
   def analyze_csv_data(csv_data: str) -> str:
       """Analyze CSV data using pandas DataFrame.
       
       Args:
           csv_data: CSV-formatted string data
           
       Returns:
           Analysis summary
       """
       df = pd.read_csv(StringIO(csv_data))
       return f"""Shape: {df.shape}
   Columns: {list(df.columns)}
   Statistics:
   {df.describe().to_string()}"""
   
2. Add File to Tools Directory

   praisonai tools add ./my_pandas_tools.py
   

   Output:

   ✅ Added tools file: my_pandas_tools.py
      Copied to: ~/.praisonai/tools/my_pandas_tools.py
      Found 1 tools: analyze_csv_data
   
3. Verify Tools Are Discovered

   Tools in ~/.praisonai/tools/ are auto-discovered:

   from praisonai.templates.tool_override import create_tool_registry_with_overrides
   
   registry = create_tool_registry_with_overrides(include_defaults=True)
   print("analyze_csv_data" in registry)  # True
   
4. Use in Agent

   from praisonaiagents import Agent
   
   agent = Agent(
       name="data_analyst",
       role="Data Analyst",
       tools=[analyze_csv_data]
   )
   
   csv = "name,age\\nAlice,30\\nBob,25"
   result = agent.start(f"Analyze this data: {csv}")
   

Why Packages Need Wrapper Tools

Running praisonai tools add pandas will show:

⚠️  Package 'pandas' is installed but NOT directly usable as tools
    Found 102 callable items in package

    To use this package with agents, create wrapper tools:
    1. Create a file: ~/.praisonai/tools/my_tools.py
    2. Define wrapper functions with docstrings
    3. Tools will be auto-discovered

Packages like pandas are NOT tools - they are libraries. To use them with agents, you must create wrapper functions with:

• Type hints for parameters
• Docstrings with Args section
• JSON-serializable return values

How to Add Tools from Local Files

1. Create Tools File

   # my_tools.py
   def my_custom_tool(query: str) -> str:
       """Process a query.
       
       Args:
           query: Input query
           
       Returns:
           Processed result
       """
       return f"Processed: {query}"
   
2. Add File to Tools

   praisonai tools add ./my_tools.py
   

   Output:

   ✅ Added tools file: my_tools.py
      Copied to: ~/.praisonai/tools/my_tools.py
      Found 1 tools: my_custom_tool
   
3. Use in Template

   Reference the tool in your agents.yaml:

   roles:
     processor:
       tools:
         - my_custom_tool
   

How to Add Tools from GitHub

1. Add from GitHub Repository

   praisonai tools add github:MervinPraison/PraisonAI-tools/praisonai_tools
   
2. Verify Download

   Tools are downloaded to ~/.praisonai/tools/

Configuration File

Tools sources are stored in ~/.praisonai/tools_sources.yaml:

sources:
- pandas
- numpy

Key Concept

Packages vs Tools: When you add a package like pandas, you’re registering it as a source. To use it with agents, you need to create wrapper functions that expose specific functionality as tools with proper docstrings and type hints.