Praison AI

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.

Diagram

Plugin System

🔌 Plugin

📋 Manager

🔧 Tool Plugin

🪝 Hook Plugin

🤖 Agent Plugin

🧠 LLM Plugin

Quick Start

  1. Create a Plugin
    typescript
    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
    typescript
    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

Diagram

Choose Your Plugin Type

Add new tools

Intercept events

Modify agent behavior

Customize LLM calls

What do you need?

🔧 Tool Plugin

🪝 Hook Plugin

🤖 Agent Plugin

🧠 LLM Plugin

Tool Plugin

typescript
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

typescript
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

typescript
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

typescript
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

HookWhen TriggeredUse Case
BEFORE_AGENTBefore agent processes inputInput validation, logging
AFTER_AGENTAfter agent produces outputOutput formatting, caching
BEFORE_TOOLBefore tool executionPermission checks, rate limiting
AFTER_TOOLAfter tool returns resultResult transformation
BEFORE_LLMBefore LLM API callToken counting, prompt injection
AFTER_LLMAfter LLM responseResponse caching, analytics
ON_ERRORWhen error occursError logging, recovery
ON_STARTWhen plugin startsInitialization
ON_STOPWhen plugin stopsCleanup

Plugin Manager

typescript
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.

typescript
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)

javascript
// ~/.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.

Function Plugin

Create simple function-based plugins:

typescript
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