AgentsAgentBase

defineTool

View as MarkdownOpen in Claude

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
boolean

Whether to require token validation on tool calls.

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.

Returns

AgentBase — Returns this for method chaining.

Example

1import { AgentBase, FunctionResult } from '@signalwire/sdk';
2
3const agent = new AgentBase({ name: 'weather-agent', route: '/weather' });
4agent.setPromptText('You are a helpful assistant.');
5
6agent.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});
22await agent.serve();