execute_swml | SignalWire

Execute a raw SWML document as an action. This is the escape hatch for advanced use cases that are not covered by the named convenience methods.

Raises TypeError if swml_content is not a str, dict, or an object with a .to_dict() method.

Most use cases are covered by the specific action methods (connect(), record_call(), send_sms(), etc.). Use execute_swml() only when you need SWML features not available through convenience methods.

Parameters

swml_content

str | dict | SWML objectRequired

SWML content in one of three formats:

str — raw SWML JSON text (parsed internally)
dict — SWML data structure
SWML object — any object with a .to_dict() method (e.g., a SWMLBuilder instance)

transfer

boolDefaults to False

When True, the call exits the agent after the SWML executes. When False, the SWML executes inline and the agent continues.

Returns

FunctionResult — self, for chaining.

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="play_announcement", description="Play an announcement")
8 def play_announcement(args, raw_data):
9     swml_doc = {
10         "version": "1.0.0",
11         "sections": {
12             "main": [
13                 {"play": {"url": "https://example.com/announcement.mp3"}},
14                 {"hangup": {}}
15             ]
16         }
17     }
18     return (
19         FunctionResult()
20         .execute_swml(swml_doc, transfer=False)
21     )
22 
23 agent.serve()