Skip to main content
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.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

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

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!"

​
Best Practices

Choose ToolPlugin for adding capabilities, HookPlugin for intercepting events, AgentPlugin for modifying behavior.
Always wrap plugin logic in try-catch blocks to prevent breaking the agent pipeline.
Plugins run in the hot path - avoid heavy computations or blocking operations.
Use semantic versioning to track plugin compatibility with SDK versions.

Hooks

Hook system for event handling

Tools

Create custom tools