Tools

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.

Tool turns are treated specially: a mid-response network failure surfaces provider_outcome_unknown instead of silently re-running the tool. See Replay-Safe Retries.

Quick Start

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?")

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?")

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

Phase	What happens
1. Discover	Agent receives tool definitions alongside the user request
2. Decide	LLM chooses whether to call a tool
3. Execute	Agent runs the tool and captures the result
4. Synthesize	LLM 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?")

Drop a @tool-decorated function into .praisonai/tools/*.py for auto-load with no imports required — see Project-local tools.

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.")

Pattern 4 — Gate a custom tool behind approval

from praisonaiagents import Agent, tool

@tool(approval=True)
def send_refund(order_id: str, amount: float) -> str:
    """Issue a refund on an order."""
    return f"Refunded {amount} for {order_id}"

agent = Agent(
    instructions="Help support agents process refunds.",
    tools=[send_refund],
)
agent.start("Refund $30 on order O-101")

Declare approval right on the @tool decorator — the agent pauses and asks a human before the tool runs. See Tool Approval.

Tool Approval

Declare a tool needs human sign-off in one line

Timeouts

Cap how long a tool may run with ToolConfig(timeout=...) — a stuck tool no longer hangs the agent.

from praisonaiagents import Agent, ToolConfig

agent = Agent(
    name="Runner",
    instructions="Call tools with a 10s ceiling.",
    tools=[my_slow_tool],
    tool_config=ToolConfig(timeout=10),
)

Since PraisonAI PR #3790, async tool calls (await agent.achat(...)) honour the timeout. A tool that exceeds the limit returns a result instead of hanging forever:

{"error": "Tool timed out after 10s", "timeout": True}

The timeout: True flag marks the call terminal, so it is not retried — the executor thread cannot be cancelled, so a retry would launch a duplicate DB write, API call, or file mutation. Timeout results are surfaced immediately, the same rule already applied to approval_denied, permission_denied, and circuit_open. The framework’s own retry verdict lives on a private _praison_retryable key that is stripped before the result reaches the model or the caller, so it never appears on the surfaced dict.A tool’s own result may include a field called retryable (common for HTTP-API wrappers). That field is the tool’s payload — it never drives the framework’s retry loop.

Best Practices

Write clear docstrings for custom tools

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.”

Return strings from tools

Tools should return strings (or JSON-serializable data that gets converted to strings). Complex objects confuse the LLM — format results as readable text.

Use tool_search for large toolsets

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.

Set timeouts for external tools

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

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Tools

Quick Start

Which Tools to Use?

How It Works

Common Patterns

Pattern 1 — Web research agent

Pattern 2 — Custom API tool

Pattern 3 — Tool search for large toolsets

Pattern 4 — Gate a custom tool behind approval

Tool Approval

Timeouts

Best Practices

​Quick Start

​Which Tools to Use?

​How It Works

​Common Patterns

​Pattern 1 — Web research agent

​Pattern 2 — Custom API tool

​Pattern 3 — Tool search for large toolsets

​Pattern 4 — Gate a custom tool behind approval

Tool Approval

​Timeouts

​Best Practices

​Related

Quick Start

Which Tools to Use?

How It Works

Common Patterns

Pattern 1 — Web research agent

Pattern 2 — Custom API tool

Pattern 3 — Tool search for large toolsets

Pattern 4 — Gate a custom tool behind approval

Timeouts

Best Practices

Related