AgentsSWMLService

defineTool

View as MarkdownOpen in Claude

Programmatically define a SWAIG function (tool) on a SWMLService. The SWAIG tool registry was lifted from AgentBase into SWMLService, so any service — including standalone SWAIG hosts and sidecars that do not produce an AI block — can register and dispatch tools.

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

Parameters

opts
SwaigFunctionOptionsRequired

Tool definition object.

opts.name
stringRequired

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

opts.description
stringRequired

Human-readable description of what the tool does.

opts.parameters
Record<string, unknown>

JSON Schema describing the tool’s parameters.

opts.handler
SwaigHandlerRequired

Callback invoked when the tool is called. 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.

opts.fillers
Record<string, string[]>

Language-specific filler phrases spoken while the tool executes.

Returns

SWMLService — Returns this for method chaining.

Example

1import { SWMLService, FunctionResult } from '@signalwire/sdk';
2
3const service = new SWMLService({ name: 'swaig-host', route: '/' });
4
5service.defineTool({
6  name: 'get_weather',
7  description: 'Get the current weather for a city',
8  parameters: {
9    type: 'object',
10    properties: { city: { type: 'string', description: 'City name' } },
11  },
12  handler: async (args) => {
13    const city = (args.city as string) ?? 'unknown';
14    return new FunctionResult(`The weather in ${city} is 72F and sunny.`);
15  },
16});