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

# 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()`.

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

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

The function name.

The underlying Python handler function.

The function description.

The parameter schema dictionary.

Whether token authentication is required.

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

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

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

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

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

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

`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 the function with the given arguments.

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

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()
```