Create Custom Tools

Step-by-step guide to creating custom tools for PraisonAI agents

Turn Python functions into agent-callable tools with clear parameters and docstrings.

from praisonaiagents import Agent, tool

@tool
def echo(query: str) -> str:
    """Return the query uppercased."""
    return query.upper()

agent = Agent(name="Tool Demo", tools=[echo])
agent.start("Use echo on hello world.")

The user defines a tool, registers it on an agent, and verifies the model invokes it correctly.

How It Works

How to Create a Simple Tool Function

1. Define Tool Function

   def my_tool(query: str) -> str:
       """Process a query and return result.
   
       Args:
           query: The input query to process
   
       Returns:
           Processed result as string
       """
       # Your tool logic here
       return f"Processed: {query}"

2. Use with Agent

   from praisonaiagents import Agent
   
   agent = Agent(
       name="processor",
       role="Data Processor",
       tools=[my_tool]
   )
   
   result = agent.start("Process this data")
   print(result)

How to Create Tools with Multiple Parameters

1. Define Multi-Parameter Tool

   def search_tool(query: str, max_results: int = 10, language: str = "en") -> dict:
       """Search for information with options.
   
       Args:
           query: Search query
           max_results: Maximum number of results
           language: Language code
   
       Returns:
           Dictionary with search results
       """
       return {
           "query": query,
           "results": [f"Result {i}" for i in range(max_results)],
           "language": language
       }

2. Use with Agent

   from praisonaiagents import Agent
   
   agent = Agent(
       name="searcher",
       role="Search Agent",
       tools=[search_tool]
   )
   
   result = agent.start("Search for AI news")
   print(result)

How to Create Tools as Classes

1. Define Tool Class

   class DatabaseTool:
       """Tool for database operations."""
   
       def __init__(self, connection_string: str):
           self.connection = connection_string
   
       def query(self, sql: str) -> list:
           """Execute SQL query.
   
           Args:
               sql: SQL query string
   
           Returns:
               List of results
           """
           # Database logic here
           return [{"id": 1, "data": "example"}]
   
       def insert(self, table: str, data: dict) -> bool:
           """Insert data into table.
   
           Args:
               table: Table name
               data: Data to insert
   
           Returns:
               Success status
           """
           return True

2. Use Class Methods as Tools

   from praisonaiagents import Agent
   
   db_tool = DatabaseTool("postgresql://localhost/mydb")
   
   agent = Agent(
       name="db_agent",
       role="Database Agent",
       tools=[db_tool.query, db_tool.insert]
   )

How to Create Async Tools

1. Define Async Tool

   import asyncio
   import aiohttp
   
   async def async_fetch_tool(url: str) -> str:
       """Fetch content from URL asynchronously.
   
       Args:
           url: URL to fetch
   
       Returns:
           Response content
       """
       async with aiohttp.ClientSession() as session:
           async with session.get(url) as response:
               return await response.text()

2. Use with Async Agent

   from praisonaiagents import Agent
   
   agent = Agent(
       name="fetcher",
       role="Web Fetcher",
       tools=[async_fetch_tool]
   )
   
   # Run async
   result = await agent.astart("Fetch https://example.com")

How to Use Optional, Literal, and Enum Parameters

1. Create Tool with Choice Parameters

   from typing import Optional, Literal
   from enum import Enum
   from praisonaiagents import Agent, tool
   
   class Priority(str, Enum):
       LOW = "low"
       MEDIUM = "medium"
       HIGH = "high"
   
   @tool
   def create_task(
       title: str,
       priority: Priority = Priority.MEDIUM,
       deadline: Optional[str] = None,
       mode: Literal["draft", "active"] = "draft"
   ) -> str:
       """Create a task with flexible parameters."""
       result = f"Task '{title}' created with priority: {priority.value}, mode: {mode}"
       if deadline:
           result += f", deadline: {deadline}"
       return result
   
   agent = Agent(
       instructions="You manage tasks",
       tools=[create_task]
   )
   
   agent.start("Create a high priority task with deadline tomorrow")

See the Tool Parameter Types page for complete reference on using Optional, Union, Literal, Enum, List, and Dict types.

Tool Function Requirements

Best Practices

Related