Praison AI

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
    python
        # 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
    bash
    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:

    python
    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
    python
    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
    python
    # 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
    bash
    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:

    yaml
    roles:
  processor:
    tools:
      - my_custom_tool

How to Add Tools from GitHub

  1. Add from GitHub Repository
    bash
    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:

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.