Plugins Module - PraisonAI

Extend your agents with powerful plugins that add tools, hooks, and custom functionality.

Quick Start

Create a Plugin

import { Plugin, PluginHook, PluginType } from 'praisonai';

const myPlugin = new Plugin({
  name: "my-plugin",
  version: "1.0.0",
  description: "Custom logging plugin",
  type: PluginType.HOOK,
  hooks: [PluginHook.BEFORE_AGENT, PluginHook.AFTER_AGENT]
});

myPlugin.onHook = (hook, ...args) => {
  console.log(`Hook triggered: ${hook}`, args);
};

import { PluginManager } from 'praisonai';

const manager = new PluginManager();
manager.register(myPlugin);
manager.enable("my-plugin");

// List all plugins
const plugins = manager.list();
console.log(plugins);

Plugin Types

Tool Plugin

import { ToolPluginProtocol, PluginHook } from 'praisonai';

const toolPlugin: ToolPluginProtocol = {
  name: "calculator",
  version: "1.0.0",
  type: "tool",
  
  execute(input: { expression: string }) {
    return eval(input.expression);
  },
  
  getSchema() {
    return {
      name: "calculate",
      description: "Evaluate math expressions",
      parameters: {
        type: "object",
        properties: {
          expression: { type: "string" }
        }
      }
    };
  }
};

Hook Plugin

import { HookPluginProtocol, PluginHook } from 'praisonai';

const hookPlugin: HookPluginProtocol = {
  name: "logger",
  version: "1.0.0",
  type: "hook",
  hooks: [PluginHook.BEFORE_TOOL, PluginHook.AFTER_TOOL],
  
  handle(hook: PluginHook, context: any) {
    if (hook === PluginHook.BEFORE_TOOL) {
      console.log(`Calling tool: ${context.toolName}`);
    } else {
      console.log(`Tool result: ${context.result}`);
    }
  }
};

Agent Plugin

import { AgentPluginProtocol } from 'praisonai';

const agentPlugin: AgentPluginProtocol = {
  name: "prompt-enhancer",
  version: "1.0.0",
  type: "agent",
  
  beforeAgent(agentName: string, input: string) {
    return `[Enhanced] ${input}`;
  },
  
  afterAgent(agentName: string, output: string) {
    return output.toUpperCase();
  }
};

LLM Plugin

import { LLMPluginProtocol } from 'praisonai';

const llmPlugin: LLMPluginProtocol = {
  name: "token-counter",
  version: "1.0.0",
  type: "llm",
  
  beforeLLM(messages: any[], options: any) {
    console.log(`Sending ${messages.length} messages`);
    return { messages, options };
  },
  
  afterLLM(response: any) {
    console.log(`Received response with ${response.usage?.total_tokens} tokens`);
    return response;
  }
};

Plugin Hooks

Hook	When Triggered	Use Case
`BEFORE_AGENT`	Before agent processes input	Input validation, logging
`AFTER_AGENT`	After agent produces output	Output formatting, caching
`BEFORE_TOOL`	Before tool execution	Permission checks, rate limiting
`AFTER_TOOL`	After tool returns result	Result transformation
`BEFORE_LLM`	Before LLM API call	Token counting, prompt injection
`AFTER_LLM`	After LLM response	Response caching, analytics
`ON_ERROR`	When error occurs	Error logging, recovery
`ON_START`	When plugin starts	Initialization
`ON_STOP`	When plugin stops	Cleanup

Plugin Manager

import { PluginManager, getPluginManager } from 'praisonai';

// Get singleton manager
const manager = getPluginManager();

// Or create new instance
const customManager = new PluginManager();

// Register plugins
manager.register(myPlugin);

// Enable/disable
manager.enable("my-plugin");
manager.disable("my-plugin");

// Check status
const isEnabled = manager.isEnabled("my-plugin");

// List all plugins
const allPlugins = manager.list();

// Get specific plugin
const plugin = manager.get("my-plugin");

Discovery & Loading

import { 
  discoverPlugins, 
  loadPlugin, 
  discoverAndLoadPlugins,
  getDefaultPluginDirs 
} from 'praisonai';

// Get default plugin directories
const dirs = getDefaultPluginDirs();
// Returns: ['./plugins', '~/.praisonai/plugins']

// Discover plugins in directory
const discovered = await discoverPlugins('./my-plugins');

// Load a single plugin
const plugin = await loadPlugin('./my-plugins/custom.ts');

// Discover and load all
const plugins = await discoverAndLoadPlugins('./my-plugins');

Function Plugin

Create simple function-based plugins:

import { FunctionPlugin } from 'praisonai';

const greetPlugin = new FunctionPlugin({
  name: "greeter",
  version: "1.0.0",
  fn: (name: string) => `Hello, ${name}!`
});

// Execute
const result = greetPlugin.execute("World");
// Returns: "Hello, World!"

API Reference

PluginManager

Plugin manager class

Plugin

Plugin base class

Best Practices

Use appropriate plugin types

Choose ToolPlugin for adding capabilities, HookPlugin for intercepting events, AgentPlugin for modifying behavior.

Handle errors gracefully

Always wrap plugin logic in try-catch blocks to prevent breaking the agent pipeline.

Keep plugins lightweight

Plugins run in the hot path - avoid heavy computations or blocking operations.

Version your plugins

Use semantic versioning to track plugin compatibility with SDK versions.

Hooks

Hook system for event handling

Tools

Create custom tools

​Quick Start

​Plugin Types

​Tool Plugin

​Hook Plugin

​Agent Plugin

​LLM Plugin

​Plugin Hooks

​Plugin Manager

​Discovery & Loading

​Function Plugin

​API Reference