AI Agents with Tools

Learn how to create AI agents that can use tools to interact with external systems and perform actions.

Diagram

python

from praisonaiagents import Agent

def search(query: str) -> str:
    return f"Results for {query}"

agent = Agent(name="Assistant", tools=[search])
agent.start("Search for Python 3.13 release notes")

The user assigns tools to an agent; the model chooses tool calls to complete the task.

Diagram

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.

Simple Usage
Use the Code tab below to attach a tool to an agent.
With Configuration
Combine multiple tools and providers — see the YAML and CLI tabs.

Code

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

Single Agent

from praisonaiagents import Agent
from duckduckgo_search import DDGS

# 1. Define the tool
def internet_search_tool(query: str):
    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
search_agent = Agent(
    instructions="Perform internet searches to collect relevant information.",
    tools=[internet_search_tool] # <--- Tool Assignment
)

# 3. Start Agent
search_agent.start("Search about AI job trends in 2025")

Multiple Agents

from praisonaiagents import Agent, AgentTeam
from duckduckgo_search import DDGS

# 1. Define the tool
def internet_search_tool(query: str):
    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
search_agent = Agent(
    instructions="Search about AI job trends in 2025",
    tools=[internet_search_tool] # <--- Tool Assignment
)

blog_agent = Agent(
    instructions="Write a blog article based on the previous agent's search results."
)

# 3. Start Agents
agents = AgentTeam(agents=[search_agent, blog_agent])
agents.start()

Start Agents
Execute your script:
Terminal
```
python app.py
```

No Code

Install PraisonAI
Install the core package and duckduckgo_search package:
Terminal
```
pip install praisonai duckduckgo_search
```

Create Custom Tool

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

python

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:

yaml

framework: praisonai
topic: create movie script about cat in mars
agents:  # Canonical: use 'agents' instead of 'roles'
  scriptwriter:
    instructions: Expert in dialogue and script structure, translating concepts into
      scripts.  # Canonical: use 'instructions' instead of 'backstory'
    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
```

Creating Custom Tool

Step

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

python

from duckduckgo_search import DDGS

def internet_search_tool(query: str):
    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

Step

Assign the tool to an agent

python

data_agent = Agent(
    instructions="Search about AI job trends in 2025",
    tools=[internet_search_tool], # <-- Tool Assignment
)

That's it!

Creating Custom Tool with Detailed Instructions

Code

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

python

from praisonaiagents import Agent, Task, AgentTeam
from duckduckgo_search import DDGS

# 1. Tool Implementation
def internet_search_tool(query: str):
    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],
    reflection=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 = AgentTeam(
    agents=[data_agent],
    tasks=[collect_task],
    process="sequential"
)

agents.start()

Start Agents
Execute your script:
Terminal
```
python app.py
```

No Code

Install PraisonAI
Install the core package and duckduckgo_search package:
Terminal
```
pip install praisonai duckduckgo_search
```

Create Custom Tool

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

python

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:

yaml

framework: praisonai
topic: create movie script about cat in mars
agents:  # Canonical: use 'agents' instead of 'roles'
  scriptwriter:
    instructions:  # Canonical: use 'instructions' instead of '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
```

MCP Tools (Model Context Protocol)

MCP allows agents to use external tools via standardized protocols. This is the recommended way to add powerful tools to your agents.

python

from praisonaiagents import Agent, MCP

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

agent.start("Search for AI trends in 2025")

MCP Overview

Introduction to Model Context Protocol

MCP Transports

stdio, HTTP, WebSocket, and SSE transports

Built-in Search Tools

PraisonAI includes built-in search tools that work with multiple providers:

python

from praisonaiagents import Agent

# Tavily Search (recommended)
agent = Agent(
    instructions="Search and analyze information",
    tools=["tavily"]  # Requires TAVILY_API_KEY
)

# You.com Search
agent = Agent(
    instructions="Search the web",
    tools=["you"]  # Requires YOU_API_KEY
)

# Exa Search
agent = Agent(
    instructions="Find relevant content",
    tools=["exa"]  # Requires EXA_API_KEY
)

