Plugins - PraisonAI

Plugins add tools, hooks, and guardrails that can rewrite — or now block — what an agent sees and does; drop a Python file in ~/.praisonai/plugins/ and load it in one line.

from praisonaiagents import Agent, discover_and_load_plugins

discover_and_load_plugins()

agent = Agent(
    name="Assistant",
    instructions="Help users with weather queries.",
    tools=["get_weather"],
)
agent.start("What's the weather in Paris?")

The user asks a question; plugins add tools and hooks before the agent answers.

Quick Start

Simple Usage

Create ~/.praisonai/plugins/my_tools.py:

"""
Plugin Name: My Tools
Description: Custom tools for my agent
Version: 1.0.0
"""

from praisonaiagents import tool

@tool
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"Sunny in {city}, 22°C"

Load and run:

from praisonaiagents import Agent, discover_and_load_plugins

discover_and_load_plugins()

agent = Agent(
    name="Assistant",
    instructions="Help users",
    tools=["get_weather"],
)
agent.start("What's the weather in Paris?")

With Configuration

Point the environment (or config file) at plugins and Agent construction wires them for you — no explicit plugins.enable() call needed:

export PRAISONAI_PLUGINS=true

from praisonaiagents import Agent

agent = Agent(name="Assistant", instructions="Help users")
agent.start("Hello!")   # entry-point plugins are wired in before this runs

Prefer to turn plugins on in code? Call plugins.enable(...) before creating the agent:

from praisonaiagents import Agent, plugins

plugins.enable(["logging", "metrics"])

agent = Agent(name="Assistant", instructions="Help users")
agent.start("Hello!")

Place plugins in ~/.praisonai/plugins/ (user-wide) or ./.praisonai/plugins/ (project-specific).

plugins.enable() auto-discovers filesystem and entry-point plugins only when PRAISONAI_ALLOW_PLUGIN_DISCOVERY=true (or 1/yes). Without this env var, plugins.enable() still bridges plugins you register manually via PluginManager.register(...), but no directory or entry-point scan runs.

How It Works

plugins.enable() auto-calls wire_into_hook_registry(), which registers each enabled plugin’s lifecycle methods on the default hook registry the agent consults at runtime — and Agent init calls this for you when the env var or config file requests it (see Auto-Enable from Env or Config). The hooks fire in this order around each agent run:

Plugin type	What it adds
Tool	Functions registered via `@tool`
Hook	Lifecycle callbacks (`before_tool`, `before_tool_definitions`, `after_llm`, …)
Guardrail	Output validation on `after_agent`

Choosing How to Load Plugins

Pick the loading method that fits your setup.

Plugin Locations

Location	Scope
`~/.praisonai/plugins/`	User-wide
`./.praisonai/plugins/`	Project-specific

Hook Plugin Example

Create ~/.praisonai/plugins/my_logger.py:

"""
Plugin Name: My Logger
Description: Logs tool calls
Version: 1.0.0
Hooks: before_tool, after_tool
"""

from praisonaiagents.hooks import add_hook

@add_hook("before_tool")
def log_before(data):
    print(f"Calling: {data.tool_name}")

@add_hook("after_tool")
def log_after(data):
    print(f"Done: {data.tool_name}")

Create ~/.praisonai/plugins/tool_sandbox.py to filter advertised tools:

"""
Plugin Name: Tool Sandbox
Description: Filters tool definitions sent to the LLM
Version: 1.0.0
Hooks: before_tool_definitions
"""

from praisonaiagents.hooks import add_hook

BLOCKED = {"delete_file", "shell_exec"}

@add_hook("before_tool_definitions")
def sandbox_tools(data):
    data.tool_definitions[:] = [
        t for t in data.tool_definitions
        if t["function"]["name"] not in BLOCKED
    ]

from praisonaiagents import Agent, discover_and_load_plugins

discover_and_load_plugins()
agent = Agent(name="Assistant", instructions="Help users")
agent.start("Search for Python tutorials")

Lifecycle-Method Plugins

Subclass Plugin and override a lifecycle method to transform prompts, messages, or responses. Call plugins.enable() — or set PRAISONAI_PLUGINS=true / [plugins] enabled = true and let Agent construction wire it — to activate the method at runtime. Create ~/.praisonai/plugins/pii_redactor.py:

