Add Tools to Recipes

Step-by-step guide to adding and configuring tools in recipes

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

Priority	Source	Description
1	tools.py	Recipe-local tools.py
2	Built-in	praisonaiagents built-in tools
3	Package	praisonai_tools package

Best Practices

Prefer recipe-local tools.py for custom logic

tools.py in the recipe directory wins resolution, so bundle recipe-specific tools there to keep them portable.

Write clear docstrings on every tool

The agent reads the docstring to decide when and how to call a tool. Describe the arguments and return value so calls are accurate.

List only the tools a role needs

Give each role the minimum tool set in agents.yaml so the agent stays focused and avoids unintended actions.

---

Related

Create Custom Recipes

Build a recipe from scratch

Debug Recipes

Troubleshoot tool resolution