> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Plugin System"
        A[🔌 Plugin] --> B{📋 Manager}
        B --> C[🔧 Tool Plugin]
        B --> D[🪝 Hook Plugin]
        B --> E[🤖 Agent Plugin]
        B --> F[🧠 LLM Plugin]
    end
    
    classDef plugin fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef manager fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef type fill:#10B981,stroke:#7C90A0,color:#fff
    
    class A plugin
    class B manager
    class C,D,E,F type
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
```

## Quick Start

**1. Create a Plugin**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Choose Your Plugin Type"
        A{What do you need?}
        A -->|Add new tools| B[🔧 Tool Plugin]
        A -->|Intercept events| C[🪝 Hook Plugin]
        A -->|Modify agent behavior| D[🤖 Agent Plugin]
        A -->|Customize LLM calls| E[🧠 LLM Plugin]
    end
    
    classDef question fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef tool fill:#10B981,stroke:#7C90A0,color:#fff
    classDef hook fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef llm fill:#189AB4,stroke:#7C90A0,color:#fff
    
    class A question
    class B tool
    class C hook
    class D agent
    class E llm
```

### Tool Plugin

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// ~/.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`.

> [!NOTE]
>
> `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:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

> [card] [PluginManager](https://praison.ai/docs/sdk/reference/typescript/classes/PluginManager.md)
>
> Plugin manager class

> [card] [Plugin](https://praison.ai/docs/sdk/reference/typescript/classes/Plugin.md)
>
> Plugin base class

***

## Best Practices

> [accordion] Use appropriate plugin types
>
> Choose `ToolPlugin` for adding capabilities, `HookPlugin` for intercepting events, `AgentPlugin` for modifying behavior.

> [accordion] Handle errors gracefully
>
> Always wrap plugin logic in try-catch blocks to prevent breaking the agent pipeline.

> [accordion] Keep plugins lightweight
>
> Plugins run in the hot path - avoid heavy computations or blocking operations.

> [accordion] Version your plugins
>
> Use semantic versioning to track plugin compatibility with SDK versions.

***

## Related

> [card] [Hooks](https://praison.ai/docs/js/hooks-manager.md)
>
> Hook system for event handling

> [card] [Tools](https://praison.ai/docs/js/tools.md)
>
> Create custom tools


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.