SWAIG | SignalWire

SWAIG is the system that lets the AI call your functions during a conversation. You define functions, SignalWire calls them via webhooks, and your responses guide the AI.

What is SWAIG?

SWAIG (SignalWire AI Gateway) connects the AI conversation to your backend logic. When the AI decides it needs to perform an action (like looking up an order or checking a balance), it calls a SWAIG function that you’ve defined.

SWAIG Function Flow. — SWAIG Function Flow

SWAIG in SWML

When your agent generates SWML, it includes SWAIG function definitions in the ai verb:

1 {
2   "version": "1.0.0",
3   "sections": {
4     "main": [
5       {
6         "ai": {
7           "SWAIG": {
8             "defaults": {
9               "web_hook_url": "https://your-agent.com/swaig"
10             },
11             "functions": [
12               {
13                 "function": "get_balance",
14                 "description": "Get the customer's current account balance",
15                 "parameters": {
16                   "type": "object",
17                   "properties": {
18                     "account_id": {
19                       "type": "string",
20                       "description": "The customer's account ID"
21                     }
22                   },
23                   "required": ["account_id"]
24                 }
25               }
26             ]
27           }
28         }
29       }
30     ]
31   }
32 }

Defining SWAIG Functions

There are three ways to define SWAIG functions in your agent:

Method 1: define_tool()

The most explicit way to register a function:

1 from signalwire_agents import AgentBase, SwaigFunctionResult
2 
3 
4 class MyAgent(AgentBase):
5     def __init__(self):
6         super().__init__(name="my-agent")
7 
8         self.define_tool(
9             name="get_balance",
10             description="Get account balance for a customer",
11             parameters={
12                 "type": "object",
13                 "properties": {
14                     "account_id": {
15                         "type": "string",
16                         "description": "The account ID to look up"
17                     }
18                 },
19                 "required": ["account_id"]
20             },
21             handler=self.get_balance
22         )
23 
24     def get_balance(self, args, raw_data):
25         account_id = args.get("account_id")
26         # Your business logic here
27         return SwaigFunctionResult(f"Account {account_id} has a balance of $150.00")

Method 2: @AgentBase.tool Decorator

A cleaner approach using decorators:

1 from signalwire_agents import AgentBase, SwaigFunctionResult
2 
3 
4 class MyAgent(AgentBase):
5     def __init__(self):
6         super().__init__(name="my-agent")
7 
8     @AgentBase.tool(
9         name="get_balance",
10         description="Get account balance for a customer",
11         parameters={
12             "type": "object",
13             "properties": {
14                 "account_id": {
15                     "type": "string",
16                     "description": "The account ID to look up"
17                 }
18             },
19             "required": ["account_id"]
20         }
21     )
22     def get_balance(self, args, raw_data):
23         account_id = args.get("account_id")
24         return SwaigFunctionResult(f"Account {account_id} has a balance of $150.00")

Method 3: DataMap (Serverless)

For direct API integration without code:

1 from signalwire_agents import AgentBase
2 
3 
4 class MyAgent(AgentBase):
5     def __init__(self):
6         super().__init__(name="my-agent")
7 
8         self.data_map.add_tool(
9             name="get_balance",
10             description="Get account balance",
11             parameters={
12                 "account_id": {
13                     "type": "string",
14                     "description": "The account ID"
15                 }
16             },
17             data_map={
18                 "webhooks": [
19                     {
20                         "url": "https://api.example.com/accounts/${enc:args.account_id}/balance",
21                         "method": "GET",
22                         "headers": {
23                             "Authorization": "Bearer ${env.API_KEY}"
24                         },
25                         "output": {
26                             "response": "Account balance is $${balance}",
27                             "action": [{"set_global_data": {"balance": "${balance}"}}]
28                         }
29                     }
30                 ]
31             }
32         )

Function Handler Signature

Every SWAIG function handler receives two arguments:

1 def my_function(self, args, raw_data):
2     """
3     args: dict - The parsed arguments from the AI
4         Example: {"account_id": "12345", "include_history": True}
5 
6     raw_data: dict - The complete request payload from SignalWire
7         Contains metadata, call info, and conversation context
8     """
9     pass

The raw_data Payload

The raw_data contains rich context about the call:

1 def my_function(self, args, raw_data):
2     # Call metadata
3     # Call information (nested under 'call' key)
4     call_data = raw_data.get("call", {})
5     call_id = call_data.get("call_id") or raw_data.get("call_id")  # Fallback for compatibility
6     call_sid = raw_data.get("call_sid")
7 
8     # Caller information (from nested call object)
9     from_number = call_data.get("from") or call_data.get("from_number")
10     to_number = call_data.get("to") or call_data.get("to_number")
11 
12     # Global data (shared state)
13     global_data = raw_data.get("global_data", {})
14     customer_name = global_data.get("customer_name")
15 
16     # Conversation context
17     meta_data = raw_data.get("meta_data", {})
18 
19     return SwaigFunctionResult("Processed")

SwaigFunctionResult

Always return a SwaigFunctionResult from your handlers:

