AI Agents with Tools - PraisonAI Documentation

Feature	Knowledge	Tools
Purpose	Static reference information	Dynamic interaction capabilities
Access	Read-only reference	Execute actions and commands
Updates	Manual through files	Real-time through tool calls
Storage	Knowledge base	Assigned to specific agents
Persistence	Permanent until changed	Available during agent execution

Quick Start

Tools are functions that agents can use to interact with external systems and perform actions. They are essential for creating agents that can do more than just process text.

Creating Custom Tool

Create any function that you want to use as a tool, that performs a specific task.

from duckduckgo_search import DDGS
from typing import List, Dict

# Tool Implementation
def internet_search_tool(query: str) -> List[Dict]:
    """
    Perform Internet Search using DuckDuckGo
    
    Args:
        query (str): The search query string
        
    Returns:
        List[Dict]: List of search results containing title, URL, and snippet
    """
    results = []
    ddgs = DDGS()
    for result in ddgs.text(keywords=query, max_results=5):
        results.append({
            "title": result.get("title", ""),
            "url": result.get("href", ""),
            "snippet": result.get("body", "")
        })
    return results

Assign the tool to an agent

    data_agent = Agent(
        name="DataCollector",
        role="Search Specialist",
        goal="Perform internet searches to collect relevant information.",
        backstory="Expert in finding and organising internet data.",
        tools=[internet_search_tool], ## Add the tool to the agent i.e the function name
    )

That's it!

You have created a custom tool and assigned it to an agent.

Implementing Tools Full Code Example

Install PraisonAI

Install the core package:

Terminal

pip install praisonaiagents duckduckgo-search

Configure Environment

Terminal

export OPENAI_API_KEY=your_openai_key

Generate your OpenAI API key from OpenAI Use other LLM providers like Ollama, Anthropic, Groq, Google, etc. Please refer to the Models for more information.

Create Agent with Tool

Create app.py

from praisonaiagents import Agent, Task, PraisonAIAgents
from duckduckgo_search import DDGS
from typing import List, Dict

# 1. Tool Implementation
def internet_search_tool(query: str) -> List[Dict]:
    """
    Perform Internet Search using DuckDuckGo
    
    Args:
        query (str): The search query string
        
    Returns:
        List[Dict]: List of search results containing title, URL, and snippet
    """
    results = []
    ddgs = DDGS()
    for result in ddgs.text(keywords=query, max_results=5):
        results.append({
            "title": result.get("title", ""),
            "url": result.get("href", ""),
            "snippet": result.get("body", "")
        })
    return results

# 2. Assign the tool to an agent
data_agent = Agent(
    name="DataCollector",
    role="Search Specialist",
    goal="Perform internet searches to collect relevant information.",
    backstory="Expert in finding and organising internet data.",
    tools=[internet_search_tool],
    self_reflect=False
)

# 3. Task Definition
collect_task = Task(
    description="Perform an internet search using the query: 'AI job trends in 2024'. Return results as a list of title, URL, and snippet.",
    expected_output="List of search results with titles, URLs, and snippets.",
    agent=data_agent,
    name="collect_data",
)

# 4. Start Agents
agents = PraisonAIAgents(
    agents=[data_agent],
    tasks=[collect_task],
    process="sequential"
)

agents.start()

Start Agents

Execute your script:

Terminal

python app.py

Install PraisonAI

Install the core package:

Terminal

pip install praisonaiagents duckduckgo-search

Configure Environment

Terminal

export OPENAI_API_KEY=your_openai_key

Generate your OpenAI API key from OpenAI Use other LLM providers like Ollama, Anthropic, Groq, Google, etc. Please refer to the Models for more information.

Create Agent with Tool

Create app.py

from praisonaiagents import Agent, Task, PraisonAIAgents
from duckduckgo_search import DDGS
from typing import List, Dict

# 1. Tool Implementation
def internet_search_tool(query: str) -> List[Dict]:
    """
    Perform Internet Search using DuckDuckGo
    
    Args:
        query (str): The search query string
        
    Returns:
        List[Dict]: List of search results containing title, URL, and snippet
    """
    results = []
    ddgs = DDGS()
    for result in ddgs.text(keywords=query, max_results=5):
        results.append({
            "title": result.get("title", ""),
            "url": result.get("href", ""),
            "snippet": result.get("body", "")
        })
    return results

