> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# FunctionResult

> Fluent interface for returning responses and actions from SWAIG tool functions.

[tool]: /docs/server-sdks/reference/python/agents/agent-base#tool

[define-tool]: /docs/server-sdks/reference/python/agents/agent-base/define-tool

[agentbase]: /docs/server-sdks/reference/python/agents/agent-base

[swaig-function]: /docs/swml/reference/ai/swaig/functions

[swml-swaig-functions-reference]: /docs/swml/reference/ai/swaig/functions

[setresponse]: /docs/server-sdks/reference/python/agents/function-result/set-response

[setpostprocess]: /docs/server-sdks/reference/python/agents/function-result/set-post-process

[addaction]: /docs/server-sdks/reference/python/agents/function-result/add-action

[addactions]: /docs/server-sdks/reference/python/agents/function-result/add-actions

[todict]: /docs/server-sdks/reference/python/agents/function-result/to-dict

[connect]: /docs/server-sdks/reference/python/agents/function-result/connect

[hangup]: /docs/server-sdks/reference/python/agents/function-result/hangup

[hold]: /docs/server-sdks/reference/python/agents/function-result/hold

[swmltransfer]: /docs/server-sdks/reference/python/agents/function-result/swml-transfer

[say]: /docs/server-sdks/reference/python/agents/function-result/say

[waitforuser]: /docs/server-sdks/reference/python/agents/function-result/wait-for-user

[stop]: /docs/server-sdks/reference/python/agents/function-result/stop

[playbackgroundfile]: /docs/server-sdks/reference/python/agents/function-result/play-background-file

[stopbackgroundfile]: /docs/server-sdks/reference/python/agents/function-result/stop-background-file

[recordcall]: /docs/server-sdks/reference/python/agents/function-result/record-call

[stoprecordcall]: /docs/server-sdks/reference/python/agents/function-result/stop-record-call

[tap]: /docs/server-sdks/reference/python/agents/function-result/tap

[stoptap]: /docs/server-sdks/reference/python/agents/function-result/stop-tap

[updateglobaldata]: /docs/server-sdks/reference/python/agents/function-result/update-global-data

[removeglobaldata]: /docs/server-sdks/reference/python/agents/function-result/remove-global-data

[setmetadata]: /docs/server-sdks/reference/python/agents/function-result/set-metadata

[removemetadata]: /docs/server-sdks/reference/python/agents/function-result/remove-metadata

[swmlchangestep]: /docs/server-sdks/reference/python/agents/function-result/swml-change-step

[swmlchangecontext]: /docs/server-sdks/reference/python/agents/function-result/swml-change-context

[switchcontext]: /docs/server-sdks/reference/python/agents/function-result/switch-context

[swmluserevent]: /docs/server-sdks/reference/python/agents/function-result/swml-user-event

[simulateuserinput]: /docs/server-sdks/reference/python/agents/function-result/simulate-user-input

[togglefunctions]: /docs/server-sdks/reference/python/agents/function-result/toggle-functions

[enablefunctionsontimeout]: /docs/server-sdks/reference/python/agents/function-result/enable-functions-on-timeout

[adddynamichints]: /docs/server-sdks/reference/python/agents/function-result/add-dynamic-hints

[cleardynamichints]: /docs/server-sdks/reference/python/agents/function-result/clear-dynamic-hints

[setendofspeechtimeout]: /docs/server-sdks/reference/python/agents/function-result/set-end-of-speech-timeout

[setspeecheventtimeout]: /docs/server-sdks/reference/python/agents/function-result/set-speech-event-timeout

[updatesettings]: /docs/server-sdks/reference/python/agents/function-result/update-settings

[enableextensivedata]: /docs/server-sdks/reference/python/agents/function-result/enable-extensive-data

[replaceinhistory]: /docs/server-sdks/reference/python/agents/function-result/replace-in-history

[sendsms]: /docs/server-sdks/reference/python/agents/function-result/send-sms

[pay]: /docs/server-sdks/reference/python/agents/function-result/pay

[createpaymentprompt]: /docs/server-sdks/reference/python/agents/function-result/create-payment-prompt

[createpaymentaction]: /docs/server-sdks/reference/python/agents/function-result/create-payment-action

[createpaymentparameter]: /docs/server-sdks/reference/python/agents/function-result/create-payment-parameter

[siprefer]: /docs/server-sdks/reference/python/agents/function-result/sip-refer

[joinroom]: /docs/server-sdks/reference/python/agents/function-result/join-room