"""
Plugin Name: PII Redactor
Description: Scrubs SSNs from LLM responses
Version: 1.0.0
"""
import re
from praisonaiagents import Plugin, PluginInfo, PluginHook

class PIIRedactor(Plugin):
    @property
    def info(self):
        return PluginInfo(
            name="pii_redactor",
            version="1.0.0",
            description="Scrubs SSNs from LLM responses",
            hooks=[PluginHook.AFTER_LLM],
        )

    def after_llm(self, response: str, usage: dict) -> str:
        return re.sub(r"\b\d{3}-\d{2}-\d{4}\b", "[SSN]", response)

def create_plugin():
    return PIIRedactor()

Load and enable:

from praisonaiagents import Agent, plugins

plugins.enable()   # bridges lifecycle methods into the runtime hook registry

agent = Agent(name="Assistant", instructions="Help users.")
agent.start("My SSN is 123-45-6789")   # response is redacted before the user sees it

Session & Error Lifecycle Plugins

Override session_start, session_end, on_error, on_config, or on_auth to react to session boundaries, errors, config, and credential resolution.

Choosing a lifecycle event

Observe sessions

session_start and session_end observe when a session opens and closes.

from praisonaiagents import Agent, plugins

plugins.enable()

agent = Agent(name="Assistant", instructions="Help users.")
agent.start("Hello!")

Create ~/.praisonai/plugins/session_logger.py:

"""
Plugin Name: Session Logger
Description: Records when sessions start and end
Version: 1.0.0
"""
from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook

class SessionLogger(Plugin):
    @property
    def info(self):
        return PluginInfo(
            name="session_logger",
            hooks=[PluginHook.SESSION_START, PluginHook.SESSION_END],
        )

    def session_start(self, context):
        print(f"session started: {context.get('session_name')}")

    def session_end(self, context):
        print(f"session ended: {context.get('reason')} after {context.get('total_turns')} turns")

def create_plugin():
    return SessionLogger()

Observe errors

on_error observes errors during a run — use it to log without changing behavior.

from praisonaiagents import Agent, plugins

plugins.enable()

agent = Agent(name="Assistant", instructions="Help users.")
agent.start("Do something that might fail")

Create ~/.praisonai/plugins/error_reporter.py:

"""
Plugin Name: Error Reporter
Description: Logs errors during agent runs
Version: 1.0.0
"""
from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook

class ErrorReporter(Plugin):
    @property
    def info(self):
        return PluginInfo(
            name="error_reporter",
            hooks=[PluginHook.ON_ERROR],
        )

    def on_error(self, error_type, error_message, context):
        print(f"{error_type}: {error_message}")
        print(context.get("stack_trace"))

def create_plugin():
    return ErrorReporter()

Rewrite config

on_config returns a dict to rewrite runtime configuration in place.

from praisonaiagents import Agent, plugins

plugins.enable()

agent = Agent(name="Assistant", instructions="Help users.")
agent.start("Hello!")

Create ~/.praisonai/plugins/config_defaults.py:

"""
Plugin Name: Config Defaults
Description: Injects a default temperature into runtime config
Version: 1.0.0
"""
from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook

class ConfigDefaults(Plugin):
    @property
    def info(self):
        return PluginInfo(
            name="config_defaults",
            hooks=[PluginHook.ON_CONFIG],
        )

    def on_config(self, config):
        config.setdefault("temperature", 0.2)
        return config

def create_plugin():
    return ConfigDefaults()

Inject credentials

on_auth returns a dict of credentials — the bridge writes them back even when credentials starts as None, so first-time injection works.

from praisonaiagents import Agent, plugins

plugins.enable()

agent = Agent(name="Assistant", instructions="Help users.")
agent.start("Call the authenticated API")

Create ~/.praisonai/plugins/token_injector.py:

"""
Plugin Name: Token Injector
Description: Supplies credentials on first-time auth
Version: 1.0.0
"""
import os
from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook

class TokenInjector(Plugin):
    @property
    def info(self):
        return PluginInfo(
            name="token_injector",
            hooks=[PluginHook.ON_AUTH],
        )

    def on_auth(self, auth_type, credentials):
        return {"token": os.environ["MY_API_TOKEN"]}

def create_plugin():
    return TokenInjector()

Auto-Enable from Env or Config

Agent construction auto-enables plugins when the environment or config file requests it — no explicit plugins.enable() call needed. Set the env var, then any Agent(...) wires plugins before it runs:

export PRAISONAI_PLUGINS=true

from praisonaiagents import Agent

agent = Agent(name="Assistant", instructions="Help users")
agent.start("Hello!")   # plugins are already active

Or turn them on in .praisonai/config.toml:

[plugins]
enabled = true          # or false, or ["logging", "metrics"]

Want each plugin to receive its own options from one file? See Configure Plugins from .praisonai/config.yaml for per-plugin option blocks.

Under the hood, Agent init calls plugins.maybe_enable_from_config(), which reads the env var and config file, then runs enable(get_enabled_plugins()) exactly once per process. Precedence: explicit plugins.enable(...) > PRAISONAI_PLUGINS env var > [plugins] in config.yaml / config.toml > disabled.

maybe_enable_from_config() is idempotent and runs at most once per process, so instantiating multiple agents is safe — plugins are wired a single time.

Auto-enable does not imply discovery. Filesystem and entry-point scanning still require PRAISONAI_ALLOW_PLUGIN_DISCOVERY=true (or 1/yes). Without it, only plugins registered manually via PluginManager.register(...) are bridged.

Verify auto-enable at runtime — constructing an Agent triggers the wiring:

from praisonaiagents import Agent, plugins

Agent(name="probe", instructions="noop")   # triggers maybe_enable_from_config
print(plugins.is_enabled(), plugins.list_plugins())

Configure Plugins from `.praisonai/config.yaml`

Turn plugins on and hand each one its own options from a single YAML file — no code. ~/.praisonai/config.yaml:

plugins:
  enabled: true
  pii_guardrail:
    redact: [email, phone]
  memory_watchdog:
    interval: 30

app.py:

from praisonaiagents import Agent

agent = Agent(name="Assistant", instructions="Help users.")
agent.start("My email is user@example.com")   # pii_guardrail redacts before the LLM sees it

Agent construction auto-loads the config, enables plugins, and hands pii_guardrail its {redact: [email, phone]} dict via on_config. Nothing else to wire up.

Where the config file is found

.praisonai/config.toml   → .praisonai/config.yaml   → .praisonai/config.yml   (project-local)
praisonai.toml           → praisonai.yaml           → praisonai.yml           (project root)
~/.praisonai/config.toml → ~/.praisonai/config.yaml → ~/.praisonai/config.yml (user global)

The first file found wins — TOML and YAML have equal standing; whichever appears first in the search stops the walk.

PyYAML is an optional dependency. Without it, .yaml configs return empty (debug log only) — install with pip install pyyaml to enable the YAML surface.

The four shapes of `enabled`

`enabled` value	Meaning	Example
`true`	Enable every discovered plugin	`enabled: true`
`false`	Disable every plugin — wins over per-plugin blocks	`enabled: false`
`[names]` (non-empty list)	Enable exactly these plugins	`enabled: [pii_guardrail, metrics]`
`"name"` (bare string, TOML)	Enable exactly this one plugin	`enabled = "pii_guardrail"`
omitted + per-plugin blocks	Enable each plugin block whose own `enabled` is not `false`	(see below)

The JSON config schema advertises boolean and array for enabled; the loader also accepts a bare string at runtime for TOML users who prefer enabled = "pii_guardrail".

Per-plugin option blocks

Reserved keys (enabled, auto_discover, directories) configure the plugin system; any other key whose value is a mapping is treated as a per-plugin option map delivered to that plugin’s on_config hook.

plugins:
  pii_guardrail:
    redact: [email, phone]
    enabled: true
  memory_watchdog:
    interval: 30
    enabled: false     # disable just this one; pii_guardrail still runs

An explicit top-level enabled: false wins over any per-plugin block. Omit enabled at the top level and per-plugin blocks decide.

Reading options inside a plugin — `on_config`

apply_plugin_options() invokes plugin.on_config(options) for every enabled plugin that has a configured option map — errors in a single plugin are logged and do not abort delivery to the others. Create ~/.praisonai/plugins/pii_guardrail.py:

"""
Plugin Name: PII Guardrail
Description: Redacts configured fields before the LLM sees them
Version: 1.0.0
"""
from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook

class PIIGuardrail(Plugin):
    def __init__(self):
        self._fields = []

    @property
    def info(self):
        return PluginInfo(
            name="pii_guardrail",
            hooks=[PluginHook.ON_CONFIG, PluginHook.BEFORE_LLM],
        )

    def on_config(self, config):
        # config is the exact dict from `plugins.pii_guardrail:` in YAML.
        self._fields = list(config.get("redact", []))
        return config

    def before_llm(self, messages, params):
        # Use self._fields to scrub before the LLM call...
        return messages, params

def create_plugin():
    return PIIGuardrail()

on_config fires once per enable — the reserved enabled flag (if present in the plugin block) is preserved so plugins can read it too.

Deliver options from code — `options_by_name`

Skip the file and hand each plugin its options directly. plugins.enable() takes an options_by_name map that it delivers to each plugin’s on_config hook:

from praisonaiagents import plugins

plugins.enable(
    ["pii_guardrail"],
    options_by_name={"pii_guardrail": {"redact": ["email"]}},
)

.praisonai/config.yaml calls this for you — maybe_enable_from_config() runs enable(get_enabled_plugins(), options_by_name=get_plugin_options()) under the hood. Call get_plugin_options() yourself to read the per-plugin maps the loader parsed.

Choose a plugin config surface

Precedence

Explicit plugins.enable(...) in code > PRAISONAI_PLUGINS env var > [plugins] in config.yaml / config.toml > disabled by default.

Edge cases

PyYAML missing — YAML configs silently return empty (debug log only); install pyyaml to enable.
Unknown reserved key — the wrapper resolver’s typo-suggestion validator only checks against {enabled, auto_discover, directories}; per-plugin blocks (dicts) are always accepted.
Removed plugin block on reload — the manager stores options with replace=True by default, so a block dropped from a later config no longer delivers stale options.
Plugin on_config raises — logged as a warning; delivery to other plugins is not aborted.

How the Bridge Works

plugins.enable() auto-calls wire_into_hook_registry() — no manual step. Only lifecycle methods a plugin actually overrides (or declares in PluginInfo.hooks) are bridged, so a plugin with one guardrail never fires on every event. Return a new value and the bridge writes it back onto the payload in place. Errors in a lifecycle method are non-fatal, and plugins.disable([...]) calls unwire_from_hook_registry(name) so the plugin truly stops firing.

The five before_* methods (before_agent, before_llm, before_tool, before_tool_definitions, before_message) also accept a deny/block decision instead of a rewrite — see Blocking Plugins.

Plugin method	Hook event	In-place mutation
`before_agent(prompt, ctx)`	`BEFORE_AGENT`	Return a `str` → rewrites `data.prompt`
`after_agent(response, ctx)`	`AFTER_AGENT`	Return a `str` → rewrites `data.response`
`before_llm(messages, params)`	`BEFORE_LLM`	Return `(new_messages, ...)` → replaces `data.messages`
`after_llm(response, usage)`	`AFTER_LLM`	Return a `str` → rewrites `data.response`
`before_tool(name, args)`	`BEFORE_TOOL`	Return a `dict` → replaces `data.tool_input`
`after_tool(name, result)`	`AFTER_TOOL`	Observational (no mutation)
`before_tool_definitions(defs)`	`BEFORE_TOOL_DEFINITIONS`	Return a `list` → replaces `data.tool_definitions`
`before_message(msg)`	`MESSAGE_RECEIVED`	Return `{"content": "..."}` → rewrites `data.content`
`after_message(msg)`	`MESSAGE_SENDING`	Return `{"content": "..."}` → rewrites `data.content`
`on_permission_ask(target, reason)`	`ON_PERMISSION_ASK`	`True`/`False`/`None` → allow/deny/allow
`on_config(config)`	`ON_CONFIG`	Return a `dict` → rewrites `data.config`
`on_auth(auth_type, credentials)`	`ON_AUTH`	Return a `dict` → rewrites `data.credentials` (works when starting as `None`)
`session_start(context)`	`SESSION_START`	Observational (session `source`, `session_name`, `session_id`)
`session_end(context)`	`SESSION_END`	Observational (`reason`, `total_turns`, `total_tokens`, `session_id`)
`on_error(error_type, error_message, context)`	`ON_ERROR`	Observational (`stack_trace`, nested `context`, `session_id`)

on_config and on_auth write their returned dict back onto the payload even when the target attribute starts as None — so a plugin can inject credentials the first time they’re requested, not only edit an existing dict.

Blocking Plugins (Guardrails & Policies)