# 2. Assign the tool to an agent
data_agent = Agent(
    name="DataCollector",
    role="Search Specialist",
    goal="Perform internet searches to collect relevant information.",
    backstory="Expert in finding and organising internet data.",
    tools=[internet_search_tool],
    self_reflect=False
)

# 3. Task Definition
collect_task = Task(
    description="Perform an internet search using the query: 'AI job trends in 2024'. Return results as a list of title, URL, and snippet.",
    expected_output="List of search results with titles, URLs, and snippets.",
    agent=data_agent,
    name="collect_data",
)

# 4. Start Agents
agents = PraisonAIAgents(
    agents=[data_agent],
    tasks=[collect_task],
    process="sequential"
)

agents.start()

Start Agents

Execute your script:

Terminal

python app.py

Install PraisonAI

Install the core package and duckduckgo_search package:

Terminal

pip install praisonai duckduckgo_search

Create Custom Tool

To add additional tools/features you need some coding which can be generated using ChatGPT or any LLM

Create a new file tools.py with the following content:

from duckduckgo_search import DDGS
from typing import List, Dict

# 1. Tool
def internet_search_tool(query: str) -> List[Dict]:
    """
    Perform Internet Search
    """
    results = []
    ddgs = DDGS()
    for result in ddgs.text(keywords=query, max_results=5):
        results.append({
            "title": result.get("title", ""),
            "url": result.get("href", ""),
            "snippet": result.get("body", "")
        })
    return results

Create Agent

Create a new file agents.yaml with the following content:

framework: praisonai
topic: create movie script about cat in mars
roles:
  scriptwriter:
    backstory: Expert in dialogue and script structure, translating concepts into
      scripts.
    goal: Write a movie script about a cat in Mars
    role: Scriptwriter
    tools:
      - internet_search_tool # <-- Tool assigned to Agent here
    tasks:
      scriptwriting_task:
        description: Turn the story concept into a production-ready movie script,
          including dialogue and scene details.
        expected_output: Final movie script with dialogue and scene details.

Start Agents

Execute your script:

Terminal

praisonai agents.yaml

In-build Tools in PraisonAI

Search Tools

Tools for searching and retrieving information from various sources

Python Tools

Essential Python utilities for data manipulation and scripting

Spider Tools

Web crawling and scraping capabilities for data extraction

Arxiv Tools

Access and search academic papers from arXiv repository

Newspaper Tools

Extract and parse content from news articles and websites

DuckDB Tools

Fast analytical SQL database operations and queries

DuckDuckGo Tools

Web search functionality using DuckDuckGo’s API

Calculator Tools

Perform mathematical calculations and conversions

YAML Tools

Parse and manipulate YAML format data

JSON Tools

Handle JSON data structures and operations

Pandas Tools

Data analysis and manipulation using Pandas

YFinance Tools

Fetch financial market data from Yahoo Finance

Shell Tools

Execute shell commands and system operations

Wikipedia Tools

Access and search Wikipedia articles and data

XML Tools

Process and manipulate XML format data

File Tools

File system operations and management utilities

Excel Tools

Work with Excel spreadsheets and workbooks

CSV Tools

Handle CSV file operations and transformations

Tools Overview

Search Tools

Tools for searching and retrieving information from various sources

File Tools

Tools for reading, writing, and manipulating files

API Tools

Tools for interacting with external APIs and services

Advanced Tool Features

Tool Configuration

def configured_tool(
    query: str,
    max_results: int = 5,
    timeout: int = 10
) -> List[Dict]:
    """
    Example of a configurable tool
    
    Args:
        query (str): Search query
        max_results (int): Maximum number of results
        timeout (int): Request timeout in seconds
        
    Returns:
        List[Dict]: Search results
    """
    # Tool implementation
    pass

Tool Chaining

def chain_tools(input_data: str) -> Dict:
    """
    Example of chaining multiple tools
    
    Args:
        input_data (str): Input data
        
    Returns:
        Dict: Processed results
    """
    # 1. Search for data
    search_results = internet_search_tool(input_data)
    
    # 2. Process results
    processed_data = process_tool(search_results)
    
    # 3. Format output
    return format_tool(processed_data)

Tool Categories

Data Collection Tools

Web scraping
API integration
Database queries

Processing Tools

Data transformation
Text analysis
Image processing

Output Tools

File generation
Report creation
Data visualization

Tool Integration

Adding Tools to Agents

# Multiple tools
agent = Agent(
    name="MultiTool Agent",
    tools=[
        internet_search_tool,
        file_processing_tool,
        api_integration_tool
    ]
)

Tool Dependencies

