on_function_call | SignalWire

Called when the SignalWire platform invokes a SWAIG function on this agent. The default implementation looks up the function in the tool registry and executes it. Override this method in a subclass to intercept tool calls for logging, metrics, pre/post-processing, or custom dispatch logic.

Most agents do not need to override this method. The default implementation handles function lookup, argument validation, and execution automatically. Token verification occurs upstream in the HTTP handler before this method is called. Override only when you need cross-cutting behavior across all tool calls.

This method is the tool dispatch mechanism. If you override it without calling super().on_function_call(name, args, raw_data), the registered tool handler will not execute. Always call super() to preserve default dispatch behavior.

Parameters

name

strRequired

The name of the SWAIG function being invoked.

args

dict[str, Any]Required

Arguments passed by the AI, conforming to the function’s parameter schema.

raw_data

Optional[dict[str, Any]]Defaults to None

The complete raw POST data from the SWAIG request, including metadata such as call_id, caller_id_number, and global_data.

Returns

FunctionResult or dict — The tool’s response. The default implementation returns the result of executing the registered handler.

Example

1 from signalwire import AgentBase
2 from signalwire.core.function_result import FunctionResult
3 
4 class LoggingAgent(AgentBase):
5     def __init__(self):
6         super().__init__(name="logging-agent", route="/logging")
7         self.set_prompt_text("You are a helpful assistant.")
8 
9     @AgentBase.tool(description="Look up an order")
10     def lookup_order(self, args, raw_data=None):
11         order_id = args.get("order_id")
12         return FunctionResult(f"Order {order_id} is in transit.")
13 
14     def on_function_call(self, name, args, raw_data=None):
15         call_id = raw_data.get("call_id", "unknown") if raw_data else "unknown"
16         print(f"[{call_id}] Tool called: {name}({args})")
17         result = super().on_function_call(name, args, raw_data)
18         print(f"[{call_id}] Tool result: {result}")
19         return result
20 
21 agent = LoggingAgent()
22 agent.run()