SwmlTransferSkill | SignalWire

Transfer calls between agents or endpoints using SWML transfer actions. The skill accepts either a Python-style transfers config (regex pattern → per-entry config) or a TypeScript-style patterns array of named destinations. At least one of the two shapes is required — setup() fails closed otherwise.

Class: SwmlTransferSkill

Tools: transfer_call always; list_transfer_destinations additionally registered when at least one entry is supplied in patterns.

Env vars: None

Multi-instance: yes — set a distinct tool_name per instance.

transfers

Record<string, TransferConfig>

Python-style map of transfer configs keyed by regex pattern (or name). Each entry includes either url or address (not both), plus optional message, return_message, post_process, final, and from_addr.

Either transfers or patterns must be provided; both may be combined. setup() fails closed when neither is configured.

patterns

TransferPattern[]

TypeScript-style array of named transfer patterns. Each object has:

name (string, required) — friendly name for the destination.
destination (string, required) — SIP URI, phone number, or agent URL.
description (string) — optional human-readable description.
message / returnMessage / postProcess / final / fromAddr — optional per-pattern overrides.

allow_arbitrary

boolean

Whether to allow transfers to arbitrary destinations not listed in patterns / transfers. When unset, defaults depend on whether any patterns are configured.

tool_name

stringDefaults to transfer_call

Name of the transfer tool exposed to the AI.

description

stringDefaults to Transfer call based on pattern matching

Description for the transfer tool shown to the AI.

parameter_name

stringDefaults to transfer_type

Name of the parameter that accepts the transfer type.

parameter_description

stringDefaults to The type of transfer to perform

Description for the transfer-type parameter.

default_message

stringDefaults to Please specify a valid transfer type.

Message spoken when no pattern matches.

default_post_process

booleanDefaults to false

Whether to post-process the default message with the AI.

required_fields

Record<string, string>Defaults to {}

Map of additional fields (name → description) the agent must collect before a transfer.

Regex patterns in transfers are matched case-sensitively. Use character classes or flags in the source pattern when case-insensitive matching is needed.

Example — TypeScript patterns

1 import { AgentBase, SwmlTransferSkill } from '@signalwire/sdk';
2 
3 const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
4 agent.setPromptText('You are a helpful assistant.');
5 
6 await agent.addSkill(new SwmlTransferSkill({
7   patterns: [
8     {
9       name: 'sales',
10       destination: 'https://your-server.com/sales-agent',
11       description: 'Sales team',
12     },
13     {
14       name: 'support',
15       destination: '+15551234567',
16       description: 'Technical support line',
17     },
18   ],
19   default_message: 'Please specify sales or support.',
20 }));
21 
22 agent.run();

Example — Python-style transfers

1 import { AgentBase, SwmlTransferSkill } from '@signalwire/sdk';
2 
3 const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
4 agent.setPromptText('You are a helpful assistant.');
5 
6 await agent.addSkill(new SwmlTransferSkill({
7   transfers: {
8     '^sales$':   { address: 'sip:sales@signalwire.com' },
9     '^support$': { url: 'https://your-server.com/support-agent' },
10   },
11 }));
12 
13 agent.run();