# Tool with dependencies
def advanced_tool(data: Dict) -> Dict:
    """
    Tool that depends on external libraries
    
    Args:
        data (Dict): Input data
        
    Returns:
        Dict: Processed data
    """
    try:
        import required_library
        # Tool implementation
        return processed_result
    except ImportError:
        raise Exception("Required library not installed")

Tool Guidelines

Best Practices

Type Hints
- Use Python type hints
- Define clear input/output types
- Document complex types
Documentation
- Write clear docstrings
- Explain parameters
- Provide usage examples
Error Handling
- Handle exceptions gracefully
- Return meaningful errors
- Validate inputs

Tool Types

Search Tools
- Web search
- Database queries
- Document search
File Tools
- Read/write operations
- File conversion
- Data extraction
API Tools
- REST API calls
- GraphQL queries
- Service integration

Best Practices Summary

Following these best practices will help you create robust, efficient, and secure tools in PraisonAI.

Design Principles

Single Responsibility

Each tool should have one clear purpose and do it well. Avoid creating tools that try to do too many things.

# Good Example
def process_image(image: np.array) -> np.array:
    return processed_image

# Avoid
def process_and_save_and_upload(image):
    # Too many responsibilities
    pass

Clear Interfaces

Define explicit input/output types and maintain consistent parameter naming.

def search_tool(
    query: str,
    max_results: int = 10
) -> List[Dict[str, Any]]:
    """
    Search for information with clear parameters
    """
    pass

Documentation

Always include detailed docstrings and type hints.

def analyze_text(
    text: str,
    language: str = "en"
) -> Dict[str, float]:
    """
    Analyze text sentiment and emotions.
    
    Args:
        text: Input text to analyze
        language: ISO language code
        
    Returns:
        Dict with sentiment scores
    """
    pass

Performance Optimization

Efficient Processing

Resource Management

Caching

Async Operations

Use async/await for I/O-bound operations.

async def fetch_data(urls: List[str]):
    async with aiohttp.ClientSession() as session:
        tasks = [fetch_url(session, url) for url in urls]
        return await asyncio.gather(*tasks)

Security Best Practices

Input Validation

Always validate and sanitize inputs to prevent security vulnerabilities.

def process_user_input(data: str) -> str:
    if not isinstance(data, str):
        raise ValueError("Input must be string")
    return sanitize_input(data.strip())

Rate Limiting

API Key Management

Error Masking

Hide sensitive information in error messages to prevent information leakage.

try:
    result = process_sensitive_data()
except Exception as e:
    # Log detailed error internally
    logger.error(f"Detailed error: {str(e)}")
    # Return sanitized error to user
    raise PublicError("Processing failed")

Pro Tip: Start with these practices from the beginning of your project. It’s easier to maintain good practices than to retrofit them later.

Process Memory

On this page

Quick Start
Creating Custom Tool
Implementing Tools Full Code Example
In-build Tools in PraisonAI
Tools Overview
Advanced Tool Features
Tool Configuration
Tool Chaining
Tool Categories
Tool Integration
Adding Tools to Agents
Tool Dependencies
Tool Guidelines
Best Practices Summary

Getting Started

Core Concepts

Workflows

Features

Models

Tools

Other Features

Monitoring

Developers

Getting Started (No Code)

API Reference

​Quick Start

​Creating Custom Tool

That's it!

​Implementing Tools Full Code Example

​In-build Tools in PraisonAI

Search Tools

Python Tools

Spider Tools

Arxiv Tools

Newspaper Tools

DuckDB Tools

DuckDuckGo Tools

Calculator Tools

YAML Tools

JSON Tools

Pandas Tools

YFinance Tools

Shell Tools

Wikipedia Tools

XML Tools

File Tools

Excel Tools

CSV Tools

​Tools Overview

Search Tools

File Tools

API Tools

​Advanced Tool Features

​Tool Configuration

​Tool Chaining

​Tool Categories

Data Collection Tools

Processing Tools

Output Tools

​Tool Integration

​Adding Tools to Agents

​Tool Dependencies

​Tool Guidelines

Best Practices

Tool Types

​Best Practices Summary

Design Principles

Performance Optimization

Security Best Practices

Quick Start

Creating Custom Tool

Implementing Tools Full Code Example

In-build Tools in PraisonAI

Tools Overview

Advanced Tool Features

Tool Configuration

Tool Chaining

Tool Categories

Tool Integration

Adding Tools to Agents

Tool Dependencies

Tool Guidelines

Best Practices Summary