Simplified API Reference

Quick reference for all simplified helper functions in PraisonAI Agents

Simplified API Reference

PraisonAI provides simplified helper functions following consistent naming patterns for common operations.

Naming Convention

Pattern	Purpose	Example
add_X	Register something	add_hook, add_tool
get_X	Retrieve something	get_tool, get_profile
has_X	Check existence	has_hook, has_tool
remove_X	Unregister	remove_hook, remove_tool
list_X	List all items	list_tools, list_profiles

---

Hooks

Intercept and modify agent behavior at lifecycle points.

from praisonaiagents.hooks import add_hook, has_hook, remove_hook

add_hook

Register a hook for an event.

@add_hook('before_tool')
def my_hook(event_data):
    print(f"Tool: {event_data.tool_name}")
    # No return = allow
    # return False = deny
    # return "reason" = deny with message

Parameters:

• event (str | HookEvent): Event name like 'before_tool', 'after_tool', 'before_llm', etc.
• callback (callable, optional): Hook function. If omitted, returns decorator.
• priority (int): Hook priority (lower = runs first). Default: 10
• matcher (str, optional): Pattern to match (e.g., 'write_*')

Events: before_tool, after_tool, before_llm, after_llm, before_agent, after_agent, session_start, session_end, on_error, on_retry

has_hook

Check if hooks exist for an event.

has_hook('before_tool')  # True/False

remove_hook

Remove a hook by ID.

hook_id = add_hook('before_tool', my_func)
remove_hook(hook_id)

---

Tools

Manage tool registration.

from praisonaiagents.tools import add_tool, has_tool, remove_tool, get_tool, list_tools

add_tool

Register a tool function.

@add_tool
def my_tool(query: str) -> str:
    """Search for information."""
    return f"Result for {query}"

has_tool

Check if a tool exists.

has_tool('my_tool')  # True/False

get_tool

Get a tool by name.

tool = get_tool('my_tool')

remove_tool

Remove a tool.

remove_tool('my_tool')  # True if found and removed

list_tools

List all registered tools.

tools = list_tools()  # ['my_tool', 'other_tool', ...]

---

Agent Profiles

Pre-configured agent personas.

from praisonaiagents.agents.profiles import (
    add_profile, get_profile, has_profile, 
    remove_profile, list_profiles, AgentProfile
)

add_profile

Register a custom profile.

profile = AgentProfile(
    name="researcher",
    description="Research agent",
    system_prompt="You are a research specialist.",
    tools=["search_web", "read_file"],
    temperature=0.3
)
add_profile(profile)

get_profile

Get a profile by name.

profile = get_profile('coder')  # Built-in profile

has_profile

Check if profile exists.

has_profile('researcher')  # True/False

remove_profile

Remove a profile.

remove_profile('researcher')

list_profiles

List all profiles.

profiles = list_profiles()  # List of AgentProfile objects

Built-in Profiles: general, coder, planner, reviewer, explorer, debugger

---

Display Callbacks

Hook into agent display output for custom UIs.

from praisonaiagents.main import add_display_callback, add_approval_callback

add_display_callback

Register a callback for display events.

def my_callback(message, response, **kwargs):
    print(f"Agent said: {response}")

add_display_callback('interaction', my_callback)

Display Types: interaction, tool_call, error, instruction, self_reflection, generating

add_approval_callback

Register callback for tool approval prompts.

from praisonaiagents.approval import ApprovalDecision

def my_approval(function_name, arguments, risk_level):
    if risk_level == 'high':
        return ApprovalDecision.DENY
    return ApprovalDecision.APPROVE

add_approval_callback(my_approval)

---

Hook Return Values

Hooks can return simple values instead of HookResult:

Return	Meaning
None or no return	Allow the operation
True	Allow the operation
False	Deny the operation
"reason"	Deny with custom message
HookResult(...)	Full control (advanced)

@add_hook('before_tool')
def simple_hook(data):
    if 'delete' in data.tool_name:
        return "Delete not allowed"  # Deny with reason
    # No return = allow

---

Quick Import Examples

# Hooks
from praisonaiagents.hooks import add_hook, has_hook, remove_hook

# Tools
from praisonaiagents.tools import add_tool, has_tool, remove_tool, list_tools

# Profiles
from praisonaiagents.agents.profiles import add_profile, get_profile, list_profiles

# Callbacks
from praisonaiagents.main import add_display_callback, add_approval_callback

---

Related

Hooks Guide

Complete hooks documentation

Tools Guide

Tool system documentation

Agent Profiles

Built-in agent profiles

Callbacks

Display callbacks guide