SwaigFunction

SwaigFunction wraps a function as a SWAIG (SignalWire AI Gateway) tool that the AI can invoke during a conversation. It manages the function’s name, description, parameter schema, security settings, and serialization to SWML.

In most cases you do not create SwaigFunction instances directly. The defineTool() method on AgentBase handles construction internally. This class is documented for advanced use cases such as custom registration via registerSwaigFunction().

For server-side API tools without a handler, see DataMap. For building the response returned from a handler, see FunctionResult.

SwaigFunction serializes to a SWML SWAIG function definition. See the SWML SWAIG functions reference for the full specification.

Constructor

1 import { SwaigFunction } from '@signalwire/sdk';
2 
3 const fn = new SwaigFunction(opts);

SwaigFunctionOptions

name

stringRequired

Unique name used to register and invoke this tool.

handler

SwaigHandlerRequired

The handler invoked when the AI calls this tool. Receives parsed arguments and optional raw request data. Can return a FunctionResult, a plain object, or a string. May be async.

description

stringRequired

Human-readable description shown to the AI so it knows when to call this tool.

parameters

Record<string, unknown>

JSON Schema properties object describing the tool’s parameters.

secure

booleanDefaults to false

Whether the tool requires session token authentication.

fillers

Record<string, string[]>

Language-keyed filler phrases to speak while the tool executes (e.g., { "en-US": ["Let me check on that..."] }).

waitFile

string

URL of an audio file to play while the tool executes. Preferred over fillers.

waitFileLoops

number

Number of times to loop waitFile.

webhookUrl

string

External webhook URL. When set, the tool call is forwarded to this URL instead of being handled locally.

required

string[]

List of required parameter names.

extraFields

Record<string, unknown>

Additional fields to include in the SWAIG definition.

isTypedHandler

boolean

Whether the handler uses typed parameters.

SwaigHandler type

1 type SwaigHandler = (
2   args: Record<string, unknown>,
3   rawData: Record<string, unknown>,
4 ) => FunctionResult | Record<string, unknown> | string
5    | Promise<FunctionResult | Record<string, unknown> | string>;

Properties

name

string

The tool name.

handler

SwaigHandler

The handler.

description

string

The tool description.

parameters

Record<string, unknown>

The parameter schema object.

secure

boolean

Whether token authentication is required.

fillers

Record<string, string[]> | undefined

Filler phrases by language code.

waitFile

string | undefined

URL of an audio file to play while the tool executes.

waitFileLoops

number | undefined

Number of times to loop waitFile.

webhookUrl

string | undefined

External webhook URL for remotely handled tools.

required

string[]

List of required parameter names.

extraFields

Record<string, unknown>

Additional SWAIG definition fields.

isTypedHandler

boolean

Whether the handler uses typed parameters.

isExternal

boolean

true when webhookUrl is set, indicating the tool is handled externally.

Methods

execute

Execute the tool with the given arguments.

toSwaig

Convert the tool to a SWAIG-compatible dictionary for SWML.

validateArgs

Validate arguments against the parameter JSON Schema.

Examples

Manual registration

1 import { AgentBase, SwaigFunction, FunctionResult } from '@signalwire/sdk';
2 
3 const fn = new SwaigFunction({
4   name: 'lookup_account',
5   description: 'Look up account status by ID',
6   handler: async (args) => {
7     const accountId = args.account_id as string;
8     return new FunctionResult(`Account ${accountId} is active.`);
9   },
10   parameters: {
11     type: 'object',
12     properties: {
13       account_id: { type: 'string', description: 'The account ID to look up' },
14     },
15     required: ['account_id'],
16   },
17   secure: true,
18   fillers: { 'en-US': ['Let me check on that...'] },
19 });
20 
21 const agent = new AgentBase({ name: 'my-agent' });
22 agent.registerSwaigFunction(fn);
23 await agent.serve();

Using defineTool (preferred)

In most cases, use defineTool() instead of constructing SwaigFunction directly:

1 import { AgentBase, FunctionResult } from '@signalwire/sdk';
2 
3 const agent = new AgentBase({ name: 'my-agent' });
4 agent.setPromptText('You are a helpful assistant.');
5 
6 agent.defineTool({
7   name: 'lookup_account',
8   description: 'Look up account status by ID',
9   parameters: {
10     type: 'object',
11     properties: {
12       account_id: { type: 'string', description: 'Account ID' },
13     },
14     required: ['account_id'],
15   },
16   secure: true,
17   handler: async (args) => {
18     const accountId = args.account_id as string;
19     return new FunctionResult(`Account ${accountId} is active.`);
20   },
21 });
22 
23 await agent.serve();

For server-side API tools without a handler, see DataMap. For building the response returned from a handler, see FunctionResult.

SwaigFunction serializes to a SWML SWAIG function definition. See the SWML SWAIG functions reference for the full specification.

Constructor

1 import { SwaigFunction } from '@signalwire/sdk';
2 
3 const fn = new SwaigFunction(opts);

SwaigFunctionOptions

name

stringRequired

Unique name used to register and invoke this tool.

handler

SwaigHandlerRequired

The handler invoked when the AI calls this tool. Receives parsed arguments and optional raw request data. Can return a FunctionResult, a plain object, or a string. May be async.

description

stringRequired

Human-readable description shown to the AI so it knows when to call this tool.

parameters