Guardrail and policy plugins can now stop an action before it happens, not just rewrite it — refuse a dangerous tool call, drop a spam message, or decline an LLM request.

Quick Start

Block a tool call

Return PluginDecision.block(reason) from before_tool to skip a forbidden tool.

from praisonaiagents import Agent, plugins
from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook, PluginDecision

class BlockDeleteFiles(Plugin):
    @property
    def info(self):
        return PluginInfo(
            name="block_delete_files",
            hooks=[PluginHook.BEFORE_TOOL],
        )

    def before_tool(self, tool_name, args):
        if tool_name == "delete_file":
            return PluginDecision.block("File deletion is not permitted")
        return args

plugins.get_plugin_manager().register(BlockDeleteFiles())
plugins.enable()

agent = Agent(name="Assistant", instructions="Help users.", tools=["delete_file", "read_file"])
agent.start("Delete /etc/hosts")   # tool call skipped; block reason surfaced

Refuse an LLM request

Return PluginDecision.deny(reason) from before_llm and the agent returns "[LLM request blocked by hook: <reason>]" without calling the model.

from praisonaiagents import Agent, plugins
from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook, PluginDecision

class BlockLLM(Plugin):
    @property
    def info(self):
        return PluginInfo(
            name="block_llm",
            hooks=[PluginHook.BEFORE_LLM],
        )

    def before_llm(self, messages, params):
        return PluginDecision.deny("LLM request refused by policy")

plugins.get_plugin_manager().register(BlockLLM())
plugins.enable()

agent = Agent(name="Assistant", instructions="Help users.")
print(agent.start("Hello"))   # [LLM request blocked by hook: LLM request refused by policy]

Drop an inbound message

Return PluginDecision.deny(reason) from before_message to drop a message before the agent sees it.

from praisonaiagents import Agent, plugins
from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook, PluginDecision

class BlockSpam(Plugin):
    @property
    def info(self):
        return PluginInfo(
            name="block_spam",
            hooks=[PluginHook.MESSAGE_RECEIVED],
        )

    def before_message(self, message):
        if "spam" in message.get("content", ""):
            return PluginDecision.deny("Spam blocked")
        return message

plugins.get_plugin_manager().register(BlockSpam())
plugins.enable()

agent = Agent(name="Assistant", instructions="Help users.")
agent.start("buy spam now")   # message dropped before the agent runs

Three Ways to Block

The same block, written three ways — pick the one that reads cleanest in your code.

Style	Return / raise	When to prefer
`PluginDecision`	`return PluginDecision.deny(reason)` / `.block(reason)`	Default. One import, reads like data.
`HookResult`	`return HookResult.deny(reason)` / `.block(reason)`	You already work with `HookResult` elsewhere.
`GuardrailBlocked`	`raise GuardrailBlocked(reason)`	Deep in a validator that would otherwise `raise` anyway.

from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook, PluginDecision

class BlockDelete(Plugin):
    @property
    def info(self):
        return PluginInfo(name="block_delete", hooks=[PluginHook.BEFORE_TOOL])

    def before_tool(self, tool_name, args):
        if tool_name == "delete_file":
            return PluginDecision.block("File deletion not permitted")
        return args

from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook
from praisonaiagents.hooks.types import HookResult

class BlockDelete(Plugin):
    @property
    def info(self):
        return PluginInfo(name="block_delete", hooks=[PluginHook.BEFORE_TOOL])

    def before_tool(self, tool_name, args):
        if tool_name == "delete_file":
            return HookResult.deny("Denied via HookResult")
        return args

from praisonaiagents.plugins import Plugin, PluginInfo, PluginHook, GuardrailBlocked

class BlockDelete(Plugin):
    @property
    def info(self):
        return PluginInfo(name="block_delete", hooks=[PluginHook.BEFORE_TOOL])

    def before_tool(self, tool_name, args):
        if tool_name == "delete_file":
            raise GuardrailBlocked("File deletion not permitted")
        return args

PluginDecision.deny(reason) and PluginDecision.block(reason) both stop the action (is_denied() is True for each); allow(reason=None) is an explicit no-op. GuardrailBlocked(reason: str = "Blocked by guardrail plugin") is caught by the bridge and converted to a block.

Where Blocks Fire

Five before_* methods can block; after_* methods are observational and cannot.

