Agents

FunctionResult

View as MarkdownOpen in Claude

FunctionResult is the return type for all SWAIG tool functions. It wraps a response (a prompt the AI reads, not text it speaks verbatim) 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.

Parameters

response
str | dict[str, Any] | NoneDefaults to None

A prompt injected into the model’s context after the function executes. The model reads it and decides what to say, so write it as an instruction in the second person: "Tell the caller their order shipped Tuesday." rather than "Your order shipped Tuesday.". A first-person script usually still works because the model tends to repeat it, but it is interpreted, not spoken, and can drift or be merged with other context.

post_process
boolDefaults to False

Let the AI take one more turn before executing actions. Set it whenever the caller must hear something before an action that ends or suspends the AI’s turn: hold pauses speech detection, connect and transfer replace the leg, and hangup ends the call.

tool_result
str | NoneDefaults to None

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

tool_prompt
str | NoneDefaults to None

Instruction for what the model should say next, in the second person. Pairs with tool_result.

Properties

response
str | dict[str, Any]Defaults to ''

The prompt injected into the model’s context. Either a plain string or a {"tool_result": ..., "tool_prompt": ...} object built by set_tool_response().

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 responds to the prompt and takes one more conversational turn with the user before executing actions. When False (default), actions execute immediately after the response.

Example

from signalwire import AgentBase
from signalwire import FunctionResult
agent = AgentBase(name="my-agent", route="/agent")
agent.set_prompt_text("You are a helpful assistant.")
@agent.tool(name="transfer_to_billing", description="Transfer the caller to billing")
def transfer_to_billing(args, raw_data):
    return (
        FunctionResult(
            "Tell the caller you are transferring them to billing and ask if they need anything else first.",
            post_process=True
        )
        .update_global_data({"transferred": True})
        .send_sms(
            to_number="+15551234567",
            from_number="+15559876543",
            body="You are being transferred to billing."
        )
        .connect("+15551234567", final=True)
    )
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.

from signalwire import AgentBase
from signalwire import FunctionResult
agent = AgentBase(name="my-agent", route="/agent")
agent.set_prompt_text("You are a helpful assistant.")
@agent.tool(name="transfer_call", description="Transfer the call")
def transfer_call(args, raw_data):
    # Data update + SMS execute before the terminal transfer
    return (
        FunctionResult("Tell the caller you are transferring them now.")
        .update_global_data({"transferred": True})
        .send_sms(
            to_number="+15551234567",
            from_number="+15559876543",
            body="Your call is being transferred."
        )
        .connect("+15551234567", final=True)  # terminal — goes last
    )
agent.serve()

Methods

Core

set_response

Set or replace the response prompt on a FunctionResult.

set_tool_response

Split the response into a factual result and a speaking instruction.

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, announce it first, and route where it resumes.

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.

Context Navigation

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 or global data into the AI agent running on another call.

rpc_ai_global_data

Merge data into another call’s global_data without a conversation turn.

rpc_ai_unhold

Release another call from hold via RPC.