AgentsAgentBase

define_tool

View as MarkdownOpen in Claude

Programmatically define a SWAIG function (tool) that the AI can invoke during a conversation. This is the imperative alternative to the @tool decorator.

Tool definitions map to SWML SWAIG function entries. See the SWML SWAIG functions reference for the full specification.

For most cases, the @tool decorator is simpler and supports automatic parameter inference from type hints. Use define_tool() when you need dynamic tool registration or when the tool definition comes from external configuration.

Parameters

name
strRequired

Function name. Must be unique within the agent. The AI uses this name to invoke the function.

description
strRequired

Human-readable description of what the function does. The AI reads this to decide when to call the function.

parameters
dict[str, Any]Required

JSON Schema describing the function’s parameters. The AI generates arguments conforming to this schema.

handler
CallableRequired

Python function to call when the AI invokes this tool. Receives (args: dict, raw_data: dict) and should return a FunctionResult.

secure
boolDefaults to True

Whether to require token validation on tool calls. Recommended for production.

fillers
Optional[dict[str, list[str]]]

Language-specific filler phrases spoken while the function executes. Format: {"en-US": ["Looking that up...", "One moment..."]}.

webhook_url
Optional[str]

External URL to forward the tool call to instead of executing locally.

required
Optional[list[str]]

List of required parameter names from the JSON Schema.

is_typed_handler
boolDefaults to False

Set to True if the handler uses type-hinted parameters instead of the standard (args, raw_data) signature.

**swaig_fields
Any

Additional SWAIG fields to include in the function definition (e.g., wait_file, meta_data).

Returns

AgentBase — Returns self for method chaining.

Example

1from signalwire import AgentBase
2from signalwire.core.function_result import FunctionResult
3
4agent = AgentBase(name="weather-agent", route="/weather")
5agent.set_prompt_text("You are a helpful assistant.")
6
7def get_weather(args, raw_data=None):
8    city = args.get("city", "unknown")
9    return FunctionResult(f"The weather in {city} is 72F and sunny.")
10
11agent.define_tool(
12    name="get_weather",
13    description="Get the current weather for a city",
14    parameters={
15        "type": "object",
16        "properties": {
17            "city": {
18                "type": "string",
19                "description": "City name"
20            }
21        }
22    },
23    handler=get_weather,
24    required=["city"],
25    fillers={"en-US": ["Checking the weather...", "Let me look that up..."]}
26)
27agent.serve()