Plugins Module

Extend agents with custom plugins for tools, hooks, and integrations

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

Quick Start

1. 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);
   };
   
2. Register with Manager

   import { PluginManager } from 'praisonai';
   
   const manager = new PluginManager();
   manager.register(myPlugin);
   manager.enable("my-plugin");
   
   // List all plugins
   const plugins = manager.listPlugins();
   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.listPlugins();

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

---

Discovery & Loading

PluginManager loads plugin files from disk and reports how many it loaded.

import { PluginManager } from 'praisonai';

const manager = new PluginManager();

// Load every plugin file from a directory. Returns the count loaded.
const n = manager.loadFromDirectory('./my-plugins');
console.log(`loaded ${n} plugins`);

// Opt-in scan of the standard locations. Gated by an env var — see below.
process.env.PRAISONAI_ALLOW_PLUGIN_DISCOVERY = 'true';
const total = manager.autoDiscoverPlugins();

loadFromDirectory(path: string): number

• Synchronous require(); supports .js, .cjs, and .ts (under ts-node / ts-jest).
• Skips .mjs, .d.ts, and files whose name starts with _.
• Broken files log a warning and do NOT abort the scan.

autoDiscoverPlugins(): number

• Scans <cwd>/.praisonai/plugins/ (project) and ~/.praisonai/plugins/ (user).
• PRAISONAI_ALLOW_PLUGIN_DISCOVERY must be 'true', '1', or 'yes' (case-insensitive) for the scan to run; otherwise it returns 0.
• Returns 0 in non-Node runtimes.

Plugin file convention (CommonJS)

// ~/.praisonai/plugins/greeter.js
const { Plugin } = require('praisonai');

module.exports.createPlugin = () => new Plugin({
  name: 'greeter',
  version: '1.0.0',
  type: 'hook',
});

Recognised shapes on the loaded module: a createPlugin() factory, a Plugin subclass constructor, or an existing Plugin instance — exported as createPlugin, plugin, or default.

autoDiscoverPlugins() and loadFromDirectory() now return a count (they used to return void). Existing callers that ignored the return value keep working; callers that want to know whether anything loaded can now read the number.

---

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.

---

Related

Hooks

Hook system for event handling

Tools

Create custom tools