> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Agents with Tools
> Learn how to create AI agents that can use tools to interact with external systems and perform actions.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart TB
subgraph Tools
direction TB
T3[Internet Search]
T1[Code Execution]
T2[Formatting]
end
Input[Input] ---> Agents
subgraph Agents
direction LR
A1[Agent 1]
A2[Agent 2]
A3[Agent 3]
end
Agents ---> Output[Output]
T3 --> A1
T1 --> A2
T2 --> A3
style Tools fill:#189AB4,color:#fff
style Agents fill:#8B0000,color:#fff
style Input fill:#8B0000,color:#fff
style Output fill:#8B0000,color:#fff
```
| Feature | [Knowledge](/concepts/knowledge) | [Tools](/concepts/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.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
)
```
You have created a custom tool and assigned it to an agent.
## Implementing Tools Full Code Example
Install the core package:
```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonaiagents duckduckgo-search
```
```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export OPENAI_API_KEY=your_openai_key
```
Generate your OpenAI API key from [OpenAI](https://platform.openai.com/api-keys)
Use other LLM providers like Ollama, Anthropic, Groq, Google, etc. Please refer to the [Models](/models) for more information.
Create `app.py`
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, AgentTeam
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],
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()
```
Execute your script:
```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
python app.py
```
Install the core package and duckduckgo\_search package:
```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai duckduckgo_search
```
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:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 a new file `agents.yaml` with the following content:
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
```
Execute your script:
```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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")
```
Introduction to Model Context Protocol
stdio, HTTP, WebSocket, and SSE transports
## Built-in Search Tools
PraisonAI includes built-in search tools that work with multiple providers:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
)
```
AI-optimized search with web search, news, and content extraction
Web search with AI-powered results
Neural search for finding similar content
## Fast Context (Code Search)
Fast Context provides rapid parallel code search for AI agents - 10-20x faster than traditional methods:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.context.fast import 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
```
Rapid parallel code search with caching and multi-language support
## In-build Tools in PraisonAI
Tools for searching and retrieving information from various sources
AI-optimized web search, news, and content extraction
Web search with AI-powered results
Neural search for finding similar content
Essential Python utilities for data manipulation and scripting
Web crawling and scraping capabilities for data extraction
Access and search academic papers from arXiv repository
Extract and parse content from news articles and websites
Fast analytical SQL database operations and queries
Web search functionality using DuckDuckGo's API
Privacy-focused web search using local SearxNG instance
Perform mathematical calculations and conversions
Parse and manipulate YAML format data
Handle JSON data structures and operations
Data analysis and manipulation using Pandas
Fetch financial market data from Yahoo Finance
Execute shell commands and system operations
AST-based structural code search and rewrite
Access and search Wikipedia articles and data
Process and manipulate XML format data
File system operations and management utilities
Work with Excel spreadsheets and workbooks
Handle CSV file operations and transformations
## Tools Overview
Tools for searching and retrieving information from various sources
Tools for reading, writing, and manipulating files
Tools for interacting with external APIs and services
## Advanced Tool Features
### Tool Configuration
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
* Web scraping
* API integration
* Database queries
* Data transformation
* Text analysis
* Image processing
* File generation
* Report creation
* Data visualization
## Tool Integration
### Adding Tools to Agents
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Multiple tools
agent = Agent(
name="MultiTool Agent",
tools=[
internet_search_tool,
file_processing_tool,
api_integration_tool
]
)
```
### Tool Dependencies
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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
1. **Type Hints**
* Use Python type hints
* Define clear input/output types
* Document complex types
2. **Documentation**
* Write clear docstrings
* Explain parameters
* Provide usage examples
3. **Error Handling**
* Handle exceptions gracefully
* Return meaningful errors
* Validate inputs
1. **Search Tools**
* Web search
* Database queries
* Document search
2. **File Tools**
* Read/write operations
* File conversion
* Data extraction
3. **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.
Each tool should have one clear purpose and do it well. Avoid creating tools that try to do too many things.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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
```
Define explicit input/output types and maintain consistent parameter naming.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def search_tool(
query: str,
max_results: int = 10
) -> List[Dict[str, Any]]:
"""
Search for information with clear parameters
"""
pass
```
Always include detailed docstrings and type hints.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```
Optimize resource usage and processing time.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Use generators for large datasets
def process_large_data():
for chunk in data_generator():
yield process_chunk(chunk)
```
Properly handle resource allocation and cleanup.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
async with aiohttp.ClientSession() as session:
# Resource automatically managed
await process_data(session)
```
Implement caching for frequently accessed data.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
@cache.memoize(timeout=300)
def expensive_operation(data: str) -> Dict:
return process_expensive(data)
```
Use async/await for I/O-bound operations.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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)
```
Always validate and sanitize inputs to prevent security vulnerabilities.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def process_user_input(data: str) -> str:
if not isinstance(data, str):
raise ValueError("Input must be string")
return sanitize_input(data.strip())
```
Implement rate limiting for API calls to prevent abuse.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
@rate_limit(calls=100, period=60)
async def api_call():
return await make_request()
```
Securely handle API keys and credentials using environment variables.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Use environment variables
api_key = os.getenv('API_KEY')
if not api_key:
raise ConfigError("API key not found")
```
Hide sensitive information in error messages to prevent information leakage.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
## Forcing Tool Usage with tool\_choice
By default, LLMs may skip calling tools even when instructed. Use `tool_choice` to control this behavior.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
subgraph Behavior["tool_choice Options"]
A["auto"]:::manager --> A1["LLM decides"]
B["required"]:::manager --> B1["Must call tool"]
C["none"]:::manager --> C1["Cannot call tools"]
end
classDef manager fill:#189AB4,color:#fff,stroke:#189AB4
```
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents:
researcher:
role: Research Specialist
tools:
- search_web
tool_choice: required # Forces the agent to call a tool
llm: gpt-4o-mini
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.tools import search_web
# For direct Agent usage, tool_choice is passed via chat()
agent = Agent(
name="researcher",
tools=[search_web],
llm="gpt-4o-mini"
)
# Force tool usage in a specific call
response = agent.chat("Search for AI news", tool_choice="required")
```
Controls when the LLM calls tools:
* `auto` - LLM decides whether to call tools (default)
* `required` - LLM **must** call a tool before responding
* `none` - LLM cannot call tools (text response only)
Use `tool_choice: required` in YAML workflows when you need **guaranteed tool execution**. This is especially important for research agents that must search the web.
## Tool Profiles
Tool profiles are composable, named sets of tools that eliminate duplication across agent configurations. The SDK ships with built-in profiles that auto-sync to all consumers.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart TD
subgraph "SDK Core (praisonaiagents)"
P["tools/profiles.py"] --> |BUILTIN_PROFILES| A["agent.py autonomy"]
P --> |resolve_profiles| E["External consumers"]
TM["tools/__init__.py
TOOL_MAPPINGS"] --> |lazy __getattr__| R["Tool Resolution"]
end
subgraph "Consumers"
E --> AIUI["AIUI Provider"]
E --> CLI["CLI Interactive"]
E --> TUI["TUI App"]
E --> BOT["Bots"]
end
style P fill:#2d8a4e,stroke:#333,color:#fff
style AIUI fill:#2d8a4e,stroke:#333,color:#fff
style A fill:#2d8a4e,stroke:#333,color:#fff
style TM fill:#189AB4,stroke:#333,color:#fff
style R fill:#189AB4,stroke:#333,color:#fff
style BOT fill:#2d8a4e,stroke:#333,color:#fff
style CLI fill:#189AB4,stroke:#333,color:#fff
style TUI fill:#189AB4,stroke:#333,color:#fff
```
### Built-in Profiles
| Profile | Tools | Description |
| ------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `file_ops` | `read_file`, `write_file`, `list_files`, `copy_file`, `move_file`, `delete_file`, `get_file_info` | File system operations |
| `shell` | `execute_command`, `list_processes`, `get_system_info` | Shell and system tools |
| `web` | `internet_search`, `search_web`, `web_crawl` | Web search and crawling |
| `memory` | `store_memory`, `search_memory` | Active memory store/search |
| `learning` | `store_learning`, `search_learning` | Categorized knowledge store/search |
| `schedule` | `schedule_add`, `schedule_list`, `schedule_remove` | Agent-centric scheduling |
| `code_intelligence` | `ast_grep_search`, `ast_grep_rewrite`, `ast_grep_scan` | Structural code search |
| `code_exec` | `execute_code`, `analyze_code`, `format_code`, `lint_code` | Code execution and analysis |
| `autonomy` | All of the above combined | Default for autonomous agents |
### Using Profiles
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.tools.profiles import resolve_profiles
# Get tools from specific profiles
tool_names = resolve_profiles("file_ops", "web", "memory")
# Register custom profiles
from praisonaiagents.tools.profiles import register_profile, ToolProfile
register_profile(ToolProfile(
name="my_tools",
tools=["my_custom_tool"],
description="My custom tool set"
))
```