FunctionResult | SignalWire

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 self, so you can chain calls into a single fluent expression.

Returned from functions defined with the @tool() decorator or define_tool() on AgentBase.

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

Properties

response

strDefaults to ''

Text the AI speaks back to the caller after the function executes.

action

list[dict[str, Any]]Defaults to []

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

post_process

boolDefaults 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

1 from signalwire import AgentBase
2 from signalwire import FunctionResult
3 
4 agent = AgentBase(name="my-agent", route="/agent")
5 agent.set_prompt_text("You are a helpful assistant.")
6 
7 @agent.tool(name="transfer_to_billing", description="Transfer the caller to billing")
8 def transfer_to_billing(args, raw_data):
9     return (
10         FunctionResult(
11             "I'll transfer you to billing. Anything else first?",
12             post_process=True
13         )
14         .update_global_data({"transferred": True})
15         .send_sms(
16             to_number="+15551234567",
17             from_number="+15559876543",
18             body="You are being transferred to billing."
19         )
20         .connect("+15551234567", final=True)
21     )
22 
23 agent.serve()

Fluent Chaining Pattern

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

Terminal actions like connect(final=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.

1 from signalwire import AgentBase
2 from signalwire import FunctionResult
3 
4 agent = AgentBase(name="my-agent", route="/agent")
5 agent.set_prompt_text("You are a helpful assistant.")
6 
7 @agent.tool(name="transfer_call", description="Transfer the call")
8 def transfer_call(args, raw_data):
9     # Data update + SMS execute before the terminal transfer
10     return (
11         FunctionResult("Transferring you now.")
12         .update_global_data({"transferred": True})
13         .send_sms(
14             to_number="+15551234567",
15             from_number="+15559876543",
16             body="Your call is being transferred."
17         )
18         .connect("+15551234567", final=True)  # terminal — goes last
19     )
20 
21 agent.serve()

Methods

Core

set_response

Set or replace the response text on a FunctionResult.

set_post_process

Enable or disable post-processing on a FunctionResult.

add_action

Append a raw action to the FunctionResult action list.

add_actions

Append multiple raw actions to the FunctionResult action list.

to_dict

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.

swml_transfer

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

Speech

say

Make the AI agent speak specific text immediately.

wait_for_user

Control how the agent pauses and waits for user input.

stop

Stop the agent execution immediately.

Media

play_background_file

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

stop_background_file

Stop the currently playing background audio file.

record_call

Start recording the call in the background.

stop_record_call

Stop an active background call recording.

tap

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

stop_tap

Stop an active media tap stream.

Data

update_global_data

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

remove_global_data

Remove one or more keys from the global session data.

set_metadata

Set function-scoped metadata on a FunctionResult.

remove_metadata

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

swml_change_step

Transition to a different step within the current conversation context.

swml_change_context

Switch to a different conversation context.

switch_context

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

Events

swml_user_event

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

simulate_user_input

Inject text as simulated user speech input.

Functions

toggle_functions

Enable or disable specific SWAIG functions at runtime.

enable_functions_on_timeout

Allow SWAIG function calls when a speaker timeout occurs.

Hints

add_dynamic_hints

Add speech recognition hints dynamically during a call.

clear_dynamic_hints

Remove all dynamically added speech recognition hints.

Settings

set_end_of_speech_timeout

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

set_speech_event_timeout

Adjust the speech event timeout for noisy environments.

update_settings

Update AI runtime settings dynamically during a call.

enable_extensive_data

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

replace_in_history

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

SMS

send_sms

Send an SMS or MMS message from a tool function.

Payment

pay

Collect and process a credit card payment during a call.

create_payment_prompt

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

create_payment_action

Build a single action entry for a payment prompt.

create_payment_parameter

Build a parameter entry for the pay() method.

SIP

sip_refer

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

Rooms and Conferences

join_room

Join a SignalWire RELAY room for multi-party communication.

join_conference

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

SWML and RPC

execute_swml

Execute a raw SWML document as an action.

execute_rpc

Execute a generic RPC method on a call.

rpc_dial

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

rpc_ai_message

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

rpc_ai_unhold

Release another call from hold via RPC.