Plugin method	Can rewrite?	Can block?	Runtime effect of block
`before_agent`	✅	✅	Agent run aborts before the first LLM call
`before_llm`	✅	✅	Model call skipped; agent returns `"[LLM request blocked by hook: <reason>]"`
`before_tool_definitions`	✅	✅	Tool surface dropped for this turn (LLM sees no tools)
`before_tool`	✅	✅	Tool call skipped; reason surfaced
`before_message`	✅	✅	Inbound message dropped
`after_*`	✅	❌	(observational — no block path)

How a Block Flows

Which Style Should I Use?

Ship a Plugin as a pip Package

[project.entry-points."praisonai.plugins"]
my_plugin = "my_package.plugins:MyPlugin"

Agent construction (or plugins.enable()) auto-discovers and bridges it — no user code changes needed.

CLI Commands

praisonai plugins init my_plugin
praisonai plugins list
praisonai plugins scan --verbose

Configuration Options

Field	Required	Description
`Plugin Name`	Yes	Display name in plugin header
`Description`	Yes	What the plugin does
`Version`	Yes	Semantic version
`Hooks`	No	Hook events this plugin registers

Best Practices

Keep plugins single-purpose

One file per concern — weather tools, logging, or guardrails, not all three.

Call discover_and_load_plugins() once

Load before creating the agent so tools and hooks register globally.

Reference tools by name

Pass tools=["get_weather"] — the string must match the @tool function name.

Use plugins.enable for built-ins

Enable logging and metrics without writing plugin files.

Call plugins.enable() to activate lifecycle methods

Tools and guardrails work without plugins.enable(). But lifecycle-method plugins (subclasses of Plugin that override before_llm, after_llm, and so on) only fire after they are wired into the runtime hook registry. Call plugins.enable() explicitly, or set PRAISONAI_PLUGINS=true / [plugins] enabled = true and Agent construction wires them automatically.

Reach for PluginDecision before HookResult

PluginDecision.deny(reason) reads as one line and only needs the plugin import. Use HookResult.deny(reason) only when you already import it for another reason, and raise GuardrailBlocked(reason) only when you’re inside a validator that already raises on failure. Prefer block over deny when the action is categorically forbidden; use deny when it’s contextually refused (this input, this user, this time).

Hooks

Hook events and the HookRegistry API

Toolsets

Create and register custom agent tools

Config File

Turn plugins on from [plugins] in config.toml

Tool Discovery

How Agent resolves tool names at runtime

Guardrails

Validate agent output — automatic retry on failure

​Quick Start

​How It Works

​Choosing How to Load Plugins

​Plugin Locations

​Hook Plugin Example

​Lifecycle-Method Plugins

​Session & Error Lifecycle Plugins

​Choosing a lifecycle event

​Observe sessions

​Observe errors

​Rewrite config

​Inject credentials

​Auto-Enable from Env or Config

​Configure Plugins from .praisonai/config.yaml

​Where the config file is found

​The four shapes of enabled

​Per-plugin option blocks

​Reading options inside a plugin — on_config

​Deliver options from code — options_by_name

​Choose a plugin config surface

​Precedence

​Edge cases

​How the Bridge Works

​Blocking Plugins (Guardrails & Policies)

​Quick Start

​Three Ways to Block

​Where Blocks Fire

​How a Block Flows

​Which Style Should I Use?

​Ship a Plugin as a pip Package

​CLI Commands

​Configuration Options

​Best Practices

​Related

Hooks

Toolsets

Config File

Tool Discovery

Guardrails

Quick Start

How It Works

Choosing How to Load Plugins

Plugin Locations

Hook Plugin Example

Lifecycle-Method Plugins

Session & Error Lifecycle Plugins

Choosing a lifecycle event

Observe sessions

Observe errors

Rewrite config

Inject credentials

Auto-Enable from Env or Config

Configure Plugins from `.praisonai/config.yaml`

Where the config file is found

The four shapes of `enabled`

Per-plugin option blocks

Reading options inside a plugin — `on_config`

Deliver options from code — `options_by_name`

Choose a plugin config surface

Precedence

Edge cases

How the Bridge Works

Blocking Plugins (Guardrails & Policies)

Quick Start

Three Ways to Block

Where Blocks Fire

How a Block Flows

Which Style Should I Use?

Ship a Plugin as a pip Package

CLI Commands

Configuration Options

Best Practices

Related