***

title: SWAIGFunction
slug: /reference/python/agents/swaig-function
description: Wrapper class for SWAIG function definitions with execution and validation.
max-toc-depth: 3
---------------------

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

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

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

## **Properties**

<ParamField path="name" type="str" toc={true}>
  The function name.
</ParamField>

<ParamField path="handler" type="Callable" toc={true}>
  The underlying Python handler function.
</ParamField>

<ParamField path="description" type="str" toc={true}>
  The function description.
</ParamField>

<ParamField path="parameters" type="dict" toc={true}>
  The parameter schema dictionary.
</ParamField>

<ParamField path="secure" type="bool" toc={true}>
  Whether token authentication is required.
</ParamField>

<ParamField path="fillers" type="Optional[dict[str, list[str]]]" toc={true}>
  Filler phrases by language code to speak while the function executes
  (e.g., `{"en-US": ["Let me check on that..."]}`).
</ParamField>

<ParamField path="wait_file" type="Optional[str]" toc={true}>
  URL of an audio file to play while the function executes. Preferred over `fillers`.
</ParamField>

<ParamField path="wait_file_loops" type="Optional[int]" toc={true}>
  Number of times to loop `wait_file`. Defaults to playing once.
</ParamField>

<ParamField path="webhook_url" type="Optional[str]" toc={true}>
  External webhook URL. When set, the function call is forwarded to this URL instead
  of being handled locally.
</ParamField>

<ParamField path="required" type="list[str]" toc={true}>
  List of required parameter names. Merged into the parameter schema's `required` array.
</ParamField>

<ParamField path="is_typed_handler" type="bool" toc={true}>
  Whether the handler uses type-hinted parameters (auto-wrapped by the `@tool` decorator).
</ParamField>

<ParamField path="is_external" type="bool" toc={true}>
  `True` when `webhook_url` is set, indicating the function is handled externally.
</ParamField>

### \_\_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**

<CardGroup cols={3}>
  <Card title="execute" href="/docs/server-sdks/reference/python/agents/swaig-function/execute">
    Execute the function with the given arguments.
  </Card>

  <Card title="to_swaig" href="/docs/server-sdks/reference/python/agents/swaig-function/to-swaig">
    Convert the function to a SWAIG-compatible dictionary for SWML.
  </Card>

  <Card title="validate_args" href="/docs/server-sdks/reference/python/agents/swaig-function/validate-args">
    Validate arguments against the parameter JSON Schema.
  </Card>
</CardGroup>

***

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