1 from signalwire_agents import SwaigFunctionResult
2 
3 
4 def simple_response(self, args, raw_data):
5     # Simple text response - AI will speak this
6     return SwaigFunctionResult("Your order has been placed successfully.")
7 
8 
9 def response_with_actions(self, args, raw_data):
10     result = SwaigFunctionResult("Transferring you now.")
11 
12     # Add actions to control call behavior
13     result.add_action("transfer", True)
14     result.add_action("swml", {
15         "version": "1.0.0",
16         "sections": {
17             "main": [
18                 {"connect": {"to": "+15551234567", "from": "+15559876543"}}
19             ]
20         }
21     })
22 
23     return result
24 
25 
26 def response_with_data(self, args, raw_data):
27     result = SwaigFunctionResult("I've saved your preferences.")
28 
29     # Store data for later functions
30     result.add_action("set_global_data", {
31         "user_preference": "email",
32         "confirmed": True
33     })
34 
35     return result

Common Actions

Action	Purpose	Example
`set_global_data`	Store data for later use	`{"key": "value"}`
`transfer`	End AI, prepare for transfer	`True`
`swml`	Execute SWML after AI ends	`{"version": "1.0.0", ...}`
`stop`	End the AI conversation	`True`
`toggle_functions`	Enable/disable functions	`[{"active": false, "function": "fn_name"}]`
`say`	Speak text immediately	`"Please hold..."`
`play_file`	Play audio file	`"https://example.com/hold_music.mp3"`

SWAIG Request Flow

SWAIG Request Processing. — SWAIG Request Processing

SWAIG Request Format

SignalWire sends a POST request with this structure:

1 {
2   "action": "swaig_action",
3   "function": "get_balance",
4   "argument": {
5     "parsed": [
6       {
7         "account_id": "12345"
8       }
9     ],
10     "raw": "{\"account_id\": \"12345\"}"
11   },
12   "call": {
13     "call_id": "uuid-here",
14     "from": "+15551234567",
15     "from_number": "+15551234567",
16     "to": "+15559876543",
17     "to_number": "+15559876543",
18     "direction": "inbound"
19   },
20   "call_id": "uuid-here",
21   "call_sid": "call-sid-here",
22   "global_data": {
23     "customer_name": "John Doe"
24   },
25   "meta_data": {},
26   "ai_session_id": "session-uuid"
27 }

Important Note on Request Structure:

Call information (caller/callee numbers, call_id, direction) is nested under the call key
Always use defensive access: call_data = raw_data.get("call", {})
Some fields may also appear at the top level for backwards compatibility
Use the pattern shown in “Accessing Call Information” above for robust code

SWAIG Response Format

Your agent responds with:

1 {
2   "response": "The account balance is $150.00",
3   "action": [
4     {
5       "set_global_data": {
6         "last_balance_check": "2024-01-15T10:30:00Z"
7       }
8     }
9   ]
10 }

Or for a transfer:

1 {
2   "response": "Transferring you to a specialist now.",
3   "action": [
4     {"transfer": true},
5     {
6       "swml": {
7         "version": "1.0.0",
8         "sections": {
9           "main": [
10             {"connect": {"to": "+15551234567", "from": "+15559876543"}}
11           ]
12         }
13       }
14     }
15   ]
16 }

Function Parameters (JSON Schema)

SWAIG functions use JSON Schema for parameter definitions:

1 self.define_tool(
2     name="search_orders",
3     description="Search customer orders",
4     parameters={
5         "type": "object",
6         "properties": {
7             "customer_id": {
8                 "type": "string",
9                 "description": "Customer ID to search for"
10             },
11             "status": {
12                 "type": "string",
13                 "enum": ["pending", "shipped", "delivered", "cancelled"],
14                 "description": "Filter by order status"
15             },
16             "limit": {
17                 "type": "integer",
18                 "description": "Maximum number of results",
19                 "default": 10
20             },
21             "include_details": {
22                 "type": "boolean",
23                 "description": "Include full order details",
24                 "default": False
25             }
26         },
27         "required": ["customer_id"]
28     },
29     handler=self.search_orders
30 )

Webhook Security

SWAIG endpoints support multiple security layers:

Basic Authentication: HTTP Basic Auth on all requests
Function Tokens: Per-function security tokens
HTTPS: TLS encryption in transit

1 ## Function-specific token security
2 self.define_tool(
3     name="sensitive_action",
4     description="Perform a sensitive action",
5     parameters={...},
6     handler=self.sensitive_action,
7     secure=True  # Enables per-function token validation
8 )

Testing SWAIG Functions

Use swaig-test to test functions locally:

$ ## List all registered functions
$ swaig-test my_agent.py --list-tools
$ 
$ ## Execute a function with arguments
$ swaig-test my_agent.py --exec get_balance --account_id 12345
$ 
$ ## View the SWAIG configuration in SWML
$ swaig-test my_agent.py --dump-swml | grep -A 50 '"SWAIG"'

Best Practices

Keep functions focused: One function, one purpose
Write clear descriptions: Help the AI understand when to use each function
Validate inputs: Check for required arguments
Handle errors gracefully: Return helpful error messages
Use global_data: Share state between function calls
Log for debugging: Track function calls and responses

1 def get_balance(self, args, raw_data):
2     account_id = args.get("account_id")
3 
4     if not account_id:
5         return SwaigFunctionResult(
6             "I need an account ID to look up the balance. "
7             "Could you provide your account number?"
8         )
9 
10     try:
11         balance = self.lookup_balance(account_id)
12         return SwaigFunctionResult(f"Your current balance is ${balance:.2f}")
13     except AccountNotFoundError:
14         return SwaigFunctionResult(
15             "I couldn't find an account with that ID. "
16             "Could you verify the account number?"
17         )

Next Steps

Now that you understand how SWAIG connects AI to your code, let’s trace the complete lifecycle of a request through the system.