> ## 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.
# hooks • AI Agent SDK
> Hooks Module for PraisonAI Agents.
# 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
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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'),...` |
***
## Related Documentation