Hooks

Hooks intercept agent actions at lifecycle points so you can log, modify, or block them without changing agent code.

from praisonaiagents import Agent
from praisonaiagents.hooks import add_hook

@add_hook("before_tool")
def log_tools(event_data):
    print(f"Running tool: {event_data.tool_name}")

agent = Agent(name="SecureAssistant", instructions="You are a helpful assistant.")
agent.start("Help me organise my files")

The user sends a request; hooks intercept tools and lifecycle steps without changing agent code.

Quick Start

Simple Usage

from praisonaiagents import Agent
from praisonaiagents.hooks import add_hook

@add_hook('before_tool')
def log_tools(event_data):
    print(f"Running tool: {event_data.tool_name}")

@add_hook('before_tool')
def block_delete(event_data):
    if "delete" in event_data.tool_name.lower():
        return "Delete operations are blocked"

agent = Agent(
    name="SecureAssistant",
    instructions="You are a helpful assistant."
)

agent.start("Help me organize my files")

Hook return values:

None or no return → Allow
False → Deny
"reason" → Deny with custom message

With HooksConfig

Attach a HooksConfig to a specific agent for scoped hooks:

from praisonaiagents import Agent, HooksConfig

def log_step(event_data):
    print(f"Step: {event_data}")

def on_tool(event_data):
    print(f"Tool called: {event_data.tool_name}")

agent = Agent(
    name="MonitoredAgent",
    instructions="You are a helpful assistant.",
    hooks=HooksConfig(
        on_step=log_step,
        on_tool_call=on_tool,
    )
)

agent.start("Write a haiku about Python")

Which Hook Point Should I Use?

Pick the lifecycle event that matches what you want to observe or block.

How It Works

Available Hook Events

The events most agents will ever need are the agent / tool / LLM / error / session ones — start here.

Event	When it fires
`before_agent`	Before the agent starts a turn
`after_agent`	After the agent completes a turn
`before_tool`	Before any tool executes
`after_tool`	After a tool returns a result
`before_tool_definitions`	After tool list assembled, before sent to LLM — shape what the model sees
`before_llm`	Before an LLM API call
`after_llm`	After an LLM API response
`on_error`	When any error occurs
`on_retry`	Before a retry attempt (sync + async LLM paths)
`session_start`	When a session begins
`session_end`	When a session ends

This is the core lifecycle subset. The SDK ships ~40 events in total — including plugin/system hooks (on_init, on_shutdown), tool-result persistence (tool_result_persist), message-level bot hooks (before_message, after_message, message_received, message_sending, message_sent), gateway hooks (gateway_start, gateway_stop), compaction hooks (before_compaction, after_compaction), permission/config/auth hooks (on_permission_ask, on_config, on_auth), schedule hooks (schedule_add, schedule_remove, schedule_trigger), background-job hooks (job_completed), kanban task hooks, and Claude-Code-parity events (user_prompt_submit, notification, subagent_stop, setup).See Hook Events for the complete reference with input dataclasses and examples for each.

on_retry is emitted once per retryable error, just before the back-off sleep. It runs whether the LLM call is agent.chat(...) (sync) or await agent.achat(...) (async). Sync-registered callbacks on the async path are run in a thread executor — they cannot block the event loop.

Two lookalike fields. Function-style hooks return HookResult and set modified_input to rewrite the payload. Shell-command hooks parse into HookOutput and use modified_data for the same purpose. When you write a hook in Python, always use HookResult(decision="allow", modified_input={...}) — the internal Agent code reads .modified_input on hook results.

Configuration Options

HooksConfig SDK Reference

Full parameter reference for HooksConfig

from praisonaiagents import Agent, HooksConfig

agent = Agent(
    instructions="...",
    hooks=HooksConfig(
        on_step=my_step_callback,
        on_tool_call=my_tool_callback,
        middleware=[my_middleware],
    )
)

Option	Type	Default	Description
`on_step`	`Callable \| None`	`None`	Called on each agent step
`on_tool_call`	`Callable \| None`	`None`	Called before each tool execution
`middleware`	`List`	`[]`	Middleware list applied to all events

Common Patterns

Security Filtering

from praisonaiagents import Agent
from praisonaiagents.hooks import add_hook