[joinconference]: /docs/server-sdks/reference/python/agents/function-result/join-conference

[executeswml]: /docs/server-sdks/reference/python/agents/function-result/execute-swml

[executerpc]: /docs/server-sdks/reference/python/agents/function-result/execute-rpc

[rpcdial]: /docs/server-sdks/reference/python/agents/function-result/rpc-dial

[rpcaimessage]: /docs/server-sdks/reference/python/agents/function-result/rpc-ai-message

[rpcaiunhold]: /docs/server-sdks/reference/python/agents/function-result/rpc-ai-unhold

[settoolresponse]: /docs/server-sdks/reference/python/agents/function-result/set-tool-response

[rpcaiglobaldata]: /docs/server-sdks/reference/python/agents/function-result/rpc-ai-global-data

`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()`][tool] decorator
or [`define_tool()`][define-tool] on
[`AgentBase`][agentbase].

> **Info**
>
> FunctionResult builds the response payload for a [SWAIG function][swaig-function].
> See the [SWML SWAIG functions reference][swml-swaig-functions-reference] for the
> full response format specification.

## Parameters

**`response`** `str | dict[str, Any] | None` — default: 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`** `bool` — default: 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 | None` — default: None

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

---

**`tool_prompt`** `str | None` — default: None

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

---

## Properties

**`response`** `str | dict[str, Any]` — default: ''

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

---

**`action`** `list[dict[str, Any]]` — default: \[]

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

---

**`post_process`** `bool` — default: 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

```python {10}
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.

> **Warning**
>
> 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.

```python {11}
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](/docs/server-sdks/reference/python/agents/function-result/set-response)

Set or replace the response prompt on a FunctionResult.

#### [set\_tool\_response](/docs/server-sdks/reference/python/agents/function-result/set-tool-response)

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

#### [set\_post\_process](/docs/server-sdks/reference/python/agents/function-result/set-post-process)

Enable or disable post-processing on a FunctionResult.

#### [add\_action](/docs/server-sdks/reference/python/agents/function-result/add-action)

Append a raw action to the FunctionResult action list.

#### [add\_actions](/docs/server-sdks/reference/python/agents/function-result/add-actions)

Append multiple raw actions to the FunctionResult action list.

#### [to\_dict](/docs/server-sdks/reference/python/agents/function-result/to-dict)

Serialize a FunctionResult to the SWAIG response format.

### Call Control

#### [connect](/docs/server-sdks/reference/python/agents/function-result/connect)

Transfer or connect the call to another destination.

#### [hangup](/docs/server-sdks/reference/python/agents/function-result/hangup)

End the call immediately.

#### [hold](/docs/server-sdks/reference/python/agents/function-result/hold)

Put the call on hold, announce it first, and route where it resumes.

#### [swml\_transfer](/docs/server-sdks/reference/python/agents/function-result/swml-transfer)

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

### Speech

#### [say](/docs/server-sdks/reference/python/agents/function-result/say)

Make the AI agent speak specific text immediately.

#### [wait\_for\_user](/docs/server-sdks/reference/python/agents/function-result/wait-for-user)

Control how the agent pauses and waits for user input.

#### [stop](/docs/server-sdks/reference/python/agents/function-result/stop)

Stop the agent execution immediately.

### Media

#### [play\_background\_file](/docs/server-sdks/reference/python/agents/function-result/play-background-file)

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

#### [stop\_background\_file](/docs/server-sdks/reference/python/agents/function-result/stop-background-file)

Stop the currently playing background audio file.

#### [record\_call](/docs/server-sdks/reference/python/agents/function-result/record-call)

Start recording the call in the background.

#### [stop\_record\_call](/docs/server-sdks/reference/python/agents/function-result/stop-record-call)

Stop an active background call recording.

#### [tap](/docs/server-sdks/reference/python/agents/function-result/tap)

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

#### [stop\_tap](/docs/server-sdks/reference/python/agents/function-result/stop-tap)

Stop an active media tap stream.

### Data

#### [update\_global\_data](/docs/server-sdks/reference/python/agents/function-result/update-global-data)

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

#### [remove\_global\_data](/docs/server-sdks/reference/python/agents/function-result/remove-global-data)

Remove one or more keys from the global session data.

#### [set\_metadata](/docs/server-sdks/reference/python/agents/function-result/set-metadata)

Set function-scoped metadata on a FunctionResult.

#### [remove\_metadata](/docs/server-sdks/reference/python/agents/function-result/remove-metadata)

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

