Skip to navigation
Agents

FunctionResult

View as MarkdownOpen in Claude

FunctionResult is the return type for all SWAIG tool functions. It wraps a response message (text for the AI to speak) and an ordered list of actions (transfers, SMS, data updates, context switches, and more). Every method returns this, so you can chain calls into a single fluent expression.

Returned from functions defined with defineTool() on AgentBase.

FunctionResult builds the response payload for a SWAIG function. See the SWML SWAIG functions reference for the full response format specification.

Parameters

response
string | { tool_result?: string; tool_prompt?: string }Defaults to ''

Context for the model after the function executes: a string of facts or an instruction, or the structured { tool_result, tool_prompt } form described under setToolResponse().

postProcess
booleanDefaults to false

Let the AI take one more turn before executing actions. Set it whenever the caller must hear something before an action takes effect, such as a hold, transfer, or hangup.

toolResult
string

Factual outcome of the call, such as "status: on hold". When given, the response takes the structured form described under setToolResponse().

toolPrompt
string

Instruction for what the model should do next. Pairs with toolResult.

Properties

response
stringDefaults to ''

The response string returned to the model as context. When the structured form is set with setToolResponse(), that is sent instead.

action
Record<string, unknown>[]Defaults to []

Ordered list of action objects to execute. Actions run sequentially in the order they were added.

postProcess
booleanDefaults to false

When true, the AI speaks the response and takes one more conversational turn with the user before executing actions. When false (default), actions execute immediately after the response.

Example

import { AgentBase, FunctionResult } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'my-agent', route: '/agent' });
agent.setPromptText('You are a helpful assistant.');
agent.defineTool({
  name: 'transfer_to_billing',
  description: 'Transfer the caller to billing',
  handler: (args, rawData) => {
    return new FunctionResult(
      "I'll transfer you to billing. Anything else first?",
      true // postProcess
    )
      .updateGlobalData({ transferred: true })
      .sendSms({
        toNumber: '+15551234567',
        fromNumber: '+15559876543',
        body: 'You are being transferred to billing.',
      })
      .connect('+15551234567', true);
  },
});
agent.run();

Fluent Chaining Pattern

Every method on FunctionResult returns this, so you build complex responses in a single expression. Actions execute in the order they are added.

Terminal actions like connect(destination, true) and hangup() end the call flow. Place them last in the chain so that preceding actions (data updates, SMS, etc.) have a chance to execute.

import { AgentBase, FunctionResult } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'my-agent', route: '/agent' });
agent.setPromptText('You are a helpful assistant.');
agent.defineTool({
  name: 'transfer_now',
  description: 'Transfer the caller',
  handler: (args, rawData) => {
    // Data update + SMS execute before the terminal transfer
    return new FunctionResult('Transferring you now.')
      .updateGlobalData({ transferred: true })
      .sendSms({
        toNumber: '+15551234567',
        fromNumber: '+15559876543',
        body: 'Your call is being transferred.',
      })
      .connect('+15551234567', true); // terminal — goes last
  },
});
agent.run();

Methods

Core

setResponse

Set or replace the response text on a FunctionResult.

setToolResponse

Split the response into a factual result and an instruction.

setPostProcess

Enable or disable post-processing on a FunctionResult.

addAction

Append a raw action to the FunctionResult action list.

addActions

Append multiple raw actions to the FunctionResult action list.

toDict

Serialize a FunctionResult to the SWAIG response format.

Call Control

connect

Transfer or connect the call to another destination.

hangup

End the call immediately.

hold

Put the call on hold with an optional timeout.

swmlTransfer

Transfer the call to a SWML endpoint with a return message.

Speech

say

Make the AI agent speak specific text immediately.

waitForUser

Control how the agent pauses and waits for user input.

stop

Stop the agent execution immediately.

Media

playBackgroundFile

Play an audio or video file in the background during a call.

stopBackgroundFile

Stop the currently playing background audio file.

recordCall

Start recording the call in the background.

stopRecordCall

Stop an active background call recording.

tap

Stream call audio to an external endpoint via WebSocket or RTP.

stopTap

Stop an active media tap stream.

Data

updateGlobalData

Set or update key-value pairs in the global session data.

removeGlobalData

Remove one or more keys from the global session data.

setMetadata

Set function-scoped metadata key-value pairs.

removeMetadata

Remove one or more keys from the current function’s metadata store.

setSemanticState

Set the semantic state that the call’s semantic gates read.

Context Navigation

swmlChangeStep

Transition to a different step within the current conversation context.

swmlChangeContext

Switch to a different conversation context.

switchContext

Perform an advanced context switch with prompt replacement and history control.

Events

swmlUserEvent

Send a custom user event through SWML for real-time UI updates.

simulateUserInput

Inject text as simulated user speech input.

Functions

toggleFunctions

Enable or disable specific SWAIG functions at runtime.

enableFunctionsOnTimeout

Allow SWAIG function calls when a speaker timeout occurs.

Hints

addDynamicHints

Add speech recognition hints dynamically during a call.

clearDynamicHints

Remove all dynamically added speech recognition hints.

Settings

setEndOfSpeechTimeout

Adjust the end-of-speech silence timeout for speech recognition.

setSpeechEventTimeout

Adjust the speech event timeout for noisy environments.

updateSettings

Update AI runtime settings dynamically during a call.

enableExtensiveData

Send full data to the LLM for the current turn only.

replaceInHistory

Control how this function call appears in the AI’s conversation history.

SMS

sendSms

Send an SMS or MMS message from a tool function.

Payment

pay

Collect and process a credit card payment during a call.

createPaymentPrompt

Build a payment prompt object for use with pay().

createPaymentAction

Build a single action entry for a payment prompt.

createPaymentParameter

Build a parameter entry for the pay() method.

SIP

sipRefer

Send a SIP REFER message to transfer the call in a SIP environment.

Rooms and Conferences

joinRoom

Join a SignalWire room for multi-party communication.

joinConference

Join an ad-hoc audio conference with extensive configuration options.

SWML and RPC

executeSwml

Execute a raw SWML document as an action.

executeRpc

Execute a generic RPC method on a call.

rpcDial

Dial out to a phone number with a destination SWML URL via RPC.

rpcAiMessage

Inject a message into the AI agent running on another call.

rpcAiUnhold

Release another call from hold via RPC.