BLOCKED_TOOLS = {"delete_file", "execute_command", "drop_table"}

@add_hook('before_tool')
def security_filter(event_data):
    if event_data.tool_name in BLOCKED_TOOLS:
        return f"Tool '{event_data.tool_name}' is not allowed in this environment"

agent = Agent(
    name="SafeAgent",
    instructions="Help users manage their documents safely."
)

agent.start("Clean up the old log files")

Audit Logging

import json
from datetime import datetime
from praisonaiagents import Agent
from praisonaiagents.hooks import add_hook

@add_hook('before_tool')
def audit_before(event_data):
    print(json.dumps({
        "ts": datetime.utcnow().isoformat(),
        "event": "before_tool",
        "tool": event_data.tool_name,
    }))

@add_hook('after_tool')
def audit_after(event_data):
    print(json.dumps({
        "ts": datetime.utcnow().isoformat(),
        "event": "after_tool",
        "tool": event_data.tool_name,
    }))

agent = Agent(
    name="AuditAgent",
    instructions="Process user requests with full audit trail."
)

agent.start("Search for the latest AI research papers")

Tool Matching with HookRegistry

from praisonaiagents import Agent
from praisonaiagents.hooks import HookRegistry, HookEvent, HookResult

registry = HookRegistry()

@registry.on(HookEvent.BEFORE_TOOL)
def file_guard(event_data) -> HookResult:
    if event_data.tool_name.startswith("write_"):
        print(f"Write operation: {event_data.tool_name}")
    return HookResult.allow()

agent = Agent(
    name="GuardedAgent",
    instructions="You are a helpful assistant.",
    hooks=registry
)

agent.start("Create a summary and save it to output.txt")

Best Practices

Keep hooks lightweight

Hooks run synchronously before/after each operation. Avoid network calls or heavy computation inside hook functions — use async queues for heavy processing.

Return None to allow, string to deny

The simplest hook contract: return nothing (or None) to allow, return a string with a reason to block. This keeps hooks readable.

Use add_hook for global rules, HooksConfig for per-agent rules

add_hook registers hooks globally — all agents in the process obey them. Use HooksConfig when you need different rules per agent.

Set _strict_hooks=True in tests

By default, hook exceptions are logged as warnings and execution continues. Set agent._strict_hooks = True in tests so hook failures surface immediately as errors.

before_agent / after_agent cost nothing when unregistered

before_agent and after_agent cost nothing when no hook is registered — the runtime checks has_hooks() before building the input (including os.getcwd() and the tools list) on both sync (chat) and async (achat) paths. Register these hooks in production without a per-turn overhead concern.

from praisonaiagents import Agent
from praisonaiagents.hooks import add_hook

# No before_agent / after_agent hook registered anywhere in the process.
# The runtime skips input construction entirely — no os.getcwd(), no tools list build.
agent = Agent(name="Fast", instructions="Be helpful.")
agent.start("Say hi")

# Only pay the cost when you actually opt in:
@add_hook("after_agent")
def log_turn(event_data):
    print(f"Turn completed by {event_data.agent_name} in {event_data.execution_time_ms:.0f}ms")

agent.start("Say hi again")   # Now the input is built and after_agent fires.

Hook Events

Complete list of ~40 events with input dataclasses and examples

Guardrails

Validate agent output quality with automatic retry

Callbacks

Observe agent events for UI and logging purposes

Multi-tool Agents: HERMES_ONLY_TOOLS

Hook Events

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

Which Hook Point Should I Use?

How It Works

Available Hook Events

Configuration Options

HooksConfig SDK Reference

Common Patterns

Security Filtering

Audit Logging

Tool Matching with HookRegistry

Best Practices

Hook Events

Guardrails

Callbacks

​Quick Start

​Which Hook Point Should I Use?

​How It Works

​Available Hook Events

​Configuration Options

HooksConfig SDK Reference

​Common Patterns

​Security Filtering

​Audit Logging

​Tool Matching with HookRegistry

​Best Practices

​Related

Hook Events

Guardrails

Callbacks

Quick Start

Which Hook Point Should I Use?

How It Works

Available Hook Events

Configuration Options

Common Patterns

Security Filtering

Audit Logging

Tool Matching with HookRegistry

Best Practices

Related