defineTool | SignalWire

Programmatically define a SWAIG function (tool) that the AI can invoke during a conversation.

Tool definitions map to SWML SWAIG function entries. See the SWML SWAIG functions reference for the full specification.

For cleaner typed handler signatures with automatic parameter inference, consider using defineTypedTool() instead.

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).

Returns

AgentBase — Returns this for method chaining.

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();