Load Tools From a Python Module

Turn a Python module full of functions into an agent tool registry — the same extraction rule PraisonAI uses internally

Point PraisonAI at any Python module and it turns the module’s public functions into tools an agent can call.

extract_functions_from_loaded_module is the single owner of the “walk a loaded module and collect its callables into a name → callable registry” rule that PraisonAI uses internally — reuse it when you already have a loaded module.

Quick Start

1. Simple — point an agent at a folder of tools

   Drop a tools.py next to your recipe/workflow YAML and set the gate. PraisonAI loads its public functions automatically — no import needed.

   export PRAISONAI_ALLOW_LOCAL_TOOLS=true

   # tools.py — sits next to your workflow YAML
   def get_weather(city: str) -> str:
       """Get the weather for a city."""
       return f"Weather in {city}: sunny"

   praisonai workflow run research.yaml
   # → Loaded 1 tools from tools.py: get_weather

2. Programmatic — load and register a module yourself

   Load the module with the safe loader, extract its callables, then hand the values to Agent(tools=...).

   import os
   from praisonaiagents import Agent
   from praisonai_code._safe_loader import load_user_module
   from praisonai_code.tool_resolver import extract_functions_from_loaded_module
   
   os.environ["PRAISONAI_ALLOW_LOCAL_TOOLS"] = "true"
   
   module = load_user_module("tools.py", name="my_tools")
   tools = extract_functions_from_loaded_module(module)
   
   agent = Agent(
       name="Tool User",
       instructions="Use the available tools to help the user",
       tools=list(tools.values()),
   )
   agent.start("What's the weather in Paris?")

3. Filter the walk

   Two independent knobs narrow what the walk accepts.

   # Only plain functions — drops callable class instances
   tools = extract_functions_from_loaded_module(module, functions_only=True)
   
   # Drop underscore-prefixed names like _helper
   tools = extract_functions_from_loaded_module(module, skip_private=True)

How It Works

The helper walks the module’s members, applies the filter, and returns a name → callable dict for the caller to register.

The helper does not load anything — the caller owns the loading step (via the safe loader). If you only have a file path and no module object, use the path-based sibling instead.

Both share the same _accept rule, so the extraction behaviour is identical — the only difference is who owns the loading step.

Which entry point should I use?

Pick the entry point that matches what you already hold.

Filter Reference

Both knobs default to False and can be combined.

With defaults, the walk accepts any member where inspect.isfunction(obj) or callable(obj) is true. Order follows inspect.getmembers(module) (alphabetical by name).

Common Patterns

# tools.py next to your workflow YAML
from third_party import external_helper  # re-export — stays OUT of the registry

def summarize(text: str) -> str:
    """Summarize a block of text."""
    return text[:100]

export PRAISONAI_ALLOW_LOCAL_TOOLS=true
praisonai workflow run research.yaml
# → Loaded 1 tools from tools.py: summarize

import os
from praisonaiagents import Agent
from praisonai_code._safe_loader import load_user_module
from praisonai_code.tool_resolver import extract_functions_from_loaded_module

os.environ["PRAISONAI_ALLOW_LOCAL_TOOLS"] = "true"

module = load_user_module("tools.py", name="my_tools")
tools = extract_functions_from_loaded_module(module, skip_private=True)

agent = Agent(name="Helper", instructions="Use my tools", tools=list(tools.values()))
agent.start("Run one of my tools")

from praisonai.tool_resolver import ToolResolver

resolver = ToolResolver()
tools = resolver.load_functions_from_module(
    "./helpers/my_tools.py",
    functions_only=True,
    skip_private=True,
)
# {"summarize": <function>, ...}

Best Practices

from praisonai_code._safe_loader import load_user_module

module = load_user_module("tools.py", name="my_tools")  # ✅ gated + safe

tools = extract_functions_from_loaded_module(module, skip_private=True)

# You already loaded `module` — extract, don't re-load
tools = extract_functions_from_loaded_module(module)

import inspect
from praisonai_code.tool_resolver import extract_functions_from_loaded_module

registry = {
    name: obj
    for name, obj in extract_functions_from_loaded_module(
        module, functions_only=True, skip_private=True
    ).items()
    if inspect.getmodule(obj) is module
}

Related