Record<string, unknown>

JSON Schema properties object describing the tool’s parameters.

secure

booleanDefaults to false

Whether the tool requires session token authentication.

fillers

Record<string, string[]>

Language-keyed filler phrases to speak while the tool executes (e.g., { "en-US": ["Let me check on that..."] }).

waitFile

string

URL of an audio file to play while the tool executes. Preferred over fillers.

waitFileLoops

number

Number of times to loop waitFile.

webhookUrl

string

External webhook URL. When set, the tool call is forwarded to this URL instead of being handled locally.

required

string[]

List of required parameter names.

extraFields

Record<string, unknown>

Additional fields to include in the SWAIG definition.

isTypedHandler

boolean

Whether the handler uses typed parameters.

SwaigHandler type

1 type SwaigHandler = (
2   args: Record<string, unknown>,
3   rawData: Record<string, unknown>,
4 ) => FunctionResult | Record<string, unknown> | string
5    | Promise<FunctionResult | Record<string, unknown> | string>;

Properties

name

string

The tool name.

handler

SwaigHandler

The handler.

description

string

The tool description.

parameters

Record<string, unknown>

The parameter schema object.

secure

boolean

Whether token authentication is required.

fillers

Record<string, string[]> | undefined

Filler phrases by language code.

waitFile

string | undefined

URL of an audio file to play while the tool executes.

waitFileLoops

number | undefined

Number of times to loop waitFile.

webhookUrl

string | undefined

External webhook URL for remotely handled tools.

required

string[]

List of required parameter names.

extraFields

Record<string, unknown>

Additional SWAIG definition fields.

isTypedHandler

boolean

Whether the handler uses typed parameters.

isExternal

boolean

true when webhookUrl is set, indicating the tool is handled externally.

Methods

execute

Execute the tool with the given arguments.

toSwaig

Convert the tool to a SWAIG-compatible dictionary for SWML.

validateArgs

Validate arguments against the parameter JSON Schema.

Examples

Manual registration

1 import { AgentBase, SwaigFunction, FunctionResult } from '@signalwire/sdk';
2 
3 const fn = new SwaigFunction({
4   name: 'lookup_account',
5   description: 'Look up account status by ID',
6   handler: async (args) => {
7     const accountId = args.account_id as string;
8     return new FunctionResult(`Account ${accountId} is active.`);
9   },
10   parameters: {
11     type: 'object',
12     properties: {
13       account_id: { type: 'string', description: 'The account ID to look up' },
14     },
15     required: ['account_id'],
16   },
17   secure: true,
18   fillers: { 'en-US': ['Let me check on that...'] },
19 });
20 
21 const agent = new AgentBase({ name: 'my-agent' });
22 agent.registerSwaigFunction(fn);
23 await agent.serve();

Using defineTool (preferred)

In most cases, use defineTool() instead of constructing SwaigFunction directly:

1 import { AgentBase, FunctionResult } from '@signalwire/sdk';
2 
3 const agent = new AgentBase({ name: 'my-agent' });
4 agent.setPromptText('You are a helpful assistant.');
5 
6 agent.defineTool({
7   name: 'lookup_account',
8   description: 'Look up account status by ID',
9   parameters: {
10     type: 'object',
11     properties: {
12       account_id: { type: 'string', description: 'Account ID' },
13     },
14     required: ['account_id'],
15   },
16   secure: true,
17   handler: async (args) => {
18     const accountId = args.account_id as string;
19     return new FunctionResult(`Account ${accountId} is active.`);
20   },
21 });
22 
23 await agent.serve();

1	import { SwaigFunction } from '@signalwire/sdk';
2
3	const fn = new SwaigFunction(opts);

1	type SwaigHandler = (
2	args: Record<string, unknown>,
3	rawData: Record<string, unknown>,
4	) => FunctionResult \| Record<string, unknown> \| string
5	\| Promise<FunctionResult \| Record<string, unknown> \| string>;

1	import { AgentBase, SwaigFunction, FunctionResult } from '@signalwire/sdk';
2
3	const fn = new SwaigFunction({
4	name: 'lookup_account',
5	description: 'Look up account status by ID',
6	handler: async (args) => {
7	const accountId = args.account_id as string;
8	return new FunctionResult(`Account ${accountId} is active.`);
9	},
10	parameters: {
11	type: 'object',
12	properties: {
13	account_id: { type: 'string', description: 'The account ID to look up' },
14	},
15	required: ['account_id'],
16	},
17	secure: true,
18	fillers: { 'en-US': ['Let me check on that...'] },
19	});
20
21	const agent = new AgentBase({ name: 'my-agent' });
22	agent.registerSwaigFunction(fn);
23	await agent.serve();

1	import { AgentBase, FunctionResult } from '@signalwire/sdk';
2
3	const agent = new AgentBase({ name: 'my-agent' });
4	agent.setPromptText('You are a helpful assistant.');
5
6	agent.defineTool({
7	name: 'lookup_account',
8	description: 'Look up account status by ID',
9	parameters: {
10	type: 'object',
11	properties: {
12	account_id: { type: 'string', description: 'Account ID' },
13	},
14	required: ['account_id'],
15	},
16	secure: true,
17	handler: async (args) => {
18	const accountId = args.account_id as string;
19	return new FunctionResult(`Account ${accountId} is active.`);
20	},
21	});
22
23	await agent.serve();