Add Hook • AI Agent SDK

add_hook: Register a hook callback. Simplified API.

add_hook

Function

</div>

This function is defined in the registry module.

Accepts both string event names and HookEvent enums: add_hook(‘before_tool’, my_callback) # String add_hook(HookEvent.BEFORE_TOOL, my_callback) # Enum

Can also be used as a decorator: @add_hook(‘before_tool’) def my_hook(data): return HookResult.allow()

Diagram

Signature

python

def add_hook(event: Union[str, HookEvent], callback: Optional[Callable[[HookInput], HookResult]], priority: int, matcher: Optional[str]) -> Union[str, Callable]

Parameters

ParamField Union[str, HookEvent]

Hook event name (‘before_tool’, ‘after_llm’, etc.) or HookEvent enum

ParamField Optional

Function to call when hook fires (optional when using as decorator)

ParamField int

Execution order (lower = earlier). Default 100 — same default bucket as `register_function/on`, so hooks added through either API keep registration order unless an explicit priority is given.

ParamField Optional[str]

Optional regex pattern to match specific targets (e.g., tool names)

Returns

ResponseField Union[str, Callable]

Hook ID for later removal, or a decorator function if callback is None

Exceptions

ValueError

If event string is not a valid HookEvent

Uses

HookEvent
ValueError
register_function
get_default_registry

Source

View on GitHub

praisonaiagents/hooks/registry.py at line 387