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.
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.
The SWAIGFunction object is callable. Calling it directly delegates to the underlying handler:
This is equivalent to func.handler(args, raw_data).
Execute the function with the given arguments.
Convert the function to a SWAIG-compatible dictionary for SWML.
Validate arguments against the parameter JSON Schema.
In most cases, use the @agent.tool() decorator instead of constructing
SWAIGFunction directly: