SWAIG
SWAIG is a JSON protocol over HTTP. It is how an AI Agent calls code you host: SignalWire POSTs a JSON object to your endpoint, and your endpoint returns a JSON object. This is the same idea as tool calling with any LLM API — see the tool calling guide for the architecture and the complete field-by-field protocol.
Each request body contains the function name (for example "search_movie"), the arguments the agent
extracted in argument.parsed, the argument schema you declared in argument_desc, and the call’s
session, caller, and project identifiers.
Each reply contains response, the text added to the agent’s context, and optionally action,
SWML-compatible objects that change what the call does next.
Remote functions
Accept a POST request
When a SWAIG function is invoked by the AI Agent, your server receives a JSON payload containing:
- The
functionname to be executed. - The structured arguments in
argument.parsed. - Contextual metadata (caller ID, project ID, session ID, etc.).
From this request, extract the function name and argument.parsed.
Example SWAIG function
The following sample SWML creates the SWAIG function search_movie:
Example request sent to server
When your SWAIG function executes, SignalWire sends a request like the following to your server.
Execute business logic
On your server, perform the actions needed to generate the desired response using the extracted function name and arguments.
In this case, our application retrieves information about a selected movie from an external API.
Return a response message
The response can directly shape the AI Agent’s next moves using natural language and SWML instructions.
In reply, your server should return a JSON object with the following:
response(string): A message in Markdown format used by the LLM in its reply.action(array): Optional list of SWML-compatible objects that can execute commands, play media, set metadata, or return inline SWML.
For example:
Response to SWAIG request
Note that this response includes both response and action sections. This means that our server has both updated the LLM’s context with the requested information from an external API, and handed off new call flow instructions in the form of valid SWML.