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.

python

from praisonaiagents.hooks import add_hook, has_hook, remove_hook

add_hook

python

@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

Lifecycle events (on_retry, on_error, before_llm, after_llm) fire on both sync and async LLM paths.

has_hook

Check if hooks exist for an event.

python

has_hook('before_tool')  # True/False

remove_hook

Remove a hook by ID.

python

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

Tools

Manage tool registration.

python

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

add_tool

python

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

has_tool

Check if a tool exists.

python

has_tool('my_tool')  # True/False

get_tool

Get a tool by name.

python

tool = get_tool('my_tool')

remove_tool

Remove a tool.

python

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

list_tools

List all registered tools.

python

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

Agent Profiles

Pre-configured agent personas.

python

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

add_profile

python

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.

python

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

has_profile

Check if profile exists.

python

has_profile('researcher')  # True/False

remove_profile

Remove a profile.

python

remove_profile('researcher')

list_profiles

List all profiles.

python

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.

python

from praisonaiagents.main import add_display_callback, add_approval_callback

add_display_callback

python

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

Agent Approval

Control tool approval directly on the agent:

python

from praisonaiagents import Agent

# Auto-approve all dangerous tools
agent = Agent(name="bot", instructions="Helper", approval=True)

# Custom approval backend
from praisonaiagents.approval import ApprovalRequest, ApprovalDecision

class MyBackend:
    def request_approval_sync(self, request: ApprovalRequest) -> ApprovalDecision:
        return ApprovalDecision(approved=True, reason="auto")
    async def request_approval(self, request: ApprovalRequest) -> ApprovalDecision:
        return ApprovalDecision(approved=True, reason="auto")

agent = Agent(name="bot", instructions="Helper", approval=MyBackend())

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)

python

@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

python

# 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

# Approval
from praisonaiagents import Agent, AutoApproveBackend

Hooks Guide

Complete hooks documentation

Tools Guide

Tool system documentation

Agent Profiles

Built-in agent profiles

Callbacks

Display callbacks guide

Simplified API Reference