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

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="play_announcement", description="Play an announcement")
def play_announcement(args, raw_data):
    swml_doc = {
        "version": "1.0.0",
        "sections": {
            "main": [
                {"play": {"url": "https://example.com/announcement.mp3"}},
                {"hangup": {}}
            ]
        }
    }
    return (
        FunctionResult()
        .execute_swml(swml_doc, transfer=False)
    )
agent.serve()