hooks • AI Agent SDK

Hooks Module for PraisonAI Agents.

hooks

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

Related Documentation