Agents

SWAIGFunction

View as MarkdownOpen in Claude

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 and define_tool() method on 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. For building the response returned from a handler, see FunctionResult.

SWAIGFunction serializes to a SWML SWAIG function definition. See the 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
Optional[dict[str, list[str]]]

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

wait_file
Optional[str]

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

wait_file_loops
Optional[int]

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

webhook_url
Optional[str]

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:

1from signalwire import AgentBase
2from signalwire import SWAIGFunction
3from signalwire import FunctionResult
4
5agent = AgentBase(name="assistant", route="/assistant")
6agent.set_prompt_text("You are a helpful assistant.")
7
8@agent.tool(description="Look up order status")
9def check_order(args, raw_data=None):
10    order_id = args.get("order_id")
11    return FunctionResult(f"Order {order_id} shipped March 28.")
12
13agent.serve()

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

Methods

execute

Execute the function with the given arguments.

to_swaig

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

validate_args

Validate arguments against the parameter JSON Schema.

Examples

Manual registration

1from signalwire import AgentBase, SWAIGFunction
2from signalwire import FunctionResult
3
4def handle_lookup(args, raw_data):
5    account_id = args.get("account_id", "")
6    return FunctionResult(f"Account {account_id} is active.")
7
8agent = AgentBase(name="my-agent")
9
10func = SWAIGFunction(
11    name="lookup_account",
12    handler=handle_lookup,
13    description="Look up account status by ID",
14    parameters={
15        "type": "object",
16        "properties": {
17            "account_id": {
18                "type": "string",
19                "description": "The account ID to look up"
20            }
21        },
22        "required": ["account_id"]
23    },
24    secure=True,
25    fillers={"en-US": ["Let me check on that..."]}
26)
27
28# Validate before registering
29is_valid, errors = func.validate_args({"account_id": "12345"})
30print(f"Valid: {is_valid}, Errors: {errors}")
31# Valid: True, Errors: []

Using the decorator (preferred)

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

1from signalwire import AgentBase
2from signalwire import FunctionResult
3
4agent = AgentBase(name="my-agent")
5agent.set_prompt_text("You are a helpful assistant.")
6
7@agent.tool(
8    description="Look up account status by ID",
9    parameters={
10        "type": "object",
11        "properties": {
12            "account_id": {"type": "string", "description": "Account ID"}
13        },
14        "required": ["account_id"]
15    },
16    secure=True,
17    fillers=["Let me check on that..."]
18)
19def lookup_account(args, raw_data):
20    account_id = args.get("account_id", "")
21    return FunctionResult(f"Account {account_id} is active.")
22
23if __name__ == "__main__":
24    agent.run()