hooks

AI Agent Hooks Module for PraisonAI Agents. Provides a powerful hook system for intercepting and modifying agent behavior at various lifecycle points. Unlike callbacks (which are for UI events), hooks can intercept, modify, or block tool execution. Features:

Event-based hook system (BeforeTool, AfterTool, BeforeAgent, etc.)
Shell command hooks for external integrations
Python function hooks for in-process customization
Matcher patterns for selective hook execution
Sequential and parallel hook execution
Decision outcomes (allow, deny, block, ask)

Zero Performance Impact:

All imports are lazy loaded via centralized _lazy.py utility
Hooks only execute when registered
No overhead when hooks are disabled

Usage:

from praisonaiagents.hooks import HookRegistry, HookEvent

# Register a Python function hook
registry = HookRegistry()

@registry.on(HookEvent.BEFORE_TOOL)
def my_hook(event_data):
    if event_data.tool_name == "dangerous_tool":
        return HookResult(decision="deny", reason="Tool blocked by policy")
    return HookResult(decision="allow")

# Register a shell command hook
registry.register_command_hook(
    event=HookEvent.BEFORE_TOOL,
    command="python /path/to/validator.py",
    matcher="write_*"  # Only match tools starting with write_
)

# Use with Agent
agent = Agent(
    name="MyAgent",
    hooks=registry
)

Import

from praisonaiagents import hooks

Constants

Name	Value
`_LAZY_GROUPS`	`{'types_core': {'HookEvent': ('praisonaiagents.hooks.types', 'HookEvent'), 'HookDecision': ('praisonaiagents.hooks.types', 'HookDecision'), 'HookResult': ('praisonaiagents.hooks.types', 'HookResult'),...`

Hooks Concept

Hook Events

Callbacks