Skip to main content
Register built-in or custom tools on recipe agents so templates can act on real data. 
from praisonaiagents import Agent, tool

@tool
def lookup_order(order_id: str) -> str:
    """Look up order status."""
    return f"Order {order_id} is shipped."

agent = Agent(name="Support", tools=[lookup_order])
agent.start("Check order 12345.")
The user adds tools to YAML or Python templates, then runs the recipe with those capabilities enabled.

​
How It Works

​
How to Add Built-in Tools

1

List Available Tools

praisonai tools list
2

Add Tools to agents.yaml

# agents.yaml
framework: praisonai
topic: "{{task}}"

roles:
  researcher:
    role: Research Agent
    goal: Research topics thoroughly
    tools:
      - internet_search
      - shell_tool
      - file_read_tool
    tasks:
      search_task:
        description: "Search for {{topic}}"
3

Run Recipe

praisonai recipe run ./my-recipe --var topic="AI agents"

​
How to Add Custom Tools via tools.py

1

Create tools.py in Recipe Directory

# tools.py
def my_custom_tool(query: str) -> str:
    """Custom tool that processes a query.
    
    Args:
        query: The input query to process
        
    Returns:
        Processed result as string
    """
    return f"Processed: {query}"

def another_tool(data: str) -> dict:
    """Another custom tool.
    
    Args:
        data: Input data
        
    Returns:
        Dictionary with results
    """
    return {"result": data, "status": "success"}
2

Reference in agents.yaml

roles:
  processor:
    role: Data Processor
    tools:
      - my_custom_tool
      - another_tool
    tasks:
      process_task:
        description: "Process the data"
3

Run Recipe

praisonai recipe run ./my-recipe

​
Tool Resolution Order

PrioritySourceDescription
1tools.pyRecipe-local tools.py
2Built-inpraisonaiagents built-in tools
3Packagepraisonai_tools package

​
Best Practices

tools.py in the recipe directory wins resolution, so bundle recipe-specific tools there to keep them portable.
The agent reads the docstring to decide when and how to call a tool. Describe the arguments and return value so calls are accurate.
Give each role the minimum tool set in agents.yaml so the agent stays focused and avoids unintended actions.

Create Custom Recipes

Build a recipe from scratch

Debug Recipes

Troubleshoot tool resolution