Tavily

AI-optimized search with web search, news, and content extraction

You.com

Web search with AI-powered results

Exa

Neural search for finding similar content

Fast Context (Code Search)

Fast Context provides parallel, cached code search for AI agents:

python

from praisonaiagents import Agent, FastContext

# Create agent with context management
agent = Agent(
    instructions="You are a code assistant",
    context=True,  # Enable context management
)

# Use FastContext directly for code search
fc = FastContext(workspace_path="/path/to/codebase")
result = fc.search("find authentication handlers")
context = result.to_context_string() if result.files else None

Fast Context

Rapid parallel code search with caching and multi-language support

In-build Tools in PraisonAI

Search Tools

Tools for searching and retrieving information from various sources

Tavily Tools

AI-optimized web search, news, and content extraction

You.com Tools

Web search with AI-powered results

Exa Tools

Neural search for finding similar content

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

SearxNG Tools

Privacy-focused web search using local SearxNG instance

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

AST-Grep Tools

AST-based structural code search and rewrite

LSP Tools

Language-server-accurate go-to-definition, find-references, and symbol search

Search Tools (grep/glob)

Fast, capped grep and glob built-ins for code-searching agents

Computer Use Tools

Agent-controlled screen: screenshots, mouse, keyboard, and scroll — gated by an approval callback

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

python

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

python

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

python

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

Tool Dependencies

python

# 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

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.

python

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

python

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.

python

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

Optimize resource usage and processing time.

python

# Use generators for large datasets
def process_large_data():
    for chunk in data_generator():
        yield process_chunk(chunk)

Resource Management

Properly handle resource allocation and cleanup.

python

async with aiohttp.ClientSession() as session:
    # Resource automatically managed
    await process_data(session)

Caching

Implement caching for frequently accessed data.

python

@cache.memoize(timeout=300)
def expensive_operation(data: str) -> Dict:
    return process_expensive(data)

Async Operations

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

python

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.

python

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

Implement rate limiting for API calls to prevent abuse.

python

@rate_limit(calls=100, period=60)
async def api_call():
    return await make_request()

API Key Management

Securely handle API keys and credentials using environment variables.

python

# Use environment variables
api_key = os.getenv('API_KEY')
if not api_key:
    raise ConfigError("API key not found")

Error Masking

Hide sensitive information in error messages to prevent information leakage.

python

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

Tool Packages Architecture

PraisonAI tools are organized into two packages for optimal performance and flexibility:

┌─────────────────────────────────────────────────┐
│                  YOUR CODE                       │
│  from praisonaiagents import Agent              │
│  from praisonai_tools import read_json          │  ← Extended Tools
│  from praisonaiagents import tavily             │  ← Core Tools
└─────────────────────────────────────────────────┘
                    │
       ┌────────────┴────────────┐
       ▼                         ▼
┌──────────────────┐    ┌──────────────────────┐
│  praisonaiagents │    │    praisonai-tools   │
│  (Core SDK)      │    │    (Extended Tools)  │
├──────────────────┤    ├──────────────────────┤
│ 21 Core Tools    │    │ 135+ Specialized     │
│ - Search         │    │ - JSON/YAML/XML/CSV  │
│ - Scraping       │    │ - Calculator         │
│ - File/Shell     │    │ - arXiv/Wikipedia    │
│ - Python Execute │    │ - YFinance/DuckDB    │
│ - Skill Tools    │    │ - Email/Slack/GitHub │
│ - CoT Training   │    │ - All heavy deps     │
└──────────────────┘    └──────────────────────┘
       │                         │
       │  Lightweight            │  Optional Install
       │  ~0.23s import time     │  pip install praisonai-tools
       ▼                         ▼
┌──────────────────────────────────────────────────┐
│              Agent(tools=[...])                   │
│  Unified tool interface - works with both        │
└──────────────────────────────────────────────────┘

Package Installation

Core Tools Only

bash

# Lightweight - includes search, scraping, file/shell tools
pip install praisonaiagents

