AgentsAgentBase

defineTypedTool

View as MarkdownOpen in Claude

Register a SWAIG tool with a typed handler that receives named parameters instead of the standard (args, rawData) convention. The SDK wraps the handler to unpack the args object into positional params.

If no parameters schema is provided, one is inferred from the handler’s source code (parameter names and default values).

Use defineTypedTool() when you want cleaner handler signatures with named parameters. Use defineTool() when you need full control over the args object.

Parameters

opts
objectRequired

Tool definition object.

opts.name
stringRequired

Tool name. Must be unique within the agent.

opts.description
stringRequired

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

opts.parameters
Record<string, unknown>

JSON Schema describing the tool’s parameters. If omitted, the schema is inferred from the handler’s parameter names and default values.

opts.handler
FunctionRequired

Typed handler that receives named parameters extracted from the args object. Parameter names must match the JSON Schema property names.

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.

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 weather assistant.');
5
6agent.defineTypedTool({
7  name: 'get_weather',
8  description: 'Get the current weather for a city',
9  handler: (city: string, unit: string = 'fahrenheit') => {
10    const temp = unit === 'celsius' ? '22C' : '72F';
11    return new FunctionResult(`The weather in ${city} is ${temp} and sunny.`);
12  },
13  required: ['city'],
14});
15
16await agent.serve();