Skip to content

Commit f9ba1c8

Browse files
MervinPraisonMervinPraison
committed
Expand tool registration documentation and examples
- Added comprehensive TypeScript documentation for tool registration methods in `docs/js/typescript.mdx` - Created new README example file `examples/README-tool-examples.md` with detailed tool registration approaches - Updated example scripts to demonstrate direct function tool registration - Refined agent tool registration logic to support multiple function registration styles - Bumped package version to 1.0.19
1 parent 14049e4 commit f9ba1c8

File tree

7 files changed

+352
-18
lines changed

7 files changed

+352
-18
lines changed

‎docs/js/typescript.mdx

+96
Original file line numberDiff line numberDiff line change
@@ -264,3 +264,99 @@ agents.start()
264264
```
265265
</Step>
266266
</Steps>
267+
268+
## Tool Calls Examples
269+
270+
<AccordionGroup>
271+
<Accordion title="Single Agent Tool Call" icon="wrench" defaultOpen>
272+
Create an agent that can use tools to get information:
273+
274+
```typescript
275+
import { Agent } from 'praisonai';
276+
277+
/**
278+
* Example of a simple agent with tool calling capability
279+
*
280+
* This example demonstrates how to create a simple agent that can use tools
281+
* to get weather information for a location.
282+
*/
283+
284+
// Define a weather tool
285+
const getWeather = {
286+
type: "function",
287+
function: {
288+
name: "get_weather",
289+
description: "Get current temperature for a given location.",
290+
parameters: {
291+
type: "object",
292+
properties: {
293+
location: {
294+
type: "string",
295+
description: "City and country e.g. Bogotá, Colombia"
296+
}
297+
},
298+
required: ["location"],
299+
additionalProperties: false
300+
},
301+
strict: true
302+
}
303+
};
304+
305+
// Make the function globally available
306+
// The agent will automatically find and use this function
307+
(global as any).get_weather = async function(location: string) {
308+
console.log(`Getting weather for ${location}...`);
309+
return `20°C`;
310+
};
311+
312+
// Create an agent with the weather tool
313+
const agent = new Agent({
314+
instructions: `You provide the current weather for requested locations.`,
315+
name: "WeatherAgent",
316+
tools: [getWeather]
317+
});
318+
319+
// Start the agent with a prompt that will trigger tool usage
320+
agent.start("What's the weather in Paris, France?");
321+
```
322+
</Accordion>
323+
324+
<Accordion title="Direct Function Tools" icon="code" defaultOpen>
325+
Create an agent with directly registered function tools:
326+
327+
```typescript
328+
import { Agent } from 'praisonai';
329+
330+
/**
331+
* Example of a simple agent with direct function registration
332+
*
333+
* This example demonstrates how to create a simple agent that uses directly
334+
* registered functions as tools without having to define tool schemas manually
335+
* or make functions globally available.
336+
*/
337+
338+
// Define the functions directly
339+
async function getWeather(location: string) {
340+
console.log(`Getting weather for ${location}...`);
341+
return `${Math.floor(Math.random() * 30)}°C`;
342+
}
343+
344+
async function getTime(location: string) {
345+
console.log(`Getting time for ${location}...`);
346+
const now = new Date();
347+
return `${now.getHours()}:${now.getMinutes()}`;
348+
}
349+
350+
// Create an agent with directly registered functions
351+
const agent = new Agent({
352+
instructions: `You provide the current weather and time for requested locations.`,
353+
name: "DirectFunctionAgent",
354+
// Register functions directly as an array without needing to make them global
355+
tools: [getWeather, getTime]
356+
});
357+
358+
// Start the agent with a prompt that will trigger tool usage
359+
agent.start("What's the weather and time in Paris, France and Tokyo, Japan?");
360+
```
361+
</Accordion>
362+
</AccordionGroup>

‎src/praisonai-ts/examples/README-tool-examples.md

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# PraisonAI Tool Registration Examples
2+
3+
This document demonstrates the three different ways to register tool functions in PraisonAI.
4+
5+
## Method 1: Using the `tools` array with function objects directly
6+
7+
```typescript
8+
import { Agent } from 'praisonai';
9+
10+
// Define the functions directly
11+
async function getWeather(location: string) {
12+
console.log(`Getting weather for ${location}...`);
13+
return `${Math.floor(Math.random() * 30)}°C`;
14+
}
15+
16+
async function getTime(location: string) {
17+
console.log(`Getting time for ${location}...`);
18+
const now = new Date();
19+
return `${now.getHours()}:${now.getMinutes()}`;
20+
}
21+
22+
// Create an agent with directly registered functions
23+
const agent = new Agent({
24+
instructions: `You provide the current weather and time for requested locations.`,
25+
name: "DirectFunctionAgent",
26+
// Register functions directly as an array
27+
tools: [getWeather, getTime]
28+
});
29+
30+
// Start the agent with a prompt that will trigger tool usage
31+
agent.start("What's the weather and time in Paris, France?");
32+
```
33+
34+
## Method 2: Using the `toolFunctions` object with name-function pairs
35+
36+
```typescript
37+
import { Agent } from 'praisonai';
38+
39+
// Define the functions directly
40+
async function getWeather(location: string) {
41+
console.log(`Getting weather for ${location}...`);
42+
return `${Math.floor(Math.random() * 30)}°C`;
43+
}
44+
45+
async function getTime(location: string) {
46+
console.log(`Getting time for ${location}...`);
47+
const now = new Date();
48+
return `${now.getHours()}:${now.getMinutes()}`;
49+
}
50+
51+
// Create an agent with directly registered functions
52+
const agent = new Agent({
53+
instructions: `You provide the current weather and time for requested locations.`,
54+
name: "DirectFunctionAgent",
55+
// Register functions with custom names
56+
toolFunctions: {
57+
get_weather: getWeather,
58+
get_time: getTime
59+
}
60+
});
61+
62+
// Start the agent with a prompt that will trigger tool usage
63+
agent.start("What's the weather and time in Paris, France?");
64+
```
65+
66+
## Method 3: Using the `tools` array with pre-defined tool definitions
67+
68+
```typescript
69+
import { Agent } from 'praisonai';
70+
71+
// Define the functions
72+
async function getWeather(location: string) {
73+
console.log(`Getting weather for ${location}...`);
74+
return `${Math.floor(Math.random() * 30)}°C`;
75+
}
76+
77+
async function getTime(location: string) {
78+
console.log(`Getting time for ${location}...`);
79+
const now = new Date();
80+
return `${now.getHours()}:${now.getMinutes()}`;
81+
}
82+
83+
// Register functions globally
84+
import { registerFunction } from 'praisonai';
85+
registerFunction('get_weather', getWeather);
86+
registerFunction('get_time', getTime);
87+
88+
// Define tool definitions
89+
const weatherTool = {
90+
type: "function",
91+
function: {
92+
name: "get_weather",
93+
description: "Get the current weather for a location",
94+
parameters: {
95+
type: "object",
96+
properties: {
97+
location: {
98+
type: "string",
99+
description: "The location to get weather for"
100+
}
101+
},
102+
required: ["location"]
103+
}
104+
}
105+
};
106+
107+
const timeTool = {
108+
type: "function",
109+
function: {
110+
name: "get_time",
111+
description: "Get the current time for a location",
112+
parameters: {
113+
type: "object",
114+
properties: {
115+
location: {
116+
type: "string",
117+
description: "The location to get time for"
118+
}
119+
},
120+
required: ["location"]
121+
}
122+
}
123+
};
124+
125+
// Create an agent with pre-defined tool definitions
126+
const agent = new Agent({
127+
instructions: `You provide the current weather and time for requested locations.`,
128+
name: "ToolDefinitionAgent",
129+
// Register pre-defined tool definitions
130+
tools: [weatherTool, timeTool]
131+
});
132+
133+
// Start the agent with a prompt that will trigger tool usage
134+
agent.start("What's the weather and time in Paris, France?");
135+
```
136+
137+
## Combined Approach
138+
139+
You can also combine these approaches as needed:
140+
141+
```typescript
142+
import { Agent } from 'praisonai';
143+
144+
// Define the functions
145+
async function getWeather(location: string) {
146+
console.log(`Getting weather for ${location}...`);
147+
return `${Math.floor(Math.random() * 30)}°C`;
148+
}
149+
150+
async function getTime(location: string) {
151+
console.log(`Getting time for ${location}...`);
152+
const now = new Date();
153+
return `${now.getHours()}:${now.getMinutes()}`;
154+
}
155+
156+
// Define a custom tool definition
157+
const calculatorTool = {
158+
type: "function",
159+
function: {
160+
name: "calculate",
161+
description: "Perform a calculation",
162+
parameters: {
163+
type: "object",
164+
properties: {
165+
expression: {
166+
type: "string",
167+
description: "The mathematical expression to calculate"
168+
}
169+
},
170+
required: ["expression"]
171+
}
172+
}
173+
};
174+
175+
// Register the calculator function globally
176+
import { registerFunction } from 'praisonai';
177+
registerFunction('calculate', async (expression: string) => {
178+
console.log(`Calculating ${expression}...`);
179+
// Simple eval for demonstration purposes only
180+
return eval(expression).toString();
181+
});
182+
183+
// Create an agent with mixed tool registration approaches
184+
const agent = new Agent({
185+
instructions: `You can provide weather, time, and perform calculations.`,
186+
name: "MixedToolAgent",
187+
// Register functions directly as an array
188+
tools: [getWeather, getTime, calculatorTool]
189+
});
190+
191+
// Start the agent with a prompt that will trigger tool usage
192+
agent.start("What's the weather in Paris, the time in Tokyo, and what is 25 * 4?");
193+
```

‎src/praisonai-ts/examples/simple/direct-function-tools.ts

+2-5
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,8 @@ async function getTime(location: string) {
2424
const agent = new Agent({
2525
instructions: `You provide the current weather and time for requested locations.`,
2626
name: "DirectFunctionAgent",
27-
// Register functions directly without needing to make them global
28-
toolFunctions: {
29-
get_weather: getWeather,
30-
get_time: getTime
31-
}
27+
// Register functions directly as an array without needing to make them global
28+
tools: [getWeather, getTime]
3229
});
3330

3431
// Start the agent with a prompt that will trigger tool usage

‎src/praisonai-ts/package.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "praisonai",
3-
"version": "1.0.18",
3+
"version": "1.0.19",
44
"description": "PraisonAI TypeScript AI Agents Framework - Node.js, npm, and Javascript AI Agents Framework",
55
"main": "dist/index.js",
66
"types": "dist/index.d.ts",
@@ -62,7 +62,7 @@
6262
"fast-xml-parser": "^4.5.1",
6363
"node-fetch": "^2.6.9",
6464
"openai": "^4.81.0",
65-
"praisonai": "^1.0.17"
65+
"praisonai": "^1.0.18"
6666
},
6767
"optionalDependencies": {
6868
"boxen": "^7.1.1",

0 commit comments

Comments
 (0)