Skip to content

Commit c881fb3

Browse files
MervinPraisonMervinPraison
authored
Merge pull request MervinPraison#408 from MervinPraison/develop
Refactor tools documentation with comprehensive examples and improved…
2 parents f431347 + 15f9cbb commit c881fb3

1 file changed

Lines changed: 162 additions & 28 deletions

File tree

‎docs/tools/tools.mdx‎

Lines changed: 162 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -45,25 +45,172 @@ flowchart TB
4545

4646
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.
4747

48-
## Creating Custom Tool
48+
<Tabs>
49+
50+
<Tab title="Code">
4951
<Steps>
50-
<Step>
51-
Create any function that you want to use as a tool, that performs a specific task.
52+
53+
<Step title="Install PraisonAI">
54+
Install the core package:
55+
```bash Terminal
56+
pip install praisonaiagents duckduckgo-search
57+
```
58+
</Step>
59+
60+
<Step title="Configure Environment">
61+
```bash Terminal
62+
export OPENAI_API_KEY=your_openai_key
63+
```
64+
Generate your OpenAI API key from [OpenAI](https://platform.openai.com/api-keys)
65+
Use other LLM providers like Ollama, Anthropic, Groq, Google, etc. Please refer to the [Models](/models) for more information.
66+
</Step>
67+
68+
<Step title="Create Agent with Tool">
69+
Create `app.py`
70+
<CodeGroup>
71+
```python Single Agent
72+
from praisonaiagents import Agent
73+
from duckduckgo_search import DDGS
74+
75+
# 1. Define the tool
76+
def internet_search_tool(query: str):
77+
results = []
78+
ddgs = DDGS()
79+
for result in ddgs.text(keywords=query, max_results=5):
80+
results.append({
81+
"title": result.get("title", ""),
82+
"url": result.get("href", ""),
83+
"snippet": result.get("body", "")
84+
})
85+
return results
86+
87+
# 2. Assign the tool to an agent
88+
search_agent = Agent(
89+
instructions="Perform internet searches to collect relevant information.",
90+
tools=[internet_search_tool] # <--- Tool Assignment
91+
)
92+
93+
# 3. Start Agent
94+
search_agent.start("Search about AI job trends in 2025")
95+
```
96+
97+
```python Multiple Agents
98+
from praisonaiagents import Agent, PraisonAIAgents
99+
from duckduckgo_search import DDGS
100+
101+
# 1. Define the tool
102+
def internet_search_tool(query: str):
103+
results = []
104+
ddgs = DDGS()
105+
for result in ddgs.text(keywords=query, max_results=5):
106+
results.append({
107+
"title": result.get("title", ""),
108+
"url": result.get("href", ""),
109+
"snippet": result.get("body", "")
110+
})
111+
return results
112+
113+
# 2. Assign the tool to an agent
114+
search_agent = Agent(
115+
instructions="Search about AI job trends in 2025",
116+
tools=[internet_search_tool] # <--- Tool Assignment
117+
)
118+
119+
blog_agent = Agent(
120+
instructions="Write a blog article based on the previous agent's search results."
121+
)
122+
123+
# 3. Start Agents
124+
agents = PraisonAIAgents(agents=[search_agent, blog_agent])
125+
agents.start()
126+
```
127+
</CodeGroup>
128+
</Step>
129+
130+
<Step title="Start Agents">
131+
Execute your script:
132+
```bash Terminal
133+
python app.py
134+
```
135+
</Step>
136+
</Steps>
137+
138+
</Tab>
139+
<Tab title="No Code">
140+
<Steps>
141+
<Step title="Install PraisonAI">
142+
Install the core package and duckduckgo_search package:
143+
```bash Terminal
144+
pip install praisonai duckduckgo_search
145+
```
146+
</Step>
147+
<Step title="Create Custom Tool">
148+
<Info>
149+
To add additional tools/features you need some coding which can be generated using ChatGPT or any LLM
150+
</Info>
151+
Create a new file `tools.py` with the following content:
52152
```python
53153
from duckduckgo_search import DDGS
54154
from typing import List, Dict
55155

56-
# Tool Implementation
156+
# 1. Tool
57157
def internet_search_tool(query: str) -> List[Dict]:
58158
"""
59-
Perform Internet Search using DuckDuckGo
60-
61-
Args:
62-
query (str): The search query string
63-
64-
Returns:
65-
List[Dict]: List of search results containing title, URL, and snippet
159+
Perform Internet Search
66160
"""
161+
results = []
162+
ddgs = DDGS()
163+
for result in ddgs.text(keywords=query, max_results=5):
164+
results.append({
165+
"title": result.get("title", ""),
166+
"url": result.get("href", ""),
167+
"snippet": result.get("body", "")
168+
})
169+
return results
170+
```
171+
</Step>
172+
<Step title="Create Agent">
173+
174+
Create a new file `agents.yaml` with the following content:
175+
```yaml
176+
framework: praisonai
177+
topic: create movie script about cat in mars
178+
roles:
179+
scriptwriter:
180+
backstory: Expert in dialogue and script structure, translating concepts into
181+
scripts.
182+
goal: Write a movie script about a cat in Mars
183+
role: Scriptwriter
184+
tools:
185+
- internet_search_tool # <-- Tool assigned to Agent here
186+
tasks:
187+
scriptwriting_task:
188+
description: Turn the story concept into a production-ready movie script,
189+
including dialogue and scene details.
190+
expected_output: Final movie script with dialogue and scene details.
191+
```
192+
</Step>
193+
194+
<Step title="Start Agents">
195+
196+
Execute your script:
197+
```bash Terminal
198+
praisonai agents.yaml
199+
```
200+
</Step>
201+
</Steps>
202+
</Tab>
203+
</Tabs>
204+
205+
206+
## Creating Custom Tool
207+
<Steps>
208+
<Step>
209+
Create any function that you want to use as a tool, that performs a specific task.
210+
```python
211+
from duckduckgo_search import DDGS
212+
213+
def internet_search_tool(query: str):
67214
results = []
68215
ddgs = DDGS()
69216
for result in ddgs.text(keywords=query, max_results=5):
@@ -79,11 +226,8 @@ def internet_search_tool(query: str) -> List[Dict]:
79226
Assign the tool to an agent
80227
```python
81228
data_agent = Agent(
82-
name="DataCollector",
83-
role="Search Specialist",
84-
goal="Perform internet searches to collect relevant information.",
85-
backstory="Expert in finding and organising internet data.",
86-
tools=[internet_search_tool], ## Add the tool to the agent i.e the function name
229+
instructions="Search about AI job trends in 2025",
230+
tools=[internet_search_tool], # <-- Tool Assignment
87231
)
88232
```
89233
</Step>
@@ -93,7 +237,7 @@ Assign the tool to an agent
93237
<Check>You have created a custom tool and assigned it to an agent.</Check>
94238
</Card>
95239

96-
## Implementing Tools Full Code Example
240+
## Creating Custom Tool with Detailed Instructions
97241
<Tabs>
98242

99243
<Tab title="Code">
@@ -119,19 +263,9 @@ pip install praisonaiagents duckduckgo-search
119263
```python
120264
from praisonaiagents import Agent, Task, PraisonAIAgents
121265
from duckduckgo_search import DDGS
122-
from typing import List, Dict
123266

124267
# 1. Tool Implementation
125-
def internet_search_tool(query: str) -> List[Dict]:
126-
"""
127-
Perform Internet Search using DuckDuckGo
128-
129-
Args:
130-
query (str): The search query string
131-
132-
Returns:
133-
List[Dict]: List of search results containing title, URL, and snippet
134-
"""
268+
def internet_search_tool(query: str):
135269
results = []
136270
ddgs = DDGS()
137271
for result in ddgs.text(keywords=query, max_results=5):

0 commit comments

Comments
 (0)