Assign Tools to Templates

Step-by-step guide to assigning and configuring tools in templates

Wire built-in or custom tools into template manifests so agents can call them at runtime.

from praisonaiagents import Agent, tool

@tool
def status_lookup(id: str) -> str:
    """Return item status."""
    return f"Status for {id}: ready"

agent = Agent(name="Template Agent", tools=[status_lookup])
agent.start("Check status for item 99.")

The user declares tools in YAML, assigns them to roles, and runs the template with those capabilities.

How It Works

---

How to Assign Built-in Tools

1. List Available Built-in Tools

   praisonai tools list
   
2. Add to TEMPLATE.yaml

   # TEMPLATE.yaml
   name: my-template
   version: "1.0.0"
   
   requires:
     tools:
       - internet_search
       - shell_tool
       - file_read_tool
   
3. Assign to Agents

   # agents.yaml
   roles:
     researcher:
       role: Research Agent
       tools:
         - internet_search
     executor:
       role: Executor Agent
       tools:
         - shell_tool
         - file_read_tool
   

How to Assign Custom Tools from tools.py

1. Create tools.py

   # tools.py
   def analyze_data(data: str) -> dict:
       """Analyze input data.
       
       Args:
           data: Data to analyze
           
       Returns:
           Analysis results
       """
       return {"analysis": "complete", "data": data}
   
2. Assign to Agent

   # agents.yaml
   roles:
     analyst:
       role: Data Analyst
       tools:
         - analyze_data
       tasks:
         analyze:
           description: "Analyze the provided data"
   
3. Run Template

   praisonai templates run ./my-template
   

How to Assign Tools from External Sources

1. Add tools_sources

   # TEMPLATE.yaml
   requires:
     tools_sources:
       - praisonai_tools.video
       - ./extra_tools.py
   
2. Assign External Tools

   # agents.yaml
   roles:
     video_editor:
       role: Video Editor
       tools:
         - shell_tool
       tasks:
         edit:
           description: |
             Use python -m praisonai_tools.video to edit videos
   

How to Assign Tools Dynamically with Python

1. Load Template

   from praisonai.templates.loader import TemplateLoader
   
   loader = TemplateLoader()
   template = loader.load_template("my-template")
   
2. Create Custom Tools

   def custom_tool(input: str) -> str:
       """Custom processing tool."""
       return f"Processed: {input}"
   
3. Run with Additional Tools

   result = template.run(
       task="Process data",
       additional_tools=[custom_tool]
   )
   

Best Practices

Assign only the tools a role needs

Listing the minimum tool set per role keeps the agent focused and avoids unintended actions.

Use descriptive tool names

Clear names help both the model and the reader understand what each assigned tool does at a glance.

Verify tools resolve before assigning

Run praisonai tools list (or doctor) so every name in the manifest actually resolves at runtime.

Group related tools together

Keeping related tools on the same role makes recipes easier to reason about and maintain.

---

Related

Create Custom Tools

Build the tools you assign

Debug Tools

Fix tools that fail to resolve