You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Welcome to the PraisonAI Tools directory! This guide will help you understand how our tools work and how to create new ones, whether you're a beginner or an experienced programmer.
4
+
5
+
## What is a Tool?
6
+
7
+
A tool is a piece of code that helps our AI agents perform specific tasks. Think of tools as special abilities that we give to our agents. For example:
8
+
- An internet search tool lets agents search the web
9
+
- A stock market tool lets agents check stock prices
10
+
- A weather tool lets agents check the weather
11
+
12
+
## Creating New Tools: The Two Approaches
13
+
14
+
### 1. Function-Based Approach (Simple Tools)
15
+
16
+
Best for simple tools that do one specific thing. Like a calculator that just adds numbers.
17
+
18
+
**When to use:**
19
+
- Tool does one simple task
20
+
- Doesn't need to remember information between uses
21
+
- Doesn't need to share information with other tools
22
+
- Quick, one-time operations
23
+
24
+
**Example:**
25
+
```python
26
+
definternet_search(query: str):
27
+
# Search the internet and return results
28
+
return search_results
29
+
```
30
+
31
+
**Usage:**
32
+
```python
33
+
from praisonaiagents.tools import internet_search
34
+
35
+
results = internet_search("AI news")
36
+
```
37
+
38
+
### 2. Class-Based Approach (Complex Tools)
39
+
40
+
Best for tools that do multiple related things or need to remember information. Like a smart calculator that remembers your previous calculations and can do many different math operations.
41
+
42
+
**When to use:**
43
+
- Tool has multiple related functions
44
+
- Needs to remember or share information
45
+
- Needs to manage resources efficiently
46
+
- Has complex setup requirements
47
+
48
+
**Example:**
49
+
```python
50
+
classStockTools:
51
+
defget_stock_price(self, symbol):
52
+
# Get current stock price
53
+
return price
54
+
55
+
defget_stock_info(self, symbol):
56
+
# Get detailed stock information
57
+
return info
58
+
```
59
+
60
+
**Usage:**
61
+
```python
62
+
from praisonaiagents.tools import get_stock_price, get_stock_info
63
+
64
+
price = get_stock_price("AAPL")
65
+
info = get_stock_info("AAPL")
66
+
```
67
+
68
+
## How to Choose Your Approach
69
+
70
+
Ask yourself these questions:
71
+
72
+
1.**Is your tool doing one simple thing?**
73
+
- Yes → Use Function-Based Approach
74
+
- No → Consider Class-Based Approach
75
+
76
+
2.**Does your tool need to remember information?**
77
+
- Yes → Use Class-Based Approach
78
+
- No → Use Function-Based Approach
79
+
80
+
3.**Are your tool's operations related to each other?**
81
+
- Yes → Use Class-Based Approach
82
+
- No → Use Function-Based Approach
83
+
84
+
4.**Does your tool need to manage resources efficiently?**
85
+
- Yes → Use Class-Based Approach
86
+
- No → Use Function-Based Approach
87
+
88
+
## Real-World Examples
89
+
90
+
### Internet Search Tool (Function-Based)
91
+
- Does one thing: searches the internet
92
+
- Doesn't need to remember previous searches
93
+
- Each search is independent
94
+
- Simple input/output operation
95
+
96
+
### Stock Market Tool (Class-Based)
97
+
- Does multiple things: check prices, get company info, get historical data
98
+
- Remembers stock information to avoid repeated downloads
99
+
- Operations are related (all about stocks)
100
+
- Manages connections efficiently
101
+
102
+
## Getting Started
103
+
104
+
1.**Choose Your Approach** based on the guidelines above
105
+
106
+
2.**Create Your Tool File**:
107
+
- Name it descriptively (e.g., `weather_tools.py`)
108
+
- Place it in the `praisonaiagents/tools` directory
109
+
110
+
3.**Write Your Tool**:
111
+
- Add clear documentation
112
+
- Include type hints for better understanding
113
+
- Handle errors gracefully
114
+
115
+
4.**Test Your Tool**:
116
+
- Make sure it works as expected
117
+
- Test error cases
118
+
- Check performance
119
+
120
+
## Best Practices
121
+
122
+
1.**Documentation**:
123
+
- Explain what your tool does
124
+
- Provide examples
125
+
- List any requirements
126
+
127
+
2.**Error Handling**:
128
+
- Always handle possible errors
129
+
- Return helpful error messages
130
+
- Don't let your tool crash
131
+
132
+
3.**Performance**:
133
+
- Keep it efficient
134
+
- Don't waste resources
135
+
- Cache when helpful
136
+
137
+
4.**User-Friendly**:
138
+
- Make it easy to use
139
+
- Use clear function/method names
140
+
- Keep it simple
141
+
142
+
## Need Help?
143
+
144
+
- Check existing tools for examples
145
+
- Ask in our community
146
+
- Read the documentation
147
+
- Don't hesitate to ask questions!
148
+
149
+
Remember: The goal is to make tools that are easy to use and maintain. Choose the approach that makes the most sense for your specific tool's needs.
0 commit comments