> ## 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. # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents.hooks import add_hook, has_hook, remove_hook ``` ### add\_hook Register a hook for an event. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} @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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} has_hook('before_tool') # True/False ``` ### remove\_hook Remove a hook by ID. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} hook_id = add_hook('before_tool', my_func) remove_hook(hook_id) ``` *** ## Tools Manage tool registration. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents.tools import add_tool, has_tool, remove_tool, get_tool, list_tools ``` ### add\_tool Register a tool function. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} @add_tool def my_tool(query: str) -> str: """Search for information.""" return f"Result for {query}" ``` ### has\_tool Check if a tool exists. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} has_tool('my_tool') # True/False ``` ### get\_tool Get a tool by name. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} tool = get_tool('my_tool') ``` ### remove\_tool Remove a tool. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} remove_tool('my_tool') # True if found and removed ``` ### list\_tools List all registered tools. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} tools = list_tools() # ['my_tool', 'other_tool', ...] ``` *** ## Agent Profiles Pre-configured agent personas. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents.agents.profiles import ( add_profile, get_profile, has_profile, remove_profile, list_profiles, AgentProfile ) ``` ### add\_profile Register a custom profile. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} profile = get_profile('coder') # Built-in profile ``` ### has\_profile Check if profile exists. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} has_profile('researcher') # True/False ``` ### remove\_profile Remove a profile. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} remove_profile('researcher') ``` ### list\_profiles List all profiles. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents.main import add_display_callback, add_approval_callback ``` ### add\_display\_callback Register a callback for display events. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} @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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ``` *** ## Related Complete hooks documentation Tool system documentation Built-in agent profiles Display callbacks guide