defineTool

Parameters

opts

objectRequired

Tool definition object.

opts.name

stringRequired

Tool name. Must be unique within the agent. The AI uses this name to invoke the function.

opts.description

stringRequired

Human-readable description of what the tool does. The AI reads this to decide when to call the tool.

opts.parameters

Record<string, unknown>

JSON Schema describing the tool’s parameters. The AI generates arguments conforming to this schema.

opts.handler

SwaigHandlerRequired

Callback invoked when the AI calls this tool. Receives (args: Record<string, unknown>, rawData: Record<string, unknown>) and should return a FunctionResult.

opts.secure

booleanDefaults to false

Whether to require token validation on tool calls. Recommended for production.

opts.fillers

Record<string, string[]>

Language-specific filler phrases spoken while the tool executes. Format: { 'en-US': ['Looking that up...', 'One moment...'] }.

opts.waitFile

string

URL of an audio file to play while the tool executes.

opts.waitFileLoops

number

Number of times to loop the wait file.

opts.required

string[]

List of required parameter names from the JSON Schema.

opts.webhookUrl

string

External webhook URL. When set, the tool is treated as externally-hosted and the tool call is forwarded to this URL instead of being dispatched to a local handler.

opts.extraFields

Record<string, unknown>

Additional fields merged into the SWAIG function definition. Equivalent to Python’s **swaig_fields kwargs (e.g., meta_data).

Example

1 import { AgentBase, FunctionResult } from '@signalwire/sdk';
2 
3 const agent = new AgentBase({ name: 'weather-agent', route: '/weather' });
4 agent.setPromptText('You are a helpful assistant.');
5 
6 agent.defineTool({
7   name: 'get_weather',
8   description: 'Get the current weather for a city',
9   parameters: {
10     type: 'object',
11     properties: {
12       city: { type: 'string', description: 'City name' },
13     },
14   },
15   handler: async (args) => {
16     const city = (args.city as string) ?? 'unknown';
17     return new FunctionResult(`The weather in ${city} is 72F and sunny.`);
18   },
19   required: ['city'],
20   fillers: { 'en-US': ['Checking the weather...', 'Let me look that up...'] },
21 });
22 await agent.serve();

Parameters

opts

objectRequired

Tool definition object.

opts.name

stringRequired

Tool name. Must be unique within the agent. The AI uses this name to invoke the function.

opts.description

stringRequired

Human-readable description of what the tool does. The AI reads this to decide when to call the tool.

opts.parameters

Record<string, unknown>

JSON Schema describing the tool’s parameters. The AI generates arguments conforming to this schema.

opts.handler

SwaigHandlerRequired

Callback invoked when the AI calls this tool. Receives (args: Record<string, unknown>, rawData: Record<string, unknown>) and should return a FunctionResult.

opts.secure

booleanDefaults to false

Whether to require token validation on tool calls. Recommended for production.

opts.fillers

Record<string, string[]>

Language-specific filler phrases spoken while the tool executes. Format: { 'en-US': ['Looking that up...', 'One moment...'] }.

opts.waitFile

string

URL of an audio file to play while the tool executes.

opts.waitFileLoops

number

Number of times to loop the wait file.

opts.required

string[]

List of required parameter names from the JSON Schema.

opts.webhookUrl

string

External webhook URL. When set, the tool is treated as externally-hosted and the tool call is forwarded to this URL instead of being dispatched to a local handler.

opts.extraFields

Record<string, unknown>

Additional fields merged into the SWAIG function definition. Equivalent to Python’s **swaig_fields kwargs (e.g., meta_data).

Example

1 import { AgentBase, FunctionResult } from '@signalwire/sdk';
2 
3 const agent = new AgentBase({ name: 'weather-agent', route: '/weather' });
4 agent.setPromptText('You are a helpful assistant.');
5 
6 agent.defineTool({
7   name: 'get_weather',
8   description: 'Get the current weather for a city',
9   parameters: {
10     type: 'object',
11     properties: {
12       city: { type: 'string', description: 'City name' },
13     },
14   },
15   handler: async (args) => {
16     const city = (args.city as string) ?? 'unknown';
17     return new FunctionResult(`The weather in ${city} is 72F and sunny.`);
18   },
19   required: ['city'],
20   fillers: { 'en-US': ['Checking the weather...', 'Let me look that up...'] },
21 });
22 await agent.serve();

defineTool

defineTool

Parameters

opts

opts.name

opts.description

opts.parameters

opts.handler

opts.secure

opts.fillers

opts.waitFile

opts.waitFileLoops

opts.required

opts.webhookUrl

opts.extraFields

Returns

Example

Parameters

opts

opts.name

opts.description

opts.parameters

opts.handler

opts.secure

opts.fillers

opts.waitFile

opts.waitFileLoops

opts.required

opts.webhookUrl

opts.extraFields

Returns

Example

1	import { AgentBase, FunctionResult } from '@signalwire/sdk';
2
3	const agent = new AgentBase({ name: 'weather-agent', route: '/weather' });
4	agent.setPromptText('You are a helpful assistant.');
5
6	agent.defineTool({
7	name: 'get_weather',
8	description: 'Get the current weather for a city',
9	parameters: {
10	type: 'object',
11	properties: {
12	city: { type: 'string', description: 'City name' },
13	},
14	},
15	handler: async (args) => {
16	const city = (args.city as string) ?? 'unknown';
17	return new FunctionResult(`The weather in ${city} is 72F and sunny.`);
18	},
19	required: ['city'],
20	fillers: { 'en-US': ['Checking the weather...', 'Let me look that up...'] },
21	});
22	await agent.serve();