Included Tools:

Search: tavily, exa, duckduckgo, searxng, web_search
Scraping: crawl4ai, spider_tools
Utilities: file_tools, shell_tools, python_tools, ast_grep_tools, computer_tools, lsp_definition, lsp_references, lsp_hover, lsp_document_symbols, lsp_workspace_symbols
Training: cot_save, cot_upload_to_huggingface

Extended Tools

bash

# Full toolkit - includes all specialized tools
pip install praisonaiagents praisonai-tools

Additional Tools:

Data: read_json, read_yaml, read_xml, read_csv, read_excel
Research: search_arxiv, wikipedia_search
Finance: yfinance, calculate, duckdb_query
Integrations: EmailTool, SlackTool, GitHubTool, NotionTool

Wrapper with Tools

bash

# Via wrapper (includes praisonai-tools automatically)
pip install "praisonai-frameworks[crewai]"
# or
pip install "praisonai-frameworks[autogen]"

Import Patterns

Core Tools (from praisonaiagents)

from praisonaiagents import Agent
from praisonaiagents import tavily, exa_search, duckduckgo
from praisonaiagents import crawl4ai, spider_tools
from praisonaiagents import read_file, write_file, execute_command
from praisonaiagents import cot_save, cot_upload_to_huggingface

agent = Agent(
    instructions="Search the web",
    tools=[tavily, crawl4ai]
)

Extended Tools (from praisonai_tools)

from praisonaiagents import Agent
from praisonai_tools import read_json, write_json, validate_json
from praisonai_tools import read_csv, read_excel, read_yaml
from praisonai_tools import search_arxiv, wikipedia_search
from praisonai_tools import EmailTool, SlackTool, GitHubTool

agent = Agent(
    instructions="Process JSON data",
    tools=[read_json, write_json]
)

Core Tools Reference

Search Tools

Package: praisonaiagents – tavily, tavily_search, tavily_extract – exa, exa_search, exa_search_contents – duckduckgo, internet_search – searxng_search – search_web (auto-fallback)

Scraping Tools

Package: praisonaiagents – crawl4ai, crawl4ai_extract – spider_tools, scrape_page, extract_links

File/Shell Tools

Package: praisonaiagents – read_file, write_file, list_files – execute_command, list_processes – execute_code, analyze_code

Training Tools

Package: praisonaiagents – cot_save, cot_upload_to_huggingface – cot_generate, cot_improve

Screen Control Tools

Package: praisonaiagents – computer_screenshot, computer_screen_size – computer_move, computer_click, computer_scroll – computer_type, computer_key – set_computer_approval (register the human-in-the-loop gate)

Extended Tools Reference

Data Format Tools

Package: praisonai-tools – read_json, write_json, validate_json – read_yaml, write_yaml, validate_yaml – read_xml, write_xml, transform_xml – read_csv, write_csv, merge_csv – read_excel, write_excel, merge_excel

Research Tools

Package: praisonai-tools – search_arxiv, get_arxiv_paper – wikipedia_search – pubmed_search

Finance/Analytics

Package: praisonai-tools – get_stock_price (YFinance) – calculate, solve_equation – duckdb_query, pandas_read_csv

Integration Tools

Package: praisonai-tools – EmailTool, SlackTool, DiscordTool – GitHubTool, NotionTool, TrelloTool – PostgresTool, MongoDBTool, RedisTool

Tool Security & Collision Prevention

Custom Tools

Build your own agent tools

Tools Overview

Browse PraisonAI tool documentation

Registry Proxy

Call hundreds of API endpoints through one token

AI Agents with Tools

Quick Start

Code

No Code

Creating Custom Tool

Creating Custom Tool with Detailed Instructions

Code

No Code

MCP Tools (Model Context Protocol)

Built-in Search Tools

Fast Context (Code Search)

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

Tool Packages Architecture

Package Installation

Core Tools Only

Extended Tools

Wrapper with Tools

Import Patterns

Core Tools Reference

Extended Tools Reference

Tool Security & Collision Prevention

Related