Skip to main content
Tools give agents the ability to take actions — search the web, run code, read files, and call APIs — beyond what an LLM knows from training. 
from praisonaiagents import Agent
from praisonaiagents.tools import duckduckgo

agent = Agent(
    name="Researcher",
    instructions="You are a research assistant. Use web search for current information.",
    tools=[duckduckgo],
)

agent.start("What are the latest developments in fusion energy?")
The user asks a research question; the agent calls web search and returns an answer grounded in live results.

​
Quick Start

1

Built-in Tools

from praisonaiagents import Agent
from praisonaiagents.tools import duckduckgo

agent = Agent(
    instructions="Search the web to answer questions.",
    tools=[duckduckgo],
)
agent.start("What is today's top AI news?")
2

Custom Tool Function

from praisonaiagents import Agent

def get_stock_price(ticker: str) -> str:
    """Get the current stock price for a ticker symbol."""
    return f"${ticker}: $150.25 (mock data)"

agent = Agent(
    instructions="You are a finance assistant.",
    tools=[get_stock_price],
)
agent.start("What is the current price of AAPL?")
3

Multiple Tools

from praisonaiagents import Agent
from praisonaiagents.tools import duckduckgo, wikipedia

agent = Agent(
    instructions="You are a comprehensive research assistant.",
    tools=[duckduckgo, wikipedia],
)
agent.start("Research the history and current state of quantum computing.")

​
Which Tools to Use?

​
How It Works

PhaseWhat happens
1. DiscoverAgent receives tool definitions alongside the user request
2. DecideLLM chooses whether to call a tool
3. ExecuteAgent runs the tool and captures the result
4. SynthesizeLLM uses the tool result to form the final answer

​
Common Patterns

​
Pattern 1 — Web research agent

from praisonaiagents import Agent
from praisonaiagents.tools import duckduckgo, wikipedia

agent = Agent(
    name="Researcher",
    instructions="You research topics using web search and Wikipedia.",
    tools=[duckduckgo, wikipedia],
)
response = agent.start("Explain the history of the Internet Protocol (TCP/IP).")
print(response)

​
Pattern 2 — Custom API tool

from praisonaiagents import Agent

def get_weather(city: str) -> str:
    """Fetch the current weather for a given city."""
    return f"{city}: 22°C, sunny (mock)"

def get_forecast(city: str, days: int = 3) -> str:
    """Get weather forecast for a city for the next N days."""
    return f"{city}: sunny for {days} days (mock)"

agent = Agent(
    instructions="You are a weather assistant.",
    tools=[get_weather, get_forecast],
)
agent.start("What's the weather in Paris and will it rain this week?")

​
Pattern 3 — Tool search for large toolsets

from praisonaiagents import Agent

agent = Agent(
    instructions="You have access to many tools. Use them as needed.",
    tools=[...],
    tool_search=True,
)
agent.start("Find the best tool for calculating compound interest.")

​
Best Practices

The LLM reads your tool’s docstring to decide when and how to use it. Write clear, specific descriptions: “Fetch the current stock price for a given ticker symbol (e.g., ‘AAPL’, ‘GOOGL’). Returns price in USD.”
Tools should return strings (or JSON-serializable data that gets converted to strings). Complex objects confuse the LLM — format results as readable text.
When you have more than 10–15 tools, enable tool_search=True to let the agent dynamically find the right tools instead of sending all tool definitions with every request.
Wrap external API calls with timeouts using ToolConfig(timeout=30). Without timeouts, a slow API can block the entire agent run.

Tool Config — timeouts, retries, and artifact storage

Tool Search — dynamic tool discovery for large toolsets