Skip to main content

​
praisonaiagents.hooks

Core SDK 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 )

​
Overview

This module provides components for hooks.

​
Constants

NameValue
_LAZY_GROUPS{'types_core': {'HookEvent': ('praisonaiagents.hooks.types', 'HookEvent'), 'HookDecision': ('praisonaiagents.hooks.types', 'HookDecision'), 'HookResult': ('praisonaiagents.hooks.types', 'HookResult'),...