### Context Navigation

#### [swml\_change\_step](/docs/server-sdks/reference/python/agents/function-result/swml-change-step)

Transition to a different step within the current conversation context.

#### [swml\_change\_context](/docs/server-sdks/reference/python/agents/function-result/swml-change-context)

Switch to a different conversation context.

#### [switch\_context](/docs/server-sdks/reference/python/agents/function-result/switch-context)

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

### Events

#### [swml\_user\_event](/docs/server-sdks/reference/python/agents/function-result/swml-user-event)

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

#### [simulate\_user\_input](/docs/server-sdks/reference/python/agents/function-result/simulate-user-input)

Inject text as simulated user speech input.

### Functions

#### [toggle\_functions](/docs/server-sdks/reference/python/agents/function-result/toggle-functions)

Enable or disable specific SWAIG functions at runtime.

#### [enable\_functions\_on\_timeout](/docs/server-sdks/reference/python/agents/function-result/enable-functions-on-timeout)

Allow SWAIG function calls when a speaker timeout occurs.

### Hints

#### [add\_dynamic\_hints](/docs/server-sdks/reference/python/agents/function-result/add-dynamic-hints)

Add speech recognition hints dynamically during a call.

#### [clear\_dynamic\_hints](/docs/server-sdks/reference/python/agents/function-result/clear-dynamic-hints)

Remove all dynamically added speech recognition hints.

### Settings

#### [set\_end\_of\_speech\_timeout](/docs/server-sdks/reference/python/agents/function-result/set-end-of-speech-timeout)

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

#### [set\_speech\_event\_timeout](/docs/server-sdks/reference/python/agents/function-result/set-speech-event-timeout)

Adjust the speech event timeout for noisy environments.

#### [update\_settings](/docs/server-sdks/reference/python/agents/function-result/update-settings)

Update AI runtime settings dynamically during a call.

#### [enable\_extensive\_data](/docs/server-sdks/reference/python/agents/function-result/enable-extensive-data)

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

#### [replace\_in\_history](/docs/server-sdks/reference/python/agents/function-result/replace-in-history)

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

### SMS

#### [send\_sms](/docs/server-sdks/reference/python/agents/function-result/send-sms)

Send an SMS or MMS message from a tool function.

### Payment

#### [pay](/docs/server-sdks/reference/python/agents/function-result/pay)

Collect and process a credit card payment during a call.

#### [create\_payment\_prompt](/docs/server-sdks/reference/python/agents/function-result/create-payment-prompt)

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

#### [create\_payment\_action](/docs/server-sdks/reference/python/agents/function-result/create-payment-action)

Build a single action entry for a payment prompt.

#### [create\_payment\_parameter](/docs/server-sdks/reference/python/agents/function-result/create-payment-parameter)

Build a parameter entry for the pay() method.

### SIP

#### [sip\_refer](/docs/server-sdks/reference/python/agents/function-result/sip-refer)

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

### Rooms and Conferences

#### [join\_room](/docs/server-sdks/reference/python/agents/function-result/join-room)

Join a SignalWire Relay room for multi-party communication.

#### [join\_conference](/docs/server-sdks/reference/python/agents/function-result/join-conference)

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

### SWML and RPC

#### [execute\_swml](/docs/server-sdks/reference/python/agents/function-result/execute-swml)

Execute a raw SWML document as an action.

#### [execute\_rpc](/docs/server-sdks/reference/python/agents/function-result/execute-rpc)

Execute a generic RPC method on a call.

#### [rpc\_dial](/docs/server-sdks/reference/python/agents/function-result/rpc-dial)

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

#### [rpc\_ai\_message](/docs/server-sdks/reference/python/agents/function-result/rpc-ai-message)

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

#### [rpc\_ai\_global\_data](/docs/server-sdks/reference/python/agents/function-result/rpc-ai-global-data)

Merge data into another call's global\_data without a conversation turn.

#### [rpc\_ai\_unhold](/docs/server-sdks/reference/python/agents/function-result/rpc-ai-unhold)

Release another call from hold via RPC.

> Fluent interface for returning responses and actions from SWAIG tool functions.

## Docs

