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

# SWAIGFunction

> Wrapper class for SWAIG function definitions with execution and validation.

[agent-tool-decorator]: /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

[datamap]: /docs/server-sdks/reference/python/agents/data-map

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

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

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

[execute]: /docs/server-sdks/reference/python/agents/swaig-function/execute

[toswaig]: /docs/server-sdks/reference/python/agents/swaig-function/to-swaig

[validateargs]: /docs/server-sdks/reference/python/agents/swaig-function/validate-args

SWAIGFunction wraps a Python callable as a SWAIG (SignalWire AI Gateway) tool
that the AI can invoke during a conversation. It manages the function's name,
description, parameter schema, security settings, and serialization to SWML.

In most cases you do not create SWAIGFunction instances directly. The
[`@agent.tool()` decorator][agent-tool-decorator]
and [`define_tool()`][define-tool] method
on [`AgentBase`][agentbase] handle construction
internally. This class is documented for advanced use cases such as custom
registration via `register_swaig_function()`.

> **Info**
>
> For server-side API tools without a Python handler, see
> [`DataMap`][datamap]. For building the
> response returned from a handler, see
> [`FunctionResult`][functionresult].

> **Info**
>
> SWAIGFunction serializes to a SWML [SWAIG function definition][swaig-function-definition].
> See the [SWML SWAIG functions reference][swml-swaig-functions-reference] for the
> full specification.

## **Properties**

**`name`** `str`

The function name.

---

**`handler`** `Callable`

The underlying Python handler function.

---

**`description`** `str`

The function description.

---

**`parameters`** `dict`

The parameter schema dictionary.

---

**`secure`** `bool`

Whether token authentication is required.

---

**`fillers`** `dict[str, list[str]] | None` — default: None

Filler phrases by language code to speak while the function executes
(e.g., `{"en-US": ["Let me check on that..."]}`).

---

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

URL of an audio file to play while the function executes. Preferred over `fillers`.

---

**`wait_file_loops`** `int | None` — default: None

Number of times to loop `wait_file`. Defaults to playing once.

---

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

External webhook URL. When set, the function call is forwarded to this URL instead
of being handled locally.

---

**`required`** `list[str]`

List of required parameter names. Merged into the parameter schema's `required` array.

---

**`is_typed_handler`** `bool`

Whether the handler uses type-hinted parameters (auto-wrapped by the `@tool` decorator).

---

**`is_external`** `bool`

`True` when `webhook_url` is set, indicating the function is handled externally.

---

### \_\_call\_\_

The SWAIGFunction object is callable. Calling it directly delegates to the
underlying handler:

```python
from signalwire import AgentBase
from signalwire import SWAIGFunction
from signalwire import FunctionResult

agent = AgentBase(name="assistant", route="/assistant")
agent.set_prompt_text("You are a helpful assistant.")

@agent.tool(description="Look up order status")
def check_order(args, raw_data=None):
    order_id = args.get("order_id")
    return FunctionResult(f"Order {order_id} shipped March 28.")

agent.serve()
```

This is equivalent to `func.handler(args, raw_data)`.

## **Methods**

#### [execute](/docs/server-sdks/reference/python/agents/swaig-function/execute)

Execute the function with the given arguments.

#### [to\_swaig](/docs/server-sdks/reference/python/agents/swaig-function/to-swaig)

Convert the function to a SWAIG-compatible dictionary for SWML.

#### [validate\_args](/docs/server-sdks/reference/python/agents/swaig-function/validate-args)

Validate arguments against the parameter JSON Schema.

---

## **Examples**

### Manual registration

```python {10}
from signalwire import AgentBase, SWAIGFunction
from signalwire import FunctionResult

def handle_lookup(args, raw_data):
    account_id = args.get("account_id", "")
    return FunctionResult(f"Account {account_id} is active.")

agent = AgentBase(name="my-agent")

func = SWAIGFunction(
    name="lookup_account",
    handler=handle_lookup,
    description="Look up account status by ID",
    parameters={
        "type": "object",
        "properties": {
            "account_id": {
                "type": "string",
                "description": "The account ID to look up"
            }
        },
        "required": ["account_id"]
    },
    secure=True,
    fillers={"en-US": ["Let me check on that..."]}
)

# Validate before registering
is_valid, errors = func.validate_args({"account_id": "12345"})
print(f"Valid: {is_valid}, Errors: {errors}")
# Valid: True, Errors: []
```

### Using the decorator (preferred)

In most cases, use the `@agent.tool()` decorator instead of constructing
SWAIGFunction directly:

```python
from signalwire import AgentBase
from signalwire import FunctionResult

agent = AgentBase(name="my-agent")
agent.set_prompt_text("You are a helpful assistant.")

@agent.tool(
    description="Look up account status by ID",
    parameters={
        "type": "object",
        "properties": {
            "account_id": {"type": "string", "description": "Account ID"}
        },
        "required": ["account_id"]
    },
    secure=True,
    fillers=["Let me check on that..."]
)
def lookup_account(args, raw_data):
    account_id = args.get("account_id", "")
    return FunctionResult(f"Account {account_id} is active.")

if __name__ == "__main__":
    agent.run()
```

> Wrapper class for SWAIG function definitions with execution and validation.

## Docs

- [execute](https://signalwire.com/docs/server-sdks/reference/python/agents/swaig-function/execute.md): Execute the function with the given arguments.
- [to_swaig](https://signalwire.com/docs/server-sdks/reference/python/agents/swaig-function/to-swaig.md): Convert the function to a SWAIG-compatible dictionary for SWML.
- [validate_args](https://signalwire.com/docs/server-sdks/reference/python/agents/swaig-function/validate-args.md): Validate arguments against the parameter JSON Schema.