***

title: execute_swml
slug: /reference/python/agents/function-result/execute-swml
description: Execute a raw SWML document as an action.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

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

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

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

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

[ref-swmlbuilder]: /docs/server-sdks/reference/python/agents/swml-builder/index

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.

<Note>
  Most use cases are covered by the specific action methods
  ([`connect()`][connect],
  [`record_call()`][record-call],
  [`send_sms()`][send-sms], etc.).
  Use `execute_swml()` only when you need SWML features not available through
  convenience methods.
</Note>

## **Parameters**

<ParamField path="swml_content" type="str | dict | SWML object" required={true} toc={true}>
  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`][ref-swmlbuilder] instance)
</ParamField>

<ParamField path="transfer" type="bool" default="False" toc={true}>
  When `True`, the call exits the agent after the SWML executes. When `False`,
  the SWML executes inline and the agent continues.
</ParamField>

## **Returns**

[`FunctionResult`][functionresult] — self, for chaining.

## **Example**

```python {20}
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()
```