Agent Tools

Understanding how tools extend agent capabilities

Tools give your agents superpowers. Without tools, agents can only chat. With tools, they can search, calculate, and interact with the world.

---

Quick Start

from praisonaiagents import Agent

# Define a tool (any Python function)
def calculate(expression: str) -> str:
    """Calculate a math expression"""
    return str(eval(expression))

# Give the tool to your agent
agent = Agent(
    instructions="You help with math problems",
    tools=[calculate]
)

agent.start("What is 25 * 48?")

Any Python function can be a tool. Just add it to the tools list.

---

How Tools Work

---

Creating Tools

1. Write a Python Function

   def get_weather(city: str) -> str:
       """Get the weather for a city"""
       # Your logic here
       return f"Weather in {city}: Sunny, 72°F"
   
2. Add Type Hints

   # Type hints help the agent understand inputs/outputs
   def search_web(query: str, max_results: int = 5) -> str:
       """Search the web for information"""
       return f"Found {max_results} results for: {query}"
   
3. Add to Agent

   agent = Agent(
       instructions="You help users find information",
       tools=[get_weather, search_web]
   )
   

---

Built-in Tools

PraisonAI includes ready-to-use tools:

from praisonaiagents import Agent

# Web search (requires API key)
agent = Agent(
    instructions="Search and summarize",
    tools=["tavily"]  # or "duckduckgo", "you", "exa"
)

# Enable web search simply
agent = Agent(
    instructions="Research topics",
    web=True  # Built-in web search
)

Web Search

tools=["tavily"] or web=True

File Operations

Read, write, and manage files

Code Execution

Run Python code safely

MCP Tools

Connect to external services

---

Complete Example

from praisonaiagents import Agent

# Tool 1: Calculator
def calculate(expression: str) -> str:
    """Calculate a math expression"""
    try:
        return str(eval(expression))
    except:
        return "Error: Invalid expression"

# Tool 2: Unit converter
def convert_units(value: float, from_unit: str, to_unit: str) -> str:
    """Convert between units"""
    conversions = {
        ("km", "miles"): 0.621371,
        ("miles", "km"): 1.60934,
        ("kg", "lbs"): 2.20462,
        ("lbs", "kg"): 0.453592,
    }
    factor = conversions.get((from_unit, to_unit), 1)
    result = value * factor
    return f"{value} {from_unit} = {result:.2f} {to_unit}"

# Agent with multiple tools
agent = Agent(
    instructions="You help with math and unit conversions",
    tools=[calculate, convert_units]
)

agent.start("Convert 100 km to miles, then calculate 62 * 3")

---

Tool Best Practices

Add Docstrings

Describe what the tool does so the agent knows when to use it

Use Type Hints

def tool(x: str) -> str: helps the agent understand inputs

Handle Errors

Return helpful error messages instead of crashing

One Purpose

Each tool should do one thing well

---

MCP Tools (Advanced)

Connect to external services using Model Context Protocol:

from praisonaiagents import Agent, MCP

agent = Agent(
    instructions="Search the web",
    tools=MCP(
        command="npx",
        args=["-y", "@anthropic/mcp-server-brave-search"],
        env={"BRAVE_API_KEY": "your-key"}
    )
)

---

Next: Agent Memory

Learn how agents remember conversations.