SwmlTransferSkill

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.

The destination list in the AI’s prompt shows each URL without the credentials it carries, and shows each transfers key without its regex slashes and flag.

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

import { AgentBase, SwmlTransferSkill } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
agent.setPromptText('You are a helpful assistant.');
await agent.addSkill(new SwmlTransferSkill({
  patterns: [
    {
      name: 'sales',
      destination: 'https://your-server.com/sales-agent',
      description: 'Sales team',
    },
    {
      name: 'support',
      destination: '+15551234567',
      description: 'Technical support line',
    },
  ],
  default_message: 'Please specify sales or support.',
}));
agent.run();

Example — Python-style transfers

import { AgentBase, SwmlTransferSkill } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
agent.setPromptText('You are a helpful assistant.');
await agent.addSkill(new SwmlTransferSkill({
  transfers: {
    '^sales$':   { address: 'sip:sales@signalwire.com' },
    '^support$': { url: 'https://your-server.com/support-agent' },
  },
}));
agent.run();