- [add_action](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/add-action.md): Append a raw action to the FunctionResult action list.
- [add_actions](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/add-actions.md): Append multiple raw actions to the FunctionResult action list.
- [add_dynamic_hints](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/add-dynamic-hints.md): Add speech recognition hints dynamically during a call.
- [clear_dynamic_hints](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/clear-dynamic-hints.md): Remove all dynamically added speech recognition hints.
- [connect](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/connect.md): Transfer or connect the call to another destination.
- [create_payment_action](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/create-payment-action.md): Build a single action entry for a payment prompt.
- [create_payment_parameter](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/create-payment-parameter.md): Build a parameter entry for the pay() method.
- [create_payment_prompt](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/create-payment-prompt.md): Build a payment prompt object for use with pay().
- [enable_extensive_data](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/enable-extensive-data.md): Send full data to the LLM for the current turn only.
- [enable_functions_on_timeout](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/enable-functions-on-timeout.md): Allow SWAIG function calls when a speaker timeout occurs.
- [execute_rpc](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/execute-rpc.md): Execute a generic RPC method on a call.
- [execute_swml](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/execute-swml.md): Execute a raw SWML document as an action.
- [hangup](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/hangup.md): End the call immediately.
- [hold](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/hold.md): Put the call on hold, announce it first, and route where the call resumes.
- [join_conference](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/join-conference.md): Join an ad-hoc audio conference with extensive configuration options.
- [join_room](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/join-room.md): Join a Relay room for multi-party communication.
- [pay](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/pay.md): Collect and process a credit card payment during a call.
- [play_background_file](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/play-background-file.md): Play an audio or video file in the background during a call.
- [record_call](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/record-call.md): Start recording the call in the background.
- [remove_global_data](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/remove-global-data.md): Remove one or more keys from the global session data.
- [remove_metadata](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/remove-metadata.md): Remove one or more keys from the current function's metadata store.
- [replace_in_history](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/replace-in-history.md): Control how this function call appears in the AI's conversation history.
- [rpc_ai_global_data](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/rpc-ai-global-data.md): Merge data into another call's global_data without adding a conversation turn.
- [rpc_ai_message](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/rpc-ai-message.md): Inject a message into the AI agent running on another call.
- [rpc_ai_unhold](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/rpc-ai-unhold.md): Release another call from hold via RPC.
- [rpc_dial](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/rpc-dial.md): Dial out to a phone number with a destination SWML URL via RPC.
- [say](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/say.md): Make the AI agent speak specific text immediately.
- [send_sms](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/send-sms.md): Send an SMS or MMS message from a tool function.
- [set_end_of_speech_timeout](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/set-end-of-speech-timeout.md): Adjust the end-of-speech silence timeout for speech recognition.
- [set_metadata](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/set-metadata.md): Set function-scoped metadata on a FunctionResult.
- [set_post_process](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/set-post-process.md): Enable or disable post-processing on a FunctionResult.
- [set_response](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/set-response.md): Set or replace the response text on a FunctionResult.
- [set_speech_event_timeout](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/set-speech-event-timeout.md): Adjust the speech event timeout for noisy environments.
- [set_tool_response](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/set-tool-response.md): Split the response into a factual result and a speaking instruction.
- [simulate_user_input](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/simulate-user-input.md): Inject text as simulated user speech input.
- [sip_refer](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/sip-refer.md): Send a SIP REFER message to transfer the call in a SIP environment.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/stop.md): Stop the agent execution immediately.
- [stop_background_file](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/stop-background-file.md): Stop the currently playing background audio file.
- [stop_record_call](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/stop-record-call.md): Stop an active background call recording.
- [stop_tap](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/stop-tap.md): Stop an active media tap stream.
- [switch_context](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/switch-context.md): Perform an advanced context switch with prompt replacement and history control.
- [swml_change_context](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/swml-change-context.md): Switch to a different conversation context.
- [swml_change_step](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/swml-change-step.md): Transition to a different step within the current conversation context.
- [swml_transfer](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/swml-transfer.md): Transfer the call to a SWML endpoint with a return message.
- [swml_user_event](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/swml-user-event.md): Send a custom user event through SWML for real-time UI updates.
- [tap](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/tap.md): Stream call audio to an external endpoint via WebSocket or RTP.
- [to_dict](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/to-dict.md): Serialize a FunctionResult to the SWAIG response format.
- [toggle_functions](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/toggle-functions.md): Enable or disable specific SWAIG functions at runtime.
- [update_global_data](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/update-global-data.md): Set or update key-value pairs in the global session data.
- [update_settings](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/update-settings.md): Update AI runtime settings dynamically during a call.
- [wait_for_user](https://signalwire.com/docs/server-sdks/reference/python/agents/function-result/wait-for-user.md): Control how the agent pauses and waits for user input.