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

ToolParameters

JSON Schema describing the tool’s parameters. Write it either as a flat map of property name to schema ({ city: { type: 'string' } }) or as a wrapped object schema ({ type: 'object', properties: { ... } }). With the flat form the handler’s args is typed from the schema, so args.city is a string and an enum narrows to its literal union. You can also build the schema with paramSchema().

opts.handler

SwaigHandlerRequired

Callback invoked when the AI calls this tool. Receives (args, rawData: SwaigRequest) and returns a FunctionResult, a plain object, or a string.

opts.secure

booleanDefaults to true

Whether to require token validation on tool calls. Tools are secure by default: the rendered webhook URL carries a per-tool token. Pass false only to expose the tool on the shared, unauthenticated webhook URL.

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

opts.onError

SwaigErrorHandler

Per-tool error hook, called when the handler throws. Return a FunctionResult to control what the caller hears, or nothing to fall back to errorMessage. Runs before the agent-level onError() hook.

opts.errorMessage

string

Message spoken to the caller when the handler throws and no error hook supplies a response. Defaults to a generic apology asking the caller to try again.

Returns

AgentBase — Returns this for method chaining.

Example

import { AgentBase, FunctionResult } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'weather-agent', route: '/weather' });
agent.setPromptText('You are a helpful assistant.');
agent.defineTool({
  name: 'get_weather',
  description: 'Get the current weather for a city',
  parameters: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name' },
    },
  },
  handler: async (args) => {
    const city = (args.city as string) ?? 'unknown';
    return new FunctionResult(`The weather in ${city} is 72F and sunny.`);
  },
  required: ['city'],
  fillers: { 'en-US': ['Checking the weather...', 'Let me look that up...'] },
});
await agent.serve();