Skip to main content

Plugins Module

The Plugins module provides dynamic plugin loading and a hook-based extension system for PraisonAI Agents.

Features

  • Dynamic Loading - Load plugins from files or directories
  • Hook System - Extend agent behavior at key points
  • Tool Plugins - Add custom tools via plugins
  • Enable/Disable - Toggle plugins at runtime

Quick Start

from praisonaiagents.plugins import PluginManager, Plugin, PluginHook
from praisonaiagents.plugins.plugin import PluginInfo

class MyPlugin(Plugin):
    @property
    def info(self):
        return PluginInfo(
            name="my_plugin",
            version="1.0.0",
            hooks=[PluginHook.BEFORE_TOOL]
        )
    
    def before_tool(self, tool_name, args):
        print(f"About to call {tool_name}")
        return args

# Register plugin
manager = PluginManager()
manager.register(MyPlugin())

Available Hooks

HookDescription
ON_INITPlugin initialization
ON_SHUTDOWNPlugin shutdown
BEFORE_AGENTBefore agent execution
AFTER_AGENTAfter agent execution
BEFORE_TOOLBefore tool call
AFTER_TOOLAfter tool call
BEFORE_LLMBefore LLM call
AFTER_LLMAfter LLM response
ON_PERMISSION_ASKPermission requested
ON_CONFIGConfiguration loaded
ON_AUTHAuthentication needed

API Reference

PluginManager

class PluginManager:
    def register(self, plugin: Plugin) -> bool:
        """Register a plugin."""
    
    def unregister(self, name: str) -> bool:
        """Unregister a plugin by name."""
    
    def enable(self, name: str) -> bool:
        """Enable a disabled plugin."""
    
    def disable(self, name: str) -> bool:
        """Disable a plugin without unregistering."""
    
    def load_from_directory(self, directory: str) -> int:
        """Load plugins from a directory. Returns count loaded."""
    
    def execute_hook(self, hook: PluginHook, *args, **kwargs) -> Any:
        """Execute a hook across all enabled plugins."""
    
    def get_all_tools(self) -> List[Dict]:
        """Get tools from all enabled plugins."""

Plugin Base Class

class Plugin(ABC):
    @property
    @abstractmethod
    def info(self) -> PluginInfo:
        """Return plugin metadata."""
    
    def on_init(self, context: Dict) -> None:
        """Called when plugin is initialized."""
    
    def before_tool(self, tool_name: str, args: Dict) -> Dict:
        """Modify tool arguments before execution."""
    
    def after_tool(self, tool_name: str, result: Any) -> Any:
        """Modify tool result after execution."""
    
    def get_tools(self) -> List[Dict]:
        """Return additional tools provided by this plugin."""

Examples

Function Plugin

from praisonaiagents.plugins.plugin import FunctionPlugin, PluginHook

def log_tool_calls(tool_name, args):
    print(f"Tool: {tool_name}, Args: {args}")
    return args

plugin = FunctionPlugin(
    name="logger",
    hooks={PluginHook.BEFORE_TOOL: log_tool_calls}
)

manager = PluginManager()
manager.register(plugin)

Loading from Directory

# plugins/my_plugin.py
from praisonaiagents.plugins import Plugin, PluginInfo

class MyPlugin(Plugin):
    @property
    def info(self):
        return PluginInfo(name="my_plugin")

# main.py
manager = PluginManager()
count = manager.load_from_directory("./plugins")
print(f"Loaded {count} plugins")

Tool Provider Plugin

class CalculatorPlugin(Plugin):
    @property
    def info(self):
        return PluginInfo(name="calculator")
    
    def get_tools(self):
        return [{
            "name": "calculate",
            "description": "Perform math calculations",
            "function": lambda expr: eval(expr),
            "parameters": {
                "type": "object",
                "properties": {
                    "expr": {"type": "string"}
                }
            }
        }]

manager = PluginManager()
manager.register(CalculatorPlugin())

# Get all plugin tools
tools = manager.get_all_tools()